Connecter un prestataire de paiement

En mode Réel, les clients paient par Mobile Money via votre propre compte pawaPay, Notch Pay ou Flutterwave. L'argent va du portefeuille du client à votre compte prestataire. Abuna lance chaque prélèvement et le suit, mais ne détient jamais l'argent.

Le mode Test n'a besoin d'aucun prestataire : les paiements Test peuvent toujours passer par le simulateur Abuna. Pour voir comment vos prestataires se comportent avant de passer en mode Réel, connectez leurs bacs à sable à votre application Test, à côté du simulateur. Voyez Tester avec le bac à sable de votre prestataire.

Choisissez un prestataire

Abuna facture en XAF. Les clients valident chaque paiement sur leur téléphone. Si aucune demande ne leur parvient, la page de paiement montre comment valider le paiement en attente depuis le menu de leur téléphone, dans leur langue. Les réseaux que chaque prestataire propose via Abuna :

• pawaPay : MTN Mobile Money et Orange Money au Cameroun, et MTN Mobile Money et Airtel Money au Congo. Les clients peuvent aussi choisir Détecter mon réseau, et pawaPay déduit le réseau de leur numéro.
• Notch Pay : MTN Mobile Money et Orange Money au Cameroun.
• Flutterwave : MTN Mobile Money et Orange Money au Cameroun.

La page de paiement n'accepte que les numéros de téléphone des pays que votre prestataire peut débiter. Chaque client ne voit que les réseaux de son propre pays, avec celui de son numéro déjà sélectionné.

Bientôt disponible : les pays en XOF, via pawaPay et Notch Pay : la Côte d'Ivoire, le Sénégal, le Bénin et le Burkina Faso.

D'autres prestataires arrivent.

Wave et Orange Money Burkina Faso ne sont proposés par aucun prestataire. Ils demandent une étape que le lien de paiement n'a pas.

Obtenez vos identifiants

Une application Réelle n'accepte que des identifiants de production, et une application Test n'accepte que des identifiants de bac à sable. Depuis le tableau de bord de votre prestataire, copiez :

• pawaPay : votre jeton d'API. Abuna ne signe pas ses requêtes vers pawaPay, alors désactivez les requêtes signées sur votre compte pawaPay. S'il n'accepte que les requêtes signées, Abuna refuse le jeton. pawaPay ne documente pas d'option de jeton limité à l'encaissement. Avant de partager un jeton, demandez à pawaPay de désactiver les versements et les remboursements sur un compte distinct pour Abuna. Un compte distinct seul n'empêche pas l'argent de sortir. pawaPay ne crée un jeton qu'une fois qu'une URL de rappel est définie, et Abuna n'affiche votre URL de rappel du prestataire qu'après votre connexion. Définissez donc d'abord une URL de rappel des Dépôts temporaire, comme l'adresse de votre propre site, puis créez le jeton. Après votre connexion, remplacez l'URL temporaire par l'URL de rappel du prestataire d'Abuna.
• Notch Pay : votre clé publique et votre clé de hachage Webhook. Utilisez vos clés Réelles. Abuna refuse les clés de bac à sable Notch Pay sur une application Réelle, car elles marqueraient des factures payées sans qu'aucun argent ne circule. Trouvez votre clé publique sous Paramètres, puis Clés d'API. Ne partagez pas votre clé privée : Notch Pay l'exige pour les transferts et les remboursements, mais Abuna n'en a pas besoin.
• Flutterwave : votre clé secrète et un hachage secret. Si vous n'avez pas encore de compte Flutterwave, inscrivez-vous. Trouvez votre clé secrète sous Paramètres, puis Clés d'API. Les clés Réelles commencent par FLWSECK-, et les clés de test par FLWSECK_TEST-. Abuna n'a pas besoin de votre clé publique ni de votre clé de chiffrement. Le hachage secret est une phrase que vous inventez. Choisissez-en une longue et aléatoire, et gardez-en une copie : vous saisirez la même dans Flutterwave quand vous définirez l'URL de rappel du prestataire. Flutterwave n'a aucune clé qui ne peut qu'encaisser des paiements. Sa clé secrète peut tout faire sur votre compte, y compris envoyer de l'argent. Avant de la partager, ouvrez Paramètres, puis Préférences professionnelles, puis Sécurité, et réglez les transferts sur Tableau de bord uniquement. Cela désactive Transfert via API. Si une clé fuite, utilisez Générer de nouvelles clés pour la remplacer. Vos anciennes clés cessent de fonctionner, alors saisissez la nouvelle clé secrète dans Abuna tout de suite.

Connectez votre compte

