BitLibera

Démarrer

API marchands BitLibera

https://exchanger.bitlibera.com/api/v1

Encaissez en Lumicash, payez vos bénéficiaires depuis votre solde BIF et utilisez Lightning pour recharger ou convertir. Toutes les requêtes et réponses sont en JSON, montants en BIF entiers.

Authentification

Envoyez votre clé dans l'en-tête x-api-key. Obtenez-la sur la page Créer un compte marchand ; l'inscription est ouverte, aucun code n'est requis. Ne jamais exposer la clé côté navigateur.

En-têtes
x-api-key: bl_live_xxxxxxxxxxxxxxxx
Content-Type: application/json

Idempotence

Chaque opération porte un order_id unique par marchand. Renvoyer la même requête retourne l'opération existante sans nouveau débit. Le même order_id avec d'autres paramètres renvoie 409.

Statuts

PROCESSINGOpération réservée, appel opérateur en cours.
PENDING_PAYMENTFacture Lightning en attente de paiement.
COMPLETEDOpération réglée et définitive.
FAILEDRefus opérateur ; un payout est recrédité au solde.
REQUIRES_REVIEWÉtat incertain : ne changez pas d'order_id, consultez /orders.

Erreurs

Format commun : 400 données invalides, 401 clé absente ou invalide, 402 solde insuffisant, 403 non autorisé, 404 introuvable, 409 conflit d'order_id, 429 trop de requêtes, 503 service indisponible.

Erreur
{
  "success": false,
  "error": "Montant invalide."
}

Compte marchand

Créer un marchand

POST/auth/register

Crée un compte marchand et retourne sa clé API. La clé n'est affichée qu'une seule fois : seule son empreinte est conservée. L'inscription est ouverte ; un jeton optionnel (x-registration-token) peut la restreindre si BitLibera le configure.

Corps de la requête

business_namestringrequis

Nom commercial, 2 à 120 caractères.

contact_emailstringrequis

Email de contact valide.

curl -X POST "https://exchanger.bitlibera.com/api/v1/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Free Tech Institute",
    "contact_email": "finance@freeti.bi"
  }'
{
  "success": true,
  "merchant_id": "mch_5de34923a8b2",
  "api_key": "bl_live_…",
  "message": "Clé affichée une seule fois."
}

Compte marchand

Solde

GET/balance

Retourne les deux soldes distincts du marchand : balance_bif (Lumicash) et balance_sats (Lightning). Aucune conversion automatique entre les deux.

En-têtes

x-api-keystringrequis

Clé API marchand.

curl -X GET "https://exchanger.bitlibera.com/api/v1/balance" \
  -H "x-api-key: bl_live_…"
{
  "success": true,
  "balance_bif": 250000,
  "balance_sats": 42000,
  "updated_at": "2026-10-17T14:00:00.000Z"
}

Compte marchand

Convertir BIF ↔ sats

POST/convert

Seul moyen de déplacer des fonds entre les deux soldes : débite un solde et crédite l'autre au taux affiché. La réponse indique le taux appliqué.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

directionstringrequis

BIF_TO_SATS ou SATS_TO_BIF.

amount_bifinteger

Montant BIF (direction BIF_TO_SATS).

amount_satsinteger

Montant en sats (direction SATS_TO_BIF).

order_idstringrequis

Identifiant unique côté marchand.

curl -X POST "https://exchanger.bitlibera.com/api/v1/convert" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "direction": "BIF_TO_SATS",
    "amount_bif": 10000,
    "order_id": "CONV-0001"
  }'
{
  "success": true,
  "order_id": "CONV-0001",
  "status": "COMPLETED",
  "direction": "BIF_TO_SATS",
  "amount_bif": 10000,
  "amount_sats": 3400,
  "rate": 2.94
}

Encaissements Lumicash

Demander un OTP

POST/onramp/request-otp

Envoie un code OTP Lumicash au client. Le défi est lié au marchand, au numéro et au montant, valable 10 minutes. Limite : 1 demande par minute et par numéro.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

phonestringrequis

Numéro Lumicash, normalisé en 257 + 8 chiffres.

amountintegerrequis

Montant en BIF, entier positif.

