L'argent est un entier
Tous les montants sont exprimés en unités mineures — centimes — sous forme d'entiers. Aucune décimale ne transite, rien ne s'arrondit donc différemment chez vous et chez nous.
Développeurs
Une API de paiement que vous pouvez garder en tête.
REST sur HTTPS, JSON en entrée comme en sortie, idempotence sur chaque écriture, et des webhooks qui réessaient jusqu'à votre accusé de réception. Les montants sont des entiers exprimés en centimes, parce que la virgule flottante n'a rien à faire près de l'argent.
Bac à sable dès le premier jour
Écritures idempotentes
Webhooks signés
# Charge a customer wallet
POST /v1/charges
Authorization: Bearer sk_live_...
Idempotency-Key: 8f14e45f-ea
{
"amount": 4500,
"currency": "USD",
"source": "wallet:+263771234567",
"reference": "INV-2048"
}
# 201 Created
{
"id": "chg_3Nk2...",
"status": "succeeded",
"amount": 4500,
"fee": 54,
"tax": 90,
"net": 4356
}
Principes
Les choix de conception que vous rencontrerez
Les écritures sont idempotentes
Envoyez un en-tête Idempotency-Key sur chaque POST. Réessayez autant que vous voulez : la même clé renvoie le résultat d'origine au lieu de débiter deux fois.
Les frais sont explicites
Chaque réponse à un débit contient les champs distincts amount, fee, tax et net. Vous n'avez jamais à déduire l'un des autres.
Les webhooks réessaient
Les événements sont réessayés avec temporisation progressive pendant 24 heures jusqu'à ce que vous renvoyiez un 2xx. Chacun porte un en-tête de signature à vérifier avant de faire confiance au corps du message.
Les statuts sont définitifs
Un débit se termine par succeeded, failed ou reversed. Aucun état ne change en silence après le règlement.
Les clés ont une portée
Les clés publiables ne peuvent que créer des intentions de paiement. Les clés secrètes n'ont leur place ni dans du code client ni dans un dépôt.
Périmètre
Les points de terminaison que vous utiliserez
| Point de terminaison | Méthode | Ce que ça fait |
|---|---|---|
| /v1/charges | POST | Encaisser depuis un portefeuille, un compte mobile money ou une carte. |
| /v1/charges/:id | GET | Récupérer un débit avec le détail des frais, de la taxe et du net. |
| /v1/refunds | POST | Rembourser tout ou partie d'un débit ; les frais sont restitués au prorata. |
| /v1/payouts | POST | Envoyer des fonds vers un portefeuille, un numéro mobile money ou un compte bancaire. |
| /v1/payouts/batches | POST | Soumettre jusqu'à 5 000 versements en un seul appel ; chaque ligne réussit ou échoue indépendamment. |
| /v1/balances | GET | Solde disponible et solde en attente, par devise. |
| /v1/settlements | GET | Les règlements, avec la liste des transactions qui composent chacun. |
| /v1/events | GET | Rejouer les événements webhook que vous auriez manqués. |
Webhooks
Vérifiez avant de faire confiance
Chaque événement porte l'en-tête ThumaPay-Signature . Calculez un HMAC du corps brut avec le secret de votre point de terminaison et comparez en temps constant. Rejetez tout ce qui ne correspond pas, ainsi que les horodatages de plus de cinq minutes, pour bloquer le rejeu.
// Node — verify a webhook
const sig = req.headers['thumapay-signature'];
const expected = crypto
.createHmac('sha256', endpointSecret)
.update(req.rawBody)
.digest('hex');
if (!crypto.timingSafeEqual(
Buffer.from(sig),
Buffer.from(expected))) {
return res.status(400).end();
}
Questions
Notes d'intégration
Oui. Les clés de bac à sable sont délivrées en même temps que les clés de production et se comportent de façon identique, y compris pour la livraison des webhooks et la simulation d'échecs. Aucun argent ne circule.
Le bac à sable expose des valeurs de déclenchement qui forcent des résultats précis — fonds insuffisants, vérification expirée, destinataire introuvable — afin de construire votre gestion d'erreurs sans attendre une panne réelle.
Les limites sont fixées par clé et renvoyées dans les en-têtes de limitation de chaque réponse. Un lot de versements compte pour une seule requête quel que soit le nombre de lignes : c'est tout l'intérêt.
Les soldes sont tenus par devise et ne sont jamais convertis implicitement. Si la devise d'un versement diffère de celle du solde, l'appel échoue plutôt que d'appliquer un taux en silence.
Les clés sont délivrées une fois votre compte professionnel vérifié. Lancez la démarche sur la page Entreprises ; l'accès au bac à sable peut être accordé pendant que la vérification est en cours.
Développez dès aujourd'hui
L'accès au bac à sable n'attend pas la vérification complète. Récupérez des clés, câblez un débit et observez le détail des frais dans votre propre corps de réponse.