Paiements : Mobile Money et carte

Un paiement CashChap est un encaissement (collection) : CashChap demande à l'opérateur de débiter le client, puis crédite votre solde. Cette page décrit les moyens de paiement, le choix de l'opérateur et le cycle de vie d'une transaction, communs à l'API, au SDK, au widget, aux liens de paiement, à la boutique et aux terminaux.

Moyens de paiement

Mobile Money

Le client reçoit sur son téléphone une demande de validation (notification ou code USSD) qu'il confirme avec son code secret. Cette demande vient de l'opérateur : elle annonce le montant dans la monnaie du compte Mobile Money (XOF au Bénin), même quand votre service est réglé dans une autre devise et que toutes les pages CashChap montrent, elles, la devise du service ; l'écran d'attente en prévient le client. Au Bénin, CashChap est raccordé à MTN Mobile Money et à Moov Money :

MTN Mobile Money — mtn-benin Moov Money — moov-benin

Dans l'API v2, payment_method vaut mobile_money (valeur par défaut) et provider désigne l'opérateur. Le numéro (phone) doit appartenir à cet opérateur, sinon la demande est refusée avec invalid_phone_number. Le numéro s'écrit au format international, sans « + » : indicatif du pays puis numéro national. Au Bénin : 229, puis 01 et 8 chiffres (2290197000000) ; l'ancien format 229 + 8 chiffres est accepté et reçoit le 01. Un numéro national seul est refusé (phone_international_required), et le numéro doit être du pays de l'opérateur. Les réponses donnent le numéro sous la même forme (2290197000000) ; voir Numéros de téléphone. Un numéro bloqué par CashChap (fraude avérée) est refusé avec phone_number_blocked, à l'encaissement comme au retrait.

D'autres passerelles Mobile Money existent pour les marchands concernés : voir la liste. La liste exacte des moyens ouverts à votre service est donnée par GET /v2/payment-methods.

Choix automatique de l'opérateur

Vous ne savez pas à quel opérateur appartient le numéro du client ? Envoyez "provider": "auto" avec un encaissement Mobile Money : CashChap reconnaît l'opérateur d'après le numéro (préfixes de chaque opérateur, règle béninoise des 10 chiffres) et l'utilise comme si vous l'aviez indiqué. Le pays est déduit de l'indicatif : seuls les opérateurs de ce pays sont candidats. La réponse 202 indique l'opérateur retenu dans provider. Pour un retrait, l'opérateur enregistré sur le compte de retrait autorisé du numéro l'emporte.

• Un seul opérateur reconnaît le numéro : il est retenu ; les contrôles habituels s'appliquent (opérateur ouvert pour votre service, devise, plafonds).
• Plusieurs opérateurs : seuls ceux ouverts pour votre service sont gardés ; s'il en reste plusieurs, la demande est refusée.
• Aucun opérateur : la demande est refusée.

Dans ces deux cas de refus, l'API v2 répond 422 provider_required avec details.field = provider : vérifiez le numéro ou indiquez l'opérateur. Un provider explicite reste toujours prioritaire. Le widget, la boutique et les liens de paiement font ce choix pour le client.

Carte bancaire

Visa — visa Mastercard — mastercard

Le paiement par carte (payment_method = card) n'est pas encore ouvert aux marchands : il peut être indisponible (card_payments_unavailable). Quand il l'est, le client saisit ses données de carte dans le widget hébergé par CashChap : votre site ne les manipule jamais. La carte est refusée sur les terminaux et en boutique (payment_method_not_allowed_on_channel).

Débit direct

Le moyen direct_debit couvre la passerelle BAXI au Nigéria (baxi-nigeria, NGN). Il fonctionne comme le Mobile Money : le client est identifié par son numéro de téléphone.

Canaux

Chaque transaction porte un canal (channel), déduit par CashChap de la clé utilisée : vous ne le déclarez jamais (un champ channel dans la requête est refusé). Le canal peut avoir ses propres frais (frais par canal et par terminal).

Cycle de vie d'une transaction

