Encaissez par Mobile Money, sans deviner ce qui se passe

Architecture du système

Cinq nœuds, un seul chemin pour l'argent. Comprendre qui parle à qui évite la moitié des questions de support.

Qui fait quoi

Démarrage en 5 minutes

Du compte vide au premier encaissement de test réussi.

1. Créer un compte et récupérer ses clés de test

Ouvrez un compte sur la console. Un projet sandbox et ses identifiants sont générés immédiatement. Le secret n'est affiché qu'une fois : copiez-le avant de fermer.

2. Vérifier que la clé fonctionne

# Sonde d'authentification : ne consomme rien, ne crée rien
curl https://api.gba-cm.online/api/v1/me \
  -H "X-BCash-Key: $BCASH_KEY" \
  -H "X-BCash-Timestamp: $(date +%s)" \
  -H "X-BCash-Signature: $SIGNATURE"

Le calcul de $SIGNATURE est décrit dans Authentification. Une réponse 200 confirme que clé, secret et horloge sont corrects.

3. Enregistrer un endpoint de notification

{
  "url": "https://boutique.example.cm/webhooks/bcash",
  "events": ["transaction.succeeded", "transaction.failed"]
}

# → 201 { "reference": "whk_…", "secret": "whsec_…" }   ← le secret n'apparaît qu'ici

4. Créer un encaissement de test

curl -X POST https://api.gba-cm.online/api/v1/collections \
  -H "X-BCash-Key: $BCASH_KEY" \
  -H "X-BCash-Timestamp: $(date +%s)" \
  -H "X-BCash-Signature: $SIGNATURE" \
  -H "Idempotency-Key: 8f1c2b4e-3a77-4c11-9f2d-6b0a5e91c7d3" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "operator": "MTN",
    "customer": { "phone": "+237650000000" },
    "merchantReference": "CMD-1042",
    "context": "API_DIRECT"
  }'

5. Forcer l'issue en sandbox

En test, personne ne va taper un code secret : provoquez vous-même le dénouement.

{ "target": "SUCCEEDED" }

# La transaction suit le chemin nominal : écritures comptables,
# webhook transaction.succeeded livré et signé, trace d'audit.

Environnements & clés

Deux environnements, la même API, des clés distinctes qui ne se croisent jamais.

Anatomie d'un credential

• Clé publique — identifie l'application appelante, transmise en clair dans X-BCash-Key. Visible dans la console.
• Secret — sert à signer. Affiché une seule fois, à la création ou à la rotation. La console n'en conserve que les quatre derniers caractères, pour vous aider à identifier la bonne clé.
• Environnement — porté par le credential, pas par le projet : un même projet peut détenir une clé de test et une clé de production.
• Scopes — ce que la clé a le droit de faire (liste).

Rotation sans interruption

1. Depuis la console, générez une nouvelle clé en mode sans interruption.
2. Déployez le nouveau couple clé/secret sur vos serveurs.
3. Vérifiez dans la console que la nouvelle clé enregistre des appels (colonne dernier usage).
4. Révoquez l'ancienne.

La révocation immédiate existe aussi, pour un secret compromis : elle coupe l'ancienne clé à l'instant, et toute intégration encore en train de l'utiliser reçoit INVALID_SIGNATURE. La console vous demande de ressaisir le nom du projet avant de l'appliquer.

Authentification

Trois manières de s'authentifier, pour trois natures d'appelant. Choisir la bonne est la première décision d'architecture d'une intégration.

Signer une requête HMAC

La chaîne à signer concatène quatre éléments séparés par des sauts de ligne :

METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + sha256_hex(corps)

# METHOD    : verbe HTTP en majuscules, ex. POST
# PATH      : chemin seul, ex. /api/v1/collections (sans hôte, sans query)
# TIMESTAMP : secondes Unix, identique à l'en-tête X-BCash-Timestamp
# corps     : le corps JSON exact envoyé ; chaîne vide en GET

$body      = json_encode($payload, JSON_UNESCAPED_SLASHES);
$timestamp = (string) time();
$toSign    = "POST\n/api/v1/collections\n{$timestamp}\n" . hash('sha256', $body);
$signature = hash_hmac('sha256', $toSign, $secret);

