Royal Finance
ParticuliersBusinessEntrepriseDéveloppeursDocumentationContact

Connexion / inscription

Espace client
Se connecterS’inscrire
Espace marchand
Se connecterS’inscrire
Espace développeur
Se connecterS’inscrire

Documentation API

Bienvenue dans la documentation de l’API Royal Finance. Notre API REST vous permet d’encaisser, transférer, gérer des wallets XOF et réagir aux événements via des webhooks signés. La devise est le franc CFA (XOF) et tous les montants sont exprimés en unités entières (pas de centimes).

La documentation est en français. Les exemples utilisent curl, mais l’API est utilisable depuis n’importe quel client HTTP.

URL de base

L’API est versionnée par préfixe URL. La version courante est v1.

GEThttps://api.royalstack.com/api/v1
GEThttp://localhost:3000/api/v1

Premiers pas en 3 minutes

  1. Créez un compte développeur depuis /developers/signup. Une clé rs_test_… vous est envoyée par email.
  2. Lancez votre premier appel depuis la sandbox, ou en local :
curl https://api.royalstack.com/api/v1/wallets/me \
  -H "Authorization: Bearer rs_test_••••"
  1. Branchez un webhook pour recevoir l’événement payment.succeeded — voir Webhooks.

Format des réponses

Toutes les réponses sont en application/json; charset=utf-8. Les codes HTTP suivent la sémantique standard :

| Code | Sens | |------|----------------------------| | 200 | Succès | | 201 | Ressource créée | | 400 | Requête invalide | | 401 | Authentification manquante | | 403 | Permission insuffisante | | 404 | Ressource introuvable | | 409 | Conflit (idempotency) | | 422 | Validation | | 429 | Rate limit | | 5xx | Erreur serveur |

Le corps d’erreur suit toujours cette forme :

{
  "error": {
    "code":    "validation_failed",
    "message": "Le champ \"amount\" doit être positif.",
    "field":   "amount"
  }
}

Idempotence

Sur tous les POST qui créent une ressource financière, envoyez un header Idempotency-Key. Royal Finance déduplique les requêtes identiques pendant 24h — vous pouvez rejouer une requête sans risque de double prélèvement.

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", "customer": "+22670111213" }'

Et après ?