curl -X POST "https://exchanger.bitlibera.com/api/v1/onramp/request-otp" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "79000000",
    "amount": 5000
  }'
{
  "success": true,
  "otp_request_id": "c1f0…",
  "expires_in": 600,
  "merchant": "Free Tech Institute"
}

Encaissements Lumicash

Encaisser avec OTP

POST/onramp/execute

Débite le compte Lumicash du client avec l'OTP reçu. La réponse initiale n'est pas un règlement : suivez le statut via /orders/{order_id}.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

otp_request_idstringrequis

Identifiant retourné par request-otp.

otpstringrequis

Code reçu par le client.

phonestringrequis

Même numéro que la demande d'OTP.

amountintegerrequis

Même montant que la demande d'OTP.

order_idstringrequis

Identifiant unique côté marchand (idempotence).

curl -X POST "https://exchanger.bitlibera.com/api/v1/onramp/execute" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "otp_request_id": "c1f0…",
    "otp": "123456",
    "phone": "79000000",
    "amount": 5000,
    "order_id": "FTP-0001"
  }'
{
  "success": false,
  "order_id": "FTP-0001",
  "status": "REQUIRES_REVIEW",
  "amount_bif": 5000,
  "recipient_phone": "25779000000",
  "transaction_ref": "YP-88231",
  "payment_request": null,
  "payment_hash": null,
  "amount_sats": null,
  "requires_review": true
}

Encaissements Lumicash

Recharger le solde (Lumicash)

POST/topup/lumicash

Même flux que /onramp/execute, mais le montant confirmé crédite le solde BIF du marchand.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

…

Mêmes champs que /onramp/execute.

curl -X POST "https://exchanger.bitlibera.com/api/v1/topup/lumicash" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "otp_request_id": "c1f0…",
    "otp": "123456",
    "phone": "79000000",
    "amount": 100000,
    "order_id": "TOP-0001"
  }'
{
  "success": true,
  "order_id": "FTP-0001",
  "status": "COMPLETED",
  "amount_bif": 100000,
  "recipient_phone": "25779000000",
  "transaction_ref": "YP-88240",
  "payment_request": null,
  "payment_hash": null,
  "amount_sats": null,
  "requires_review": false
}

Payouts

Payer un bénéficiaire

POST/payouts

Verse des BIF sur un numéro Lumicash depuis le solde marchand. Le solde est réservé avant l'appel opérateur et recrédité automatiquement en cas d'échec. Renvoyer le même order_id ne débite jamais deux fois.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

recipient_phonestringrequis

Numéro Lumicash du bénéficiaire.

amount_bifintegerrequis

Montant en BIF.

order_idstringrequis

Identifiant unique côté marchand.

curl -X POST "https://exchanger.bitlibera.com/api/v1/payouts" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_phone": "79000000",
    "amount_bif": 5000,
    "order_id": "FTP-0002"
  }'
{
  "success": true,
  "order_id": "FTP-0002",
  "status": "COMPLETED",
  "amount_bif": 5000,
  "recipient_phone": "25779000000",
  "transaction_ref": "AF-55102",
  "payment_request": null,
  "payment_hash": null,
  "amount_sats": null,
  "requires_review": false
}

Payouts

Payer une facture Lightning

POST/payouts/lightning

Paie une facture Lightning depuis le solde sats du marchand (jamais le solde BIF). Une réserve couvrant les frais (~1 %, min 10 sats) est bloquée puis recréditée en partie après succès, en totalité en cas d'échec.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

payment_requeststringrequis

Facture BOLT11 (lnbc…).

amount_satsinteger

Montant en sats si la facture n'en précise pas.

order_idstringrequis

Identifiant unique côté marchand.

curl -X POST "https://exchanger.bitlibera.com/api/v1/payouts/lightning" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_request": "lnbc3400n1p…",
    "order_id": "FTP-0004"
  }'
{
  "success": true,
  "order_id": "FTP-0004",
  "status": "COMPLETED",
  "amount_sats": 3400,
  "fee_sats": 34,
  "payment_hash": "a3f9…"
}

Lightning

Créer une facture offramp

POST/offramp/create-invoice