// Envoyez exactement le même $body : re-sérialiser après signature invalide la requête.

const body = JSON.stringify(payload);
const ts = Math.floor(Date.now() / 1000).toString();
const digest = crypto.createHash('sha256').update(body).digest('hex');
const signature = crypto
  .createHmac('sha256', secret)
  .update(`POST\n/api/v1/collections\n${ts}\n${digest}`)
  .digest('hex');

Jeton éphémère pour les clients

Votre backend échange sa clé HMAC contre un jeton court, qu'il remet au client. Le jeton porte un sous-ensemble strict des scopes de la clé et vit au maximum 900 secondes.

// Requête, signée en HMAC depuis VOTRE serveur
{ "scopes": ["collections:create", "transactions:read"], "ttl": 600 }

// Réponse
{ "token": "bt_9f2c…", "expiresIn": 600, "scopes": ["collections:create", "transactions:read"] }

• Un jeton ne peut pas en émettre un autre : la route refuse un Bearer bt_….
• Révoquer le credential invalide instantanément tous les jetons qu'il a émis.
• Demandez le strict nécessaire : un jeton d'écran de paiement n'a pas besoin de lire vos soldes.

Idempotence

Le réseau mobile coupe. La règle qui garantit qu'une coupure ne débite jamais deux fois votre client.

Toute route qui déplace de l'argent exige l'en-tête Idempotency-Key, un UUID que vous générez et que vous conservez le temps de l'opération.

Comment choisir sa clé

Rattachez la clé à l'intention métier, pas à la tentative technique. Une commande qu'on paie une fois mérite une clé stable ; si vous en générez une nouvelle à chaque clic, vous autorisez le double paiement que l'idempotence était censée empêcher.

// À la création de la commande, une fois pour toutes :
order.paymentIdempotencyKey ??= crypto.randomUUID();
// Toutes les tentatives de paiement de CETTE commande réutilisent cette clé.

Retrouver une transaction après une coupure

Si vous perdez la réponse, ne recréez rien : interrogez.

Ces deux routes existent précisément pour cette situation. La seconde suppose que vous ayez renseigné merchantReference à la création — faites-le systématiquement.

Montants & devise

Le franc CFA n'a pas de sous-unité. Cette simplicité est un piège pour qui vient d'une API en centimes.

• amount est un entier strictement positif : 25000 signifie vingt-cinq mille francs.
• Ne multipliez jamais par 100, n'arrondissez jamais un flottant : une addition en virgule flottante finit toujours par produire un franc fantôme dans un rapprochement.
• currency vaut XAF. Le champ existe pour l'avenir ; aujourd'hui il n'a qu'une valeur.
• Trois montants coexistent sur une transaction : amount (ce qui est demandé), feeAmount (les frais) et netAmount (ce qui vous reste). Affichez celui qui correspond à la question posée, pas celui qui est le plus flatteur.

Erreurs & correlation ID

Toutes les erreurs partagent la même enveloppe, et chacune porte de quoi être retrouvée par le support.

{
  "error": {
    "code": "INSUFFICIENT_FUNDS",           // code machine stable
    "message": "Solde insuffisant.",        // texte lisible, susceptible d'évoluer
    "correlationId": "c7f3a91b4e2d",        // à citer au support
    "retryable": false,                     // rejouer peut-il aider ?
    "retryAfter": null,                     // délai conseillé, en secondes
    "details": {}                             // contexte selon le code
  }
}

Comment réagir

• Branchez-vous sur code, jamais sur message : le texte peut être reformulé, le code est un contrat.
• retryable: true — rejouez la même requête avec la même Idempotency-Key, en respectant retryAfter.
• retryable: false — rejouer ne changera rien. Corrigez la requête ou remontez l'erreur à l'utilisateur.
• Journalisez correlationId à côté de votre référence de commande. C'est ce qui transforme un ticket de support en diagnostic de trois minutes.

Codes HTTP

Le catalogue exhaustif des codes machine est publié par l'API elle-même : GET /api/v1/meta → errors.catalog. Consommez-le plutôt que de recopier une liste qui vieillira.

