Accueil Documentation API

Docs Introduction

Introduction à AfrikMoney Pay

AfrikMoney est une infrastructure de paiement unifiée conçue pour simplifier l'intégration des services Mobile Money au Bénin. Notre API robuste permet aux entreprises de gérer les encaissements (Payins) et les décaissements (Payouts) via une interface unique, sécurisée et ultra-rapide.

Sécurité Bancaire

Authentification par clés sécurisées et chiffrement TLS 1.3 de toutes les données de transaction.

Haute Disponibilité

Connectivité redondante avec les passerelles opérateurs locaux (MTN, Moov, Celtiis) pour un taux de succès maximal.

Configuration Authentification

Authentification

Toutes les requêtes API doivent inclure votre clé secrète dans l'en-tête HTTP. L'absence d'en-tête ou une clé invalide retourne 401 Unauthorized.

Header HTTP


                    Authorization: Bearer pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Formats de référence

TXN_XXXXXXXXXXXXXXXX— Transaction d'encaissement (Payin)

PYO_XXXXXXXXXXXXXXXX— Payout direct (API Payouts)

pay_req_XXXXXXXXXXXX— Lien de paiement hébergé (Checkout)

WALLET-XXXXXXXXXXXX— Recharge wallet Mobile Money

Encaissements v1 (Payins)

Collectez des fonds auprès de vos clients via Push USSD ou page de paiement hébergée.

Séparation des fonds — Encaissements vs Wallet

Les fonds perçus via les encaissements (Payins) sont conservés sur votre compte de collecte, distinct de votre wallet marchand.

→ Pour reverser les fonds collectés vers votre compte bancaire ou Mobile Money, connectez-vous à votre tableau de bord et soumettez une demande de reversement.
→ Le wallet marchand est un solde séparé, rechargeable via l'API, utilisé exclusivement pour déclencher des payouts (décaissements) depuis vos applications.

POST /api/v1/direct

Déclenche un Push USSD directement sur le téléphone du client. Le client reçoit une invite de confirmation sur son mobile et valide le paiement sans être redirigé vers une page externe.

Requête (Body JSON)

{
    "amount": 5000,
    "provider": "MTN_BJ",
    "customer_phone": "2290167030967",
    "customer_email": "jean@gmail.com",
    "customer_name": "Jean Durand",
    "description": "Facture internet"
}

Réponse (201 Created)

{
    "success": true,
    "data": {
        "transaction_id": "420b41ce-faac-403d-8431-3fbad7da740f",
        "reference": "TXN_IYGNKBFNSHUQTWOO",
        "merchant_reference": "ORD-20260609133102-YEUM1R",
        "amount": 5000,
        "fees": 100,
        "total": 5100,
        "status": "processing",
        "metadata": {
            "amount": 5000,
            "provider": "MTN_BJ",
            "method": "api",
            "customer": {
                "name": "Jean Durand",
                "email": "jean@gmail.com",
                "phone": "2290167030967"
            },
            "description": "Facture internet",
            "timestamp": "2025-12-09 13:31:02"
        }
    }
}

POST /api/v1/request

Génère un lien de paiement hébergé (pay_req_…) valable 10 minutes que vous partagez à votre client. Frais de 2 % automatiquement ajoutés au montant.

Requête (Body JSON)

{
    "amount": 10000,
    "customer_phone": "2290167000003",
    "customer_email": "client@mail.com",
    "customer_name": "Paul Dubois",
    "description": "Paiement facture #2024"
}

Réponse (201 Created)

{
    "success": true,
    "message": "Payment link generated successfully.",
    "data": {
        "reference": "pay_req_c5SNT5ftoyyj",
        "amount": 10000,
        "fees": 200,
        "total": 10200,
        "currency": "XOF",
        "status": "pending",
        "customer_phone": "2290167030967",
        "customer_email": "client@mail.com",
        "customer_name": "Paul Dubois",
        "description": "Paiement facture #2024",
        "payment_url": "https://pay.afrikmoney.com/pay_req_c5SNT5ftoyyj"
    }
}

GET /api/v1/{reference}

Paramètre {reference} : TXN_XXXXXXXXXXXXXXXX ou votre merchant_reference

Récupère le statut et les détails d'un encaissement depuis la base de données locale.

Réponse (200 OK)

{
    "success": true,
    "data": {
        "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
        "reference": "TXN_A1B2C3D4E5F6G7H8",
        "merchant_reference": "CMD-2024-001",
        "amount": 2500,
        "fees": 87.50,
        "total": 2587.50,
        "net_amount": 2500,
        "status": "success",
        "customer_phone": "2290167000001",
        "failure_reason": null,
        "created_at": "2025-12-01T10:00:00.000000Z",
        "completed_at": "2025-12-01T10:02:14.000000Z"
    }
}