1. Dans le tableau de bord, passez en mode Réel et ouvrez Paramètres, puis Paiements.
2. Cliquez sur Connecter un prestataire, choisissez votre prestataire, et collez vos identifiants.
3. Cliquez sur Vérifier et enregistrer. Abuna vérifie les identifiants auprès de votre prestataire avant de les enregistrer.
4. Définissez l'URL de rappel du prestataire dans le tableau de bord de votre prestataire. Cette étape est obligatoire : voyez Définir l'URL de rappel du prestataire.
5. Faites vous-même un petit paiement en mode Réel, depuis votre propre téléphone, pour confirmer la connexion.

Seul un propriétaire d'équipe peut connecter un prestataire, et uniquement depuis le tableau de bord. Chaque application a un prestataire à la fois. En connecter un autre remplace le précédent. Pour modifier une connexion enregistrée, laissez un champ secret vide pour garder sa valeur enregistrée.

Abuna stocke vos identifiants secrets chiffrés et ne les affiche plus jamais, seulement un court indice. Si le prestataire refuse les identifiants, l'enregistrement échoue avec le code provider_credentials_rejected. Si Abuna ne peut pas joindre le prestataire pour les vérifier, il échoue avec provider_unreachable. Réessayez dans un instant.

Les identifiants du mauvais environnement échouent avec 422 :

• provider_sandbox_credentials_required : des clés Réelles Notch Pay ou Flutterwave sur une application Test. Utilisez vos clés de bac à sable ou de test.
• provider_live_credentials_required : des clés de bac à sable Notch Pay ou des clés de test Flutterwave sur une application Réelle. Utilisez vos clés Réelles.
• provider_credentials_rejected : un jeton de production pawaPay sur une application Test, ou un jeton de bac à sable sur une application Réelle. pawaPay refuse les jetons de son autre environnement.

Définissez l'URL de rappel du prestataire

Une fois connecté, la page Paiements affiche une URL de rappel du prestataire. Votre prestataire l'appelle quand un paiement change, pour que le paiement se mette à jour dans Abuna dès que le client le valide. Cette étape est obligatoire : tant qu'elle n'est pas définie, les paiements peuvent ne pas se mettre à jour dans Abuna, et les factures payées peuvent rester ouvertes.

https://api.abuna.app/v1/providers/pawapay/3f9c0a7d5e2b4c18a6f1e9d2b7c4a051/webhook

• pawaPay : dans votre tableau de bord pawaPay, ouvrez Configuration du système, puis URL de rappel, et collez-la comme URL de rappel des Dépôts.
• Notch Pay : dans votre tableau de bord Notch Pay, ouvrez Paramètres, puis Webhooks. Ajoutez un point de terminaison avec cette URL et activez les événements de paiement. Ensuite, si Notch Pay affiche pour ce point de terminaison une clé de hachage différente de celle que vous avez saisie, cliquez sur Modifier sur la page Paiements et saisissez-la comme clé de hachage Webhook. Laissez le champ de clé publique vide pour la garder. Tant que les clés de hachage ne correspondent pas, Abuna ne peut pas vérifier les mises à jour de Notch Pay.
• Flutterwave : dans votre tableau de bord Flutterwave, ouvrez Paramètres, puis Webhooks. Collez cette URL, et saisissez le même hachage secret que celui entré dans Abuna. Cochez Activer les nouvelles tentatives de webhook et Activer le webhook pour les transactions échouées, puis enregistrez. Tant que les hachages secrets ne correspondent pas, Abuna ne peut pas vérifier les mises à jour de Flutterwave.

Pour confirmer la connexion, faites vous-même un petit paiement en mode Réel : ouvrez l'un de vos liens de paiement Réels et payez depuis votre propre téléphone. La page Paiements indique En attente de la première mise à jour tant que votre prestataire n'a pas signalé de paiement, puis Mises à jour reçues avec l'heure de la dernière. Le tableau de bord vous rappelle de définir l'URL jusque-là. Si vous passez à un autre prestataire, définissez à nouveau son URL.

Cette URL n'appartient qu'à cette application, gardez-la privée. Votre application Test et votre application Réelle ont chacune la leur. À chaque appel, Abuna demande le statut du paiement à votre prestataire avec vos propres identifiants avant de marquer quoi que ce soit comme payé. Modifier vos identifiants garde la même URL. Si vous vous déconnectez puis vous reconnectez, vous en obtenez une nouvelle.

Essayez les paiements en mode Test

Chaque application Test a le simulateur Abuna, listé en premier sur la page Paiements en mode Test. C'est le choix par défaut des liens de paiement Test, qui proposent alors quatre méthodes de test au lieu de vrais réseaux. Chacune donne un résultat fixe, et aucune ne déplace d'argent :

• Paiement réussi (test) : le paiement réussit.
• Validation requise, puis réussite (test_pending) : le paiement attend environ 10 secondes, comme pour une validation sur un téléphone, puis réussit.
• Paiement refusé (test_declined) : le paiement échoue avec payment_declined.
• Solde insuffisant (test_insufficient) : le paiement échoue avec insufficient_funds.