Pagination & filtres

Les collections sont paginées côté serveur. Ne rapatriez jamais tout pour filtrer en mémoire.

La réponse porte le total ; ne le recalculez pas à partir du nombre d'éléments reçus.

Opérateurs

La liste est dynamique : elle porte l'état de service de chaque opérateur.

Frais & devis

Deux questions différentes se cachent derrière « combien ça coûte ». L'API vous demande laquelle vous posez.

Choisir sa base de calcul

// Requête
{
  "type": "COLLECTION",
  "context": "WOOCOMMERCE",
  "amount": 25000,
  "amountBasis": "ORDER_NET",
  "operator": "MTN"
}

// Réponse
{
  "reference": "fq_7Q4K…",
  "orderAmount": 25000,
  "customerFeeAmount": 500,
  "customerPayableAmount": 25500,   // ← à utiliser comme "amount" à la création
  "merchantNetAmount": 25000,
  "feePayer": "CUSTOMER",
  "ruleVersion": "2026-07-01",
  "expiresAt": "2026-07-27T10:15:00Z"   // 900 s
}

Consommer un devis

Pour garantir au client le prix affiché, passez feeQuoteId à la création — et amount doit alors valoir exactement customerPayableAmount. Toute autre valeur est refusée : c'est la protection contre l'écran qui affiche un prix et l'API qui en débite un autre.

• Un devis est valable 900 secondes et se consomme une seule fois.
• ruleVersion identifie la grille appliquée : conservez-la avec votre commande, elle explique un écart six mois plus tard.
• Sans devis, les frais sont calculés à la création avec la grille en vigueur à cet instant.

Encaissements

La route à utiliser dans neuf cas sur dix : elle fixe le type et résout votre wallet destinataire toute seule.

Corps de la requête

Réponse

{
  "reference": "TRX7QK4M2",
  "type": "COLLECTION",
  "status": "PENDING_CONFIRMATION",
  "amount": 25500,
  "feeAmount": 500,
  "netAmount": 25000,
  "merchantReference": "CMD-1042",
  "nextAction": {
    "type": "AWAIT_MOBILE_CONFIRMATION",
    "displayMessage": "Confirmez le paiement sur votre téléphone.",
    "expiresAt": "2026-07-27T10:05:00Z"
  },
  "createdAt": "2026-07-27T10:00:00Z"
}

Utiliser nextAction

Ce bloc vous dit quoi afficher pendant l'attente, sans que vous ayez à inventer un texte par opérateur :

• AWAIT_MOBILE_CONFIRMATION — le client doit valider sur son téléphone. Affichez displayMessage et un compte à rebours vers expiresAt.
• AWAIT_PROCESSING — rien à faire pour le client, l'exécution est en cours.

Décaissements

Envoyer de l'argent depuis votre solde vers un numéro Mobile Money.

{
  "amount": 50000,                       // ce que REÇOIT le bénéficiaire
  "operator": "ORANGE",
  "recipient": { "phone": "+237690000000", "name": "Fournisseur ALBA" },
  "merchantReference": "FACT-2026-118"
}

Un décaissement échoue si le solde disponible est insuffisant : le montant nécessaire est réservé dès la création, puis libéré en cas d'échec.

Cycle de vie d'une transaction

Douze statuts, quatre terminaux. Une transaction n'est jamais « peut-être payée ».

Suivre une transaction

Deux stratégies, et l'une est nettement meilleure :

• Webhooks — recommandé. Vous êtes notifié dès le changement d'état, sans interroger l'API.
• Interrogation périodique — acceptable comme filet de sécurité, par exemple une vérification des transactions non terminales de plus de dix minutes. Espacez vos appels : interroger chaque seconde ne fait pas confirmer le client plus vite.

Annulation & remboursement

Annuler

Possible uniquement avant exécution : CREATED, FEE_QUOTED, HELD, QUEUED. Une transaction en PROCESSING ne s'annule pas — l'argent est peut-être déjà en mouvement. L'appel libère les fonds réservés et reste idempotent : annuler une transaction déjà annulée renvoie 200.

