Commencer
Cette page est servie par votre instance CashLink. La même adresse constitue la base de l’API.
| Surface | Préfixe | Usage |
|---|---|---|
| API marchand | /api/v1 | Intégration de paiement côté serveur. |
| Administration | /admin/v1 | Utilisateurs, marchands, opérations et configuration. |
| Espace marchand | /merchant/v1 | Applications, secrets, webhooks, transactions et comptes DAP. |
| État du service | /up | Point 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.
/v1 est maintenu pour les intégrations existantes. Toute nouvelle intégration doit utiliser /api/v1./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.
/api/v1/meVé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
| Cas | HTTP | Corps |
|---|---|---|
| Lecture ou transition | 200 | La ressource directement. |
| Création | 201 | La ressource créée. |
| Liste | 200 | data et pagination. |
| Suppression / enregistrement du FCM token | 204 | Corps 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.
/api/v1/paymentsCrée une demande. Envoyez un en-tête Idempotency-Key unique pour éviter les doublons lors d’une reprise réseau.
/api/v1/paymentsListe paginée. Filtres disponibles : from, to, per-page, page, status et reference.
/api/v1/payments/{paymentId}Retourne les détails et la chronologie de la transaction.
/api/v1/payments/{paymentId}/cancelAnnule une demande tant qu’elle n’est pas prise en charge.
| Opération | Requête | Succès | Erreurs usuelles |
|---|---|---|---|
| Créer | external_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. |
| Lister | Query : from, to, status, reference, page, per_page. | 200 · liste paginée. | 400 INVALID_REQUEST si un filtre est mal formé. |
| Consulter | Paramè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. |
| Annuler | Corps 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.
/agent/login-pinConnexion agent avec login (téléphone ou compte flotte) et pin. Le FCM token ne fait pas partie de cette requête.
/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).
/agent/pin/forgotPIN 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.
/agent/pin/resetPIN oublié, étape 2 : vérifie le code (10 minutes, 5 tentatives) et pose le nouveau PIN. Révoque toutes les sessions de l’agent.
/agent/v1/meProfil de l’agent authentifié — même forme que le bloc agent de la connexion.
/agent/v1/pinRemplace obligatoirement le PIN initial avant toute action de traitement.
/agent/v1/deviceEnregistre ou renouvelle le fcm_token après connexion ; il est facultatif, mais conditionne la notification push (voir plus bas).
/agent/v1/paymentsListe 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.
/agent/v1/payments/get-traited-paymentListe 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.
/agent/v1/withdrawal-codes/lookupPaiement 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.
/agent/v1/withdrawal-codes/settlePiè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.
/agent/v1/payments/{paymentId}Détail d’une transaction affectée à l’agent (403 sinon).
/agent/v1/payments/{paymentId}/eventsHistorique paginé des transitions de la transaction affectée.
/agent/v1/payments/{paymentId}/acceptAcceptation 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.
/agent/v1/payments/{paymentId}/processPrend 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.
/agent/v1/payments/{paymentId}/succeedAprè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).
/agent/v1/payments/{paymentId}/failRé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.
/agent/v1/payments/{paymentId}/releaseLibè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.
/agent/v1/availabilityEn 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.
/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.
/agent/v1/smsSMS 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).
/agent/v1/payments/{paymentId}/refuseDé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ération | Entrée | Succès | Erreurs |
|---|---|---|---|
| Connexion PIN | login = 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 agent | GET /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é · demande | login = 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érification | login, 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. |
| Profil | Aucune (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 PIN | current_pin, pin, pin_confirmation (5 chiffres). | 200 · profil avec pin_must_be_changed: false. | 403 FORBIDDEN si PIN actuel incorrect. |
| Enregistrer appareil | fcm_token (20-255 car.), device_name facultatif. | 204 · aucun corps. | 422 token absent ou trop court/long. |
| Voir la file | Query 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 / historique | Aucune (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 charge | pin (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éussite | pin 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. |
| Échec | pin 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ées | Query 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érer | POST /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. |
| Refuser | Aucune (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. |
- 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/forgotpuis/agent/pin/resets’il l’a perdu. - 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. - Effectuer le paiement manuellement. Réalisez l’opération chez l’opérateur choisi et récupérez sa référence.
- Rendre compte. Appelez
succeedoufail. CashLink historise l’agent, les dates et la référence. Aprèssucceed, le marchand n’est notifié du succès qu’une fois le SMS de l’opérateur rapproché ; aprèsfail, 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érateur | Gabarit 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 synchroniser | Quoi 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 serveur | Les nouveaux SMS de ces expéditeurs. Si le SMS de l’opérateur n’est pas encore arrivé, il partira à la synchronisation suivante. |
/agent/v1/smsJeton agent requis. Lots de 200 SMS au plus : découpez au-delà.
| Champ | Obligatoire | Description |
|---|---|---|
device_name | non | Nom du téléphone (ex. "Tecno Spark 10"), affiché dans la console. |
messages[].local_id | oui | Identifiant du SMS dans le téléphone (repris tel quel dans la réponse). |
messages[].sender | oui | Expéditeur tel que lu : OrangeMoney ou MobileMoney. Les autres sont refusés (rejected) : ne les envoyez pas. |
messages[].body | oui | Texte complet du SMS, sans modification (5 000 caractères max). |
messages[].received_at | oui | Date de réception Android, en millisecondes epoch. |
messages[].sent_at | non | Date d’envoi par l’opérateur (ms epoch), si disponible. |
messages[].line_msisdn | fortement 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é (
acceptedouduplicate) 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é.
/api/v1/get-destinatorCorps 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ègle | Détail |
|---|---|
| Accès | Le 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. |
| Abonnement | Un 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écompte | Une 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 test | Réponse simulée ("sandbox": true, titulaire TITULAIRE TEST) : aucun abonnement requis, aucun décompte, aucun appel au core banking. |
| Numéros pris en charge | Camerounais uniquement (+237 + 9 chiffres). Autre format : 400 INVALID_PHONE_NUMBER. |
| Suivi | Espace 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 · code | Cause | Action |
|---|---|---|
400 INVALID_PHONE_NUMBER | Numéro absent, mal formé ou hors +237. | Envoyer +237 suivi de 9 chiffres. |
403 DESTINATION_NOT_ENABLED | Service non ouvert pour votre compte. | Demander l’activation à votre interlocuteur. |
403 DESTINATION_SUBSCRIPTION_REQUIRED | Aucun abonnement en cours (jamais souscrit ou expiré). | Demander le renouvellement. |
404 DESTINATION_NOT_FOUND | Aucun compte pour ce numéro. | Vérifier le numéro (la recherche est décomptée). |
429 DESTINATION_QUOTA_EXCEEDED | Recherches de la période épuisées. | Renouveler ou changer de formule. |
429 TOO_MANY_REQUESTS | Quota de requêtes par minute de l’application. | Réessayer après Retry-After. |
503 PROVIDER_UNAVAILABLE | Core 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ête | Rôle |
|---|---|
X-Webhook-Signature | Signature HMAC du corps transmis. |
X-Webhook-Id | Identifiant de l’événement, à conserver pour dédupliquer. |
X-Webhook-Timestamp | Horodatage Unix pris en compte dans la signature. |
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ération | Requête | Succès | Erreurs usuelles |
|---|---|---|---|
| Créer un agent | POST /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 / suspendre | PUT /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 test | PUT /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ées | POST /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 ligne | PUT /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 agents | GET /admin/v1/agents/statistics. | 200 · rang, volumes et durées moyennes par agent. | 403 permission manquante. |
| Superviser paiements | GET /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 agent | POST / 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 agent | POST /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érateur | GET /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’agent | Un 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 potentiels | Une 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’agent | POST /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ée | POST /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ée | POST /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ée | POST /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 code | POST /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 mode | GET /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 temps | GET / 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 paiements | GET /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 paiements | GET /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 bord | GET /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 heure | GET /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 application | PUT /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 plafond | PUT /admin/v1/settings/payments : {"maximum_amount": 5000000}. | 200 · {"maximum_amount":5000000}. | 400 montant invalide, 403 permission manquante. |
| Alertes de solde — destinataires internes | GET / 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édit | PUT /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 solde | PUT /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 partenaire | GET /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 / corriger | POST …/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 solde | GET …/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 bancaire | GET /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.
- Connectez-vous. Selon votre profil, vous accédez à l’espace d’administration ou au portail marchand.
- Créez ou ouvrez un marchand. Ajoutez ses coordonnées, puis contrôlez son statut avant toute utilisation de l’API.
- 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.
- Configurez le webhook. Définissez son URL, activez-le et conservez le secret de signature dans un coffre de secrets.
- Suivez les opérations. Les agents font passer les paiements en traitement puis enregistrent leur issue ; la chronologie est disponible sur chaque transaction.
- 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/paymentsavec{"maximum_amount": 5000000}.
| Rôle interne | Accès principal |
|---|---|
super_admin, admin | Paramétrage, utilisateurs, marchands et supervision complète. |
operator, agent | Traitement et suivi opérationnel des paiements. |
support, viewer | Consultation 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}.
| Statut | Famille | À retenir |
|---|---|---|
400 | Requête invalide | Format incorrect : corrigez puis renvoyez. |
401 | Authentification | Jeton absent, invalide ou expiré : reconnectez-vous. |
403 | Accès refusé | Compte, application, adresse IP ou service non autorisé : inutile de réessayer à l’identique. |
404 | Introuvable | Identifiant ou référence inconnu. |
409 | Conflit d’état | Relisez l’état de la ressource avant d’agir. |
422 | Règle métier | La requête est bien formée mais refusée par une règle : lisez message. |
429 | Quota atteint | Patientez (Retry-After) et étalez vos appels. |
500 / 503 | Incident | Réessayez avec un délai croissant (même clé d’idempotence pour une création). |
94 codes
400 · Requête invalide
| Code | Signification | Action recommandée |
|---|---|---|
INVALID_AMOUNT | Montant 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_NUMBER | Numéro de compte bancaire invalide. | Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la. |
INVALID_COUNTRY_CODE | Code pays invalide (ISO 3166-1 alpha-2 attendu). | Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la. |
INVALID_CURRENCY | Code devise invalide (ISO 4217 sur trois lettres attendu). | Utilisez une devise prise en charge (XAF). |
INVALID_IDEMPOTENCY_KEY | Clé d'idempotence mal formée. | Ajoutez l'en-tête Idempotency-Key (valeur unique par création, UUID conseillé). |
INVALID_IP_ADDRESS | Adresse IP ou plage CIDR invalide. | Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la. |
INVALID_PHONE_NUMBER | Numéro de téléphone invalide (format international attendu, ex. +2376XXXXXXXX). | Envoyez le numéro au format international E.164, ex. +237690123456. |
INVALID_REQUEST | Requê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_URL | URL de webhook invalide (HTTPS public attendu). | Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la. |
MISSING_IDEMPOTENCY_KEY | En-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_PARAMETER | Un paramètre obligatoire est absent. | Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la. |
WEAK_PASSWORD | Mot de passe trop faible. | Corrigez la requête (le champ fautif est dans `field`) puis renvoyez-la. |
401 · Authentification
| Code | Signification | Action recommandée |
|---|---|---|
INVALID_CREDENTIALS | Identifiants 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_OTP | Code de vérification (OTP) incorrect ou expiré. | Authentifiez-vous à nouveau puis renvoyez la requête. |
TOKEN_EXPIRED | Jeton 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_INVALID | Jeton d'accès invalide. | Obtenez un nouveau jeton (POST /v1/auth) et renvoyez la requête avec l'en-tête Authorization: Bearer. |
TOKEN_MISSING | Jeton 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_REVOKED | Jeton d'accès révoqué. | Obtenez un nouveau jeton (POST /v1/auth) et renvoyez la requête avec l'en-tête Authorization: Bearer. |
UNAUTHENTICATED | Authentification 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é
| Code | Signification | Action recommandée |
|---|---|---|
ACCOUNT_SUSPENDED | Le compte utilisateur est suspendu. | Contactez votre interlocuteur pour faire lever la suspension ; inutile de réessayer avant. |
APPLICATION_SUSPENDED | L'application est suspendue. | Contactez votre interlocuteur pour faire lever la suspension ; inutile de réessayer avant. |
DESTINATION_NOT_ENABLED | Le 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_REQUIRED | Aucun 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). |
FORBIDDEN | Action 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_PERMISSIONS | Permissions 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_ALLOWED | Adresse 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_SUSPENDED | Le compte partenaire est suspendu. | Contactez votre interlocuteur pour faire lever la suspension ; inutile de réessayer avant. |
PAYMENT_NOT_ASSIGNED | Cette 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
| Code | Signification | Action recommandée |
|---|---|---|
ADMIN_USER_NOT_FOUND | Utilisateur back-office introuvable. | Vérifiez l'identifiant ou la référence fournie. |
APPLICATION_NOT_FOUND | Application introuvable. | Vérifiez l'identifiant ou la référence fournie. |
BANK_ACCOUNT_NOT_FOUND | Compte bancaire introuvable auprès du core banking. | Vérifiez l'identifiant ou la référence fournie. |
BANK_TRANSACTION_NOT_FOUND | Virement bancaire introuvable. | Vérifiez l'identifiant ou la référence fournie. |
DAP_CREDENTIALS_NOT_FOUND | Identifiants du core banking (DAP) non configurés. | Vérifiez l'identifiant ou la référence fournie. |
DEFAULT_TERMINATION_ACCOUNT_NOT_FOUND | Aucun compte de terminaison par défaut n'est configuré. | Vérifiez l'identifiant ou la référence fournie. |
DESTINATION_NOT_FOUND | Aucun 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_FOUND | Formule get destination introuvable. | Vérifiez l'identifiant ou la référence fournie. |
MERCHANT_NOT_FOUND | Partenaire introuvable. | Vérifiez l'identifiant ou la référence fournie. |
MERCHANT_TERMINATION_NOT_FOUND | Aucun compte de terminaison associé à ce partenaire. | Vérifiez l'identifiant ou la référence fournie. |
OPERATION_ACCOUNT_NOT_FOUND | Compte d'opération introuvable. | Vérifiez l'identifiant ou la référence fournie. |
PAYMENT_FAILURE_REASON_NOT_FOUND | Motif d'échec introuvable. | Vérifiez l'identifiant ou la référence fournie. |
PAYMENT_NOT_FOUND | Transaction introuvable. | Vérifiez l'identifiant ou la référence fournie. |
RESOURCE_NOT_FOUND | Ressource introuvable. | Vérifiez l'identifiant ou la référence fournie. |
TERMINATION_ACCOUNT_NOT_FOUND | Compte de terminaison introuvable. | Vérifiez l'identifiant ou la référence fournie. |
TRANSACTION_FEES_NOT_FOUND | Aucun 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_INVALID | Code 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
| Code | Signification | Action recommandée |
|---|---|---|
METHOD_NOT_ALLOWED | Méthode HTTP non autorisée sur cette route. | Utilisez la méthode HTTP documentée pour cette route. |
409 · Conflit d’état
| Code | Signification | Action recommandée |
|---|---|---|
ACCOUNT_ALREADY_ACTIVE | Le compte est déjà actif. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
ACCOUNT_ALREADY_SUSPENDED | Le compte est déjà suspendu. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
AGENT_PAYMENT_IN_PROGRESS | L'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_ACTIVE | L'application est déjà active. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
APPLICATION_ALREADY_SUSPENDED | L'application est déjà suspendue. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
BANK_TRANSACTION_NOT_SUBMITTABLE | Le virement ne peut pas être (ré)envoyé dans son état actuel. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
CANNOT_TARGET_SELF | Action impossible sur votre propre compte. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
DUPLICATE_APPLICATION_NAME | Une application porte déjà ce nom. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
DUPLICATE_DESTINATION_PLAN | Une formule get destination porte déjà ce code. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
DUPLICATE_EXTERNAL_REFERENCE | Une 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_NAME | Un partenaire porte déjà ce nom. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
DUPLICATE_PAYMENT_FAILURE_REASON | Un motif d'échec porte déjà ce code. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
DUPLICATE_TERMINATION_ACCOUNT | Un 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_USED | Adresse e-mail déjà utilisée. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
IDEMPOTENCY_CONFLICT | Clé 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_PENDING | Une 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_TRANSITION | Changement de statut non autorisé depuis le statut actuel. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
LAST_SUPER_ADMIN | Impossible de retirer le dernier super administrateur. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
MERCHANT_ALREADY_ACTIVE | Le partenaire est déjà actif. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
MERCHANT_ALREADY_SUSPENDED | Le partenaire est déjà suspendu. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
MERCHANT_HAS_APPLICATIONS | Le partenaire possède encore des applications. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
PAYMENT_ACCEPTANCE_REQUIRED | Cette 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_LOCKED | Motif 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_CANCELLABLE | La 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_CONFLICT | Conflit avec l'état actuel de la ressource. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
TERMINATION_ACCOUNT_IN_USE | Compte de terminaison encore associé à des partenaires. | Relisez l'état actuel de la ressource avant toute nouvelle action. |
422 · Règle métier
| Code | Signification | Action recommandée |
|---|---|---|
AMOUNT_ABOVE_MAXIMUM | Montant supérieur au maximum autorisé. | Respectez les bornes indiquées dans `details` (minimum, maximum, devise). |
AMOUNT_BELOW_MINIMUM | Montant inférieur au minimum autorisé. | Respectez les bornes indiquées dans `details` (minimum, maximum, devise). |
BANK_ACCOUNT_NOT_VERIFIED | Compte 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_SUBMITTED | Le 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_CONFIGURED | Configuration 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_ELIGIBLE | Cette 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_SUPPORTED | Devise non prise en charge. | Utilisez une devise prise en charge (XAF). |
DESTINATION_PLAN_INACTIVE | Cette formule get destination n'est plus proposée. | Choisissez une formule encore proposée, ou saisissez durée et montant convenus. |
INSUFFICIENT_WALLET_BALANCE | Solde du portefeuille insuffisant pour ce paiement. | Rechargez le portefeuille du partenaire, ou enregistrez un paiement externe avec preuve. |
INVALID_CURRENT_PASSWORD | Mot 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_CONFIG | Barè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_SETTLED | La 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_REQUEST | Requê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_CONFIGURED | Webhook 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_CONFIGURED | Aucune 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
| Code | Signification | Action recommandée |
|---|---|---|
DESTINATION_QUOTA_EXCEEDED | Le 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_REQUESTS | Trop 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_EXCEEDED | Plafond 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
| Code | Signification | Action recommandée |
|---|---|---|
INTERNAL_ERROR | Erreur 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
| Code | Signification | Action recommandée |
|---|---|---|
PROVIDER_UNAVAILABLE | Service 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_UNAVAILABLE | Service temporairement indisponible. | Réessayez dans un instant avec un délai croissant ; avec la même clé d'idempotence pour une création. |