Branchez l'encaissement de la scolarité à votre logiciel.

Votre logiciel de gestion garde ses élèves et ses classes. BARO est la couche encaissement + relance par-dessus : vous branchez l'API, BARO fait payer les parents sur le compte de chaque établissement et vous renvoie chaque règlement.

Démarrage rapide

Trois étapes, du roster au règlement en temps réel.

Authentification

Deux niveaux, par isolation et sécurité. Règle : la clé dev provisionne, le token d'établissement opère.

Clé développeur — X-Dev-Key

Une clé par intégrateur. Elle sert à provisionner et gérer vos établissements — jamais ceux d'un autre intégrateur, jamais la clé maître BARO. Vous ne payez pas la fuite d'un client par celle des autres.

X-Dev-Key: bk_live_<votre clé>

Créez un établissement — il vous répond son slug et son provider_token :

curl -X POST https://baro.africa/api/v1/dev/providers \
  -H "X-Dev-Key: bk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Markaz An-Nour",
    "sector": "education",
    "settlement": {
      "rail": "djomy",
      "client_id": "djomy-client-…",
      "client_secret": "…",
      "merchant_code": "727066"
    }
  }'

Token d'établissement — X-Provider-Token

Un token par établissement, renvoyé à la création. Il autorise les opérations courantes de cet établissement (import, statuts, relances). Un token qui fuit n'expose qu'un établissement.

X-Provider-Token: <token de l'établissement>

Endpoints

Provisioning — avec l'en-tête X-Dev-Key :

Opérations d'un établissement — avec l'en-tête X-Provider-Token. {slug} = l'identifiant de l'établissement.

Référence interactive complète (Swagger) : baro.africa/api/v1/sdk/docs — ou le schéma brut /api/v1/sdk/openapi.json à importer dans Postman ou un générateur de client.

Idempotence

Les créations acceptent un en-tête Idempotency-Key. Un rejeu (timeout, retry automatique) avec la même clé et le même corps ne crée pas de doublon — la réponse d'origine est renvoyée. La même clé avec un corps différent renvoie 409. Générez une clé unique (ex. un UUID) par opération.

curl -X POST https://baro.africa/api/v1/dev/providers \
  -H "X-Dev-Key: bk_live_…" \
  -H "Idempotency-Key: 9f2c1a4e-…" \
  -H "Content-Type: application/json" \
  -d '{ … }'

Webhook temps-réel

Fini le polling : BARO pousse chaque règlement vers votre logiciel, en temps réel et signé.

1 · Configurez votre URL

curl -X PUT https://baro.africa/api/v1/recovery/{slug}/webhook \
  -H "X-Provider-Token: <token>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://votre-logiciel.example/baro/webhook"}'

La réponse contient un webhook_secret — renvoyé une seule fois, à stocker pour vérifier les signatures.

2 · Recevez l'événement

À chaque règlement, BARO POST vers votre URL, avec l'en-tête X-Baro-Signature: v1:<hmac>.

{
  "eventType": "installment.settled",
  "eventId": "a1b2c3…",
  "timestamp": "2026-10-01T09:12:00Z",
  "data": {
    "provider": "markaz-an-nour",
    "loan_ref": "PLAN-…-3",
    "amount_paid": 203046,
    "received_amount": 200000,
    "gateway_fee": 3046,
    "transactionId": "…",
    "payer": "224620000001",
    "status": "PAID"
  }
}

3 · Vérifiez la signature

Recalculez le HMAC-SHA256 du corps brut avec votre webhook_secret et comparez-le à l'en-tête. S'il correspond, traitez l'événement ; sinon, ignorez-le.

const crypto = require("crypto");

function verify(rawBody, header, secret) {
  const expected = "v1:" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(header), Buffer.from(expected)
  );
}

Sandbox

Testez votre réception de webhook de bout en bout, sans argent réel. Un appel simule un règlement : BARO POST vers votre URL un événement installment.settled signé exactement comme en production, marqué "sandbox": true. Aucune écriture en base, aucun rail sollicité.

Configurez d'abord votre webhook (PUT /dev/webhook), puis :

curl -X POST https://baro.africa/api/v1/dev/sandbox/simulate-payment \
  -H "X-Dev-Key: bk_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200000,
    "student_name": "Élève Test",
    "loan_ref": "PLAN-SANDBOX-1"
  }'

La réponse confirme la livraison et vous redonne la signature envoyée — de quoi vérifier votre implémentation :

{
  "sandbox": true,
  "delivered": true,
  "http_status": 200,
  "eventType": "installment.settled",
  "eventId": "a1b2c3…",
  "signature": "v1:9f86d0…"
}

Facturation & usage

BARO mesure le volume réglé via votre intégration et accumule la commission convenue (accrued_fees, au taux rev_share_rate). Zéro-custody : c'est un dû comptabilisé, facturé hors-bande — jamais un prélèvement. L'argent va toujours directement sur le compte de l'établissement.

curl https://baro.africa/api/v1/dev/usage \
  -H "X-Dev-Key: bk_live_…"

{
  "integrator": "logiciel-markaz",
  "rev_share_rate": 0.01,
  "currency": "GNF",
  "count": 128,
  "gross_volume": 25600000,
  "accrued_fees": 256000
}

Période par défaut : le mois calendaire courant. Bornez avec ?from=YYYY-MM-DD&to=YYYY-MM-DD.

Zéro-custody — les invariants

Le SDK garantit, par construction :