Rembourser

• Remboursables : COLLECTION et MERCHANT_PAYMENT au statut SUCCEEDED.
• Un remboursement est une nouvelle transaction de type REFUND, reliée par parentReference.
• Sans amount, le restant dû est intégralement remboursé ; sinon le remboursement est partiel et peut être répété.
• Quand la somme des remboursements atteint le montant d'origine, la transaction initiale passe REVERSED et l'événement transaction.reversed est émis.
• Aucun frais n'est prélevé sur un remboursement.

POST /api/v1/transactions/TRX7QK4M2/refund
Idempotency-Key: 3d9a1c77-2f40-4b8e-9c15-77e0a2b4d611

{ "amount": 5000, "reason": "Article manquant" }

Soldes & wallets

Un solde n'est pas un nombre unique : trois compartiments cohabitent.

Le wallet marchand est créé automatiquement au premier encaissement. Un wallet peut être gelé par la conformité : la consultation reste possible, les mouvements sont bloqués. Le gel d'un wallet et la suspension d'une organisation sont deux mécanismes distincts.

Webhooks : principe

Vous n'attendez pas l'API : c'est elle qui vous appelle quand l'état change.

{
  "id": "evt_9K2mQ7…",              // stable entre les tentatives → clé de déduplication
  "type": "transaction.succeeded",
  "apiVersion": "2026-07-20",
  "createdAt": "2026-07-27T10:02:13Z",
  "livemode": true,                  // false en sandbox
  "data": {
    "object": { /* la transaction complète */ },
    "previousAttributes": { "status": "PENDING_CONFIRMATION" }
  }
}

Les quatre règles à respecter

1. Vérifiez la signature avant de lire le corps. Un endpoint non vérifié est une porte ouverte : n'importe qui peut poster « paiement réussi ».
2. Répondez 2xx vite, sous quelques secondes. Accusez réception, puis traitez en tâche de fond. Un traitement lent déclenche des reprises inutiles.
3. Dédupliquez sur id. Le même evt_… peut arriver deux fois ; votre traitement doit être sans effet la seconde fois.
4. Ne supposez pas l'ordre. Un transaction.succeeded peut précéder un transaction.pending_confirmation. Fiez-vous au statut porté par l'objet, pas à l'ordre d'arrivée.

Vérifier la signature

La seule étape non négociable de l'intégration.

// Le corps BRUT est indispensable : un JSON re-sérialisé ne redonne pas les mêmes octets.
app.post('/webhooks/bcash', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-BCash-Timestamp');
  const raw = req.body.toString('utf8');

  // Fenêtre anti-rejeu : on refuse un événement trop ancien.
  if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(400);

  const expected = crypto.createHmac('sha256', process.env.BCASH_WEBHOOK_SECRET)
    .update(`${ts}\n${raw}`).digest('hex');

  const candidates = [req.get('X-BCash-Signature'), req.get('X-BCash-Signature-Previous')].filter(Boolean);
  const valid = candidates.some(sig =>
    sig.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)));   // comparaison à temps constant

  if (!valid) return res.sendStatus(401);

  res.sendStatus(200);              // on accuse réception AVANT de traiter
  queue.push(JSON.parse(raw));       // traitement asynchrone, dédupliqué sur event.id
});

$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_BCASH_TIMESTAMP'] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(400); exit; }

$expected = hash_hmac('sha256', "{$ts}\n{$raw}", $secret);
$ok = hash_equals($expected, $_SERVER['HTTP_X_BCASH_SIGNATURE'] ?? '')
   || hash_equals($expected, $_SERVER['HTTP_X_BCASH_SIGNATURE_PREVIOUS'] ?? '');

if (!$ok) { http_response_code(401); exit; }

Gérer ses endpoints

La référence d'un endpoint a la forme whk_… et son secret whsec_…. Le secret n'est affiché qu'à la création et à la rotation ; l'objet ne renvoie ensuite que secretLast4.

Rotation du secret

