C CashLink

Documentation développeur

Intégrez les paiements CashLink avec confiance.

Créez et suivez des demandes de paiement, recevez leur résultat par webhook, puis administrez vos applications depuis la Console CashLink.

REST / JSONJWT · 60 secondesWebhooks HMACAPI v1

Commencer

Cette page est servie par votre instance CashLink. La même adresse constitue la base de l’API.

BASE URL https://api.paymebusiness.com
Production : l’API publique est disponible sur https://api.paymebusiness.com. La Console est accessible sur console.paymebusiness.com.
SurfacePréfixeUsage
API marchand/api/v1Intégration de paiement côté serveur.
Administration/admin/v1Utilisateurs, marchands, opérations et configuration.
Espace marchand/merchant/v1Applications, secrets, webhooks, transactions et comptes DAP.
État du service/upPoint de contrôle de disponibilité.

Authentification

Une application fournit un secret et une private_api_key. Conservez-les exclusivement sur votre serveur : ne les exposez jamais dans une application mobile ou un navigateur.

Compatibilité : le préfixe historique /v1 est maintenu pour les intégrations existantes. Toute nouvelle intégration doit utiliser /api/v1.
POST
/api/v1/auth

Émet un jeton d’accès. Sa durée de vie est de 60 secondes ; vous pouvez le mettre en cache jusqu’à son expiration ou en demander un avant chaque appel.

GET
/api/v1/me

Vérifie le jeton et retourne le contexte de l’application authentifiée.

const response = await fetch('https://api.paymebusiness.com/api/v1/auth', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    secret: process.env.PAYME_SECRET,
    private_api_key: process.env.PAYME_PRIVATE_API_KEY
  })
});

const { access_token, expires_at } = await response.json();
import os, requests

response = requests.post('https://api.paymebusiness.com/api/v1/auth', json={
    'secret': os.environ['PAYME_SECRET'],
    'private_api_key': os.environ['PAYME_PRIVATE_API_KEY'],
})
response.raise_for_status()
token = response.json()['access_token']
var client = java.net.http.HttpClient.newHttpClient();
var body = "{\\\"secret\\\":\\\"" + System.getenv("PAYME_SECRET")
    + "\\\",\\\"private_api_key\\\":\\\"" + System.getenv("PAYME_PRIVATE_API_KEY") + "\\\"}";
var request = java.net.http.HttpRequest.newBuilder()
    .uri(java.net.URI.create("https://api.paymebusiness.com/api/v1/auth"))
    .header("Content-Type", "application/json")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofString(body)).build();
var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());

Pour les routes protégées, transmettez le jeton avec Authorization: Bearer <access_token>.

{
  "access_token": "eyJ…",
  "token_type": "Bearer",
  "expires_in": 60,
  "expires_at": "2026-09-24T10:16:30+00:00"
}
{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Les identifiants fournis sont invalides."
  }
}

Formats de requête et de réponse

Toutes les requêtes utilisent Content-Type: application/json et les dates sont des chaînes ISO-8601 UTC. Les réponses JSON ne sont pas enveloppées dans un champ data, sauf les listes paginées.

Succès

CasHTTPCorps
Lecture ou transition200La ressource directement.
Création201La ressource créée.
Liste200data et pagination.
Suppression / enregistrement du FCM token204Corps vide.
{
  "id": "pay_01J...",
  "reference": "PM-202609-000001",
  "external_reference": "ORDER-2026-0042",
  "status": "PAYMENT_PENDING",
  "amount": 15000,
  "currency": "XAF",
  "recipient": { "name": "Jean Dupont", "phone_number": "+237690000000" },
  "created_at": "2026-09-24T10:15:30+00:00",
  "updated_at": "2026-09-24T10:15:30+00:00"
}
{
  "data": [{ "id": "pay_01J...", "status": "PAYMENT_PENDING", "amount": 15000, "currency": "XAF" }],
  "pagination": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
}

Erreur

Le format d’erreur métier est stable sur toutes les surfaces. field est présent lorsqu’un champ précis est concerné ; details.errors peut contenir l’ensemble des erreurs de validation.

{
  "error": {
    "code": "AMOUNT_ABOVE_MAXIMUM",
    "message": "Le montant maximum est de 5000000 XAF.",
    "field": "amount",
    "details": {
      "amount": 6000000,
      "maximum": 5000000,
      "currency": "XAF"
    }
  }
}

Ne déduisez jamais le résultat d’un paiement depuis le code HTTP de création : une demande acceptée est d’abord PAYMENT_PENDING. Attendez son statut final ou le webhook.

Paiements

Une demande de paiement est créée par le marchand, puis traitée manuellement par les équipes CashLink. Votre intégration suit son état sans dépendre du mode de traitement.

POST
/api/v1/payments

Crée une demande. Envoyez un en-tête Idempotency-Key unique pour éviter les doublons lors d’une reprise réseau.

GET
/api/v1/payments

Liste paginée. Filtres disponibles : from, to, per-page, page, status et reference.

GET
/api/v1/payments/{paymentId}

Retourne les détails et la chronologie de la transaction.

POST
/api/v1/payments/{paymentId}/cancel

Annule une demande tant qu’elle n’est pas prise en charge.

OpérationRequêteSuccèsErreurs usuelles
Créerexternal_reference, amount, currency, recipient.phone_number, recipient.name (facultatif en Mobile Money ; obligatoire pour un paiement manuel) et l’en-tête Idempotency-Key. Sans nom : on reprend celui de votre dernière transaction vers ce numéro, sinon on génère « {votre nom}-{code} », le même code pour le même numéro. Le nom d’un autre partenaire n’est jamais repris.201 · demande PAYMENT_PENDING — ou directement PAYMENT_FAILED avec failure_code: "PARTNER_BALANCE_INSUFFICIENT" si le solde de votre compte d’opération ne couvre pas le montant et les frais (rien n’est débité, le webhook d’échec part).400 champ invalide, 409 DUPLICATE_EXTERNAL_REFERENCE ou conflit d’idempotence, 422 AMOUNT_ABOVE_MAXIMUM. Bénéficiaire Orange Money : montant multiple de 5 obligatoire, sinon 400 INVALID_AMOUNT sur amount. Le montant doit aussi être un multiple de la valeur réglée pour le mode de paiement (100 par défaut, Mobile Money comme manuel), sinon 400 INVALID_AMOUNT.
ListerQuery : from, to, status, reference, page, per_page.200 · liste paginée.400 INVALID_REQUEST si un filtre est mal formé.
ConsulterParamètre d’URL paymentId.200 · demande complète. Si votre compte est réglé pour arrondir les montants au multiple imposé, amount est le montant arrondi (celui qui est payé) et amount_adjustment donne requested_amount (montant envoyé), rounded_amount, multiple, rounding (UP / DOWN) et changed ; sinon amount_adjustment vaut null.404 PAYMENT_NOT_FOUND.
AnnulerCorps facultatif : reason.200 · PAYMENT_CANCELLED.409 PAYMENT_NOT_CANCELLABLE dès que la demande est en traitement ou finale.

Cycle de vie

PAYMENT_PENDING PAYMENT_PROCESSING PAYMENT_TREATED PAYMENT_SUCCEEDED ou PAYMENT_FAILED. L’annulation n’est possible que tant que le paiement n’est pas en PAYMENT_PROCESSING.

PAYMENT_TREATED (non final) : l’agent a réglé le bénéficiaire, CashLink attend la confirmation de l’opérateur. Le paiement passe PAYMENT_SUCCEEDED dès qu’elle arrive (quelques secondes en général) : c’est seulement à ce moment que le webhook payment.completed est envoyé. Un paiement traité peut encore finir PAYMENT_FAILED si le règlement n’est pas confirmé.

Paiement manuel (retrait au guichet)

À la création, payment_mode: "MANUAL" (défaut MOBILE_MONEY) avec la pièce d’identité du bénéficiaire, obligatoire : recipient.identity_document = type (NATIONAL_ID_CARD, PASSPORT, RESIDENCE_PERMIT, DRIVING_LICENSE) et number. Le paiement n’est confié à aucun agent : CashLink envoie au bénéficiaire, par SMS, un code de retrait de 10 caractères (ex. K7M4-QX9P-2R), valable 48 h et utilisable une seule fois. Il se présente chez un agent Mamoni avec ce code et sa pièce ; l’agent contrôle le nom, le type et le numéro de la pièce, puis paie : PAYMENT_PENDING → PAYMENT_PROCESSING → PAYMENT_SUCCEEDED et le webhook payment.completed part aussitôt. Le code n’apparaît jamais dans l’API, la console ni les journaux (seule son empreinte, calculée avec une clé secrète du serveur, est conservée). Pas de règle Orange « multiple de 5 » pour un paiement manuel (le multiple réglé pour le mode manuel s’applique). Les réponses et le webhook portent payment_mode. Code perdu ou expiré : nouveau code depuis l’espace client (POST /merchant/v1/payments/{paymentId}/withdrawal-code/resend), l’ancien est révoqué ; un paiement annulé révoque son code.

const payment = await fetch('https://api.paymebusiness.com/api/v1/payments', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer VOTRE_JETON_ACCES',
    'Idempotency-Key': crypto.randomUUID()
  },
  body: JSON.stringify({
    external_reference: 'ORDER-2026-0042',
    amount: 15000,
    currency: 'XAF',
    recipient: { name: 'Jean Dupont', phone_number: '+237690000000' }
  })
});
const result = await payment.json();
from uuid import uuid4
import requests

response = requests.post('https://api.paymebusiness.com/api/v1/payments', headers={
    'Authorization': 'Bearer VOTRE_JETON_ACCES',
    'Idempotency-Key': str(uuid4()),
}, json={
    'external_reference': 'ORDER-2026-0042',
    'amount': 15000,
    'currency': 'XAF',
    'recipient': {'name': 'Jean Dupont', 'phone_number': '+237690000000'},
})
response.raise_for_status()
var request = java.net.http.HttpRequest.newBuilder()
    .uri(java.net.URI.create("https://api.paymebusiness.com/api/v1/payments"))
    .header("Authorization", "Bearer VOTRE_JETON_ACCES")
    .header("Idempotency-Key", java.util.UUID.randomUUID().toString())
    .header("Content-Type", "application/json")
    .POST(java.net.http.HttpRequest.BodyPublishers.ofString("""
      {"external_reference":"ORDER-2026-0042","amount":15000,"currency":"XAF","recipient":{"name":"Jean Dupont","phone_number":"+237690000000"}}
    """)).build();
var response = client.send(request, java.net.http.HttpResponse.BodyHandlers.ofString());

Réponse de création

{
  "id": "pay_01J...",
  "reference": "PM-202609-000001",
  "external_reference": "ORDER-2026-0042",
  "status": "PAYMENT_PENDING",
  "amount": 15000,
  "currency": "XAF",
  "recipient": { "name": "Jean Dupont", "phone_number": "+237690000000" },
  "created_at": "2026-09-24T10:15:30+00:00",
  "updated_at": "2026-09-24T10:15:30+00:00"
}
{
  "error": {
    "code": "DUPLICATE_EXTERNAL_REFERENCE",
    "message": "Une transaction existe déjà pour cette référence externe.",
    "field": "external_reference"
  }
}

