Mode Test et mode Réel

Chaque application possède deux environnements, Test et Réel. Chacun a son propre ID d'application, ses clés secrètes, sa clé publiable, son secret de signature de webhook, son URL de webhook et ses données. L'ID d'application dans le chemin détermine le mode. Il n'existe aucun paramètre de mode.

Dans le tableau de bord, utilisez le sélecteur Test / Réel pour passer de l'un à l'autre. Dans l'API, GET /v1/apps/{appID} renvoie l'environment de l'application, test ou live. Chaque corps de webhook le porte aussi.

Mode Test

Développez et testez avec l'ID d'application Test et sa clé sk_test_. Le mode Test fonctionne comme le mode Réel, à ces différences près :

• Les paiements ne déplacent aucun argent. Ils passent par le simulateur Abuna, ou par le bac à sable d'un prestataire que vous connectez. Voir Paiements de test.
• Vous n'avez pas besoin d'un e-mail vérifié.
• Les limites de forfait sur les abonnés ne s'appliquent pas, et votre forfait ne rend jamais une application Test en lecture seule.
• Les e-mails et messages Telegram destinés aux clients ne sont pas envoyés. Abuna enregistre chacun comme un événement notification.captured, qui n'atteint jamais votre endpoint de webhook. La liste des notifications reste vide.
• Les success_url et cancel_url d'une session de paiement peuvent être des URL http sur localhost, 127.0.0.1 ou [::1]. Le mode Réel n'accepte que https.
• Une nouvelle application Test ne copie pas l'URL de webhook de l'application Réelle. Définissez-en une pour Test séparément, sous Webhooks en mode Test.

Paiements de test

Une application Test peut toujours encaisser des paiements via le simulateur Abuna. Un propriétaire d'équipe peut aussi connecter le bac à sable de chaque prestataire, pawaPay, Notch Pay et Flutterwave, côte à côte. La page Paiements, sous Paramètres en mode Test, liste le simulateur et chaque bac à sable connecté. Chaque bac à sable a sa propre URL de rappel chez le prestataire.

Sur une page de paiement Test, le payeur choisit sous Tester avec : Simulateur Abuna, par défaut, ou un bac à sable connecté, comme bac à sable pawaPay. Les pages de paiement Réelles n'offrent jamais ce choix.

• Simulateur Abuna : vous choisissez chaque résultat sur la page de paiement. Voir Paiements simulés.
• Un bac à sable de prestataire : la page de paiement propose les réseaux du prestataire, un champ de numéro de téléphone et les numéros de test du prestataire. Choisir un numéro de test remplit le numéro de téléphone et son réseau. Les paiements sont mis à jour et échouent selon ce que le prestataire rapporte. Voir Numéros de test.

Connectez un bac à sable pour voir comment votre prestataire se comporte avant de passer en Réel. Le déconnecter laisse le simulateur et vos autres bacs à sable tels quels. Les deux sont gratuits et illimités sur tous les forfaits. Voir Tester avec le bac à sable de votre prestataire.

Paiements simulés

Le simulateur Abuna a une méthode de paiement par résultat. Sur la page de paiement Test, le client en choisit une :

• Paiement réussi (test) : le paiement réussit.
• Demande une approbation, puis réussit (test_pending) : le paiement est d'abord pending, comme une demande de mobile money. Il réussit à la première vérification de statut après 10 secondes. La page de paiement s'en charge pour vous.
• Paiement refusé (test_declined) : échoue avec 402 et le code payment_declined.
• Solde insuffisant (test_insufficient) : échoue avec 402 et le code insufficient_funds.

Quand votre serveur débite une facture avec POST /v1/apps/{appID}/invoices/{id}/charge, une application Test utilise toujours la méthode test du simulateur, donc le paiement réussit.

Pour essayer un autre résultat sans la page de paiement, envoyez-le à l'endpoint du lien de paiement. Cet endpoint ne demande aucune clé. Utilisez le pay_token de la période de facturation.

curl https://api.abuna.app/v1/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d \
  -H "Content-Type: application/json" \
  -d '{"method": "test_declined"}'

{
  "code": "payment_declined",
  "error": "payment was declined"
}

Pour payer plutôt via un bac à sable connecté, ajoutez provider : pawapay, notchpay ou flutterwave. Laissez-le de côté pour le simulateur. method est alors l'un des réseaux du prestataire, et phone_number est le numéro à débiter au lieu de celui du client. Un prestataire que l'application Test n'a pas connecté renvoie 422 avec le code payment_unavailable, et il en va de même pour provider sur un lien de paiement Réel.

curl https://api.abuna.app/v1/pay/3a7e1c9f5b2d8a4e6c0f7b3d9a1e5c8f2b6d \
  -H "Content-Type: application/json" \
  -d '{"provider": "pawapay", "method": "MTN_MOMO_CMR", "phone_number": "+237653456039"}'

Numéros de test

Le bac à sable de chaque prestataire règle un paiement selon le numéro de téléphone débité. Les pages de paiement Test affichent les mêmes numéros que ces tableaux, pour le réseau choisi. La raison de l'échec que voit votre client dépend de ce que le prestataire rapporte.

Les numéros marqués Bientôt disponible sont sur des réseaux XOF. Abuna ne facture qu'en XAF pour l'instant, donc les pages de paiement ne les proposent pas encore.

• pawaPay : le bac à sable ne demande jamais de code PIN. Un numéro qui ne reçoit pas de réponse reste pending. Voir les numéros de test de pawaPay.
• Notch Pay : le dernier chiffre détermine le résultat. Notch Pay vérifie aussi la fraude dans son bac à sable, donc n'utilisez pas un seul numéro pour tous les tests. Il n'a pas de numéros de test pour le Bénin ni le Burkina Faso. Voir la page de test de Notch Pay.
• Flutterwave : son mode test valide chaque paiement mobile money après quelques secondes, quel que soit le numéro. Il n'a aucun numéro qui fait échouer un paiement au Cameroun, utilisez donc le simulateur Abuna pour tester les échecs. Voir la page de test de Flutterwave.

pawaPay

Notch Pay

Flutterwave

Mode Réel

Le mode Réel facture de vrais clients avec l'ID d'application Réel et sa clé sk_live_. Avant qu'il fonctionne, trois éléments sont nécessaires :

1. Un e-mail vérifié pour le propriétaire d'équipe. D'ici là, chaque endpoint Réel sauf GET /v1/apps/{appID} renvoie 403 avec le code email_unverified.
2. Un prestataire de paiement connecté. Connectez votre compte pawaPay, Notch Pay ou Flutterwave dans le tableau de bord. D'ici là, vous pouvez configurer des produits, des tarifs et des clients. Démarrer un abonnement ou encaisser un paiement renvoie 422 avec le code not_accepting_payments.
3. Un contact de support. Ajoutez un e-mail ou une URL de support sous Paramètres, puis Général. D'ici là, démarrer un abonnement ou encaisser un paiement renvoie 422 avec le code not_accepting_payments.

GET /v1/apps/{appID} indique où vous en êtes. Son objet payments contient email_verified, provider_connected, support_contact et ready.

Les paiements Réels sont débités sur le téléphone du client via votre propre compte prestataire. Abuna ne détient jamais l'argent.

Passer en Réel

Changez l'ID d'application et la clé secrète ensemble. Votre code reste le même. Le mode Réel démarre sans données : les produits, tarifs, clients et abonnements ne sont pas repris depuis Test, recréez-les donc en Réel. Définissez votre endpoint de webhook Réel et utilisez le secret de signature de webhook Réel pour vérifier les signatures.