Le nouveau secret signe immédiatement dans X-BCash-Signature, tandis que l'ancien co-signe dans X-BCash-Signature-Previous pendant 24 heures. Si votre vérification accepte les deux en-têtes, la rotation ne fait perdre aucune livraison. La date de fin de chevauchement est lisible dans previousSecretValidUntil.

Filtrer les événements

Le champ events vide signifie « tous ». Restreindre est plus sain : votre endpoint ne reçoit que ce qu'il sait traiter, et les événements ajoutés plus tard ne le surprennent pas.

Livraison, reprise, doublons

Journal et relivraison

La console conserve chaque tentative : code HTTP, délai de réponse, corps renvoyé. Une livraison peut être rejouée manuellement.

Politique de référence

Les paramètres exacts (nombre de tentatives, intervalles, fenêtre de tolérance) sont publiés par l'API : GET /api/v1/meta → webhookDelivery. Lisez-les plutôt que de les supposer ; ils peuvent être ajustés sans changement de version majeure.

Sandbox

Le même code, les mêmes réponses, les mêmes webhooks — sans un franc en jeu.

Cette route force l'issue d'une transaction non terminale, en empruntant le chemin nominal : écritures comptables, webhooks signés, trace d'audit. Ce n'est pas une simulation de façade — c'est la vraie mécanique, déclenchée à la main.

{ "target": "SUCCEEDED" }   // ou "FAILED", "EXPIRED"

Appelée avec un credential de production, elle répond 403. La liste à jour des scénarios est publiée dans GET /api/v1/meta → sandbox.

Scénarios de test

Ce qu'il faut avoir essayé avant de demander l'accès production. Le chemin heureux ne prouve presque rien.

Passer en production

1. Complétez votre dossier dans la console : profil légal, pièces justificatives, numéro Mobile Money de règlement, téléphone vérifié.
2. Soumettez-le. Seul le propriétaire du compte peut le faire : c'est un acte qui engage l'organisation.
3. Répondez aux demandes de l'équipe conformité, le cas échéant. Le motif exact est affiché dans la console.
4. Après approbation, créez une clé de production depuis votre projet.
5. Basculez vos variables d'environnement et vérifiez avec un petit montant réel.

Vue d'ensemble

Une seule console pour les marchands, les développeurs, le support et l'administration : le menu et les droits diffèrent, pas l'application.

La console s'authentifie en JWT de session et consomme les routes /api/dashboard/*. Elle n'utilise jamais la signature HMAC : celle-ci reste réservée aux échanges de serveur à serveur.

Organisations & activation

Une organisation est l'entité qui encaisse. Son statut détermine ce qui est permis.

Suivre sa progression par l'API

{
  "organizationStatus": "READY_TO_SUBMIT",
  "completionPercent": 83,
  "steps": [
    { "code": "EMAIL_VERIFIED",       "status": "DONE" },
    { "code": "SANDBOX_PROJECT",      "status": "DONE" },
    { "code": "FIRST_SANDBOX_TX",     "status": "DONE" },
    { "code": "ORGANIZATION_PROFILE", "status": "DONE" },
    { "code": "PHONE_VERIFIED",       "status": "DONE" },
    { "code": "APPLICATION_FILE",     "status": "IN_PROGRESS" }
  ],
  "nextAction": "SUBMIT_APPLICATION_FILE",
  "statusReason": null
}

Pièces demandées

La liste dépend de votre forme juridique et s'affiche dans votre dossier. Le socle commun : pièce d'identité du représentant (recto et verso) et preuve de titularité du numéro Mobile Money de règlement. Les sociétés y ajoutent l'extrait RCCM et l'attestation NIU.

• Formats acceptés : PDF, JPEG, PNG — 10 Mo maximum par pièce.
• Chaque fichier est analysé avant d'être visible par la conformité.
• Un nouveau fichier s'ajoute comme nouvelle version : rien n'est écrasé, et une décision passée reste rattachée au dossier exact qui a été examiné.

Rôles & équipe

Un utilisateur peut appartenir à plusieurs organisations, avec un rôle différent dans chacune.