API des agents de règlement

Un agent ne s’inscrit pas et n’utilise pas la Console. Un administrateur crée son profil (coordonnées, compte flotte facultatif et PIN initial 12345 communiqué par un canal externe). Ses identifiants sont un téléphone E.164 ou un compte flotte 807…, plus un PIN à cinq chiffres. La réponse de connexion et le profil exposent tous deux pin_must_be_changed : un client doit checker ce champ pour savoir s’il doit forcer un changement de PIN avant de laisser l’agent traiter quoi que ce soit.

POST
/agent/login-pin

Connexion agent avec login (téléphone ou compte flotte) et pin. Le FCM token ne fait pas partie de cette requête.

GET
/agent/check/{phone-ou-compte}

Sonde partenaire : retourne uniquement l’existence d’un agent — true actif, false inconnu, null (réponse vide) si son compte est suspendu. Exige l’en-tête secret X-APP-CHECK-REQUEST (valeur = variable d’environnement PAYME_AGENT_CHECK_REQUEST_KEY).

POST
/agent/pin/forgot

PIN oublié, étape 1 : envoie un code à 6 chiffres par SMS au téléphone du profil. Réponse identique que le compte existe ou non.

POST
/agent/pin/reset

PIN oublié, étape 2 : vérifie le code (10 minutes, 5 tentatives) et pose le nouveau PIN. Révoque toutes les sessions de l’agent.

GET
/agent/v1/me

Profil de l’agent authentifié — même forme que le bloc agent de la connexion.

PUT
/agent/v1/pin

Remplace obligatoirement le PIN initial avant toute action de traitement.

PUT
/agent/v1/device

Enregistre ou renouvelle le fcm_token après connexion ; il est facultatif, mais conditionne la notification push (voir plus bas).

GET
/agent/v1/payments

Liste exclusivement les transactions déjà affectées à cet agent (affectations ouvertes seulement) : PAYMENT_PENDING (proposées) et PAYMENT_PROCESSING (acceptées). Une transaction traitée (PAYMENT_TREATED, en attente du SMS de l’opérateur) n’y figure plus : l’agent en a fini, elle passe dans ses transactions traitées.

GET
/agent/v1/payments/get-traited-payment

Liste les transactions que cet agent a menées à leur terme (PAYMENT_TREATED puis PAYMENT_SUCCEEDED, ou PAYMENT_FAILED) — un abandon ne compte pas comme « traitée ». Une transaction traitée y apparaît dès le succeed, avant l’arrivée du SMS, avec le statut PAYMENT_TREATED, puis PAYMENT_SUCCEEDED une fois le SMS rapproché. Chaque ligne porte has_sms (SMS de l’opérateur rapproché) et has_proof (règlement prouvé : SMS, preuve apportée par un administrateur — référence ou capture — ou code de retrait d’un paiement manuel réussi), et sms : le SMS rapproché (reference, operator, amount, transacted_at, sender, body avec le solde masqué, received_at), null sans SMS.

POST
/agent/v1/withdrawal-codes/lookup

Paiement manuel : {"code"} (casse, espaces et tirets indifférents) → payment (montant, recipient.name, recipient.identity_document type, libellé et numéro), code_expires_at, pin_required. Ne change rien : l’agent contrôle la personne en face de lui. 404 WITHDRAWAL_CODE_INVALID si le code est inconnu, expiré, utilisé ou si le paiement n’est plus en attente (jamais distingués). 403 si le paiement n’est pas de l’environnement de l’agent : seuls les agents de test paient les paiements de test, et jamais ceux de production.

POST
/agent/v1/withdrawal-codes/settle

Pièce contrôlée, l’agent paie : {"code", "pin"} (PIN si pin_required). Le paiement passe PAYMENT_SUCCEEDED d’un geste (webhook, virement, commission de l’agent), le code est consommé. 403 PIN invalide ou paiement d’un autre environnement que celui de l’agent, 404 WITHDRAWAL_CODE_INVALID. Codes erronés limités par agent (10 par 15 min par défaut) : au-delà, 429 avec Retry-After.

GET
/agent/v1/payments/{paymentId}

Détail d’une transaction affectée à l’agent (403 sinon).

GET
/agent/v1/payments/{paymentId}/events

Historique paginé des transitions de la transaction affectée.

POST
/agent/v1/payments/{paymentId}/accept

Acceptation en deux temps. L’agent accepte l’affectation avec le PIN : PAYMENT_PENDING → PAYMENT_ACCEPTED (l’heure de prise en charge est celle de l’acceptation). Il clique ensuite sur payer : …/process (PAYMENT_ACCEPTED → PAYMENT_PROCESSING). Une transaction acceptée compte comme détenue (une seule à la fois, 409 AGENT_PAYMENT_IN_PROGRESS), reste dans la file de l’agent (GET /agent/v1/payments?status=PAYMENT_ACCEPTED) et peut être relâchée (…/release, même privilège). Réglage de distribution « acceptation obligatoire » (Paramètres › Distribution, PUT /admin/v1/settings/dispatch {"acceptance_required": true}, désactivé par défaut) : activé, …/process depuis PAYMENT_PENDING est refusé par 409 PAYMENT_ACCEPTANCE_REQUIRED ; désactivé, process directement depuis PAYMENT_PENDING fonctionne comme avant. Les administrateurs gardent la prise en charge directe. PAYMENT_ACCEPTED est un statut interne : l’API marchand et l’espace marchand la présentent comme PAYMENT_PROCESSING.

POST
/agent/v1/payments/{paymentId}/process

Prend en charge une affectation avec le PIN : PAYMENT_PENDING → PAYMENT_PROCESSING. Horloge de l’app : la file, le détail, la push et la réponse de process portent assigned_at (heure d’affectation à cet agent), server_time (heure du serveur à l’émission) et assignment_ttl_seconds ; vrai temps restant d’une proposition = assigned_at + assignment_ttl_seconds − (heure locale + (server_time − heure locale à la réception)). Une transaction affichée en retard (réseau, appareil lent) peut ainsi être retirée sans attendre le prochain rafraîchissement.

POST
/agent/v1/payments/{paymentId}/succeed

Après le règlement manuel, confirme le règlement avec le PIN : PAYMENT_PROCESSING → PAYMENT_TREATED (réussi quand le SMS de l’opérateur est rapproché) ; référence opérateur facultative. L'opérateur n'est plus un champ de la requête : détecté automatiquement (voir mobile_operator plus bas).

POST
/agent/v1/payments/{paymentId}/fail

Réservé aux agents qui en ont le privilège (fiche agent can_fail_payments, refusé par défaut) ; sinon 403 INSUFFICIENT_PERMISSIONS, sur cette route comme sur /admin/v1/payments/{paymentId}/fail. failure_code normalisé obligatoire. Même règle pour …/release (remise en file) avec can_release_payments, autorisé par défaut : le retirer évite qu’un agent paie puis relâche la transaction (double paiement). GET /agent/v1/me renvoie les deux privilèges pour masquer les actions refusées. Fiche agent can_receive_while_treated (oui par défaut) : à false, l’agent ne reçoit ni n’accepte (409 AGENT_PAYMENT_IN_PROGRESS sur …/process) une autre transaction tant qu’une des siennes est PAYMENT_TREATED ; actions groupées treated_allow / treated_deny.

POST
/agent/v1/payments/{paymentId}/release

Libère une transaction déjà acceptée (problème de l’agent) : PAYMENT_PROCESSING → PAYMENT_PENDING, elle repart aussitôt vers un autre agent. reason facultatif, PIN exigé si la transaction a required_pin. 403 PAYMENT_NOT_ASSIGNED si elle ne lui est plus affectée.

PUT
/agent/v1/availability

En ligne / hors ligne : {"online": false}. Hors ligne, l’agent ne reçoit plus aucune demande et ses propositions non acceptées repartent aussitôt (reassigned_count) ; une transaction déjà acceptée reste la sienne. De retour en ligne, les demandes en attente lui sont redistribuées. GET sur la même route renvoie l’état : is_online, pin_must_be_changed, can_receive_payments (aussi dans /agent/v1/me). Un agent qui n’a pas remplacé son PIN initial ne reçoit aucune demande.

PUT
/agent/v1/sms-permission

État de la permission SMS du téléphone, à envoyer à chaque arrivée sur l’écran des mandats : {"status": "active"} ou "inactive". Le back-office peut exiger la lecture des SMS pour un agent (sms_permission_required, faux par défaut) : tant que l’état est inactive, l’agent ne reçoit aucune demande et ses propositions non acceptées repartent (reassigned_count) ; active lui redistribue les demandes en attente. GET sur la même route (et /agent/v1/availability, /agent/v1/me) renvoie sms_permission_required, sms_permission_status, sms_permission_checked_at et can_receive_payments. L’app n’affiche le bouton d’activation que si la lecture est exigée et l’état inactive.

POST
/agent/v1/sms

SMS Orange Money / MTN MoMo lus sur le téléphone, par lots (200 max) : messages[] = local_id, sender (OrangeMoney, MobileMoney), body, received_at (ms epoch), sent_at et line_msisdn facultatifs ; device_name facultatif. Réponse : results[] (accepted, duplicate, rejected) et accepted. Idempotent (un SMS purgé en console répond aussi duplicate : l’app peut renvoyer tout l’historique) ; traitement différé (7 s) : la référence de l’opérateur devient la Réf. opérateur du paiement réglé — rapprochement automatique avec un paiement traité (ou réussi avant régularisation) et sans preuve seulement ; rapproché, un paiement traité passe PAYMENT_SUCCEEDED (webhook au marchand, virement bancaire).

POST
/agent/v1/payments/{paymentId}/refuse

Décline une affectation pas encore prise en charge (aucun PIN requis) : elle repart aussitôt vers un autre agent actif, en excluant celui qui a refusé. Le paiement reste PAYMENT_PENDING — seule l’affectation change. Si tous les agents actifs ont déjà refusé, la demande revient vers l’un d’eux plutôt que de rester bloquée. Refus impossible s’il ne reste aucun autre agent actif (un seul agent actif, ou tous les autres suspendus) : une transaction doit toujours rester chez un agent — 403 FORBIDDEN dans ce cas.

