Formats de numéros de téléphone
Comment Wajub lit un numéro Mobile Money, pays par pays, et ce qu'il rejette.
Le Mobile Money est identifié par numéro de téléphone partout où Wajub y touche : un client qui paie, un payout qui quitte votre solde, une marketplace qui règle un vendeur. Si le format est faux, le paiement échoue avant même que le client voie une demande de confirmation, ce qui en fait l'erreur d'intégration la plus fréquente que nous observons.
Envoyer au format E.164
Wajub attend la forme internationale : un +, l'indicatif du pays, puis le numéro d'abonné. Pas
d'espaces, pas de tirets, pas de parenthèses, pas de zéro initial issu du format national.
+[country code][subscriber number]
+237670000000 Cameroon, MTN
+221770000000 Senegal, Orange
+254700000000 Kenya, SafaricomUn numéro qui arrive sans son indicatif n'est pas automatiquement refusé. Quand l'appel porte un
pays sur lequel l'ancrer (un channel comme cm.mtn suffit), un numéro local tel que
670000000 est lu comme +237670000000. Sans cet ancrage, il n'y a rien sur quoi s'appuyer pour
deviner, et le numéro revient en 422.
Envoyez quand même au format E.164
Compter sur ce repli, c'est compter sur l'exactitude de votre propre channel. Normalisez de votre
côté, au moment où le client saisit le numéro, et vous éliminez toute une catégorie d'échecs de
chaque appel qui suit.
Tous les pays couverts par Wajub
Vingt-trois pays : chacun de ceux où le catalogue annonce un canal payé avec un numéro de téléphone, avec son indicatif et ces canaux.
| Pays | Indicatif | Canaux |
|---|---|---|
 Afrique du SudAfrique du Sud | +27 | Capitec Pay |
   BéninBénin | +229 | MTN MoMo, Moov Money |
  Burkina FasoBurkina Faso | +226 | Orange Money, Moov Money |
  CamerounCameroun | +237 | MTN MoMo, Orange Money, Express Union |
  CongoCongo | +242 | MTN MoMo, Airtel Money |
  Côte d'IvoireCôte d'Ivoire | +225 | MTN MoMo, Orange Money, Moov Money, Wave, Djamo |
 ÉgypteÉgypte | +20 | Vodafone Cash |
 GabonGabon | +241 | Airtel Money, Moov Money |
 GhanaGhana | +233 | MTN MoMo, Vodafone Cash, AirtelTigo Money |
 GuinéeGuinée | +224 | MTN MoMo, Orange Money |
  KenyaKenya | +254 | M-Pesa, Airtel Money |
 LibériaLibéria | +231 | MTN MoMo |
 MalawiMalawi | +265 | Airtel Money, TNM Mpamba |
 MaliMali | +223 | Orange Money, Moov Money |
 MozambiqueMozambique | +258 | M-Pesa |
 OugandaOuganda | +256 | MTN MoMo, Airtel Money |
 RD CongoRD Congo | +243 | Airtel Money, Vodacom M-Pesa, Orange Money, Africell Money |
 RwandaRwanda | +250 | MTN MoMo, Airtel Money |
 SénégalSénégal | +221 | Orange Money, Free Money, Wave, Djamo |
 Sierra LeoneSierra Leone | +232 | Orange Money |
 TanzanieTanzanie | +255 | M-Pesa, Tigo Pesa, Airtel Money, HaloPesa |
 TogoTogo | +228 | T-Money, Moov Money |
 ZambieZambie | +260 | MTN MoMo, Airtel Money, Zamtel Kwacha |
