Pour commencer
Montants, devises et horodatages
Comment l'API écrit les montants, les devises et les dates.
L'API écrit les montants en nombres entiers avec un code de devise, et les dates en secondes Unix.
Montants
Un montant est un entier dans la plus petite unité de la devise. Le XAF et le XOF n'ont pas d'unité plus petite, donc 5000 signifie 5 000 FCFA. Les montants en USD sont en cents, donc 1000 signifie 10,00 $.
{
"amount": 5000,
"currency": "XAF"
}Le montant d'un prix doit être supérieur à 0. Un montant de 0 ou moins renvoie 422 avec le code invalid. Un décimal comme 5000.5 ou une chaîne comme "5000" renvoie 400 avec le code invalid_json.
Chaque facture conserve le montant et la devise que son prix avait au moment de son émission. Le montant que paie un client figure sur la facture.
Devises
Abuna prend en charge trois devises : XAF (franc CFA d'Afrique centrale), XOF (franc CFA d'Afrique de l'Ouest) et USD (dollar américain). Vous pouvez envoyer le code dans n'importe quelle casse. L'API le stocke et le renvoie en majuscules. Tout autre code renvoie 422 avec le code currency_unsupported.
Chaque application a une base_currency, que vous choisissez à sa création. Chaque prix a sa propre currency. Les deux peuvent valoir XAF, XOF ou USD.
Paiement en FCFA
Les clients paient toujours par mobile money en FCFA, dans la devise de leur réseau : le XAF pour les réseaux d'Afrique centrale, comme au Cameroun, et le XOF pour ceux d'Afrique de l'Ouest, comme en Côte d'Ivoire ou au Sénégal. Quand la facture est dans cette devise, le client paie le montant de la facture. Sinon, Abuna le convertit :
- Entre XOF et XAF : 1 pour 1, sans marge. Une facture de 5 000 FCFA en XOF se paie 5 000 FCFA en XAF.
- Depuis l'USD : au taux de change du jour plus 2 %, arrondi au franc supérieur. Les 2 % font partie du montant que vous recevez. Abuna n'en prend rien.
Le client voit le montant exact en FCFA avant de valider le paiement sur son téléphone. Les pages hébergées, comme la page d'abonnement et la page de paiement, affichent le prix dans sa devise, avec le montant en FCFA à côté, comme 10,00 $ · 6 039 FCFA. Une requête renvoyée pour le même paiement garde le montant de la première.
Les factures restent dans la devise du prix. Le taux est enregistré sur chaque paiement : amount et currency sont ce que le client a payé, original_amount et original_currency ceux de la facture, et exchange_rate les francs payés par unité de la devise de la facture, 2 % compris. Voir L'objet payment.
{
"amount": 6039,
"currency": "XAF",
"original_amount": 1000,
"original_currency": "USD",
"exchange_rate": 603.8094,
"exchange_margin_bps": 200,
"exchange_rate_at": 1791100800
}Si aucun taux de change récent n'est disponible, le paiement d'une facture en USD est refusé avec 503 et le code exchange_rate_unavailable. Rien n'est débité, et la page de paiement demande au client de réessayer plus tard. Les taux sont normalement disponibles chaque jour.
Certains prestataires de paiement n'acceptent que le XAF. Les prix en XOF ou en USD se paient quand même par eux avec des numéros camerounais, convertis en XAF. Voir Choisissez un prestataire.
Horodatages
Chaque date dans l'API est un nombre entier de secondes depuis l'époque Unix, en UTC. Une date qui n'est pas encore arrivée est null, comme activated_at avant le premier paiement.
{
"starts_at": 1727600000,
"activated_at": null,
"canceled_at": null,
"created_at": 1727600000
}Les périodes de facturation se comptent à partir du début de l'abonnement. Un abonnement mensuel qui commence le 31 janvier se renouvelle le dernier jour de février, puis le 31 mars. Les périodes conservent l'heure de début.
Étapes suivantes
- PrixFixez le prix d'un produit et sa fréquence de renouvellement : chaque jour, chaque semaine, chaque mois ou chaque année.
- Factures et paiementsLes périodes de facturation, leurs factures et les paiements associés. Listez et lisez les factures.
- ErreursCodes de statut, codes d'erreur, erreurs de champ, limites de débit, identifiants de requête, et comment réessayer sans risque.