OpérationEntréeSuccèsErreurs
Connexion PINlogin = téléphone E.164 ou compte 807… ; pin = 5 chiffres ; device_name facultatif.200 · access_token, token_type, expires_at, profil agent.422 champs manquants/mal formés ; 401 INVALID_CREDENTIALS identifiant ou PIN invalide ; 403 ACCOUNT_SUSPENDED compte suspendu.
Contrôler un agentGET /agent/check/{identifier}, avec X-APP-CHECK-REQUEST: <clé-commune>. Encodez + d’un téléphone en %2B.200 · uniquement {"data":true} (agent actif), {"data":false} (inconnu) ou {"data":null} (compte suspendu : réponse vide).401 INVALID_CREDENTIALS si la clé est absente, invalide ou non configurée.
PIN oublié · demandelogin = téléphone ou compte flotte.200 · message générique, code envoyé par SMS si le compte existe.422 si login absent. Jamais d’erreur liée à l’existence du compte (anti-énumération) ; 429 au-delà du quota.
PIN oublié · vérificationlogin, code (6 chiffres reçus par SMS), pin + pin_confirmation (5 chiffres, nouveau PIN).200 · message de confirmation, PIN changé, sessions révoquées.401 INVALID_OTP code faux, expiré (10 min), tentatives épuisées (5) ou identifiant inconnu ; 422 champs mal formés ; 429 au-delà du quota.
ProfilAucune (jeton agent).200 · même forme que le bloc agent de la connexion, avec is_online et can_receive_payments (faux hors ligne ou tant que le PIN initial n’est pas remplacé).401 jeton absent/expiré/révoqué.
Changer PINcurrent_pin, pin, pin_confirmation (5 chiffres).200 · profil avec pin_must_be_changed: false.403 FORBIDDEN si PIN actuel incorrect.
Enregistrer appareilfcm_token (20-255 car.), device_name facultatif.204 · aucun corps.422 token absent ou trop court/long.
Voir la fileQuery optionnelle : status, page, per_page (max 100).200 · data[] (résumé, avec recipient et mobile_operator) + pagination, seulement les demandes affectées à l’agent.401 jeton absent/expiré.
Détail / historiqueAucune (route). events accepte page, per_page.200 · transaction complète (avec mobile_operator et ussd_code), ou liste paginée des transitions.403 FORBIDDEN si la transaction n’est pas affectée à l’agent.
Prendre en chargepin (5 chiffres), reason facultatif.200 · PAYMENT_PROCESSING.403 PAYMENT_NOT_ASSIGNED proposition expirée ou passée à un autre agent (vérifié avant le PIN) ; 403 FORBIDDEN PIN invalide, seulement si required_pin est vrai ; 422 UNPROCESSABLE_REQUEST PIN initial non changé ; 409 INVALID_STATUS_TRANSITION.
Réussitepin requis ; provider_reference facultative. Plus de champ provider : opérateur déduit du numéro du bénéficiaire.200 · PAYMENT_TREATED : réussi (PAYMENT_SUCCEEDED) quand le SMS de l’opérateur est rapproché. L’agent est libéré dès ce statut.403 PAYMENT_NOT_ASSIGNED plus affectée, 403 FORBIDDEN PIN invalide (si required_pin) ; 409 statut incompatible.
Échecpin requis ; failure_code requis (INSUFFICIENT_FUNDS, RECIPIENT_UNREACHABLE, INVALID_RECIPIENT, RECIPIENT_ACCOUNT_LIMIT, OPERATOR_ERROR, OPERATOR_UNAVAILABLE, DUPLICATE_PAYMENT, REJECTED_BY_AGENT, EXPIRED, OTHER) ; reason facultatif. Plus de champ provider : opérateur déduit du numéro du bénéficiaire.200 · PAYMENT_FAILED.400 si failure_code absent ou hors liste ; 403 PIN ou affectation ; 409 statut incompatible.
Transactions traitéesQuery optionnelle : status, page, per_page (max 100).200 · data[] (résumé) + pagination, uniquement les demandes menées à leur terme par l’agent.401 jeton absent/expiré.
LibérerPOST /agent/v1/payments/{paymentId}/release : reason facultatif, pin si required_pin.200 · PAYMENT_PENDING, demande redistribuée à un autre agent.403 PAYMENT_NOT_ASSIGNED plus affectée, 403 FORBIDDEN PIN invalide, 409 pas en traitement.
DisponibilitéGET / PUT /agent/v1/availability : {"online": true|false}.200 · is_online, pin_must_be_changed, can_receive_payments, reassigned_count (PUT).400 INVALID_REQUEST online absent ou non booléen.
RefuserAucune (route). Pas de PIN.200 · transaction toujours PAYMENT_PENDING, réaffectée à un autre agent.403 FORBIDDEN si non affectée à l’agent, déjà prise en charge, ou si aucun autre agent actif n’est disponible.
  1. Se connecter. L’administrateur crée l’agent et lui communique son PIN initial hors plateforme. L’agent remplace ce PIN dès sa première connexion — ou utilise /agent/pin/forgot puis /agent/pin/reset s’il l’a perdu.
  2. Prendre en charge avant l’action externe. Passez le paiement en PAYMENT_PROCESSING ; si un autre agent l’a déjà pris ou si le client l’a annulé, l’API retourne un conflit.
  3. Effectuer le paiement manuellement. Réalisez l’opération chez l’opérateur choisi et récupérez sa référence.
  4. Rendre compte. Appelez succeed ou fail. CashLink historise l’agent, les dates et la référence. Après succeed, le marchand n’est notifié du succès qu’une fois le SMS de l’opérateur rapproché ; après fail, aussitôt.

Opérateur mobile et code USSD

Chaque transaction retourne mobile_operator ("orange", "mtn" ou null), détecté automatiquement à partir du numéro E.164 du bénéficiaire (indicatif +237 uniquement — un numéro d'un autre pays renvoie null). L'agent n'indique jamais l'opérateur lui-même : un provider éventuellement envoyé serait ignoré. La transaction détaillée (GET /agent/v1/payments/{paymentId}) ajoute ussd_code, le code déjà composé avec le montant et le numéro local (sans l'indicatif) :

OpérateurGabarit USSD
Orange Money#149*1*{montant}*{numéro local}#
MTN MoMo*126*1*{numéro local}*{montant}#

Synchronisation des SMS opérateur (preuve de règlement)

Chaque règlement fait par l’agent (USSD Orange Money ou MTN MoMo) déclenche un SMS de l’opérateur sur le téléphone de service. L’app agent remonte ces SMS à CashLink : le serveur les décrypte (toutes les 7 secondes) et rattache l’opération au paiement correspondant. La référence de l’opérateur devient alors la Réf. opérateur du paiement, et le paiement est marqué « avec preuve opérateur » dans la console.

La réussite exige cette preuve. Confirmé par l’agent, un paiement n’est que PAYMENT_TREATED ; le SMS rapproché le passe PAYMENT_SUCCEEDED, ce qui envoie le webhook de succès au marchand et ouvre le virement bancaire. Un paiement rapproché à la main avant d’être terminé passe réussi au passage suivant, une fois traité par l’agent. Régularisation des anciennes réussites sans preuve : php artisan payme:payments:regularize-unproven [--since=AAAA-MM-JJ] [--dry-run] (repassées PAYMENT_TREATED ; webhook et virement déjà partis ne sont ni défaits ni renvoyés quand leur SMS arrive).

Quand synchroniserQuoi envoyer
À chaque connexion d’un agent sur le téléphone (login-pin réussi)Tous les SMS des expéditeurs OrangeMoney et MobileMoney reçus depuis la dernière synchronisation réussie (à la toute première : les 7 derniers jours), par lots jusqu’à épuisement. Bouton « Resynchroniser » : renvoie toute la semaine, le serveur ignore ce qu’il a déjà (duplicate).
Après chaque succeed ou fail acquitté par le serveurLes nouveaux SMS de ces expéditeurs. Si le SMS de l’opérateur n’est pas encore arrivé, il partira à la synchronisation suivante.
POST
/agent/v1/sms

Jeton agent requis. Lots de 200 SMS au plus : découpez au-delà.

ChampObligatoireDescription
device_namenonNom du téléphone (ex. "Tecno Spark 10"), affiché dans la console.
messages[].local_idouiIdentifiant du SMS dans le téléphone (repris tel quel dans la réponse).
messages[].senderouiExpéditeur tel que lu : OrangeMoney ou MobileMoney. Les autres sont refusés (rejected) : ne les envoyez pas.
messages[].bodyouiTexte complet du SMS, sans modification (5 000 caractères max).
messages[].received_atouiDate de réception Android, en millisecondes epoch.
messages[].sent_atnonDate d’envoi par l’opérateur (ms epoch), si disponible.
messages[].line_msisdnfortement recommandéNuméro de la SIM du téléphone qui a reçu le SMS (ex. 690000801), via le subscriptionId du SMS. Le téléphone de service étant partagé entre agents, CashLink ne le déduit jamais de l’agent connecté. Sans lui, le rapprochement fonctionne quand même, mais le sens de l’opération affiché peut être inexact.
POST /agent/v1/sms
Authorization: Bearer <jeton agent>
{
  "device_name": "Tecno Spark 10",
  "messages": [{
    "local_id": 1842,
    "sender": "OrangeMoney",
    "body": "Transfert de 690000801 AGENT vers 690123456 JEAN MBALLA reussi. Details: ID transaction: PP261009.1102.A11111, Montant Transaction: 5000FCFA, ...",
    "received_at": 1791540120000,
    "line_msisdn": "690000801"
  }]
}
{
  "results": [
    { "local_id": 1842, "status": "accepted" }
  ],
  "accepted": 1
}

// status : "accepted" (nouveau), "duplicate" (déjà reçu : sans effet),
//          "rejected" + "error": "sender_not_allowed" (expéditeur non accepté)
  • Idempotent. Un SMS déjà reçu (même expéditeur, même date, même texte) est ignoré (duplicate) : en cas d’erreur réseau, renvoyez le lot entier sans risque.
  • Mémoriser la dernière synchronisation. Gardez la date du dernier SMS acquitté (accepted ou duplicate) et repartez de là ; une réponse en erreur (réseau, 401) se retente telle quelle.
  • Aucun retour direct sur le paiement. Le décryptage et le rapprochement sont faits par le serveur (toutes les 7 s). Une même référence d’opérateur n’est enregistrée qu’une fois par opérateur.
  • Agent connecté. L’agent qui remonte le SMS est seulement tracé : ce n’est pas un critère de rapprochement (un autre agent a pu faire le règlement sur le même téléphone).
  • Permission Android. Lecture des SMS (READ_SMS) à demander à l’installation ; ne lisez et n’envoyez que les deux expéditeurs ci-dessus.

Notification push (assignation)

Dès qu’une demande est affectée à un agent (émission ou réaffectation après expiration), CashLink tente un push Firebase Cloud Messaging vers chacun de ses appareils enregistrés via PUT /agent/v1/device. L’envoi part après la validation en base de l’affectation, jamais depuis la requête qui l’a créée : un agent ne bloque jamais sur Firebase. Sans FIREBASE_CREDENTIAL configuré ou sans appareil enregistré, l’affectation reste valide et visible via GET /agent/v1/payments — le push n’est jamais le seul canal. Le résultat (PENDING_DEVICE_DELIVERY, SENT, NOT_CONFIGURED, NO_DEVICE, FAILED) est visible côté back-office dans assignments[].notification_status du détail admin d’un paiement, jamais retourné à l’agent lui-même.

data.payment est le paiement complet (même forme que AdminPaymentSummaryResource, cf. section Agents) sérialisé en JSON — FCM n’accepte que des chaînes dans data, un objet imbriqué doit donc être décodé côté app (JSON.parse(data.payment)) plutôt que lu directement.

{
  "notification": {
    "title": "Nouveau transfert de 32 000 XAF à +237655289520",
    "body": "Réglez 32 000 XAF pour roberto (+237655289520)."
  },
  "data": {
    "type": "payment_assigned",
    "notification_type": "PAYMENT_MANDAT",
    "payment_id": "pay_01M3CZH3D7BYT8CP98MYXG7RQF",
    "assignment_id": "pas_01M3D1RJ7VS340HQ3ZXKSDBXYN",
    "payment": "{\"id\":\"pay_01M3CZH3D7BYT8CP98MYXG7RQF\",\"reference\":\"PAY-2026-00000024\",\"external_reference\":\"TEST-M5ITZDOK\",\"status\":\"PAYMENT_PENDING\",\"amount\":32000,\"currency\":\"XAF\",\"recipient\":{\"name\":\"roberto\",\"phone_number\":\"+237655289520\"},\"mobile_operator\":\"orange\",\"merchant_id\":\"mch_01M34GWZJ5DR2RXC4BKXRS21NC\",\"environment\":\"sandbox\",\"processed_by\":null,\"created_at\":\"2026-09-25T19:09:00+00:00\",\"updated_at\":\"2026-09-25T19:09:00+00:00\"}"
  }
}
// 1. Authentification de l'agent interne
const login = await fetch('https://api.paymebusiness.com/agent/login-pin', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    login: '+237690000000', // ou le compte flotte 807…
    pin: process.env.PAYME_AGENT_PIN,
    device_name: 'poste-reglement-01'
  })
});
const { access_token } = await login.json();

