Erreurs

Les erreurs renvoient un statut HTTP différent de 2xx et une enveloppe où success vaut false :

{
  "success": false,
  "message": "Insufficient permissions. Required scope: pay",
  "request_id": "b2f1c3a0-...",
  "required_scopes": ["pay"]
}

Branchez toujours votre logique sur le code de statut HTTP et affichez message pour le débogage. Journalisez request_id : indiquez-le lorsque vous contactez le support.

Codes de statut

Code	Signification	Causes fréquentes
`200`	OK	Lecture réussie ou écriture synchrone
`201`	Created	Ressource créée (payout, bénéficiaire, webhook, …)
`202`	Accepted	Traitement asynchrone démarré — pas encore réglé (`/pay`, `/process` d’un lot)
`400`	Bad Request	Champs manquants ou invalides, refus de l’opérateur, solde insuffisant
`401`	Unauthorized	Token ou clé API manquant, invalide ou expiré
`403`	Forbidden	Scope requis absent du token, compte inactif, ou IP hors liste blanche
`404`	Not Found	L’identifiant n’existe pas ou ne vous appartient pas
`409`	Conflict	`reference` en double, ou slug déjà pris
`429`	Too Many Requests	Limite de débit atteinte (ex. `/auth` : 20 par 15 min)
`500`	Server Error	Erreur inattendue — réessayez avec un délai croissant, puis contactez le support

Idempotence et doublons

/pay et /deposit acceptent une reference. Si vous renvoyez une requête avec une reference déjà utilisée, vous recevez un 409 accompagné de la transaction existante :

{
  "success": false,
  "message": "Transaction with this reference already exists",
  "existing_transaction": { "id": 88213, "status": "pending" }
}

Définissez toujours une reference stable et unique par transaction logique, afin qu’une nouvelle tentative ne crée pas de double débit.

Gérer les paiements en attente

Un 202 renvoyé par /pay n’est pas un paiement abouti. Interrogez GET /merchant/api/transactions/{id} ou attendez le webhook payment_received. Voir Statut d’un paiement. Les valeurs de status que vous pouvez rencontrer :

Statut	Signification
`pending`	Demande envoyée ; en attente de confirmation du client
`processing`	Règlement en cours
`success`	Abouti et crédité
`failed`	Refusé ou impossible à finaliser
`cancelled`	Annulé avant la fin
`reversed`	Abouti puis contrepassé
`expired`	Le client n’a pas confirmé à temps

Démarrer

Guides

Codes de statut

Idempotence et doublons

Gérer les paiements en attente

​Codes de statut

​Idempotence et doublons

​Gérer les paiements en attente

Codes de statut

Idempotence et doublons

Gérer les paiements en attente