GET /api/v1/{reference}/verify

Paramètre {reference} : TXN_XXXXXXXXXXXXXXXX ou votre merchant_reference

Interroge en temps réel MTN / Moov / Celtiis pour confirmer le statut définitif, puis synchronise la base de données locale. À utiliser en cas de doute sur l'état d'une transaction.

Réponse (200 OK)

{
    "success": true,
    "message": "Transaction status verified with provider.",
    "data": {
        "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
        "reference": "TXN_A1B2C3D4E5F6G7H8",
        "merchant_reference": "CMD-2024-001",
        "status": "success",
        "provider_reference": "660ba8c2-93aa-4165-b905-e0ff4c5e0d08",
        "failure_reason": null,
        "updated_at": "2025-12-01T10:02:14.000000Z"
    }
}

Wallet & Décaissements v1

Consultez le solde de votre wallet marchand, rechargez-le via Mobile Money et déclenchez des payouts vers vos bénéficiaires.

GET /api/v1/balance

Récupère le solde net disponible du wallet marchand avec détail par opérateur.

Réponse (200 OK)

{
    "success": true,
    "balance": 150000,
    "currency": "XOF",
    "breakdown": [
        { "operator": "MTN_BJ", "balance": 100000 },
        { "operator": "MOOV_BJ", "balance": 50000 },
        { "operator": "CELTIIS_BJ", "balance": 0 }
    ]
}

POST /api/v1/wallet/recharge

Génère un lien de paiement hébergé (pay_req_…) pour recharger le wallet marchand via Mobile Money. La personne ouvre l'URL, confirme, puis valide sur son téléphone. Frais de plateforme : 3 % ajoutés automatiquement. Lien valable 10 minutes.

Requête (Body JSON)

{
    "amount": 20000,
    "phone_number": "2290167030967",
    "operator": "MTN_BJ"
}

Réponse (201 Created)

{
    "success": true,
    "message": "Lien de recharge généré avec succès.",
    "data": {
        "reference": "pay_req_aB3xK9mZqR2s",
        "checkout_url": "https://pay.afrikmoney.com/pay_req_aB3xK9mZqR2s",
        "amount": 20000,
        "fees": 600,
        "total": 20600,
        "currency": "XOF",
        "operator": "MTN_BJ",
        "phone_number": "2290167030967",
        "expires_at": "2025-12-01T10:10:00.000000Z",
        "status": "pending"
    }
}

Paramètres

Champ	Type	Description
amount	number	Montant net à créditer dans le wallet (min 100 XOF). Les 3 % sont ajoutés automatiquement.
phone_number	string	Numéro Mobile Money (8 à 13 chiffres, ex : 2290167030967).
operator	string	`MTN_BJ`, `MOOV_BJ` ou `CELTIIS_BJ`.

Webhook envoyé après confirmation : wallet_recharge.success ou wallet_recharge.failed.

POST /api/v1/payout/verify-recipient

Vérifie le titulaire réel d'un numéro Mobile Money avant d'envoyer un payout — utile pour confirmer que vous envoyez bien à la bonne personne avant que l'argent ne parte. Disponible uniquement pour MTN_BJ pour le moment.

Deux garde-fous

Le solde de votre wallet doit être positif, et vous êtes limité à 20 vérifications par jour. Ces règles évitent que cet endpoint ne serve de simple outil de recherche d'identité par numéro de téléphone.

Requête (Body JSON)

{
    "phone": "2290167000004",
    "payment_method": "MTN_BJ"
}

Réponse (200 OK)

{
    "success": true,
    "verified": true,
    "name": "Koffi Mensah",
    "phone": "2290167000004"
}

422 Solde insuffisant

{
    "success": false,
    "message": "Solde insuffisant pour vérifier ce bénéficiaire. Solde disponible : 0 XOF."
}

429 Limite quotidienne atteinte

{
    "success": false,
    "message": "Nombre maximal de vérifications atteint pour aujourd'hui (20/jour)."
}

⚠️ "verified": false (avec "name": null) signifie que l'opérateur n'a pas pu identifier le titulaire — numéro non enregistré en Mobile Money ou informations non disponibles. Ce n'est pas une erreur : vous pouvez tout de même tenter le payout.

POST /api/v1/payout

Initie un versement de fonds depuis votre wallet marchand vers un bénéficiaire Mobile Money.

