Aller au contenu
MafPayMafPay Docs

Démarrage rapide

Objectif : réaliser votre premier paiement de test en quelques minutes, avec uniquement curl (un outil disponible dans votre terminal). Aucun argent réel n’est utilisé.

Étape 1 — Créer votre compte

  1. Ouvrez le portail client MafPay et cliquez sur Créer un compte.
  2. Renseignez votre nom, votre email, votre téléphone et le nom de votre entreprise.
  3. Vous recevez un code à 6 chiffres par email : saisissez-le pour vérifier votre adresse.
  4. Connectez-vous.

Étape 2 — Créer une application

Dans le portail, ouvrez Applications puis Nouvelle application (ex : « Ma boutique »).

MafPay génère pour cette application deux paires de clés :

Clé publique Secret
Sandbox (test) pk_test_… sk_test_…
Live (production) pk_live_… sk_live_…

Pour ce guide, utilisez uniquement les clés _test_.

Étape 3 — Récupérer votre identifiant d’entreprise

Sur la page Entreprise du portail, copiez votre endpoint_key (24 caractères, ex : d7f5c1eb86d42ff82775fa7b). Il fait partie de l’adresse de chaque requête.

Gardez ces quatre informations sous la main : les exemples de cette page les désignent par les noms ci-dessous, à remplacer par vos valeurs.

Dans les exemples À remplacer par Où le trouver
$MAFPAY_URL l’adresse de l’API (http://localhost:8000 en local, sinon celle fournie par MafPay) communiquée par MafPay
$ENDPOINT_KEY votre endpoint_key page Entreprise
$PK votre clé publique sandbox (pk_test_…) page de votre application
$SK votre secret sandbox (sk_test_…) page de votre application

Étape 4 — Activer un moyen de paiement

Dans la page de votre application, ouvrez Moyens de paiement, choisissez l’onglet Sandbox, puis Configurer Wave (ou Orange Money). Le formulaire est le même qu’en production : il demande vos identifiants marchands.

Valeurs de test du sandbox

En sandbox, MafPay vérifie vos identifiants comme le ferait l’opérateur : une valeur incorrecte fait échouer l’initiation (« Identifiants sandbox invalides »). Saisissez exactement ces valeurs de test :

Moyen de paiement Champ Valeur de test
Wave Clé API sandbox_wave_key_demo
Wave Secret de webhook (facultatif ; s’il est renseigné, il doit être exact) whsec_sandbox_demo
Orange Money Client ID sandbox_client_id
Orange Money Client secret sandbox_client_secret
Orange Money Code marchand 123456

Cliquez sur Enregistrer, puis activez le moyen de paiement (l’interrupteur « Activé » de sa carte).

Pour vérifier que tout est prêt, vous pouvez demander à MafPay la liste des moyens de paiement disponibles :

GET/api/v1/{endpoint_key}/providers/?country=SN

La réponse indique "environment": "sandbox" (vous êtes bien en mode test) et la liste des moyens de paiement activés, chacun avec son code (WAVE_SN, ORANGE_MONEY_SN). Le détail et des exemples de code sont dans Moyens de paiement.

Étape 5 — Créer un paiement

Votre serveur demande à MafPay de créer le paiement :

POST/api/v1/{endpoint_key}/payments/initiate/

Comment vous vous identifiez. Chaque requête porte deux en-têtes : X-Api-Key (votre clé publique pk_test_…) et X-Api-Secret (votre secret sk_test_…). Voir Authentification.

Ce que vous envoyez (au format JSON) :

Champ Exemple Obligatoire
provider WAVE_SN oui
amount "5000" oui
currency XOF non (XOF par défaut)
description Commande #123 non
customer_phone +221771234567 non
customer_name Awa Diop non
metadata { "order_id": 123 } : vos propres données non
success_url / error_url adresses de retour de votre site non

Ce que MafPay vous répond (code HTTP 201) :

Champ de la réponse Signification
reference l’identifiant du paiement (MAFPAY-XXXXXXXX) : notez-le
status PROCESSING : MafPay attend que le client paie
deep_links le lien à ouvrir pour payer
qr_code le QR code du paiement (image PNG encodée en base64)
expires_at la date limite pour payer
metadata vos données, renvoyées telles quelles

Les exemples de code prêts à copier (curl, JavaScript, Python, PHP), avec la réponse complète, sont dans Initier un paiement.

Étape 6 — Payer comme un client

En sandbox, il n’y a pas de vrai téléphone : MafPay fournit une page de paiement de test, exactement comme le ferait l’application de l’opérateur.

  1. Ouvrez dans votre navigateur le lien de deep_links reçu à l’étape 5 (ou scannez le qr_code : il mène à la même page).
  2. La page affiche le montant déjà chargé, le marchand et le moyen de paiement.
  3. Cliquez sur Payer (ou Annuler pour tester l’échec).

Le paiement passe à SUCCESS et, si vous avez configuré votre webhook_url, MafPay envoie la notification transaction.success à votre serveur (voir Webhooks).

Étape 7 — Vérifier le résultat

Pour connaître l’état d’un paiement, interrogez-le avec sa référence :

GET/api/v1/{endpoint_key}/payments/{reference}/status/

Les en-têtes d’identification sont les mêmes qu’à l’étape 5. La réponse contient notamment :

Champ Signification
status SUCCESS : le paiement est réussi (autres valeurs possibles : FAILED, CANCELLED, EXPIRED)
paid_at la date du paiement
error_message le motif en cas d’échec, sinon vide

Vous voyez aussi le paiement dans la page Transactions du portail. Les statuts sont détaillés dans Suivre un paiement, avec des exemples de code.

Et ensuite ?