Recharges télécom et vouchers par API : ajouter des services du quotidien à votre application

En bref

• Recharges télécom et vouchers sont des services à valeur ajoutée qui font revenir l'utilisateur : petits montants, besoin fréquent, résultat immédiat.
• La recharge se fait en deux appels (catalogue, exécution) quand le partenaire paie, ou avec un aperçu préalable quand le wallet du client est débité.
• Le voucher suit un parcours marques, articles, aperçu, confirmation ; le code est remis à la confirmation.
• Deux prérequis reviennent partout : le module activé pour votre compte partenaire et un float pour les opérations débitrices.

---

Pourquoi ces deux services

Dans une application financière, la recharge de téléphone et l'achat de vouchers numériques jouent le même rôle : ils donnent une raison d'utiliser le solde souvent, pour de petits montants, avec un résultat visible tout de suite. Ils complètent le paiement de factures dans l'offre de services à valeur ajoutée de Chari Money.

Nos articles sur la recharge téléphone en ligne et les vouchers et bons digitaux présentent ces services du point de vue de l'utilisateur. Ce guide s'adresse à l'équipe qui les intègre.

Avant de commencer

Trois éléments sont nécessaires, en sandbox comme en production :

1. Une clé API valide, propre à chaque environnement.
2. Le module activé pour votre compte partenaire : la recharge télécom comme les vouchers sont activés sur demande par l'équipe Chari Money. Pour les vouchers, le catalogue doit en plus être provisionné en sandbox.
3. Un float sur le compte de votre agent principal, car ces opérations débitent un solde.

Le compte de l'agent principal est celui qui porte votre statut de partenaire ; notre article sur le statut d'agent principal explique ce qu'il recouvre. En production, l'activation de chacun de ces cas d'usage nécessite l'accord préalable de la Direction de la Supervision Bancaire.

La recharge télécom, appel par appel

Le catalogue des offres

Le catalogue B2B renvoie les produits de recharge disponibles pour un numéro, un montant et un opérateur, ce dernier étant désigné par un code numérique. Chaque produit porte un code produit unique, à réutiliser pour la recharge, et un indicateur de disponibilité.

L'exécution

La recharge s'exécute avec le code produit choisi et le code de votre agent principal, qui désigne le compte débité. Deux types de recharge coexistent : la recharge classique, exprimée en dirhams, et la recharge de type produit, qui correspond à un pass du catalogue.

La variante client

Si la recharge est payée depuis le wallet d'un client, et non par le partenaire, on utilise la variante client. Elle commence par un aperçu : le wallet débité et le numéro rechargé y sont distincts, et la réponse renvoie les frais et le montant total. Une fois l'aperçu validé par l'utilisateur, l'exécution reprend le même corps.

L'historique

L'historique des recharges d'un client est paginé et filtrable par statut, plusieurs statuts pouvant être combinés dans une même requête.

Les vouchers, du catalogue au code

Marques et articles

La liste des marques est paginée et exige le numéro de téléphone du client. Pour une marque donnée, la liste de ses articles expose le prix et surtout les deux identifiants exigés par la suite : l'identifiant de l'article chez le fournisseur et l'identifiant du fournisseur. Conservez-les.

Aperçu

L'aperçu vérifie la faisabilité de l'achat. Son corps porte cinq champs obligatoires : le téléphone du client, le téléphone de destination, le nom du bénéficiaire et les deux identifiants de l'article. La réponse renvoie les frais et le montant total : affichez-les avant toute confirmation.

Confirmation et remise du code

La confirmation reprend le même corps. C'est sa réponse qui porte le livrable : le code du voucher, avec son nom, sa description et un éventuel montant de cashback. Stockez le code de façon sécurisée et remettez-le au bénéficiaire, par exemple dans l'écran de reçu et dans l'historique.

L'API expose aussi un catalogue de vouchers locaux, filtrable par marque et par mot-clé, qui alimente un second flux d'achat distinct : ne mélangez pas les deux parcours dans une même intégration sans l'avoir prévu.

Erreurs et traçage

Les erreurs suivent les codes HTTP standards. Une erreur métier revient en 400 avec, dans le corps, un code d'erreur Chari et sa description. Les cas les plus fréquents en intégration :

• Service non activé : le module n'est pas activé pour votre compte ; demandez l'activation.
• Catalogue vide : les marques de vouchers ne sont pas provisionnées en sandbox ; ce n'est pas un bug.
• Paramètre manquant : un champ obligatoire du corps manque, par exemple le code de l'agent, le code produit ou le type de recharge, ou l'un des cinq champs de l'aperçu d'un voucher.
• 401 : clé d'API non autorisée ou utilisée dans le mauvais environnement.

Incluez un identifiant de requête unique dans chaque appel : il est renvoyé dans la réponse et accélère tout échange avec le support.

Bien concevoir l'expérience

• Montrez les frais avant de confirmer. L'aperçu existe pour ça : le total affiché doit être celui qui sera débité.
• Gardez une trace. Un reçu par opération, accessible dans l'historique, avec le code du voucher quand il y en a un.
• Prévoyez l'échec proprement. Si l'exécution échoue, n'affichez aucun débit et proposez de réessayer : l'historique filtré par statut permet de vérifier ce qui s'est réellement passé avant de relancer une opération, et évite ainsi de recharger deux fois la même ligne.
• Gérez le float. Côté partenaire, surveillez le solde de l'agent principal pour que les recharges B2B ne s'arrêtent pas ; le dépôt par carte, dans sa variante agent, permet de le reconstituer.

Où placer ces services dans le produit

Ces services ne se vendent pas seuls : ils se placent là où l'utilisateur en a besoin. Dans une application grand public, une tuile « Recharger » sur l'écran d'accueil, avec les numéros récents, fait souvent plus que n'importe quelle campagne. Pour les vouchers, une rubrique par univers (jeux, divertissement, cartes cadeaux) aide à trouver la bonne marque sans parcourir tout le catalogue.

Dans un réseau d'agents, la logique est différente : c'est l'agent qui vend la recharge ou le voucher à un client de passage, depuis le float de l'agent principal. La recharge B2B est faite pour cet usage, et le réseau d'agents de Chari Money en est le canal naturel.

Dans les deux cas, gardez la même discipline : un aperçu qui montre le total, une confirmation explicite, un reçu conservé dans l'historique, et un code de voucher qu'on peut retrouver plus tard si le bénéficiaire l'a perdu.

Et pour un commerçant ?

Ces intégrations s'adressent aux partenaires qui opèrent des wallets pour leurs utilisateurs. Un commerçant qui veut simplement recharger les lignes de son équipe depuis l'argent de ses ventes n'a pas besoin de tout cela : ChariPay, la plateforme de paiement opérée par Chari Money, le permet par l'API depuis le solde du compte de paiement d'un commerçant. Pour l'essayer, ouvrez un compte en mode test : Commencer en mode test.

Prochaine étape

Pour activer la recharge télécom et les vouchers dans votre sandbox, consultez la documentation de l'API partenaire et demandez l'activation des modules et un float de test à votre contact Chari Money.