Convertit un montant BIF en sats et retourne une facture Lightning. Le BIF est versé au numéro seulement après paiement de la facture et appel à /offramp/verify.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

recipient_phonestringrequis

Numéro Lumicash à créditer.

amount_bifintegerrequis

Montant à verser en BIF.

order_idstringrequis

Identifiant unique.

curl -X POST "https://exchanger.bitlibera.com/api/v1/offramp/create-invoice" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_phone": "79000000",
    "amount_bif": 5000,
    "order_id": "FTP-0003"
  }'
{
  "success": true,
  "order_id": "FTP-0003",
  "status": "PENDING_PAYMENT",
  "amount_bif": 5000,
  "recipient_phone": "25779000000",
  "transaction_ref": null,
  "payment_request": "lnbc17u1p…",
  "payment_hash": "a3f9…",
  "amount_sats": 1700,
  "requires_review": false
}

Lightning

Vérifier l'offramp

POST/offramp/verify

Vérifie que la facture est payée puis déclenche le versement Lumicash une seule fois. Retourne 202 tant que la facture n'est pas payée.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

order_idstringrequis

Commande offramp.

curl -X POST "https://exchanger.bitlibera.com/api/v1/offramp/verify" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "FTP-0003"
  }'
{
  "success": true,
  "order_id": "FTP-0003",
  "status": "COMPLETED",
  "amount_bif": 5000,
  "recipient_phone": "25779000000",
  "transaction_ref": "AF-55190",
  "payment_request": null,
  "payment_hash": null,
  "amount_sats": 1700,
  "requires_review": false
}

Lightning

Recharger le solde (Lightning)

POST/topup/lightning

Crée une facture Lightning dont le paiement crédite le solde sats du marchand (pas le solde BIF). Fournir amount_sats ou amount_bif ; un montant BIF est converti en sats au taux du moment.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

amount_satsinteger

Montant en sats à créditer.

amount_bifinteger

Alternative : montant BIF converti en sats.

order_idstringrequis

Identifiant unique.

curl -X POST "https://exchanger.bitlibera.com/api/v1/topup/lightning" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_sats": 1000,
    "order_id": "TOP-0002"
  }'
{
  "success": true,
  "order_id": "TOP-0002",
  "status": "PENDING_PAYMENT",
  "amount_bif": 50000,
  "recipient_phone": null,
  "transaction_ref": null,
  "payment_request": "lnbc170u1p…",
  "payment_hash": null,
  "amount_sats": 17000,
  "requires_review": false
}

Lightning

Vérifier la recharge

POST/topup/lightning/verify

Crédite le solde une seule fois quand la facture est payée. Retourne 202 sinon.

En-têtes

x-api-keystringrequis

Clé API marchand.

Corps de la requête

order_idstringrequis

Commande de recharge.

curl -X POST "https://exchanger.bitlibera.com/api/v1/topup/lightning/verify" \
  -H "x-api-key: bl_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "TOP-0002"
  }'
{
  "success": true,
  "order_id": "TOP-0002",
  "status": "COMPLETED",
  "amount_bif": 50000,
  "recipient_phone": null,
  "transaction_ref": null,
  "payment_request": null,
  "payment_hash": null,
  "amount_sats": 17000,
  "requires_review": false
}

Commandes

Statut d'une commande

GET/orders/{orderId}

Retourne l'état d'une commande du marchand. Les commandes d'autres marchands retournent 404. Les encaissements en revue sont revérifiés automatiquement auprès de l'opérateur.

En-têtes

x-api-keystringrequis

Clé API marchand.

Paramètres de chemin

orderIdstringrequis

order_id fourni à la création.

curl -X GET "https://exchanger.bitlibera.com/api/v1/orders/FTP-0001" \
  -H "x-api-key: bl_live_…"
{
  "success": true,
  "order_id": "FTP-0001",
  "status": "COMPLETED",
  "amount_bif": 5000,
  "recipient_phone": "25779000000",
  "transaction_ref": "AF-55102",
  "payment_request": null,
  "payment_hash": null,
  "amount_sats": null,
  "requires_review": false
}

Exemples illustratifs ; les valeurs réelles dépendent des taux et des opérateurs.