Skip to main content
Catalogue statique de référence — les mêmes données sont aussi disponibles en direct via Lister les pays et Lister les réseaux, mais sans le format de téléphone attendu (une convention côté plateforme, non exposée par ces deux endpoints).
Seuls les pays ayant au moins un réseau mobile money actif peuvent recevoir un paiement softpay ou un retrait — c’est la liste ci-dessous. Le référentiel /countries/ complet en contient davantage (pays sans réseau, réservés à un usage futur).

​
Format du numéro de téléphone

Le numéro du client (customer.phone sur un paiement) ou du bénéficiaire (recipient.msisdn sur un retrait) accepte trois écritures équivalentes, normalisées côté serveur avant l’envoi au gateway :
  • Local, tel que composé dans le pays (ex. Bénin : 0197505050, 10 chiffres depuis la numérotation 2021 — le 0 initial fait partie du numéro, ce n’est pas un préfixe à retirer)
  • International sans + (ex. 2290197505050)
  • International avec + (ex. +2290197505050)
Le serveur ajoute l’indicatif s’il est absent, mais ne retire ni ne reformate jamais un numéro local — un numéro mal saisi (mauvaise longueur, mauvais préfixe opérateur) n’est détecté qu’au moment où le gateway le rejette, pas à la validation de la requête.

​
Réseaux globaux : card et crypto

En plus des réseaux mobile money ci-dessous (rattachés chacun à un pays précis), deux réseaux sont globaux — ils ne dépendent d’aucun pays et sont proposables quel que soit le pays de votre client :
Passez le country que vous voulez (le pays réel de votre client, ou l’ISO technique XX) — pour card/crypto, il est ignoré : la transaction est systématiquement créée en USD, rattachée au pays technique XX (“International (USD)”), quel que soit ce que vous envoyez. Si votre amount/currency de départ ne sont pas déjà en USD, la conversion se fait automatiquement au taux configuré, comme pour tout autre mismatch de devise en entrée.
customer.phone reste requis par le endpoint softpay même pour card/crypto (aucun push USSD n’est fait, le champ n’est simplement pas utilisé) — envoyez une valeur qui passe la validation de format basique, elle n’a pas besoin de suivre le format d’un pays réel.
return_url devient obligatoire dès que network vaut card ou crypto sur /payments/softpay/ — ces deux réseaux n’ont que la page hébergée du fournisseur, jamais de push. Sans lui, votre client n’aurait aucun moyen de revenir chez vous une fois payé : la requête est rejetée en 422 avant même de créer un paiement.

​
Catalogue

network (paiement) / method (retrait) attend le code exact de la colonne Réseaux — pas le nom lisible.
Un réseau marqué inactif existe dans le catalogue mais n’est routé vers aucun gateway pour le moment — l’utiliser renvoie une erreur invalid_method (422). La liste ci-dessus reflète l’état par défaut du catalogue ; utilisez Lister les réseaux pour l’état réel et à jour (is_active).