Requête (Body JSON)

{
    "amount": 5000,
    "phone": "2290167000004",
    "payment_method": "MTN_BJ",
    "client_fullname": "Abel Sossou",
    "objet": "Règlement prestation"
}

Réponse (200 OK)

{
    "message": "Transfert réussi instantanément",
    "status": "SUCCESSFUL",
    "payout_id": "550e8400-e29b-41d4-a716-446655440001",
    "payout_intern_reference": "PYO_A1B2C3D4E5F6G7H8",
    "client_fullname": "Abel Sossou",
    "payment_method": "mtn_bj",
    "balance": 145000,
    "amount_will_be_deducted": true
}

400 Solde wallet insuffisant

{
    "success": false,
    "message": "Échec du retrait: Solde insuffisant. Solde disponible: 0 XOF"
}

⚠️ Cette erreur survient lorsque le solde de votre wallet marchand est insuffisant pour couvrir le montant demandé. Rechargez votre wallet avant de relancer le payout.

Suivi des Payouts

Consultez l'état d'un payout en base locale ou vérifiez-le directement auprès de l'opérateur.

GET /api/payouts/{reference}

Paramètre {reference} : PYO_XXXXXXXXXXXXXXXX

Récupère le statut et les détails d'un payout direct depuis la base de données locale.

Réponse (200 OK)

{
    "success": true,
    "data": {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "reference": "PYO_X9Y8Z7W6V5U4T3S2",
        "amount": 10000,
        "fees": 0,
        "currency": "XOF",
        "status": "success",
        "recipient_phone": "2290167000005",
        "recipient_name": "Koffi Mensah",
        "provider_reference": "660ba8c2-93aa-4165-b905-e0ff4c5e0d08",
        "failure_reason": null,
        "created_at": "2025-12-01T10:00:00.000000Z"
    }
}

GET /api/payouts/{reference}/verify

Paramètre {reference} : PYO_XXXXXXXXXXXXXXXX

Vérifie l'état réel du payout directement auprès de l'opérateur (MTN, Moov, Celtiis) et synchronise la base locale.

Réponse (200 OK)

{
    "success": true,
    "message": "Payout status verified with provider.",
    "data": {
        "payout_id": "550e8400-e29b-41d4-a716-446655440002",
        "reference": "PYO_X9Y8Z7W6V5U4T3S2",
        "status": "success",
        "provider_reference": "660ba8c2-93aa-4165-b905-e0ff4c5e0d08",
        "updated_at": "2025-12-01T10:02:14.000000Z"
    }
}

Configuration Webhooks

Webhooks

Nos serveurs envoient un POST signé à votre URL de webhook à chaque changement de statut. Répondez 200 OK pour accuser réception (5 tentatives avec backoff en cas d'échec).

Idempotence requise

Vérifiez toujours le champ reference en base avant de traiter l'événement — un même webhook peut être retransmis en cas d'erreur réseau.

Signature dans le header : X-Webhook-Signature: HMAC-SHA256(payload, webhook_secret)

Payload — transaction.success

{
    "event": "transaction.success",
    "transaction": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "reference": "TXN_YNPY1E5GAXZ7I6QK",
        "merchant_reference": "CMD-2024-001",
        "checkout_reference": null,
        "amount": "100.00",
        "fees": "0.80",
        "net_amount": "100.00",
        "currency": "XOF",
        "status": "success",
        "customer_phone": "2290167000001",
        "customer_email": "client@exemple.bj",
        "failure_reason": null,
        "created_at": "2025-12-09T11:34:46.000000Z",
        "completed_at": "2025-12-09T11:34:56.000000Z"
    },
    "timestamp": "2025-12-09T12:34:56+01:00"
}

Payload — transaction.failed

{
    "event": "transaction.failed",
    "transaction": {
        "id": "550e8400-e29b-41d4-a716-446655440001",
        "reference": "TXN_HFWXD1JAMPYZUKX1",
        "merchant_reference": "CMD-2024-002",
        "checkout_reference": "CMD-2024-002",
        "amount": "2550.00",
        "fees": "20.40",
        "net_amount": "2550.00",
        "currency": "XOF",
        "status": "failed",
        "customer_phone": "2290167000002",
        "customer_email": "client@exemple.bj",
        "failure_reason": "COULD_NOT_PERFORM_TRANSACTION",
        "created_at": "2025-12-04T16:30:36.000000Z",
        "completed_at": "2025-12-04T16:35:29.000000Z"
    },
    "timestamp": "2025-12-04T17:35:31+01:00"
}