1. Demande : votre serveur, le widget, un lien de paiement ou un terminal envoie la demande. CashChap contrôle la clé, le service, l'opérateur, le numéro, la devise, les plafonds et les limites antifraude. Une demande refusée reçoit tout de suite une erreur et aucune transaction n'est créée.
2. pending : la transaction existe (réponse 202 avec son id) ; l'opérateur attend la validation du client (pending_reason = awaiting_provider). Cette attente dure de quelques secondes à quelques minutes ; l'opérateur la clôt lui-même si le client ne répond pas.
3. succeeded : le client a payé. Votre solde est crédité du montant net (net_amount) ; CashChap envoie le webhook payment.success et, si la notification est activée, un reçu au client.
4. failed ou expired : refus du client, solde insuffisant, délai dépassé… La raison est dans failure (code et message en français) et dans le webhook payment.failed.

Un paiement remboursé garde le statut succeeded ; le montant remboursé figure dans refunded_amount. Le remboursement lui-même est une opération distincte (Remboursements).

Confirmer un paiement avant de livrer

Deux sources de vérité, à combiner :

• La lecture de la transaction : GET /v2/transactions/{id} avec la clé secrète, ou GET /v2/transactions?reference=… avec votre référence. Ajoutez ?wait=5 pour que la réponse attende jusqu'à 5 secondes un statut final. Interrogez-la au retour du client, puis périodiquement tant qu'elle est pending (toutes les 5 à 10 secondes pendant deux minutes, puis plus espacé).
• Le webhook : CashChap appelle votre adresse dès que la transaction aboutit. Vérifiez la signature, déchiffrez la charge, puis traitez. Détail dans Webhooks.

Dans les deux cas, contrôlez que mode vaut live, que amount et currency correspondent à la commande, et que la transaction n'a pas déjà été traitée chez vous. amount et currency restent ceux de votre demande ; les montants prélevés (amount_charged) et crédités (net_amount) sont dans la devise de l'opérateur et en XOF, et le bloc display donne ce que le client a vu, dans la devise du service.

Identifiants d'une transaction

• id : identifiant (UUID) attribué par CashChap, renvoyé dans la réponse 202 et dans l'en-tête Location. C'est lui qu'il faut garder pour suivre la transaction.
• reference : votre propre référence (1 à 64 caractères : lettres, chiffres, _ . : / -), par exemple un numéro de commande. Elle est unique par environnement : une seconde demande avec la même référence est refusée (duplicate_reference, avec l'id de la transaction existante). C'est la meilleure protection contre le double paiement.
• Idempotency-Key : en-tête obligatoire sur les créations. Rejouer la même requête avec la même clé (après une coupure réseau) rend la même réponse sans créer une seconde transaction. Voir Idempotence.
• metadata : objet libre (20 clés au plus, valeurs texte de 500 caractères au plus) renvoyé tel quel dans la transaction.
• request_id : identifiant de chaque appel (en-tête X-Request-Id), à donner au support.

Reçu et facture

Une transaction réussie génère une facture PDF (numéro CS + dix chiffres ; TS en mode test) accessible depuis le portail, et un reçu « Reçu Cashchap » envoyé par e-mail au client dont l'adresse est connue (paiements initiés par le client : widget, lien de paiement, API). Pour être prévenu vous-même, cochez Prélèvement validé dans Compte › Préférences, bloc Notifications : à chaque paiement Live validé, le titulaire reçoit l'e-mail « [CashChap] Paiement reçu » (avec le montant dans la devise du service, puis en XOF) et une notification dans le portail. Retrait validé ajoute une notification dans le portail ; l'e-mail de confirmation de chaque retrait est envoyé dans tous les cas. Rien n'est envoyé pour le Sandbox. Reçu, facture et e-mail du client sont dans la devise du service au moment du paiement : le client n'y voit jamais le XOF prélevé par l'opérateur. Un reçu imprimable (texte de 32 ou 48 colonnes, pour les imprimantes de caisse) s'obtient avec GET /v2/transactions/{id}/receipt?format=text. Reçus et factures portent un QR code d'authentification qui mène à la page publique de vérification : voir Reçus et vérification.