Authentification

Toutes les routes /v1/* s'authentifient par clé API :

Authorization: Bearer sk_live_...

X-API-Key: sk_live_... est accepté à l'identique, pour les clients HTTP qui réservent Authorization à autre chose.

Clés test et clés live

Préfixe	Mode	Argent réel
sk_test_…	Test	Non — tout le code s'exécute (routage, frais, validations), aucun mouvement d'argent
sk_live_…	Production	Oui

Les objets créés en mode test portent is_test: true et n'apparaissent jamais dans vos rapports de production.

Le mode test ne couvre pas le paiement instantané. Les familles PI et tontine refusent les clés de test : elles parlent à un système externe qui n'a pas de bac à sable chez nous.

Le secret n'existe qu'une fois

À la création (ou à la rotation) d'une clé, le secret est affiché une seule fois. Côté serveur, seule son empreinte HMAC est stockée : personne — pas même le support — ne peut vous le redonner. Perdu ? Faites une rotation : l'ancienne clé est révoquée, la nouvelle est affichée une fois.

Pourquoi ma clé répond client_inactive ?

Une clé s'émet dès l'inscription, mais elle n'admet aucun appel tant que le compte n'est pas validé (dossier KYB approuvé, compte en statut active). C'est la porte de conformité : elle s'ouvre à la validation et se referme immédiatement en cas de suspension — la même clé, sans autre changement.

Portées

Chaque clé porte des portées, et une opération hors portée répond 403 insufficient_scope : encaisser, verser, rembourser, lire, gérer les webhooks. Émettez la clé la plus étroite qui fasse le travail — une clé de lecture pour vos rapports n'a pas besoin de pouvoir verser.

Idempotence

Sur les créations (POST /v1/payments, POST /v1/payouts, POST /v1/refunds…), passez un en-tête Idempotency-Key de votre choix — par exemple votre référence de commande. Un rejeu avec la même clé renvoie l'opération d'origine, jamais un doublon ; la même clé avec une charge utile différente est refusée en 409.

Une clé par opération, jamais par objet parent. Un encaissement peut être remboursé en plusieurs fois : une clé d'idempotence portant l'identifiant du paiement ferait passer le second remboursement partiel pour un rejeu du premier. Succès côté marchand, client non remboursé.

Limite de débit

300 requêtes par minute et par clé. Au-delà, 429 avec un en-tête Retry-After — honorez-le plutôt que de réessayer immédiatement.

Bonnes pratiques

• Une clé par environnement (production, staging), jamais partagée entre services.
• Le secret vit dans un gestionnaire de secrets, jamais dans le code ni dans le front.
• Rotation immédiate au moindre doute — sans coupure si vous déployez la nouvelle clé avant de révoquer l'ancienne.