Payload — payout.success

{
    "event": "payout.success",
    "payout": {
        "id": "550e8400-e29b-41d4-a716-446655440002",
        "reference": "PAYOUT-B3FAEJE6FRIN",
        "amount": "18.00",
        "fees": 0,
        "currency": "XOF",
        "status": "success",
        "recipient_phone": "2290167000005",
        "recipient_name": "John DOE",
        "failure_reason": null,
        "created_at": "2025-12-03T12:35:11.000000Z",
        "completed_at": "2025-12-03T12:36:11.000000Z"
    },
    "timestamp": "2025-12-03T13:36:11+01:00"
}

Payload — wallet_recharge.success

{
    "event": "wallet_recharge.success",
    "wallet_recharge": {
        "id": "550e8400-e29b-41d4-a716-446655440003",
        "reference": "e38a4544-219d-42fb-990d-f5233c4ffd0d",
        "checkout_reference": "pay_req_dyUiSwaKjph5",
        "amount": "10.00",
        "amount_charged": "11.00",
        "fee_amount": "1.00",
        "currency": "XOF",
        "status": "success",
        "phone_number": "2290167000001",
        "operator": "MTN_BJ",
        "failure_reason": null,
        "created_at": "2025-12-03T12:08:12.000000Z",
        "updated_at": "2025-12-03T12:08:25.000000Z"
    },
    "timestamp": "2025-12-03T13:08:28+01:00"
}

Payload — wallet_recharge.failed

{
    "event": "wallet_recharge.failed",
    "wallet_recharge": {
        "id": "550e8400-e29b-41d4-a716-446655440004",
        "reference": "1d16adba-1b1b-4307-80dc-a433b65d0c02",
        "checkout_reference": "pay_req_3VvPJNBNCGhB",
        "amount": "20000.00",
        "amount_charged": "20600.00",
        "fee_amount": "600.00",
        "currency": "XOF",
        "status": "failed",
        "phone_number": "2290167000002",
        "operator": "MTN_BJ",
        "failure_reason": "Solde insuffisant ou limite de réception du bénéficiaire atteinte.",
        "created_at": "2025-12-04T12:44:02.000000Z",
        "updated_at": "2025-12-04T12:44:05.000000Z"
    },
    "timestamp": "2025-12-04T13:44:05+01:00"
}

Automatisations Notifications Telegram

Notifications Telegram

Recevez en temps réel les alertes de paiements, payouts et recharges directement dans Telegram, sans avoir à surveiller votre tableau de bord.

1 Connecter votre compte

Depuis votre tableau de bord, rendez-vous dans Paramètres › Canaux de notification et cliquez sur Connecter Telegram.

Un lien unique est généré (valable 10 minutes). Il ouvre directement notre bot Telegram @afrikmoney_bot avec un token de liaison. Le bot confirme instantanément la connexion.

Chaque lien est à usage unique. Si vous ne validez pas dans les 10 minutes, il expire — générez-en un nouveau depuis le tableau de bord.

2 Activer les notifications

Une fois le bot connecté, activez le canal Telegram dans vos préférences de notification. Vous pouvez désactiver à tout moment, ou déconnecter le bot en envoyant /unlink dans la conversation.

Notifications reçues automatiquement

Événement	Déclencheur
transaction.success	Paiement Mobile Money reçu
transaction.failed	Tentative de paiement échouée
wallet_recharge.success	Recharge du wallet confirmée
wallet_recharge.failed	Recharge du wallet échouée
payout.success	Payout envoyé avec succès
payout.failed	Payout échoué

Format des messages

Exemple de notification pour un paiement reçu :

Paiement reçu

Montant : 5 000 XOF

Numero : 22967000000 (MTN_BJ)

Ref : pay_XXXXXXXXXXXX

10/06/2025 14:32

Commandes disponibles dans le bot

Commande	Action
/start	Message de bienvenue et instructions
/unlink	Déconnecter votre compte du bot

Référence Codes de réponse

Codes de Réponse API

200

SUCCESS

La requête a été reçue et traitée avec succès.

201

CREATED

La ressource (transaction, payout, lien) a été créée avec succès.

401

UNAUTHORIZED

Clé API manquante, invalide ou expirée.

403

FORBIDDEN

Transaction bloquée par le système de détection de fraude.

404

NOT FOUND

La référence passée ne correspond à aucune ressource de ce marchand.

422

UNPROCESSABLE ENTITY

Validation échouée — champ obligatoire manquant, montant insuffisant ou numéro invalide.

Retourner à

Page d'accueil

Initier un Paiement