• Il y a exactement un propriétaire par organisation. Le retirer est impossible : il faut d'abord transférer la propriété, opération confirmée par un code à usage unique.
• Une invitation est valable 7 jours, à usage unique, et ne révèle à l'invité que le nom de l'organisation et le rôle proposé — rien d'autre avant acceptation.
• Le compte créé depuis une invitation est verrouillé sur l'adresse invitée : un lien transféré ne permet pas de rejoindre sous une autre identité.

Changer d'organisation

La bascule émet un nouveau jeton dont le périmètre est l'organisation choisie. Un jeton porte un seul périmètre : il n'existe pas d'en-tête permettant de viser une autre organisation au fil des requêtes.

Projets & credentials

Un projet représente une intégration : une boutique, une application, un backend.

• Chaque projet porte un type (WooCommerce, Flutter, API directe, lien de paiement), un domaine ou bundle ID, et ses credentials.
• Un même projet peut détenir une clé sandbox et une clé de production : l'environnement est porté par le credential.
• Les endpoints de notification se rattachent au projet, ce qui permet d'isoler les intégrations : une panne de webhook sur la boutique n'affecte pas l'application mobile.
• Séparez vos projets par intégration réelle. Partager une clé entre une boutique et une application rend toute rotation risquée et tout incident illisible.

API de la console

Les mêmes données que l'interface, si vous souhaitez construire vos propres tableaux de bord.

Exécution des opérations

Ce que devient une transaction entre votre appel d'API et le compte Mobile Money de votre client.

Une fois la transaction enregistrée, B-Cash la confie à sa couche d'orchestration. C'est elle qui relaie l'opération vers l'opérateur concerné, en suit l'issue et la reporte dans le registre. Votre intégration n'a rien à en connaître : elle observe des statuts, pas des mécanismes.

Ce que cela change pour vous

• Le délai n'est pas instantané. Une opération traverse un système externe : quelques secondes en temps normal, davantage lorsqu'un opérateur est chargé. Concevez vos écrans autour d'une attente, jamais autour d'une réponse immédiate.
• La disponibilité varie par opérateur. C'est le sens du champ d'état renvoyé par GET /v1/operators : lisez-le plutôt que de supposer que tout est toujours joignable.
• Une issue peut rester non confirmée. C'est le cas traité ci-dessous, et le seul qui demande un comportement particulier de votre part.

Quand l'issue n'est pas confirmée

Il arrive qu'une opération ne puisse pas être conclue immédiatement : l'opérateur ne répond pas de manière exploitable, ou la confirmation n'arrive pas dans la fenêtre attendue. La transaction passe alors en PENDING_RECONCILIATION et les fonds concernés restent réservés, le temps que le rapprochement tranche.

Le dénouement est automatique : la transaction rejoint un statut terminal et l'événement correspondant vous est livré. Aucune action ne vous est demandée — et c'est précisément le point important.

WooCommerce

Le chemin le plus court : votre boutique encaisse sans que vous écriviez de code.

1. Créez un projet de type WooCommerce dans la console et notez sa clé publique et son secret sandbox.
2. Installez l'extension B-Cash dans WooCommerce, puis renseignez la clé, le secret et l'environnement.
3. Copiez l'URL de notification affichée par l'extension et enregistrez-la comme endpoint dans la console, rattachée à ce projet.
4. Passez une commande de test et forcez l'issue depuis le sandbox : la commande doit passer en « payée » toute seule.
5. Après approbation de votre dossier, remplacez les clés par celles de production.

Le context transmis par l'extension vaut WOOCOMMERCE et le numéro de commande est envoyé dans merchantReference : vous retrouvez ainsi n'importe quelle transaction depuis votre back-office WooCommerce.

Applications mobiles

Le schéma est simple, à condition de ne jamais inverser les rôles : c'est votre backend qui détient le secret, jamais l'application.

App mobile          Votre backend             API B-Cash
    │                     │                        │
    │  « je veux payer »  │                        │
    │────────────────────>│                        │
    │                     │  POST /v1/auth/token   │   (signé HMAC)
    │                     │───────────────────────>│
    │                     │<── bt_… (TTL 600 s) ───│
    │<── jeton éphémère ──│                        │
    │                                              │
    │  POST /v1/collections  (Bearer bt_…)         │
    │─────────────────────────────────────────────>│
    │<── nextAction : AWAIT_MOBILE_CONFIRMATION ───│
    │                                              │
    │  Écran d'attente jusqu'à expiresAt           │
    │                     │<── webhook signé ──────│
    │<── votre push /     │                        │
    │    votre polling ───│                        │