const headers = { Authorization: `Bearer ${access_token}`, 'Content-Type': 'application/json' };

// 2. Réserver la demande AVANT de la régler manuellement.
await fetch('https://api.paymebusiness.com/agent/v1/payments/pay_01H.../process', {
  method: 'POST', headers, body: JSON.stringify({ pin: process.env.PAYME_AGENT_PIN, reason: 'Traitement MTN MoMo' })
});

// 3. Composer le code USSD retourné par l'API (mobile_operator/ussd_code),
//    effectuer le paiement, puis conserver la référence fournie par l'opérateur.
await fetch('https://api.paymebusiness.com/agent/v1/payments/pay_01H.../succeed', {
  method: 'POST', headers,
  body: JSON.stringify({ pin: process.env.PAYME_AGENT_PIN, provider_reference: 'MOMO-8492017' })
});

Réponses agent

{
  "access_token": "1|…",
  "token_type": "Bearer",
  "expires_at": "2026-09-24T18:00:00+00:00",
  "agent": {
    "id": "adm_01J…",
    "name": "Agent Exemple",
    "phone": "+237690000000",
    "float_account": { "label": "Compte flotte", "account_number": "8070000000" },
    "pin_must_be_changed": false,
    "status": "active"
  }
}
{ "data": true }

// Si aucun agent ne correspond au téléphone ou au compte flotte :
{ "data": false }

// Si le compte de l’agent est suspendu (réponse vide) :
{ "data": null }
// POST /agent/pin/forgot — toujours la même réponse, compte existant ou non
{ "message": "Si ce compte existe, un code de vérification a été envoyé par SMS." }

// POST /agent/pin/reset — succès
{ "message": "Code PIN réinitialisé. Reconnectez-vous." }
{
  "data": [
    {
      "id": "pay_01M3CX2HV5WT8RAAFEFS242CCP",
      "reference": "PAY-2026-00000023",
      "external_reference": "CMD-2026-000145",
      "status": "PAYMENT_PENDING",
      "amount": 60000,
      "currency": "XAF",
      "recipient": { "name": "Roberto Nkoulou", "phone_number": "+237690123456" },
      "mobile_operator": "orange",
      "merchant_id": "mch_01M34GWZJ5DR2RXC4BKXRS21NC",
      "environment": "sandbox",
      "processed_by": null,
      "created_at": "2026-09-25T18:26:06Z",
      "updated_at": "2026-09-25T18:26:06Z"
    }
  ],
  "pagination": { "page": 1, "per_page": 20, "total": 1, "total_pages": 1 }
}
{
  "id": "pay_01J…",
  "status": "PAYMENT_PROCESSING",
  "settlement": { "processed_by": "adm_01J…", "taken_in_charge_at": "2026-09-24T10:20:00+00:00" },
  "timing": { "time_to_take_in_charge_seconds": 270, "processing_duration_seconds": null, "lifetime_seconds": 270, "ended_at": null }
}
{
  "error": {
    "code": "UNPROCESSABLE_REQUEST",
    "message": "Le code PIN initial doit être remplacé avant tout traitement.",
    "field": "pin"
  }
}
// POST /agent/pin/reset — code faux, expiré, tentatives épuisées ou identifiant inconnu
{
  "error": {
    "code": "INVALID_OTP",
    "message": "Code invalide ou expiré."
  }
}

À l’émission, CashLink choisit aléatoirement un agent actif sans affectation ouverte, en évitant le dernier agent ayant traité une transaction si une alternative existe. Après une minute sans prise en charge, payme:check-sent-transactions archive la proposition expirée et passe à un autre agent. Chaque proposition, échéance, prise en charge et clôture est visible dans le détail admin de la transaction.

Le back-office consulte GET /admin/v1/agents/statistics pour comparer, par agent, le nombre d’affectations, de clôtures et les durées moyennes de prise en charge et de traitement.

Délais suivis

La réponse détaillée d’un paiement contient timing.time_to_take_in_charge_seconds (émission → agent), timing.processing_duration_seconds (prise en charge → issue) et timing.lifetime_seconds (émission → fin, ou jusqu’à maintenant si le paiement est encore actif). Le virement bancaire associé expose aussi timing.lifetime_seconds, de sa création jusqu’à sa confirmation bancaire.

Get destination — titulaire d’un numéro

Service payant, sur abonnement : à partir d’un numéro de téléphone, retrouvez le nom du titulaire du compte associé avant d’envoyer un paiement. Il est désactivé par défaut : CashLink l’ouvre pour votre compte et enregistre votre abonnement (formule du catalogue, ou durée et montant convenus), réglé depuis votre portefeuille ou par un paiement externe (virement…) justifié.

POST
/api/v1/get-destinator

Corps JSON : phone, au format international +237 suivi de 9 chiffres (les espaces sont ignorés). Authentification et quota par application, comme les paiements.

curl -X POST https://api.paymebusiness.com/api/v1/get-destinator \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{ "phone": "+237690444983" }'
{
  "phone": "+237690444983",
  "holder_name": "NGANSO KEMWE STEVE",
  "operator_name": "Orange Money(Cameroon)",
  "sandbox": false
}
{
  "error": {
    "code": "DESTINATION_NOT_FOUND",
    "message": "Aucun compte n'est associé à ce numéro.",
    "field": "phone"
  }
}
{
  "error": {
    "code": "DESTINATION_SUBSCRIPTION_REQUIRED",
    "message": "Aucun abonnement get destination en cours : contactez votre interlocuteur pour le renouveler."
  }
}
RègleDétail
AccèsLe service doit être ouvert pour votre compte et un abonnement doit être en cours. Fermer le service ne raccourcit pas l’abonnement : le temps payé est conservé et reprend à la réouverture.
AbonnementUn paiement = une période. Les renouvellements s’enchaînent (la nouvelle période démarre à la fin de la précédente). Une formule peut limiter le nombre de recherches par période (DESTINATION_QUOTA_EXCEEDED une fois atteint) ou être illimitée.
DécompteUne recherche est décomptée dès que le core banking est interrogé — y compris un numéro inconnu (404). Elle n’est pas décomptée si le service est indisponible (503).
Environnement de testRéponse simulée ("sandbox": true, titulaire TITULAIRE TEST) : aucun abonnement requis, aucun décompte, aucun appel au core banking.
Numéros pris en chargeCamerounais uniquement (+237 + 9 chiffres). Autre format : 400 INVALID_PHONE_NUMBER.
SuiviEspace marchand → Get destination : état du service, abonnement en cours, recherches restantes, paiements d’abonnement (avec la référence de votre règlement) et historique des recherches.
Statut · codeCauseAction
400 INVALID_PHONE_NUMBERNuméro absent, mal formé ou hors +237.Envoyer +237 suivi de 9 chiffres.
403 DESTINATION_NOT_ENABLEDService non ouvert pour votre compte.Demander l’activation à votre interlocuteur.
403 DESTINATION_SUBSCRIPTION_REQUIREDAucun abonnement en cours (jamais souscrit ou expiré).Demander le renouvellement.
404 DESTINATION_NOT_FOUNDAucun compte pour ce numéro.Vérifier le numéro (la recherche est décomptée).
429 DESTINATION_QUOTA_EXCEEDEDRecherches de la période épuisées.Renouveler ou changer de formule.
429 TOO_MANY_REQUESTSQuota de requêtes par minute de l’application.Réessayer après Retry-After.
503 PROVIDER_UNAVAILABLECore banking injoignable ou refus d’accès.Réessayer plus tard ; rien n’est décompté.

Back-office. Les administrateurs gèrent le catalogue (GET|POST /admin/v1/destination/plans, PUT …/plans/{planId}), ouvrent ou ferment le service (PUT /admin/v1/merchants/{merchantId}/destination/access {"enabled": true, "reason": "…"}), enregistrent un abonnement (POST …/destination/payments : plan_id — montant calculé, ou amount convenu — ou, sans formule, amount + duration_days ; method = WALLET (portefeuille débité) ou EXTERNAL avec proof_reference obligatoire), consultent paiements, recherches et journal d’audit (GET …/destination/payments|lookups|events) et testent un numéro (POST /admin/v1/destination/test {"phone": "+237…"}, sans abonnement ni décompte, journalisé). Lecture : permission core_banking.view ; écriture et essai : core_banking.manage. Chaque action est tracée avec son auteur.

Webhooks

Lorsque le traitement est terminé, CashLink émet l’événement payment.completed vers l’URL configurée sur l’application. Répondez rapidement par un statut 2xx, puis traitez le contenu de façon asynchrone.

Double notification (option). Sur demande, une application peut aussi recevoir l’événement payment.treated dès que l’agent a réglé le bénéficiaire (statut PAYMENT_TREATED, preuve de l’opérateur encore attendue), puis payment.completed au statut final. Même enveloppe et même signature ; le champ data.status vaut PAYMENT_TREATED. L’option se règle par notify_treated (booléen) sur la configuration du webhook ; elle est désactivée par défaut. payment.treated n’est pas un statut final : ne clôturez la commande qu’à la réception de payment.completed.

En-têteRôle
X-Webhook-SignatureSignature HMAC du corps transmis.
X-Webhook-IdIdentifiant de l’événement, à conserver pour dédupliquer.
X-Webhook-TimestampHorodatage Unix pris en compte dans la signature.
Important : vérifiez la signature sur le corps brut de la requête, pas sur un JSON reconstitué. Les tentatives de livraison sont rejouées en cas d’échec.
import crypto from 'node:crypto';

const rawBody = request.rawBody;
const timestamp = request.headers['x-webhook-timestamp'];
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.PAYME_WEBHOOK_SECRET)
  .update(`${timestamp}.${rawBody}`).digest('hex');

if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(request.headers['x-webhook-signature']))) {
  throw new Error('Signature webhook invalide');
}
// Dédupliquez avec X-Webhook-Id avant de traiter l’événement.
import hashlib, hmac, os

raw_body = request.get_data(as_text=True)
signed = f"{request.headers['X-Webhook-Timestamp']}.{raw_body}".encode()
expected = 'sha256=' + hmac.new(os.environ['PAYME_WEBHOOK_SECRET'].encode(), signed, hashlib.sha256).hexdigest()

