Modèle de paiement

Deux familles d’opérations

Famille	Qui paie	Exemples	Résultat
A. Vous dépensez votre solde	Votre compte partenaire	Opérations de service pour vos clients	Immédiat : la réponse donne le résultat
B. Le client vous paie	Le client, depuis son compte SAMA Money	Encaissement d’une commande, d’une facture, d’un abonnement, d’un don	Asynchrone : le client confirme sur son téléphone, vous êtes notifié

Le guide correspondant à la famille B : Encaisser un paiement.

Il n’y a pas de retrait par API : un client qui retire de l’espèce initie lui-même le retrait depuis son application.

Cycle de vie d’un encaissement

pending ──► succeeded   le client a confirmé : le paiement est acquis
        ──► failed      l'encaissement n'a pas abouti
        ──► expired     la demande est restée sans réponse 90 jours

Un encaissement n’est jamais débité sans l’accord explicite du client (code secret saisi dans l’application). Vous ne saisissez jamais le code secret d’un client : il n’existe aucune route pour cela. Un encaissement pending n’est pas payé : attendez succeeded.

Une demande reste pending jusqu’à sa confirmation ou son refus. Restée sans réponse, elle expire au bout de 90 jours : son état devient expired.

Identifiants et montants

Chaque encaissement a une reference (de la forme chg_…) : c’est l’identifiant à conserver et à utiliser dans GET /v1/charges/{reference}. Le champ reference que vous envoyez à la création est votre propre référence (numéro de commande).
Les montants sont des entiers en francs CFA dans amount_xof, sans décimale.
Les numéros de téléphone s’écrivent avec l’indicatif du pays, par exemple 22370000000.

Idempotence

Un délai dépassé n’est pas un échec : la requête a peut-être abouti. Envoyez un en-tête Idempotency-Key (un UUID par opération métier) sur toute opération monétaire : si vous rejouez la même requête avec la même clé, l’API renvoie le même résultat au lieu d’exécuter l’opération une seconde fois. Pour une nouvelle opération, utilisez toujours une nouvelle clé.