Règles côté application

• Demandez un jeton avec le strict minimum de scopes, juste avant le paiement.
• Affichez nextAction.displayMessage plutôt qu'un texte figé : il est adapté à l'opérateur choisi.
• Gérez expiresAt : compte à rebours visible, et surtout aucune conclusion avant cette échéance.
• N'affichez jamais « paiement réussi » sur la seule foi d'un retour d'écran. Attendez le statut renvoyé par votre backend, lui-même notifié par webhook.
• Un jeton expiré n'est pas une erreur de paiement : redemandez-en un et poursuivez.

Backend sur mesure

Intégration directe : vous contrôlez tout, vous portez donc tout.

Liste de contrôle avant production

Machine à états minimale côté commande

async function handleEvent(event) {
  // 1. Déduplication : la contrainte d'unicité fait le travail
  if (await events.exists(event.id)) return;
  await events.insert(event.id);

  const tx = event.data.object;
  const order = await orders.findByReference(tx.merchantReference);
  if (!order) return;                       // événement d'un autre système

  // 2. On se fie au STATUT porté par l'objet, jamais à l'ordre d'arrivée
  switch (tx.status) {
    case 'SUCCEEDED':               return order.markPaid(tx);
    case 'FAILED':
    case 'EXPIRED':                 return order.markUnpaid(tx);
    case 'REVERSED':                return order.markRefunded(tx);
    case 'PENDING_RECONCILIATION':  return order.markUnderReview(tx);   // on attend
    default:                        return;                            // état transitoire
  }
}

Statuts & types

Statuts de transaction

CREATED, FEE_QUOTED, HELD, QUEUED, PROCESSING, PENDING_CONFIRMATION, SUCCEEDED, FAILED, CANCELLED, REVERSED, EXPIRED, PENDING_RECONCILIATION. Détail en Cycle de vie.

Types de transaction

Événements

La liste exhaustive et à jour est publiée dans GET /api/v1/meta. Un événement inconnu doit être ignoré sans erreur : de nouveaux types peuvent apparaître en 1.x.

Scopes

Un jeton éphémère ne peut porter qu'un sous-ensemble strict des scopes de la clé qui l'a émis. Accordez à chaque credential le minimum nécessaire : une clé de boutique n'a aucune raison de pouvoir décaisser.

Versionnement

L'API est en version 1.3. En 1.x, ces garanties tiennent :

• Aucun champ existant n'est supprimé ni renommé.
• Aucune valeur d'énumération n'est retirée ; de nouvelles peuvent apparaître.
• De nouveaux champs facultatifs peuvent être ajoutés à tout moment.
• Un champ déprécié reste accepté, mais cesse d'avoir un effet : c'est le cas de callbackUrl, ignoré au profit des endpoints enregistrés.

Conséquence pratique : votre désérialisation doit être tolérante. Un client qui plante sur un champ inconnu cassera à la prochaine évolution mineure.

Le champ apiVersion des webhooks (ex. 2026-07-20) date le format de l'enveloppe ; conservez-le dans vos journaux, il explique les différences entre deux événements anciens et récents.

État & support

/v1/meta mérite d'être lu au moins une fois : il publie les énumérations, la liste exhaustive des événements, la spécification de signature, les règles d'idempotence et de devis, ainsi que le catalogue des codes d'erreur. Tout ce que cette page décrit y est disponible sous forme exploitable par votre code.

Contacter le support efficacement

Trois éléments suffisent presque toujours à trancher un incident :

1. Le correlationId de la réponse en erreur.
2. La reference de la transaction, ou votre merchantReference.
3. L'horodatage précis et l'environnement concerné.

Écrivez à support@gba-cm.online. N'envoyez jamais un secret ni une capture contenant une clé : si vous pensez qu'un secret a fuité, faites-le tourner d'abord, signalez ensuite.