if not hmac.compare_digest(expected, request.headers['X-Webhook-Signature']):
    abort(401)
# Dédupliquez avec X-Webhook-Id avant le traitement.
String rawBody = requestBody;
String signed = request.getHeader("X-Webhook-Timestamp") + "." + rawBody;
var mac = javax.crypto.Mac.getInstance("HmacSHA256");
mac.init(new javax.crypto.spec.SecretKeySpec(
    System.getenv("PAYME_WEBHOOK_SECRET").getBytes(java.nio.charset.StandardCharsets.UTF_8), "HmacSHA256"));
String expected = "sha256=" + java.util.HexFormat.of().formatHex(mac.doFinal(signed.getBytes()));
// Comparez expected et X-Webhook-Signature à temps constant.

API d’administration

Ces opérations alimentent la Console et exigent un jeton back-office obtenu avec POST /admin/v1/auth/login. Le rôle doit posséder la permission correspondante.

Connexion en deux étapes (consoles). POST /auth/login, POST /admin/v1/auth/login et POST /merchant/v1/auth/login vérifient le mot de passe puis répondent 202 sans jeton : otp_required: true, kind (admin | merchant), challenge_id, email masqué, expires_at, expires_in (180 s), resend_available_in. Un code à 6 chiffres part par e-mail (gestionnaire de notifications) ; il est stocké haché, valable 3 minutes, 5 essais. POST /auth/login/verify {"challenge_id", "code"} → 201, même réponse de session qu’avant (kind, access_token, user ou merchant). POST /auth/login/resend {"challenge_id"} : nouveau code (30 s entre deux envois, 3 renvois). Erreurs : 401 INVALID_OTP (code faux, expiré ou essais épuisés), 429, 503 SERVICE_UNAVAILABLE si l’e-mail n’a pas pu partir. L’app agent (/agent/login-pin) n’est pas concernée. PAYME_LOGIN_OTP_ENABLED=false rétablit la connexion directe (secours). Par compte : login_otp_enabled (défaut true) sur PUT /admin/v1/users/{adminUserId} et PUT /admin/v1/merchants/{merchantId} ; à false, ce compte se connecte directement (201, sans code).

