Remboursements

Un remboursement renvoie de l’argent au client, sur le numéro mobile qui a payé. Il est prélevé sur le solde disponible du marchand. Il se fait en deux temps : un devis (montants figés, aucun mouvement d’argent), puis le remboursement.

ConditionsCopier le lien de la section

• Le paiement est confirmed.
• Le paiement a été créé avec customer_phone : sans numéro du client, rembourser est impossible.
• Le montant ne dépasse pas le reste remboursable (montant du paiement moins les remboursements déjà faits ou en cours). Les remboursements partiels sont possibles. Au-delà : 400 INVALID_REQUEST avec fields.amount, qui donne le reste remboursable.
• Le solde disponible couvre le montant prélevé (merchant_debited).

La vérification d’identité n’est pas exigée pour rembourser.

1. Obtenir un devisCopier le lien de la section

curl -X POST "$API_URL/v1/refund-quotes" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "8d1f0c6e-3b7a-4c55-9a51-2f0e5c1d7a90",
    "amount": "5000",
    "fee_payer": "merchant"
  }'

{
  "payment_id": "8d1f0c6e-3b7a-4c55-9a51-2f0e5c1d7a90",
  "amount": "5000",
  "fee": "…",
  "customer_receives": "5000",
  "merchant_debited": "…",
  "fee_payer": "merchant",
  "quote_hash": "a3f9…",
  "expires_at": "2026-10-07T10:02:00Z"
}

Le devis expire après 2 minutes. Le présenter avant confirmation : il donne les montants exacts.

Qui paie les frais : fee_payerCopier le lien de la section

Sans fee_payer, le réglage par défaut du projet s’applique.

2. RembourserCopier le lien de la section

Reprendre les valeurs du devis, ajouter reason et une Idempotency-Key :

curl -X POST "$API_URL/v1/refunds" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Idempotency-Key: remboursement-commande-1042" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_id": "8d1f0c6e-3b7a-4c55-9a51-2f0e5c1d7a90",
    "amount": "5000",
    "fee_payer": "merchant",
    "reason": "customer_request",
    "quote_hash": "a3f9…"
  }'

Un devis ne sert qu’une fois. Expiré : 409 QUOTE_EXPIRED. Inconnu, déjà utilisé ou différent de la requête (autre montant, autre fee_payer) : 409 QUOTE_INVALID. Le message est aussi dans fields.quote_hash. Demander alors un nouveau devis. IDEMPOTENCY_CONFLICT ne désigne plus que la clé Idempotency-Key réutilisée avec un autre corps.

Réponse : 201 à la création, 200 pour une requête rejouée avec la même clé et le même corps.

{
  "id": "c27e5a10-6f8b-4d2c-b1e3-7a9d0f4c8e21",
  "payment_id": "8d1f0c6e-3b7a-4c55-9a51-2f0e5c1d7a90",
  "status": "processing",
  "amount": "5000",
  "currency": "XOF",
  "fee": "…",
  "customer_receives": "5000",
  "merchant_debited": "…",
  "fee_payer": "merchant",
  "reason": "customer_request",
  "created_at": "2026-10-07T10:01:00Z",
  "updated_at": "2026-10-07T10:01:01Z"
}

StatutsCopier le lien de la section

Relire et listerCopier le lien de la section

curl "$API_URL/v1/refunds/$REFUND_ID" -H "Authorization: Bearer $API_KEY"
curl "$API_URL/v1/refunds?payment_id=$PAYMENT_ID" -H "Authorization: Bearer $API_KEY"

Filtres : payment_id, status, from, to, limit, offset. GET /v1/payments/{id} liste aussi les remboursements du paiement dans refunds.

Réglage par défaut du projetCopier le lien de la section

curl "$API_URL/v1/settings" -H "Authorization: Bearer $API_KEY"

curl -X PUT "$API_URL/v1/settings" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"refund_fee_payer_default": "customer"}'

refund_fee_payer_default vaut merchant ou customer. Chaque changement est journalisé. Le même réglage est disponible dans le tableau de bord, rubrique Remboursements.

Le taux des frais de remboursement : voir Frais.