Comment l'opérateur est identifié
C'est là que la production et la sandbox diffèrent vraiment, et cette différence compte.
En production, Wajub identifie l'opérateur qui détient le numéro à partir des données de numérotation à jour. Un numéro qu'il ne peut attribuer à aucun opérateur pris en charge est considéré comme n'en ayant aucun.
Certains canaux portent le nom d'un portefeuille et non celui d'un opérateur, et le numéro est lu en
conséquence. Wave (ci.wave, sn.wave), Express Union (cm.eu), Djamo (ci.djamo, sn.djamo),
Capitec Pay (za.capitec), OPay (ng.opay) et PalmPay (ng.palmpay) se détiennent quel que soit
l'opérateur du payeur : un numéro n'y est jamais refusé à cause du réseau auquel il appartient. Les autres portefeuilles appartiennent à un
opérateur, et un numéro de cet opérateur paie sur le canal du portefeuille : ke.mpesa prend les
numéros Safaricom, tz.mpesa et mz.mpesa prennent les numéros Vodacom, et gh.vodafone prend les
numéros de Telecel, anciennement Vodafone Ghana.
Tous les autres canaux portent le nom de leur opérateur, comme zm.zamtel, mw.tnm ou
cd.africell. Un agrégat se résout de la même façon : un numéro Telecel envoyé sur mobile est
débité sur gh.vodafone.
En sandbox, il n'existe aucun vrai numéro à consulter : Wajub compare donc plutôt les préfixes
ci-dessous. Ils sont synthétiques : ils servent à rendre les résultats de test déterministes, pas à
décrire l'attribution des vrais numéros. Un portefeuille détenu quel que soit l'opérateur, comme
Capitec Pay, prend le numéro de test de n'importe quel opérateur, le sien (+2761…) ou celui d'un
autre, mais jamais un numéro qui n'est pas un numéro de test.
Ne construisez pas votre propre table de préfixes
Les préfixes ci-dessous sont ceux de la sandbox. Les recopier dans votre code revient à réimplémenter la détection d'opérateur avec des données fausses en production, et périmées le jour où une plage est réattribuée. Envoyez le numéro et laissez Wajub le résoudre.
| Pays et opérateur | Préfixe sandbox | Canal |
|---|---|---|
| Cameroun / MTN MoMoCameroun / MTN MoMo | +23767… | cm.mtn |
| Cameroun / Orange MoneyCameroun / Orange Money | +23769… | cm.orange |
| Cameroun / Express UnionCameroun / Express Union | +23768… | cm.eu |
| Côte d'Ivoire / MTN MoMoCôte d'Ivoire / MTN MoMo | +22505… | ci.mtn |
| Côte d'Ivoire / Orange MoneyCôte d'Ivoire / Orange Money | +22507… | ci.orange |
| Côte d'Ivoire / Moov MoneyCôte d'Ivoire / Moov Money | +22501… | ci.moov |
| Côte d'Ivoire / WaveCôte d'Ivoire / Wave | +22503… | ci.wave |
| Sénégal / Orange MoneySénégal / Orange Money | +22177… | sn.orange |
| Sénégal / Free MoneySénégal / Free Money | +22176… | sn.free |
| Sénégal / WaveSénégal / Wave | +22178… | sn.wave |
| Bénin / MTN MoMoBénin / MTN MoMo | +22990… | bj.mtn |
| Bénin / Moov MoneyBénin / Moov Money | +22991… | bj.moov |
| Burkina Faso / Orange MoneyBurkina Faso / Orange Money | +22670… | bf.orange |
| Burkina Faso / Moov MoneyBurkina Faso / Moov Money | +22671… | bf.moov |
| Ghana / MTN MoMoGhana / MTN MoMo | +23324… | gh.mtn |
| Ghana / Vodafone CashGhana / Vodafone Cash | +23320… | gh.vodafone |
| Ghana / AirtelTigo MoneyGhana / AirtelTigo Money | +23327… | gh.airteltigo |
| Kenya / M-PesaKenya / M-Pesa | +25470… | ke.mpesa |
| Kenya / Airtel MoneyKenya / Airtel Money | +25478… | ke.airtel |
| Ouganda / MTN MoMoOuganda / MTN MoMo | +25677… | ug.mtn |
| Ouganda / Airtel MoneyOuganda / Airtel Money | +25675… | ug.airtel |
| Rwanda / MTN MoMoRwanda / MTN MoMo | +25078… | rw.mtn |
| Rwanda / Airtel MoneyRwanda / Airtel Money | +25073… | rw.airtel |
| Tanzanie / Airtel MoneyTanzanie / Airtel Money | +25567… | tz.airtel |
| Tanzanie / Tigo PesaTanzanie / Tigo Pesa | +25565… | tz.tigo |
| Tanzanie / HaloPesaTanzanie / HaloPesa | +25562… | tz.halopesa |
| Tanzanie / M-PesaTanzanie / M-Pesa | +25576… | tz.mpesa |
| RD Congo / Airtel MoneyRD Congo / Airtel Money | +24399… | cd.airtel |
| RD Congo / Orange MoneyRD Congo / Orange Money | +24389… | cd.orange |
| RD Congo / Vodacom M-PesaRD Congo / Vodacom M-Pesa | +24381… | cd.vodacom |
| RD Congo / Africell MoneyRD Congo / Africell Money | +24390… | cd.africell |
| Gabon / Airtel MoneyGabon / Airtel Money | +2410… | ga.airtel |
| Gabon / Moov MoneyGabon / Moov Money | +2416… | ga.moov |
| Congo / MTN MoMoCongo / MTN MoMo | +24206… | cg.mtn |
| Congo / Airtel MoneyCongo / Airtel Money | +24204… | cg.airtel |
| Zambie / MTN MoMoZambie / MTN MoMo | +26096… | zm.mtn |
| Zambie / Airtel MoneyZambie / Airtel Money | +26097… | zm.airtel |
| Zambie / Zamtel KwachaZambie / Zamtel Kwacha | +26095… | zm.zamtel |
| Malawi / Airtel MoneyMalawi / Airtel Money | +26599… | mw.airtel |
| Malawi / TNM MpambaMalawi / TNM Mpamba | +26588… | mw.tnm |
| Mali / Orange MoneyMali / Orange Money | +22370… | ml.orange |
| Mali / Moov MoneyMali / Moov Money | +22366… | ml.moov |
| Togo / Moov MoneyTogo / Moov Money | +22899… | tg.moov |
| Togo / T-MoneyTogo / T-Money | +22890… | tg.tmoney |
| Guinée / MTN MoMoGuinée / MTN MoMo | +22466… | gn.mtn |
| Guinée / Orange MoneyGuinée / Orange Money | +22462… | gn.orange |
| Liberia / MTN MoMoLiberia / MTN MoMo | +23188… | lr.mtn |
| Mozambique / M-PesaMozambique / M-Pesa | +25884… | mz.mpesa |
| Égypte / Vodafone CashÉgypte / Vodafone Cash | +2010… | eg.vodafone |
| Sierra Leone / Orange MoneySierra Leone / Orange Money | +23276… | sl.orange |
| Afrique du Sud / Capitec PayAfrique du Sud / Capitec Pay | +2761… | za.capitec |
Laisser Wajub choisir le canal
La page hébergée et les composants choisissent l'opérateur avec le client : ceci ne concerne donc que
l'appel de débit d'une intégration API directe. Sur cet appel, channel est
obligatoire. Envoyez mobile, ou cm.mobile pour le Cameroun, et Wajub résout l'opérateur à partir
du numéro, puis route vers le meilleur prestataire disponible pour cet opérateur. C'est le cas à
privilégier. Ce sont les deux seuls agrégats : dans un autre pays, nommez le canal de l'opérateur,
comme ci.orange.
Le corps de l'appel de débit nomme alors l'agrégat et le numéro :
Ne nommez un canal précis comme cm.mtn que si vous voulez imposer un opérateur. Si le numéro et le
canal ne concordent pas, l'appel est refusé plutôt que rerouté en silence.
Un agrégat fonctionne aussi sur un paiement restreint par
accept. La restriction est vérifiée
sur l'opérateur que donne le numéro : cm.mobile avec un numéro MTN est accepté partout où cm.mtn
l'est, et refusé là où il ne l'est pas.
Ce qui revient quand le numéro est faux
| Réponse | Cause | Correction |
|---|---|---|
422 sur phone | Pas de +, pas d'indicatif et rien pour ancrer le numéro | Normalisez au format E.164 avant l'envoi |
422 sur channel | Le canal désigne un opérateur qui ne dessert pas ce pays | Vérifiez les opérateurs du pays ci-dessus |
422, numéro et canal discordants | Le numéro appartient à un autre opérateur que celui indiqué | Envoyez cm.mobile et laissez Wajub le résoudre |
422 sur phone, aucun opérateur trouvé | Aucun opérateur pris en charge ne détient le numéro | Demandez au client de confirmer son numéro, ou envoyez l'opérateur qu'il a choisi dans data.operator |
Les quatre sont refusés sur l'appel de débit, POST /payments/{id}, et non à la création du
paiement. Le paiement reste pending et rien n'atteint un opérateur : le même paiement peut donc être
débité de nouveau une fois le numéro corrigé. Un numéro que l'opérateur refuse après l'envoi de la
demande est un autre cas : le paiement échoue, et le motif figure dans le catalogue des motifs
d'échec.
Pages associées
- Moyens de paiement et canauxChaque opérateur, son canal et où il fonctionne.
- Numéros de test sandboxLes suffixes qui déclenchent chaque résultat en mode test.
- Motifs d'échecPourquoi un paiement qui a atteint un opérateur revient en échec.
- TransfertsLe même format, utilisé comme destination de payout.
- SyncLe même format, utilisé pour régler un vendeur de marketplace.