OpérationRequêteSuccèsErreurs usuelles
Créer un agentPOST /admin/v1/agents : name, email, phone, compte flotte 807… facultatif.201 · profil agent. Le PIN initial est 12345 et doit être transmis hors API.400 téléphone/compte invalide, 409 EMAIL_ALREADY_USED, 403 INSUFFICIENT_PERMISSIONS.
Modifier / suspendrePUT /admin/v1/agents/{agentId} ou POST …/suspend. pin_required (vrai par défaut) et sms_permission_required (faux par défaut : s’il est vrai, l’agent ne reçoit rien tant que son téléphone n’a pas accordé la permission SMS).200 · profil mis à jour.404 ADMIN_USER_NOT_FOUND, 403 permission manquante.
Agents de testPUT /admin/v1/agents/{agentId} {"sandbox_agent": true} (ou à la création, ou en groupe : sandbox_on / sandbox_off). Seuls les agents de test reçoivent les paiements de l’environnement de test (sandbox) et paient ses paiements manuels ; ils ne reçoivent ni ne paient jamais un paiement de production (403 au guichet). Au changement, leurs propositions non acceptées du mauvais environnement repartent et les demandes en attente qu’ils peuvent désormais recevoir sont rattrapées. Sans agent de test disponible, un paiement de test reste en attente.200 · fiche (sandbox_agent).400, 403 permission manquante.
Actions groupéesPOST /admin/v1/agents/bulk {"action": "suspend" | "restore" | "online" | "offline" | "sandbox_on" | "sandbox_off" | "fail_allow" | "fail_deny" | "release_allow" | "release_deny", "all": true} ou {"action", "agent_ids": [...]}, reason facultatif pour suspend. Mêmes règles que les actions unitaires (désactivation : jetons révoqués ; hors ligne : propositions redistribuées, compte actif). Seuls les agents sont visés. Réponse : requested, applied, unchanged (déjà dans l’état demandé), skipped (agent_id, message) — le reste est appliqué.200 · bilan.400 action ou cible manquante, 403 permission manquante.
En ligne / hors lignePUT /admin/v1/agents/{agentId}/availability {"online": false} : sans suspendre le compte (l’agent reste actif et peut se connecter). Hors ligne, il ne reçoit plus de paiements et ses propositions non acceptées sont redistribuées ; une transaction déjà acceptée reste la sienne. En ligne, les demandes en attente sont rattrapées. L’agent peut ensuite changer lui-même sa disponibilité depuis l’app.200 · profil (is_online, can_receive_payments).400 online manquant, 404 ADMIN_USER_NOT_FOUND, 403 permission manquante.
Statistiques agentsGET /admin/v1/agents/statistics.200 · rang, volumes et durées moyennes par agent.403 permission manquante.
Superviser paiementsGET /admin/v1/payments?agent_id=…&status=…, aussi operator (orange | mtn, d’après le numéro du bénéficiaire) et has_operator_proof (1 avec / 0 sans SMS de l’opérateur rapproché ; un paiement réussi sans preuve reste réussi). Chaque ligne porte has_operator_proof, provider_reference, mobile_operator et processing_duration_seconds (prise en charge → fin) et lifetime_seconds (création → fin). Détail GET …/{paymentId}.200 · détail enrichi : cycle de vie, affectations, intervenants et délais.404 PAYMENT_NOT_FOUND.
Plafonds d’un agentPOST / PUT /admin/v1/agents/{agentId} : cap_daily_amount, cap_weekly_amount, cap_monthly_amount, cap_yearly_amount (montants entiers > 0, null = ignoré, défaut). Par opérateur : operator_caps {"orange": {"daily": …, "weekly": …, "monthly": …, "yearly": …}, "mtn": {…}} (opérateur déduit du numéro du bénéficiaire) ; une transaction est refusée à l’agent si elle dépasse son plafond tous opérateurs OU celui de son opérateur. Montant engagé = transactions en cours chez l’agent + réglées par lui (traitées ou réussies) sur la période calendaire (heure de Douala, semaine du lundi). Une transaction qui ferait dépasser l’un de ses plafonds ne lui est pas proposée ; s’il est le seul agent, elle attend. GET /admin/v1/agents/{agentId} ajoute caps : par portée (all, orange, mtn) et période, cap, used, remaining, resets_at.200 · fiche agent.400 montant invalide.
Notification de test à un agentPOST /admin/v1/agents/{agentId}/push-test : même canal que les transactions (Firebase, notification + data type: "push_test", notification_type: "TEST") vers tous les téléphones enregistrés de l’agent.200 · status (SENT | NO_DEVICE | NOT_CONFIGURED | FAILED), device_count, success_count, failure_count, error, devices (nom, dernière activité).403 permission manquante, 404 agent inconnu.
Notifications push (console)PUT /admin/v1/auth/push-token : fcm_token, device_name facultatif — à chaque connexion ; DELETE même route, {"fcm_token": …}, à la déconnexion. POST …/push-token/test : notification de test vers les navigateurs du compte connecté, renvoie status (SENT, NO_DEVICE, NOT_CONFIGURED, FAILED), device_count, success_count, failure_count, error. Les comptes actifs super_admin / admin reçoivent une notification pour chaque transaction créée par un marchand (data.type = payment_created, payment_id, reference, merchant_name, status…).204.400 jeton absent ou trop court, 401 session absente.
SMS opérateurGET /admin/v1/operator-sms (status, operator, agent_ids[] un ou plusieurs agents — agent_id seul reste accepté, aussi sur les transactions opérateur et le traitement par lots —, from, to, search), détail, POST …/{smsId}/process (retraitement), POST /admin/v1/operator-sms/process (SMS en attente) et POST /admin/v1/operator-sms/reprocess (tous les SMS, rapprochements retentés sans défaire un lien), par lots : chunk (50 par défaut, 500 max), filtres facultatifs agent_ids[], from / to (réception du SMS), amount ou amount_min / amount_max, curseur after_id ; renvoient scanned, processed, skipped, sms, matches, next_after_id, remaining, done, GET …/statistics. Purge : GET /admin/v1/operator-sms/purge (aperçu ignored, failed, duplicates, transactions, total — failed n'entre dans total qu'avec include_failed=1) puis POST /admin/v1/operator-sms/purge par lots (chunk, 200 par défaut, 1 000 max ; include_failed et include_unmatched facultatifs, curseur after_id ; renvoie purged {ignored, failed, duplicates, transactions, transactions_kept, unmatched, unmatched_kept, sms}, next_after_id, remaining, done ; l'aperçu compte aussi unmatched, les transactions non rapprochées à examiner) : SMS ignorés, SMS en échec sur option, sur option encore les transactions non rapprochées sans aucun paiement (tout statut, toute date) de même montant vers l'un de leurs numéros (6…, 237…, +237…, 00237…) avec leurs SMS, SMS en double (même référence opérateur, hors SMS principal) et transactions ni dépôt ni transfert avec leurs SMS ; une transaction rapprochée d'un paiement n'est jamais purgée, ni une transaction (de tout type) pour laquelle un paiement a le même montant et l'un de ses numéros (transactions_kept, unmatched_kept) — elles sont examinées une à une avec le curseur after_id, un SMS purgé renvoyé par l'app répond duplicate. DELETE /admin/v1/operator-sms/{smsId} : supprime ce SMS, et sa transaction opérateur (avec ses SMS rattachés) s'il en est le SMS principal → {sms, transaction_deleted} ; 409 RESOURCE_CONFLICT si cette transaction est rapprochée d'un paiement. GET /admin/v1/operator-transactions (match_status UNMATCHED · MATCHED · AMBIGUOUS · NOT_APPLICABLE, mismatch…), détail avec candidates (paiements réussis) / loose_candidates (en traitement ou réussis, jamais en échec), POST …/{id}/match {"payment_id"} (409 pour un paiement en échec), DELETE …/{id}/match. GET /admin/v1/payments/{paymentId}/operator-transaction.200.403 agents et rôles sans droit ; 409 RESOURCE_CONFLICT paiement déjà rapproché.
SMS avant la déclaration de l’agentUn SMS de l’opérateur qui correspond (montant, bénéficiaire, opérateur, postérieur à la première prise en charge, candidat unique) à une demande en traitement ou relâchée après prise en charge la rend réussie sans attendre l’agent : PROCESSING (ou PENDING) → PAYMENT_TREATED → PAYMENT_SUCCEEDED par la plateforme, motif « SMS de l’opérateur reçu avant la déclaration de l’agent », heure de fin = heure du rapprochement. Le règlement est crédité à l’agent qui détenait la demande à l’heure du SMS. Tout autre agent qui la détient ou à qui elle est proposée voit sa proposition close et reçoit un push notification_type PAYMENT_ALREADY_PAID (ne pas payer). POST /agent/v1/payments/{paymentId}/succeed d’un agent dont le règlement a été ainsi confirmé répond 200. Réglage serveur PAYME_SMS_CONFIRMS_UNFINISHED : off · log (défaut : journal seulement, rien ne change) · on. Les transactions déjà traitées gardent le rapprochement habituel, prioritaire.200.—
Doubles paiements potentielsUne transaction (en cours, traitée, réussie ou en échec, hors paiement manuel) est suspecte quand l’opérateur a envoyé plus de fois son montant à son bénéficiaire (SMS aux références distinctes) qu’il n’existe de demandes semblables (même montant, même numéro, ±3 jours) pour le justifier. Un SMS la concerne comme au rapprochement : même montant, de la veille de la demande à 3 jours après, numéro du bénéficiaire en contrepartie ou cité dans le texte ; le sens (in/out) n’est pas un critère. Deux demandes réelles payées chacune une fois ne sont pas signalées. Les suspectes sont enregistrées (table payment_double_flags) par php artisan payme:payments:scan-doubles : sans option, toutes les transactions sont examinées, les nouvelles suspectes enregistrées et celles qui ne le sont plus retirées ; options --days, --from, --to, --merchant, --dry-run, --csv=fichier.csv, --payment=pay_… (explique le verdict d’une transaction, sans rien modifier). Le planificateur réexamine les 4 derniers jours toutes les 5 minutes. Liste : GET /admin/v1/payments?suspected_double=1, et suspected_double sur chaque ligne. Détail : GET /admin/v1/payments/{paymentId}/double-payment → operator_payments_count, payments_count, suspected, flagged (enregistrée), regularized / regularized_at / regularized_by_name / regularization_note (vérifiée par un administrateur), operator_transactions, similar_payments. Régulariser (vérifié et réglé) : POST /admin/v1/payments/{paymentId}/double-payment/regularize (note facultative, administrateur) — la transaction sort du filtre et suspected_double passe à false (double_regularized à true) ; elle se rouvre seule si l’opérateur envoie encore ce montant. DELETE sur la même URL la rouvre à la main. Fenêtres réglables : PAYME_DOUBLE_PAYMENT_SMS_DAYS_BEFORE, …_SMS_DAYS_AFTER, …_SIBLING_DAYS.200.403 agent ou permission manquante.
Demander le SMS à l’agentPOST /admin/v1/payments/{paymentId}/request-sms (permission payments.transition, refusé aux agents) : transaction PAYMENT_TREATED ou PAYMENT_SUCCEEDED sans SMS rapproché ni preuve manuelle. Push à l’agent qui l’a réglée, mêmes informations qu’une nouvelle transaction (payment en JSON, délai, PIN) avec type: "sms_requested" et notification_type: "REQUEST_SMS". Une demande par minute et par transaction.200 · agent_id, push (status SENT | NO_DEVICE | NOT_CONFIGURED | FAILED, success_count, failure_count, error).403 agent ou permission manquante, 409 paiement manuel, statut non concerné ou preuve déjà là, 429 déjà demandé il y a moins d’une minute.
Confirmer le succès d’une transaction traitéePOST /admin/v1/payments/{paymentId}/confirm-success (multipart, permission payments.reverse, refusé aux agents) : proof_type = OPERATOR_REFERENCE (operator_reference obligatoire) ou SCREENSHOT (screenshot image JPG/PNG/WEBP, 5 Mo au plus ; operator_reference facultative), note interne facultative. PAYMENT_TREATED → PAYMENT_SUCCEEDED : webhook au marchand et virement bancaire comme pour la preuve SMS. Par SMS : GET /admin/v1/payments/{paymentId}/operator-transaction-candidates (opérations non rapprochées du même montant, same_recipient en tête ; ?same_recipient=1 : même numéro seulement) puis POST /admin/v1/operator-transactions/{id}/match. Une transaction réussie sans aucune preuve reçoit aussi une référence ou une capture par confirm-success : le statut ne change pas, ni webhook ni virement, success_proof.mode vaut ADDED (sinon CONFIRMATION) et l’ajout est tracé dans l’historique de la transaction (context.action: "success_proof_added", auteur, date) ; 409 si elle a déjà sa preuve. Une transaction réussie sans SMS se rapproche de la même façon (même numéro et même montant) : son statut ne change pas, aucun webhook n’est renvoyé, le SMS devient sa preuve et sa Réf. opérateur. Liste admin : manual_proof (type) par ligne, filtre proof = operator | manual | none ; une transaction prouvée manuellement n’est jamais repassée « traitée » par la régularisation. Preuve exposée en success_proof (admin : auteur et note ; marchand : type, référence, has_screenshot) ; capture servie par GET …/success-proof/screenshot (admin et /merchant/v1/payments/{paymentId}/success-proof/screenshot), stockée sur un disque privé.200 · demande PAYMENT_SUCCEEDED.400 preuve manquante ou fichier invalide, 403 agent ou permission manquante, 409 transaction non traitée.
Marquer en échec une transaction réussie ou traitéePOST /admin/v1/payments/{paymentId}/reverse-to-failed (PAYMENT_SUCCEEDED ou PAYMENT_TREATED) : failure_code (motif actif, obligatoire), reason facultatif. Administrateurs uniquement (permission payments.reverse). Tout ce qui suit un échec s’applique : solde partenaire recrédité, webhook au marchand (PAYMENT_FAILED), virement bancaire jamais parti annulé (CANCELLED) — un virement déjà envoyé ou effectué n’est pas défait (alerte, régularisation manuelle). L’historique (…/events) garde l’administrateur, le motif et reversed_from ; la Réf. opérateur et l’agent du règlement sont conservés.200 · transaction au statut PAYMENT_FAILED.400 motif absent ou inconnu, 403 non administrateur, 409 transaction non réussie.
Remettre en réussite une transaction échouéePOST /admin/v1/payments/{paymentId}/reverse-to-succeeded : provider_reference et reason facultatifs. Administrateurs uniquement (payments.reverse). Tout ce qui suit une réussite s’applique : solde partenaire débité de nouveau (montant + frais), virement bancaire ouvert ou réactivé s’il avait été annulé, webhook au marchand (PAYMENT_SUCCEEDED). Le motif d’échec est effacé du paiement mais reste dans l’historique (reversed_from, previous_failure_code).200 · transaction au statut PAYMENT_SUCCEEDED.403 non administrateur, 409 transaction non échouée, 422 UNPROCESSABLE_REQUEST solde partenaire insuffisant (rien n’est modifié).
Paiement manuel : renvoyer le codePOST /admin/v1/payments/{paymentId}/withdrawal-code/resend (permission payments.transition, pas les agents). Nouveau code de retrait par SMS au bénéficiaire, le précédent est révoqué. Le détail d’un paiement manuel porte payment_mode, recipient.identity_document et withdrawal_code (status ACTIVE · USED · EXPIRED · REVOKED, expires_at, sent_at, used_at, issued_count — jamais le code) ; filtre de liste payment_mode.200 · paiement.409 RESOURCE_CONFLICT paiement non manuel ou plus en attente.
Multiple du montant par modeGET /admin/v1/settings/payments renvoie amount_multiples ; PUT /admin/v1/settings/payments/amount-multiples {"amount_multiples": {"MOBILE_MONEY": 100, "MANUAL": 500}} (un mode absent garde sa valeur, 1 = aucune contrainte, 1 000 000 au plus). Vérifié à la création d’un paiement.200 · amount_multiples.400 valeur invalide, 403 permission manquante.
Arrondi au multiple (par partenaire)PUT /admin/v1/merchants/{merchantId} {"amount_rounding": "UP" | "DOWN" | null}. Par défaut (null), un montant qui n’est pas un multiple est refusé. UP : arrondi par excès au multiple suivant (130 → 200 pour un multiple de 100) ; DOWN : par défaut (130 → 100), refusé s’il tomberait à 0. Le montant arrondi remplace le montant envoyé pour tout le cycle (frais, solde, virement) ; le montant envoyé, le multiple et le sens sont gardés sur la transaction (amount_adjustment).200 · fiche (amount_rounding).400 valeur invalide, 403 permission manquante.
Distribution et tolérance de tempsGET / PUT /admin/v1/settings/dispatch : assignment_ttl_seconds, sms_match_tolerance_minutes (tolérance par défaut, 1 à 1440 min), duplicate_guard_enabled. Par agent : sms_match_tolerance_minutes sur PUT /admin/v1/agents/{agentId} (null = valeur par défaut). Le SMS de l’opérateur est rapproché si son heure tombe entre la prise en charge du paiement (à défaut sa création) et sa fin (marqué réussi) + tolérance de l’agent qui l’a terminé — même point de départ que la règle anti-doublon. Règle anti-doublon (si activée) : un agent qui a traité, ou à qui est proposé, un montant vers un numéro ne reçoit plus ce même montant vers ce même numéro tant que l’autre demande n’est pas terminée, puis pendant sa tolérance comptée à partir du moment où il l’a marquée terminée (la demande va à un autre agent ou attend).200 · réglages à jour.400 valeur hors bornes, 403 sans droit de configuration.
Preuve opérateur (espace client)GET /merchant/v1/payments/{paymentId}/operator-proof : SMS de l'opérateur rapproché d'un paiement du partenaire — reference, operator, amount, transacted_at, sms {sender, body, received_at}, solde du téléphone de service remplacé par xxxxx dans body.200 · {operator_proof}, null tant que le paiement n'est pas rapproché.404 paiement d'un autre partenaire.
Exporter les paiementsGET /admin/v1/payments/export (permission payments.export) et, pour l’espace client, GET /merchant/v1/payments/export : mêmes filtres que la liste, pagination ignorée — toutes les lignes, bénéficiaire compris, jusqu’à 20 000.200 · {data, total, truncated} (truncated : plafond atteint, affiner les filtres).403 sans droit d’export.
Rechercher paiementsGET /admin/v1/payments?search=… : « contient », sur le téléphone et le nom du client, l’e-mail (contact du marchand ou métadonnées du paiement) et les références. Un numéro peut se saisir avec espaces ou tirets.200 · liste paginée.400 plus de 150 caractères.
Statistiques du tableau de bordGET /admin/v1/payments/statistics : succeeded_count et succeeded_by_currency (paiements réussis) en plus de by_status / by_currency (toutes demandes). GET …/statistics/timing : délais globaux + by_outcome.succeeded et by_outcome.failed.200.403 permission manquante.
Statistiques par heureGET /admin/v1/payments/statistics/timeseries?group_by=hour&from=…&to=… (aussi virements, marchands, webhooks). from/to acceptent une heure (ISO 8601).200 · tranches "2026-10-03 14:00", en UTC.400 group_by hors hour, day, week, month.
Plafonds d’une applicationPUT /admin/v1/applications/{applicationId} : {"transaction_caps": [{"max_transactions": 5, "window_minutes": 1}, {"max_transactions": 69, "window_minutes": 1440}]}. Fenêtre glissante, au plus 10 règles, [] retire tout plafond. L’ancien couple max_transactions + max_transactions_window reste accepté (une règle).200 · transaction_caps triées de l’intervalle le plus court au plus long.400 deux règles sur le même intervalle, ou un intervalle court qui autorise plus qu’un intervalle long. À l’usage : 429 TRANSACTION_CAP_EXCEEDED.
Configurer plafondPUT /admin/v1/settings/payments : {"maximum_amount": 5000000}.200 · {"maximum_amount":5000000}.400 montant invalide, 403 permission manquante.
Alertes de solde — destinataires internesGET / PUT /admin/v1/settings/core-banking/partner-balance-alerts {"alert_emails": ["tresorerie@…"]} (20 au plus ; [] = aucun). Chaque alerte de solde envoyée à un marchand (seuil franchi, solde épuisé, solde insuffisant) part aussi, en version interne (« [CashLink interne] Marchand — seuil de X franchi », solde, détail, lien vers sa fiche), à ces adresses et à celles de PAYME_PARTNER_BALANCE_ALERT_EMAILS (renvoyées en lecture seule dans environment_alert_emails). Le marchand reçoit seul l’e-mail qui lui est adressé.200 · alert_emails, environment_alert_emails.400 adresse invalide ou en double, 403 permission manquante.
Plafond de créditPUT /admin/v1/merchants/{merchantId}/balance/credit-limit {"credit_limit": 10000000} (null = aucun). Ne vaut que contrôle du solde désactivé : les transactions passent sans recharge et débitent le solde, qui peut devenir négatif ; une transaction qui ferait passer le solde sous −credit_limit est refusée (PAYMENT_FAILED, PARTNER_BALANCE_INSUFFICIENT, « Plafond de crédit atteint ») avec l’alerte e-mail habituelle. Une correction au débit ne descend jamais sous ce plancher. Sans plafond : comportement d’origine (contrôle désactivé, le solde n’est pas consommé). Contrôle activé : le solde ne descend jamais sous 0, plafond ignoré.200 · solde (credit_limit, credit_active, available = encore utilisable avant refus, null sans limite).400 montant invalide, 403 permission manquante.
Seuils d’alerte du soldePUT /admin/v1/merchants/{merchantId}/balance/alert-thresholds {"alert_thresholds": [5000000, 3000000, 1000000, 300000]} (10 au plus, entiers > 0, distincts ; [] = aucune alerte). Chaque fois qu’un débit fait passer le solde sous un seuil, un e-mail part au contact du partenaire (et aux adresses internes d’alerte) : « il vous reste X, rechargez ». Plusieurs seuils franchis d’un coup : un seul e-mail (le plus bas). Un seuil n’est signalé qu’une fois jusqu’à la prochaine recharge (un remboursement ne le réarme pas). Solde épuisé : l’alerte existante « solde épuisé » s’applique.200 · solde (alert_thresholds du plus haut au plus bas, alert_threshold_notified, alert_threshold_notified_at).400 liste invalide, 403 permission manquante.
Solde partenaireGET /admin/v1/merchants/{merchantId}/balance ; activer le contrôle : PUT …/balance/settings {"control_enabled": true}. Compte d’opération simulé : un paiement de production le débite à sa création (montant + frais marchand), un paiement échoué ou annulé est remboursé ; rien n’est envoyé à la banque.200 · balance, currency, control_enabled, insufficient_notified_at.403 permission manquante (lecture : core_banking.view, activation : core_banking.manage), 404 MERCHANT_NOT_FOUND.
Recharger / corrigerPOST …/balance/credits : amount, external_reference et comment facultatifs. POST …/balance/adjustments : direction (CREDIT | DEBIT), amount, comment obligatoire. Administrateurs uniquement.201 · {movement, balance}.400 montant ou commentaire invalide, 422 correction qui rendrait le solde négatif, 403 sans core_banking.manage.
Relevé du soldeGET …/balance/movements : type (TOP_UP, PAYMENT_DEBIT, PAYMENT_REFUND, ADJUSTMENT), direction, from, to, search, pagination. Espace client, lecture seule : GET /merchant/v1/balance et /merchant/v1/balance/movements.200 · lignes avec montant signé, solde avant/après, paiement (principal + frais), compte d’opération, pièce, auteur.—
Virement bancaireGET /admin/v1/payments/{paymentId}/bank-transaction.200 · détails, statut et journal du virement DAP.404 BANK_TRANSACTION_NOT_FOUND, 422 PAYMENT_NOT_SETTLED selon l’opération.
{
  "data": [{
    "agent_id": "adm_01J…",
    "name": "Agent Exemple",
    "assigned_count": 42,
    "taken_in_charge_count": 39,
    "completed_count": 37,
    "average_time_to_take_in_charge_seconds": 112,
    "average_processing_duration_seconds": 185,
    "rank": 1
  }]
}
{
  "id": "pay_01J…",
  "status": "PAYMENT_SUCCEEDED",
  "settlement": { "processed_by": "adm_01J…", "settled_by": "adm_01J…" },
  "assignments": [{
    "sequence": 1,
    "status": "COMPLETED",
    "agent": { "id": "adm_01J…", "name": "Agent Exemple", "phone": "+237690000000" },
    "assigned_at": "2026-09-24T10:15:30+00:00",
    "acknowledged_at": "2026-09-24T10:20:00+00:00",
    "ended_at": "2026-09-24T10:23:05+00:00"
  }]
}

Utiliser la Console CashLink

La Console centralise l’administration interne et l’espace marchand. Elle est disponible sur console.paymebusiness.com.

  1. Connectez-vous. Selon votre profil, vous accédez à l’espace d’administration ou au portail marchand.
  2. Créez ou ouvrez un marchand. Ajoutez ses coordonnées, puis contrôlez son statut avant toute utilisation de l’API.
  3. Créez une application. Copiez immédiatement le secret et la clé privée affichés à l’émission : le secret API n’est pas relisible par la suite.
  4. Configurez le webhook. Définissez son URL, activez-le et conservez le secret de signature dans un coffre de secrets.
  5. Suivez les opérations. Les agents font passer les paiements en traitement puis enregistrent leur issue ; la chronologie est disponible sur chaque transaction.
  6. Définissez le plafond. Les administrateurs règlent le montant maximal global accepté dans Paramètres → Plafond des transactions, ou via PUT /admin/v1/settings/payments avec {"maximum_amount": 5000000}.
Rôle interneAccès principal
super_admin, adminParamétrage, utilisateurs, marchands et supervision complète.
operator, agentTraitement et suivi opérationnel des paiements.
support, viewerConsultation et assistance selon les permissions accordées.

Sécurité

Utilisez HTTPS en production, stockez les secrets dans les variables d’environnement, appliquez une clé d’idempotence à chaque création et ne journalisez jamais les jetons, secrets ni codes à usage unique.

Codes d’erreur

Toute réponse en échec porte error.code (stable, à utiliser dans votre code), error.message (lisible, en français, non contractuel) et, si un champ est en cause, error.field. Les 94 codes ci-dessous sont générés depuis la source du service : cette liste est toujours à jour. Même catalogue en JSON, sans authentification : GET https://api.paymebusiness.com/api/v1/error-codes (filtre ?http_status=409) et GET …/error-codes/{CODE}.

StatutFamilleÀ retenir
400Requête invalideFormat incorrect : corrigez puis renvoyez.
401AuthentificationJeton absent, invalide ou expiré : reconnectez-vous.
403Accès refuséCompte, application, adresse IP ou service non autorisé : inutile de réessayer à l’identique.
404IntrouvableIdentifiant ou référence inconnu.
409Conflit d’étatRelisez l’état de la ressource avant d’agir.
422Règle métierLa requête est bien formée mais refusée par une règle : lisez message.
429Quota atteintPatientez (Retry-After) et étalez vos appels.
500 / 503IncidentRéessayez avec un délai croissant (même clé d’idempotence pour une création).

94 codes

400 · Requête invalide

CodeSignificationAction recommandée
INVALID_AMOUNTMontant invalide : entier positif exprimé dans la plus petite unité de la devise.Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la.
INVALID_BANK_ACCOUNT_NUMBERNuméro de compte bancaire invalide.Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la.
INVALID_COUNTRY_CODECode pays invalide (ISO 3166-1 alpha-2 attendu).Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la.
INVALID_CURRENCYCode devise invalide (ISO 4217 sur trois lettres attendu).Utilisez une devise prise en charge (XAF).
INVALID_IDEMPOTENCY_KEYClé d'idempotence mal formée.Ajoutez l'en-tête Idempotency-Key (valeur unique par création, UUID conseillé).
INVALID_IP_ADDRESSAdresse IP ou plage CIDR invalide.Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la.
INVALID_PHONE_NUMBERNuméro de téléphone invalide (format international attendu, ex. +2376XXXXXXXX).Envoyez le numéro au format international E.164, ex. +237690123456.
INVALID_REQUESTRequête invalide : un ou plusieurs champs ne respectent pas le format attendu.Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la.
INVALID_WEBHOOK_URLURL de webhook invalide (HTTPS public attendu).Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la.
MISSING_IDEMPOTENCY_KEYEn-tête Idempotency-Key absent sur une création de paiement.Ajoutez l'en-tête Idempotency-Key (valeur unique par création, UUID conseillé).
MISSING_PARAMETERUn paramètre obligatoire est absent.Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la.
WEAK_PASSWORDMot de passe trop faible.Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la.

401 · Authentification

CodeSignificationAction recommandée
INVALID_CREDENTIALSIdentifiants incorrects.Vérifiez le secret et la clé privée de l'application (le secret n'est plus relisible : régénérez-le si besoin).
INVALID_OTPCode de vérification (OTP) incorrect ou expiré.Authentifiez-vous à nouveau puis renvoyez la requête.
TOKEN_EXPIREDJeton d'accès expiré : obtenez-en un nouveau.Obtenez un nouveau jeton (POST /v1/auth) et renvoyez la requête avec l'en-tête Authorization: Bearer.
TOKEN_INVALIDJeton d'accès invalide.Obtenez un nouveau jeton (POST /v1/auth) et renvoyez la requête avec l'en-tête Authorization: Bearer.
TOKEN_MISSINGJeton d'accès absent de l'en-tête Authorization.Obtenez un nouveau jeton (POST /v1/auth) et renvoyez la requête avec l'en-tête Authorization: Bearer.
TOKEN_REVOKEDJeton d'accès révoqué.Obtenez un nouveau jeton (POST /v1/auth) et renvoyez la requête avec l'en-tête Authorization: Bearer.
UNAUTHENTICATEDAuthentification requise : jeton absent, invalide ou expiré.Obtenez un nouveau jeton (POST /v1/auth) et renvoyez la requête avec l'en-tête Authorization: Bearer.

