Remboursements

Un remboursement renvoie le montant intégral d’un paiement réussi sur le portefeuille du client. Il n’y a pas de remboursement partiel.

curl -s -X POST http://localhost:4000/v1/payments/$PAYMENT_ID/refunds \
  -H "Authorization: Bearer $XAALIS_KEY" \
  -H "Idempotency-Key: refund:order_1042"

{ "id": "re_…", "object": "refund", "payment_id": "pay_…", "amount": 15000, "currency": "XOF",
  "status": "succeeded", "fee_refunded": 0, "created_at": "…" }

• L’Idempotency-Key est obligatoire. Répéter la requête renvoie le même remboursement : un paiement ne peut jamais être remboursé deux fois, quel que soit le nombre de nouvelles tentatives.
• Seuls les paiements Wave réussis peuvent être remboursés (le mode test simule Wave).
• GET /v1/payments/{id}/refunds renvoie le remboursement (une liste de zéro ou un élément) : utilisez-le pour vérifier une issue sans relancer la requête.

Qui paie les frais

Le client récupère toujours le montant brut. Par défaut, Xaalis conserve ses frais : votre solde available doit donc couvrir le montant brut.

Paiement	Vos frais	Débité de votre solde	Reçu par le client
15 000	225	15 000	15 000

fee_refunded indique les frais que Xaalis a restitués (0 avec la politique par défaut). Si votre solde ne suffit pas, la requête échoue avec 422 insufficient_funds et rien ne se passe ; relancez une fois les fonds arrivés.

Statuts

status	Signification	Ce que vous faites
succeeded	l’argent est revenu au client ; le paiement est désormais refunded	rien — vous recevez aussi payment.refunded
pending	la réponse du prestataire n’est pas encore connue (l’API a pu renvoyer 503)	attendez payment.refunded, ou relancez avec la même clé
needs_review	le prestataire a refusé ; le montant reste réservé sur votre solde	contactez Xaalis : un opérateur effectue le rapprochement avec le prestataire

Une facture d’abonnement remboursée reste payée ; le remboursement ne relance pas son cycle de facturation.