Paiements

L’objet payment représente un mouvement monétaire entre deux parties. Tous les montants sont en XOF entiers.

Endpoints

POST/paymentsCréer un paiement

GET/paymentsLister

GET/payments/:idDétail

POST/payments/:id/refundRembourser

L’objet Payment

{
  "id":          "pay_3K2x9Vp",
  "object":      "payment",
  "amount":      5000,
  "currency":    "XOF",
  "fee":         50,
  "status":      "succeeded",
  "description": "Repas — Chez Wend-Kuni",
  "method":      "wallet",
  "customer":    "+22670111213",
  "merchant":    "mer_5K4z2Yp",
  "metadata":    { "order_id": "WK-1042" },
  "created_at":  "2026-05-30T14:32:14Z",
  "settled_at":  "2026-05-30T14:32:18Z"
}

Champs clefs

| Champ | Type | Description | |--------------|---------|-------------------------------------------------| | amount | int | Montant en XOF (entier ≥ 100) | | currency | string | Toujours "XOF" actuellement | | method | enum | wallet, qr, orange_money, moov_money | | status | enum | pending, succeeded, failed, refunded | | customer | string | Numéro ou ID utilisateur Royal Finance | | metadata | object | Libre, max 20 clés, valeurs ≤ 500 caractères |

Créer un paiement

curl -X POST https://api.royalstack.com/api/v1/payments \
  -H "Authorization: Bearer rs_test_••••" \
  -H "Idempotency-Key: 7f3d-9a12" \
  -H "Content-Type: application/json" \
  -d '{
    "amount":      5000,
    "currency":    "XOF",
    "description": "Repas — Chez Wend-Kuni",
    "customer":    "+22670111213",
    "method":      "wallet",
    "metadata":    { "order_id": "WK-1042" }
  }'

N’utilisez jamais l’Idempotency-Key pour deux paiements distincts — vous recevrez la première réponse, sans vrai second prélèvement.

Rembourser

curl -X POST https://api.royalstack.com/api/v1/payments/pay_3K2x9Vp/refund \
  -H "Authorization: Bearer rs_test_••••" \
  -d '{ "amount": 5000, "reason": "duplicate" }'

amount est optionnel. Sans amount, le remboursement est total.