403 · Accès refusé

CodeSignificationAction recommandée
ACCOUNT_SUSPENDEDLe compte utilisateur est suspendu.Contactez votre interlocuteur pour faire lever la suspension ; inutile de réessayer avant.
APPLICATION_SUSPENDEDL'application est suspendue.Contactez votre interlocuteur pour faire lever la suspension ; inutile de réessayer avant.
DESTINATION_NOT_ENABLEDLe service get destination n'est pas activé pour ce partenaire.Le service get destination n'est pas ouvert pour votre compte : demandez son activation à votre interlocuteur.
DESTINATION_SUBSCRIPTION_REQUIREDAucun abonnement get destination en cours : contactez votre interlocuteur pour l'activer ou le renouveler.Aucun abonnement en cours : demandez le renouvellement (paiement par le portefeuille ou règlement externe).
FORBIDDENAction non autorisée pour ce compte ou cette ressource.Vérifiez les droits, le statut et les restrictions du compte ou de l'application ; ne réessayez pas à l'identique.
INSUFFICIENT_PERMISSIONSPermissions insuffisantes pour cette action.Vérifiez les droits, le statut et les restrictions du compte ou de l'application ; ne réessayez pas à l'identique.
IP_NOT_ALLOWEDAdresse IP appelante absente de la liste autorisée de l'application.Appelez depuis une adresse autorisée, ou ajoutez cette adresse à la liste de l'application dans la console.
MERCHANT_SUSPENDEDLe compte partenaire est suspendu.Contactez votre interlocuteur pour faire lever la suspension ; inutile de réessayer avant.
PAYMENT_NOT_ASSIGNEDCette transaction ne vous est pas (ou plus) affectée : elle a expiré ou est passée à un autre agent.Vérifiez les droits, le statut et les restrictions du compte ou de l'application ; ne réessayez pas à l'identique.

