Alimenter un wallet par carte : le dépôt avec 3-D Secure expliqué aux intégrateurs
En bref
- Le dépôt par carte crédite le wallet d'un utilisateur depuis sa carte bancaire. C'est l'une des façons d'alimenter un solde, aux côtés du cash-in en espèces chez un agent.
- Le parcours : aperçu des frais, exécution, authentification 3-D Secure, webhook de dépôt autorisé, vérification de l'opération.
- La règle d'or : le solde se met à jour sur la confirmation (webhook et lecture de l'opération), jamais sur le seul retour de la redirection.
- À ne pas confondre avec l'encaissement d'un achat par un commerçant, qui relève d'une plateforme de paiement.
Pourquoi proposer le dépôt par carte
Un wallet sans moyen simple de l'alimenter reste vide. Au Maroc, deux portes d'entrée se complètent : les espèces, déposées chez un agent du réseau grâce à une référence, et la carte bancaire, depuis le téléphone, à toute heure. Notre guide du portefeuille électronique au Maroc replace ces usages dans le paysage, et la page m-wallet au Maroc décrit l'offre en marque blanche de Chari Money.
Le dépôt par carte s'adresse aux applications qui donnent un solde à leurs utilisateurs : super-app, application de livraison qui verse les gains de ses livreurs, plateforme de services. Il ne s'agit pas d'encaisser un achat, mais de transformer l'argent d'une carte en solde de wallet.
Les prérequis
- Une clé API de sandbox active, demandée depuis la documentation de l'API.
- Un client enregistré : le dépôt crédite le wallet associé à son numéro de téléphone. Le guide « wallet client » de la documentation décrit l'inscription, la confirmation par code et l'activation.
- Pour recevoir les notifications : un point de terminaison HTTPS et la clé de webhook que vous fournissez à Chari Money, renvoyée dans l'en-tête
X-Api-Keyde chaque notification.
En sandbox, une carte de test documentée et son code 3-D Secure permettent de dérouler tout le parcours sans argent réel. Voir aussi notre page sandbox de l'API partenaire.
Le parcours pas à pas
1. Prévisualiser le dépôt
Avant tout débit, l'appel d'aperçu vérifie la faisabilité du dépôt et renvoie les frais. Le numéro de téléphone du client passe en paramètre de requête, le montant dans le corps. Affichez le montant, les frais et le total à l'utilisateur avant qu'il ne confirme.
2. Exécuter le dépôt
L'appel d'exécution porte les données de la carte : numéro, CVV, date d'expiration au format année-mois sur quatre chiffres. Une option permet de conserver la carte sous forme de jeton pour les dépôts suivants. 3-D Secure est activé par défaut, et la réponse indique si une redirection est nécessaire, avec l'adresse de la page d'authentification.
3. Faire compléter l'authentification 3-D Secure
Si une redirection est demandée, ouvrez l'adresse fournie dans un navigateur. Le porteur s'authentifie auprès de sa banque, puis il est redirigé vers votre adresse de succès ou d'échec. L'adresse de retour contient un code de réponse, zéro en cas de succès, et un code de raison lisible. Vérifiez les deux pour décider de l'écran suivant.
4. Recevoir le webhook de dépôt autorisé
Quand le dépôt par carte est accepté, Chari Money notifie votre point de terminaison avec l'événement de dépôt par carte autorisé, en POST JSON. Le corps reprend votre identifiant de traçage, le type d'opération (dépôt), son statut (terminé), la méthode (carte) et les identifiants de la transaction côté passerelle. Répondez 200 OK en moins de cinq secondes avec un corps vide.
5. Vérifier l'opération
Avec l'identifiant d'opération reçu, lisez le détail de l'opération : type dépôt, statut terminé. Le montant total renvoyé est le montant après application des frais et commissions. C'est seulement après cette vérification que le solde affiché à l'utilisateur doit changer.
Deux variantes utiles
| Variante | À quoi elle sert | Ce qui change |
|---|---|---|
| Dépôt sur le wallet d'un agent | Alimenter le solde d'un agent de votre réseau | Le code de l'agent remplace le numéro de téléphone ; le flux 3-D Secure est le même |
| Dépôt avec une carte enregistrée | Recharger sans ressaisir la carte | Vous récupérez l'identifiant de la carte enregistrée, puis rejouez le dépôt avec le CVV et le montant seulement |
La variante agent intéresse les partenaires qui opèrent un réseau de cash-in et cash-out : leurs agents peuvent reconstituer leur solde sans se déplacer.
Carte, espèces : combiner les entrées d'argent
Le dépôt par carte n'est pas la seule porte d'entrée d'un wallet, et il ne doit pas l'être. Une partie de vos utilisateurs n'a pas de carte, ou préfère payer en espèces. Pour eux, le cash-in par référence via le réseau d'agents fait le même travail : votre application crée une demande de dépôt qui génère une référence à durée de validité limitée, le client la présente à un agent, et l'agent exécute l'opération.
Les deux parcours aboutissent au même résultat, un solde crédité et confirmé par webhook. Proposez-les côte à côte sur l'écran « Alimenter mon compte », avec les frais de chacun affichés avant confirmation.
Pensez aussi au niveau de compte de votre client. Le profil renvoyé par l'API indique un niveau KYC de 1 à 4, et les plafonds d'un wallet dépendent de ce niveau : vérifiez-le avant de proposer un dépôt important, et guidez l'utilisateur vers la vérification complémentaire quand c'est nécessaire, plutôt que de laisser l'opération échouer.
Les bonnes pratiques
- Confirmer sur l'opération, pas sur la redirection. Le retour du navigateur peut être interrompu, rejoué ou falsifié ; le webhook et la lecture de l'opération font foi.
- Rendre le traitement idempotent. Sans réponse 2xx, les nouvelles tentatives s'enchaînent : après 1, 5, 30 et 60 minutes, puis toutes les six heures jusqu'à 72 heures au total. Une même notification peut donc arriver plusieurs fois.
- Tracer chaque requête. Envoyez un
C-Request-Idunique : il revient dans la réponse et dans la notification, et facilite les échanges avec le support. - Protéger les données de carte. Elles transitent par votre serveur pour être transmises à l'API : ne les journalisez jamais, et faites le point avec votre conseil sur vos obligations de sécurité des données de carte.
- Expliquer les échecs. Un refus de la banque, une authentification abandonnée ou des données erronées n'appellent pas le même message ; le code de raison vous aide à les distinguer.
Ce qu'il ne faut pas confondre
Le dépôt par carte crédite le wallet de votre utilisateur. Un commerçant qui veut encaisser l'achat de son client utilise un autre outil : une page de paiement hébergée, où le client saisit sa carte et s'authentifie avec 3-D Secure sans que le commerçant voie jamais le numéro de carte. C'est le rôle de ChariPay, la plateforme de paiement opérée par Chari Money ; son guide 3-D Secure et taux de réussite détaille ce que l'authentification change pour un marchand, et son guide du paiement en ligne au Maroc explique comment encaisser.
Pour aller plus loin
Une fois le dépôt par carte en place, le solde du wallet peut servir à des services du quotidien : notre guide des recharges télécom et vouchers par API montre comment les ajouter, et celui sur l'intégration du paiement de factures complète l'offre.
Prochaine étape
Demandez votre accès sandbox depuis la documentation de l'API, faites activer la passerelle carte pour votre compte partenaire et déroulez le parcours avec la carte de test. Le lancement en production reste soumis à l'approbation de Bank Al-Maghrib, moyennant l'obtention du statut d'agent principal, et tout nouveau cas d'usage nécessite l'accord préalable de la Direction de la Supervision Bancaire.
Questions fréquentes
- Comment alimenter un wallet par carte ?
- Avec l'API de Chari Money, en quatre temps : prévisualiser le dépôt pour obtenir les frais, l'exécuter avec les données de la carte, faire compléter l'authentification 3-D Secure au porteur, puis confirmer le crédit à réception du webhook et par la lecture de l'opération. Le wallet crédité est celui associé au numéro de téléphone du client.
- Le 3-D Secure est-il obligatoire ?
- Dans ce parcours, 3-D Secure est activé par défaut. La réponse d'exécution indique si une redirection est nécessaire et fournit l'adresse de la page d'authentification. Après l'authentification, le porteur revient sur votre adresse de succès ou d'échec, avec un code de résultat à vérifier.
- Peut-on considérer le dépôt réussi au retour de la redirection ?
- Non. La redirection indique le résultat de l'authentification, mais le crédit du wallet se confirme à réception du webhook de dépôt autorisé et par la lecture de l'opération : type dépôt, statut terminé. C'est cette confirmation qui doit mettre à jour le solde affiché.
- Peut-on enregistrer la carte du client ?
- Oui. Si vous demandez la conservation de la carte à l'exécution, elle est enregistrée sous forme de jeton. Les dépôts suivants se rejouent avec l'identifiant de la carte enregistrée, le CVV et le montant, sans retransmettre le numéro de carte.
- Que se passe-t-il si mon serveur ne répond pas au webhook ?
- Répondez 200 OK en moins de cinq secondes. Tout code non 2xx déclenche une nouvelle tentative après 1, 5, 30 et 60 minutes, puis toutes les six heures jusqu'à 72 heures au total. Votre traitement doit être idempotent, car une notification peut arriver plusieurs fois.
- Je veux encaisser des achats par carte, est-ce le même parcours ?
- Non. Le dépôt par carte crédite le wallet d'un utilisateur. Pour encaisser les achats de vos clients en tant que commerçant, Chari Money opère ChariPay : le client paie sur une page hébergée avec 3-D Secure et vous ne voyez jamais de numéro de carte.