Trois appels et une notification : l’API BitriPay

La plupart des intégrations de paiement sont de l’archéologie. Vous lisez la documentation, découvrez qu’elle décrit l’API de l’an dernier, et apprenez le comportement réel dans les messages d’erreur, en production, à onze heures du soir.

Nous avons pris tôt une décision qui supprime l’essentiel de cela : la documentation est produite à partir de la même table qui sert les requêtes.

Une table, deux rendus

Il existe une seule liste d’opérations à l’intérieur de la plateforme. Le document OpenAPI en est produit. La référence lisible en est produite. Les requêtes en sont servies.

Ce n’est pas une politique de documentation, c’est une décision d’architecture, et elle a une conséquence précise : la référence ne peut pas décrire un point de terminaison qui n’existe pas, et un point de terminaison ne peut pas exister sans apparaître dans la référence. Ce sont deux rendus du même objet.

Une idempotence qui refuse réellement

Chaque POST qui déplace de l’argent exige une clé d’idempotence.

Envoyez deux fois la même clé avec le même corps et vous récupérez l’objet d’origine — pas de second paiement. Envoyez la même clé avec un corps différent et la requête est refusée, avec une erreur précise, au lieu de créer quelque chose en silence.

C’est cette seconde règle qui compte. Une collision de clés dans votre code est un bug qui apparaîtrait autrement sous forme de double débit mystérieux des semaines plus tard. Ici il apparaît comme un 409 avec un message lisible, pendant les tests, là où les bugs sont bon marché.

Des notifications signées deux fois

Chaque livraison porte un HMAC-SHA256 horodaté sur le corps exact, avec le secret propre à votre point de terminaison. Elle porte aussi une signature Ed25519 de la clé de la plateforme, que vous pouvez récupérer dans un registre public gérant la rotation.

Vérifiez l’une. Vérifiez les deux. Rejetez tout horodatage de plus de cinq minutes et le rejeu est fermé.

La livraison est au moins une fois, selon un calendrier de reprise publié qui s’étale sur 24 heures, et chaque événement a un identifiant pour la déduplication. Nous disons « au moins une fois » parce que c’est le cas ; un prestataire qui promet « exactement une fois » décrit une chose qu’il ne peut pas livrer.

Des erreurs sur lesquelles brancher

Chaque échec renvoie error.code — descriptif, pour un humain qui lit un journal — et error.bp, une famille numérique stable : authentification, validation, grand livre, rail, conformité, intelligence.

Branchez sur la famille. Elle ne change pas quand nous améliorons un message, et elle n’oblige pas votre code à analyser de l’anglais.

Un bac à sable qui échoue correctement

Les clés de test pilotent la même machine d’états que la production. Le bac à sable publie des numéros magiques pour des issues précises : succès, solde insuffisant, délai dépassé puis succès.

Ce dernier est celui que personne d’autre ne vous donne, et c’est celui qui trouve le bug de votre logique de reprise avant vos clients.

Par où commencer

La référence est sur /developers/api — chaque opération avec sa portée, ses paramètres, ses champs et un exemple prêt à copier. Le document lisible par machine est le même contenu en OpenAPI 3.1.

Trois appels et une notification. Le café sera encore chaud.

Ce que vous pouvez vérifier

Ce sont des faits sur la plateforme en fonctionnement, pas des adjectifs. Chacun est visible dans le produit, dans la référence de l’API ou dans le grand livre.

• Le document OpenAPI et la référence lisible sont produits à partir d’une seule table d’opérations : ils ne peuvent pas se contredire.
• Chaque POST qui déplace de l’argent exige une clé d’idempotence : un rejeu renvoie l’objet d’origine, et la même clé avec un corps différent est refusée.
• Les notifications sont signées deux fois — HMAC-SHA256 sur le corps horodaté, et une signature Ed25519 de la plateforme — et réessayées selon un calendrier publié sur 24 heures.
• Les erreurs portent un code descriptif et une famille numérique stable : un logiciel peut brancher sur la famille sans analyser de l’anglais.
• Un bac à sable avec des numéros magiques documentés pilote la vraie machine d’états, échecs compris, sans toucher à un opérateur.

Ce que cela coûte

L’API ne coûte rien. Vous payez les paiements qu’elle déplace, au tarif de votre compte.

Est-ce activé ?

La disponibilité dépend des autorisations en place et de ce que l’administrateur d’un déploiement donné a activé. Cela change, un article non — la réponse vivante est donc sur la page de la fonctionnalité, qui la lit dans la plateforme elle-même : L’API de la passerelle sur la page des fonctionnalités.

À lire ensuite

• Notifications signées — Votre logiciel l’apprend avant votre client.
• Comptes connectés — Intégrez vos clients par API. Transmettez quand ils sont prêts.
• Page de paiement hébergée — Une page qui ne propose que ce qui marchera.