Skip to content
ABUNA
DocumentationMontants, devises et horodatages

Pour commencer

Montants, devises et horodatages

Comment l'API écrit les montants, les devises et les dates.

Voir en Markdown

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 $.

Le montant d'un prix
{
  "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.

Une facture de 10,00 $ payée en XAF
{
  "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.

Les dates d'un abonnement
{
  "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