Paiements

Un paiement est une demande d’encaissement adressée à un client, sur un moyen de paiement donné. Il est enregistré à created, passe à pending dès que l’opérateur a répondu (la réponse de création porte déjà pending), puis se termine en confirmed, failed ou expired.

Créer un paiementCopier le lien de la section

curl -X POST "$API_URL/v1/payments" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: commande-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "5000",
    "currency": "XOF",
    "rail": "sn_wave",
    "merchant_reference": "commande-1042",
    "return_url": "https://boutique.example/paiement/retour",
    "customer_phone": "77 123 45 67"
  }'

Un champ absent de ce tableau est refusé : 400 INVALID_REQUEST, avec fields.<nom du champ>. Les champs de la réponse, comme payment_link_description, ne s’envoient pas.

RéponseCopier le lien de la section

201 à la création, 200 pour une requête rejouée avec la même Idempotency-Key et le même corps.

{
  "id": "8d1f0c6e-3b7a-4c55-9a51-2f0e5c1d7a90",
  "status": "pending",
  "amount": "5000",
  "currency": "XOF",
  "rail": "sn_wave",
  "merchant_reference": "commande-1042",
  "checkout_url": "https://…",
  "next_action": { "type": "redirect", "url": "https://…" },
  "created_at": "2026-10-07T10:00:00Z",
  "withdrawal_eligibility": "not_confirmed",
  "fee": null,
  "net": null,
  "livemode": false
}

Rediriger le client vers checkout_url. Sur Wave, next_action est une redirection (type redirect) vers la même page. livemode vaut false avec une clé de test, true avec une clé live. fee (frais) et net (montant crédité au marchand) sont renseignés à la confirmation.

Un paiement fait sur un lien de paiement porte en plus payment_link_description, la description du lien, à afficher à la place de merchant_reference (de la forme link:<lien>:<paiement>). Le champ est absent des autres paiements.

Action client : next_actionCopier le lien de la section

Selon l’opérateur, la réponse porte next_action, l’étape à accomplir par le client. checkout_url vaut alors null quand l’opérateur ne fournit pas de page.

L’issue arrive ensuite par webhook ou par relecture du paiement.

StatutsCopier le lien de la section

confirmed est définitif. withdrawal_eligibility passe alors à confirmed : le montant net peut être retiré.

Relire et listerCopier le lien de la section

curl "$API_URL/v1/payments/$PAYMENT_ID" -H "Authorization: Bearer $API_KEY"
curl "$API_URL/v1/payments?status=confirmed,failed&limit=20" -H "Authorization: Bearer $API_KEY"

GET /v1/payments/{id} ajoute au paiement error_code, error_message (dans la langue de Accept-Language), customer.phone et refunds.

Filtres de GET /v1/payments :

La réponse contient data, next_cursor et total_count.

Rejouer sans doublon : Idempotency-KeyCopier le lien de la section

L’en-tête Idempotency-Key est obligatoire sur POST /v1/payments (1 à 128 caractères). Une clé désigne une tentative logique, par exemple une commande.

• Même clé, même corps : le même paiement est renvoyé (200), jamais un second.
• Même clé, corps différent : 409 IDEMPOTENCY_CONFLICT, rien n’est créé.
• Une clé ne vaut que pour la route où elle a servi.

Après un délai d’attente ou une coupure réseau, renvoyer exactement la même requête avec la même clé. merchant_reference est unique par projet : une référence déjà utilisée avec une autre clé renvoie 409 DUPLICATE_MERCHANT_REFERENCE.

Issue inconnueCopier le lien de la section

Une coupure peut rendre l’issue d’un paiement incertaine. 221 Pay ne redemande jamais un paiement de lui-même : un double encaissement est exclu.

Un paiement unknown ne crédite le solde qu’une fois confirmé.

Erreurs fréquentesCopier le lien de la section

Table complète : Erreurs.