Quand vous payez une facture via l'API en mode Test, Abuna utilise la première méthode du simulateur, donc le paiement réussit. Voyez Factures et paiements.

Testez avec le bac à sable de votre prestataire

Avant de passer en mode Réel, vous pouvez tester contre le bac à sable de votre prestataire depuis votre application Test. Vous pouvez connecter un bac à sable par prestataire, et le simulateur Abuna reste disponible à côté. Quand un payeur choisit un bac à sable sur un lien de paiement Test, les paiements se comportent comme en mode Réel : le lien de paiement propose les réseaux du prestataire, les paiements se mettent à jour comme le prestataire les signale, et les paiements échoués portent les vraies raisons du prestataire. Aucun argent ne circule. Le mode Test reste gratuit et illimité sur tous les forfaits.

1. Obtenez des identifiants de bac à sable. Ils sont distincts de vos identifiants de production.
   • pawaPay : connectez-vous au tableau de bord bac à sable sur dashboard.sandbox.pawapay.io. Définissez une URL de rappel des Dépôts temporaire, puis créez un jeton d'API, comme pour le mode Réel.
   • Notch Pay : passez votre tableau de bord en Sandbox, puis copiez votre clé publique et votre clé de hachage Webhook de bac à sable.
   • Flutterwave : ouvrez Paramètres, puis Clés d'API, et passez en Test. Copiez votre clé secrète de test, qui commence par FLWSECK_TEST-, et inventez un hachage secret.
2. Connectez-les dans votre application Test. Dans le tableau de bord, passez en mode Test, ouvrez Paramètres, puis Paiements. Cliquez sur Connecter un bac à sable, choisissez votre prestataire, et collez vos identifiants de bac à sable. Abuna les vérifie auprès de votre prestataire, comme dans Connectez votre compte. Seul un propriétaire d'équipe peut le faire. La page liste alors bac à sable pawaPay, bac à sable Notch Pay, ou bac à sable Flutterwave sous simulateur Abuna, avec sa propre URL de rappel du prestataire. Répétez pour chaque prestataire que vous voulez essayer.
3. Définissez l'URL de rappel du prestataire dans le tableau de bord du bac à sable. Copiez-la depuis la page Paiements de l'application Test.
   • pawaPay : dans le tableau de bord bac à sable, ouvrez Configuration du système, puis URL de rappel, et remplacez l'URL de rappel des Dépôts temporaire par celle-ci.
   • Notch Pay : avec votre tableau de bord sur Sandbox, ouvrez Paramètres, puis Webhooks, et ajoutez un point de terminaison avec l'URL. Faites correspondre les clés de hachage comme dans Définir l'URL de rappel du prestataire.
   • Flutterwave : ouvrez Paramètres, puis Webhooks, et définissez l'URL et le hachage secret comme dans Définir l'URL de rappel du prestataire.
4. Payez un lien de paiement Test avec un numéro de test. Sous Tester avec, choisissez le bac à sable de votre prestataire. Le lien de paiement propose alors ses réseaux et liste ses numéros de test : choisissez-en un pour remplir le numéro de téléphone. Voyez Numéros de test.
5. Suivez le changement de statut. La page de paiement suit le paiement jusqu'à sa réussite ou son échec. La page Paiements passe de En attente de la première mise à jour à Mises à jour reçues, ce qui montre que votre URL de rappel du prestataire fonctionne.

Numéros de test

Le bac à sable de chaque prestataire règle un paiement selon le numéro de téléphone débité. Pour MTN Mobile Money au Cameroun, le +237653456789 de pawaPay réussit et le +237670000001 de Notch Pay échoue pour solde insuffisant. Le mode test de Flutterwave valide chaque paiement après quelques secondes, quel que soit le numéro. Pour chaque numéro de chaque réseau, voyez Numéros de test.

Les identifiants de bac à sable ne sont pas repris en mode Réel. Quand vous passez en mode Réel, connectez des identifiants de production dans votre application Réelle et définissez sa propre URL de rappel du prestataire.

Déconnecter un prestataire

Un propriétaire d'équipe peut déconnecter le prestataire depuis la page Paiements. Tant que vous n'en reconnectez pas un, les clients ne peuvent pas payer en mode Réel, et les nouvelles pages de paiement et les nouveaux paiements échouent avec le code not_accepting_payments. Les paiements déjà effectués ne sont pas touchés. Dans une application Test, déconnecter un bac à sable le retire des liens de paiement Test. Le simulateur Abuna et vos autres bacs à sable restent.

Pendant que vous êtes déconnecté, personne n'est annulé pour non-paiement. Les factures de renouvellement restent ouvertes, et les rappels de paiement attendent. Une fois reconnecté, les clients avec un renouvellement impayé obtiennent un délai de paiement complet à partir de ce moment.