404 · Introuvable

CodeSignificationAction recommandée
ADMIN_USER_NOT_FOUNDUtilisateur back-office introuvable.Vérifiez l'identifiant ou la référence fournie.
APPLICATION_NOT_FOUNDApplication introuvable.Vérifiez l'identifiant ou la référence fournie.
BANK_ACCOUNT_NOT_FOUNDCompte bancaire introuvable auprès du core banking.Vérifiez l'identifiant ou la référence fournie.
BANK_TRANSACTION_NOT_FOUNDVirement bancaire introuvable.Vérifiez l'identifiant ou la référence fournie.
DAP_CREDENTIALS_NOT_FOUNDIdentifiants du core banking (DAP) non configurés.Vérifiez l'identifiant ou la référence fournie.
DEFAULT_TERMINATION_ACCOUNT_NOT_FOUNDAucun compte de terminaison par défaut n'est configuré.Vérifiez l'identifiant ou la référence fournie.
DESTINATION_NOT_FOUNDAucun compte n'est associé à ce numéro.Aucun compte pour ce numéro : vérifiez le numéro ; la recherche est décomptée.
DESTINATION_PLAN_NOT_FOUNDFormule get destination introuvable.Vérifiez l'identifiant ou la référence fournie.
MERCHANT_NOT_FOUNDPartenaire introuvable.Vérifiez l'identifiant ou la référence fournie.
MERCHANT_TERMINATION_NOT_FOUNDAucun compte de terminaison associé à ce partenaire.Vérifiez l'identifiant ou la référence fournie.
OPERATION_ACCOUNT_NOT_FOUNDCompte d'opération introuvable.Vérifiez l'identifiant ou la référence fournie.
PAYMENT_FAILURE_REASON_NOT_FOUNDMotif d'échec introuvable.Vérifiez l'identifiant ou la référence fournie.
PAYMENT_NOT_FOUNDTransaction introuvable.Vérifiez l'identifiant ou la référence fournie.
RESOURCE_NOT_FOUNDRessource introuvable.Vérifiez l'identifiant ou la référence fournie.
TERMINATION_ACCOUNT_NOT_FOUNDCompte de terminaison introuvable.Vérifiez l'identifiant ou la référence fournie.
TRANSACTION_FEES_NOT_FOUNDAucun barème de frais configuré pour ce partenaire.Vérifiez l'identifiant ou la référence fournie.
WEBHOOK_EVENT_NOT_FOUNDÉvénement webhook introuvable.Vérifiez l'identifiant ou la référence fournie.
WITHDRAWAL_CODE_INVALIDCode de retrait invalide, expiré ou déjà utilisé.Vérifiez le code saisi ; s'il est expiré ou déjà utilisé, demandez au partenaire d'en émettre un nouveau.

405 · Méthode non autorisée

CodeSignificationAction recommandée
METHOD_NOT_ALLOWEDMéthode HTTP non autorisée sur cette route.Utilisez la méthode HTTP documentée pour cette route.

409 · Conflit d’état

CodeSignificationAction recommandée
ACCOUNT_ALREADY_ACTIVELe compte est déjà actif.Relisez l'état actuel de la ressource avant toute nouvelle action.
ACCOUNT_ALREADY_SUSPENDEDLe compte est déjà suspendu.Relisez l'état actuel de la ressource avant toute nouvelle action.
AGENT_PAYMENT_IN_PROGRESSL'agent a déjà une transaction en cours de traitement : il doit la terminer avant d'en accepter une autre.Relisez l'état actuel de la ressource avant toute nouvelle action.
APPLICATION_ALREADY_ACTIVEL'application est déjà active.Relisez l'état actuel de la ressource avant toute nouvelle action.
APPLICATION_ALREADY_SUSPENDEDL'application est déjà suspendue.Relisez l'état actuel de la ressource avant toute nouvelle action.
BANK_TRANSACTION_NOT_SUBMITTABLELe virement ne peut pas être (ré)envoyé dans son état actuel.Relisez l'état actuel de la ressource avant toute nouvelle action.
CANNOT_TARGET_SELFAction impossible sur votre propre compte.Relisez l'état actuel de la ressource avant toute nouvelle action.
DUPLICATE_APPLICATION_NAMEUne application porte déjà ce nom.Relisez l'état actuel de la ressource avant toute nouvelle action.
DUPLICATE_DESTINATION_PLANUne formule get destination porte déjà ce code.Relisez l'état actuel de la ressource avant toute nouvelle action.
DUPLICATE_EXTERNAL_REFERENCEUne transaction existe déjà pour cette référence externe.Une transaction existe déjà pour cette référence : consultez-la au lieu d'en créer une autre.
DUPLICATE_MERCHANT_NAMEUn partenaire porte déjà ce nom.Relisez l'état actuel de la ressource avant toute nouvelle action.
DUPLICATE_PAYMENT_FAILURE_REASONUn motif d'échec porte déjà ce code.Relisez l'état actuel de la ressource avant toute nouvelle action.
DUPLICATE_TERMINATION_ACCOUNTUn compte de terminaison porte déjà ce nom ou ce numéro.Relisez l'état actuel de la ressource avant toute nouvelle action.
EMAIL_ALREADY_USEDAdresse e-mail déjà utilisée.Relisez l'état actuel de la ressource avant toute nouvelle action.
IDEMPOTENCY_CONFLICTClé d'idempotence déjà utilisée avec une requête différente.Cette clé a déjà servi pour une requête différente : générez une nouvelle clé, ou rejouez la requête d'origine à l'identique.
IDEMPOTENT_REQUEST_PENDINGUne requête avec la même clé d'idempotence est encore en cours de traitement.La requête d'origine est encore en cours : patientez quelques secondes puis rejouez-la avec la même clé.
INVALID_STATUS_TRANSITIONChangement de statut non autorisé depuis le statut actuel.Relisez l'état actuel de la ressource avant toute nouvelle action.
LAST_SUPER_ADMINImpossible de retirer le dernier super administrateur.Relisez l'état actuel de la ressource avant toute nouvelle action.
MERCHANT_ALREADY_ACTIVELe partenaire est déjà actif.Relisez l'état actuel de la ressource avant toute nouvelle action.
MERCHANT_ALREADY_SUSPENDEDLe partenaire est déjà suspendu.Relisez l'état actuel de la ressource avant toute nouvelle action.
MERCHANT_HAS_APPLICATIONSLe partenaire possède encore des applications.Relisez l'état actuel de la ressource avant toute nouvelle action.
PAYMENT_ACCEPTANCE_REQUIREDCette transaction doit d'abord être acceptée avant de pouvoir être payée.Acceptez d'abord la transaction (POST …/accept), puis payez-la.
PAYMENT_FAILURE_REASON_LOCKEDMotif d'échec utilisé par la plateforme elle-même : il ne peut être que désactivé.Relisez l'état actuel de la ressource avant toute nouvelle action.
PAYMENT_NOT_CANCELLABLELa transaction n'est plus annulable (déjà prise en charge ou dénouée).Consultez le statut de la transaction : elle est déjà prise en charge ou dénouée.
RESOURCE_CONFLICTConflit avec l'état actuel de la ressource.Relisez l'état actuel de la ressource avant toute nouvelle action.
TERMINATION_ACCOUNT_IN_USECompte de terminaison encore associé à des partenaires.Relisez l'état actuel de la ressource avant toute nouvelle action.

422 · Règle métier

CodeSignificationAction recommandée
AMOUNT_ABOVE_MAXIMUMMontant supérieur au maximum autorisé.Respectez les bornes indiquées dans `details` (minimum, maximum, devise).
AMOUNT_BELOW_MINIMUMMontant inférieur au minimum autorisé.Respectez les bornes indiquées dans `details` (minimum, maximum, devise).
BANK_ACCOUNT_NOT_VERIFIEDCompte bancaire non vérifié auprès du core banking.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
BANK_TRANSACTION_NOT_SUBMITTEDLe virement n'a pas encore été envoyé au core banking.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
BANK_TRANSFER_NOT_CONFIGUREDConfiguration bancaire du partenaire incomplète pour effectuer le virement.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
BANK_TRANSFER_NOT_ELIGIBLECette transaction ne donne pas lieu à un virement.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
CURRENCY_NOT_SUPPORTEDDevise non prise en charge.Utilisez une devise prise en charge (XAF).
DESTINATION_PLAN_INACTIVECette formule get destination n'est plus proposée.Choisissez une formule encore proposée, ou saisissez durée et montant convenus.
INSUFFICIENT_WALLET_BALANCESolde du portefeuille insuffisant pour ce paiement.Rechargez le portefeuille du partenaire, ou enregistrez un paiement externe avec preuve.
INVALID_CURRENT_PASSWORDMot de passe actuel incorrect.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
INVALID_FEES_CONFIGBarème de frais incohérent.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
PAYMENT_NOT_SETTLEDLa transaction n'est pas réglée.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
UNPROCESSABLE_REQUESTRequête bien formée mais refusée par une règle métier.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
WEBHOOK_NOT_CONFIGUREDWebhook non configuré pour cette application.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.
WEBHOOK_URL_NOT_CONFIGUREDAucune URL de webhook n'est configurée.La règle métier refuse la demande : corrigez la donnée ou régularisez la situation décrite dans `message`, puis réessayez.

429 · Quota atteint

CodeSignificationAction recommandée
DESTINATION_QUOTA_EXCEEDEDLe nombre de recherches de la formule est atteint.Le quota de recherches de la période est épuisé : renouvelez ou changez de formule.
TOO_MANY_REQUESTSTrop de requêtes : réessayez après le délai indiqué par Retry-After.Réessayez après le délai de l'en-tête Retry-After, en étalant vos appels.
TRANSACTION_CAP_EXCEEDEDPlafond de transactions atteint pour ce partenaire ou cette application.Étalez vos envois : réessayez quand la fenêtre du plafond s'est libérée.

500 · Erreur interne

CodeSignificationAction recommandée
INTERNAL_ERRORErreur interne : réessayez plus tard ou contactez le support.Réessayez avec un délai croissant ; contactez le support si l'erreur persiste.

503 · Service indisponible

CodeSignificationAction recommandée
PROVIDER_UNAVAILABLEService partenaire (core banking, notifications) temporairement indisponible.Réessayez dans un instant avec un délai croissant ; avec la même clé d'idempotence pour une création.
SERVICE_UNAVAILABLEService temporairement indisponible.Réessayez dans un instant avec un délai croissant ; avec la même clé d'idempotence pour une création.