Bienvenue sur AfriGate

Paiements (Collect)

Initiez un encaissement depuis le compte mobile money d'un client vers votre compte marchand.

Créer un paiement

Headers requis

Corps de la requête

{
  "amount": 5000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "orange",
  "country": "CI",
  "customer": {
    "phone": "+2250700000000",
    "name": "Jean Kouassi",
    "email": "jean@example.com"
  },
  "successUrl": "https://mysite.com/payment/success",
  "failedUrl": "https://mysite.com/payment/failed",
  "callbackUrl": "https://mysite.com/webhooks/afrigate",
  "merchantTransactionId": "ORDER-12345",
  "feeBearer": "merchant",
  "channel": "PUSH",
  "designation": "Online purchase",
  "description": "Order #12345",
  "metadata": {
    "orderId": "12345",
    "customField": "value"
  }
}

Champs

Réponse 201 Created

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "token": "pay_xK9mN2pQ",
    "merchantId": "m_abc123",
    "amount": 5000,
    "currency": "XOF",
    "feeAmount": 150,
    "netAmount": 4850,
    "status": "initiated",
    "paymentMethod": "MOBILE_MONEY",
    "operator": "orange",
    "country": "CI",
    "redirectUrl": "https://pay.afrigate.dev/a1b2c3...",
    "expiresAt": "2024-01-15T15:30:00.000Z",
    "createdAt": "2024-01-15T15:00:00.000Z"
  }
}

Consulter un paiement

Renvoie la même structure que la réponse de création.

Lister les paiements

Annuler un paiement

{ "reason": "Customer changed their mind" }

Cycle de vie d'un paiement

initiated --> pending --> processing --> success
                                    --> failed
                                    --> expired
         --> cancelled

success --> refunded             (remboursement total)
        --> partially_refunded   (remboursement partiel)

Opérateurs & flux de paiement

La façon dont le client autorise un paiement dépend de l'opérateur (operator) et du pays (country). Le champ channel pilote ce flux. Il existe quatre flux, et envoyer le mauvais channel pour un opérateur peut faire échouer silencieusement la transaction chez certains PSP.

Flux 1 — Redirect (Wave, Orange Money SN, Opay, Palmpay)

Le client est redirigé vers une page de paiement où il autorise le débit auprès de son opérateur.

• Envoyez channel: "REDIRECT".
• La réponse 201 contient redirectUrl = https://pay.afrigate.dev/{token} (page hébergée par AfriGate). Redirigez toujours le client vers cette URL ; la page AfriGate le renvoie ensuite vers l'opérateur. Vous ne manipulez jamais l'URL brute de l'opérateur.
• Rien à collecter (pas d'OTP), rien d'envoyé sur le téléphone.
• Le résultat final arrive via le webhook (payment.completed) ; vous pouvez aussi interroger GET /v1/payments/{token}.

POST /v1/payments
{
  "amount": 5000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "wave",
  "country": "SN",
  "channel": "REDIRECT",
  "customer": { "phone": "+221770000000", "name": "Awa Diop" },
  "successUrl": "https://mysite.com/ok",
  "failedUrl": "https://mysite.com/ko",
  "callbackUrl": "https://mysite.com/webhooks/afrigate",
  "merchantTransactionId": "ORDER-12345"
}

Flux 2 — OTP direct (Orange Money CI)

Le client génère un code auprès de son opérateur, vous le collectez sur votre interface et l'envoyez dans le champ otp avec channel: "OTP". Le paiement est autorisé directement, sans redirection.

Étapes côté client — Orange Money Côte d'Ivoire :

1. Le client compose sur son téléphone : #144*82#.
2. Il reçoit un code de paiement (OTP) par SMS.
3. Il vous communique ce code sur votre interface (page de paiement, application, TPE…).
4. Vous appelez POST /v1/payments avec channel: "OTP" et otp: "<code>".

• Champ otp : chaîne, 20 caractères max.
• Aucun redirectUrl n'est renvoyé. Le résultat final arrive via le webhook.

POST /v1/payments
{
  "amount": 5000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "orange",
  "country": "CI",
  "channel": "OTP",
  "otp": "123456",
  "customer": { "phone": "+2250700000000", "name": "Jean Kouassi" },
  "successUrl": "https://mysite.com/ok",
  "failedUrl": "https://mysite.com/ko",
  "callbackUrl": "https://mysite.com/webhooks/afrigate"
}

Flux 3 — Push / STK (MTN MoMo, Moov, …)

Une invite de validation est envoyée (push) sur le téléphone du client ; il la valide avec son PIN. Rien à rediriger, rien à collecter.

• Envoyez channel: "PUSH" (valeur par défaut si channel est omis).
• Le résultat final arrive via le webhook.

POST /v1/payments
{
  "amount": 5000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "momo",
  "country": "CI",
  "channel": "PUSH",
  "customer": { "phone": "+2250500000000", "name": "Ama Kone" },
  "successUrl": "https://mysite.com/ok",
  "failedUrl": "https://mysite.com/ko",
  "callbackUrl": "https://mysite.com/webhooks/afrigate"
}

Flux 4 — Voucher / prépayé (Botswana)

Le client achète un voucher (jeton prépayé) dans un point de vente ou une application, obtient un PIN et vous le communique. Vous envoyez ce PIN dans l'objet metadata (metadata.voucherPin). Il n'y a ni redirection ni push : le PIN seul autorise le débit.

• Botswana (country: "BW", devise BWP) : PIN dans metadata.voucherPin.
• Le résultat final arrive via le webhook (payment.completed) ; vous pouvez aussi interroger GET /v1/payments/{token}. Aucun redirectUrl n'est renvoyé.

POST /v1/payments
{
  "amount": 100,
  "currency": "BWP",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "voucher",
  "country": "BW",
  "customer": { "phone": "+26771000000", "name": "Kgomotso M." },
  "successUrl": "https://mysite.com/ok",
  "failedUrl": "https://mysite.com/ko",
  "callbackUrl": "https://mysite.com/webhooks/afrigate",
  "metadata": { "voucherPin": "12345678" }
}

Récapitulatif

Transferts

Envoyez des fonds depuis votre compte marchand vers le compte mobile money d'un bénéficiaire.

Créer un transfert

{
  "amount": 10000,
  "currency": "XOF",
  "paymentMethod": "MOBILE_MONEY",
  "operator": "momo",
  "country": "CI",
  "recipient": {
    "phone": "+2250700000000",
    "name": "Awa Traore",
    "email": "awa@example.com"
  },
  "callbackUrl": "https://mysite.com/webhooks/afrigate",
  "merchantTransactionId": "TRANSFER-789",
  "designation": "Supplier payment",
  "metadata": { "invoiceId": "789" }
}

Champs

Cycle de vie d'un transfert

Remboursements

Remboursez tout ou partie d'un paiement réussi.

{
  "amount": 2500,
  "currency": "XOF",
  "refundType": "partial",
  "reason": "Product returned"
}

Lister les remboursements

Checkout Session

Le checkout est une page de paiement hébergée par AfriGate. Utilisez-la pour offrir une expérience de paiement clé en main.

Consulter la session

Vérifier le statut

Webhooks

Les webhooks vous notifient en temps réel des changements de statut de vos transactions.

Événements

Format du payload

{
  "event": "payment.completed",
  "data": {
    "token": "pay_xK9mN2pQ",
    "merchantId": "m_abc123",
    "amount": "5000",
    "currency": "XOF",
    "status": "success",
    "completedAt": "2024-01-15T15:05:00.000Z"
  },
  "timestamp": "2024-01-15T15:05:01.000Z"
}

Payload de remboursement

Un remboursement n'émet pas son propre événement : il réutilise payment.completed avec le nouveau status du paiement — refunded (total) ou partially_refunded (partiel). Le token est celui du paiement (pas du remboursement), et l'objet data contient des champs supplémentaires propres au remboursement :

{
  "event": "payment.completed",
  "data": {
    "token": "pay_xK9mN2pQ",
    "merchantId": "m_abc123",
    "status": "partially_refunded",
    "refundId": "ref_a1b2c3d4",
    "paymentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "amount": "2500",
    "currency": "XOF",
    "refundType": "partial"
  },
  "timestamp": "2024-01-15T16:00:00.000Z"
}

Headers des webhooks

Vérification de la signature

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, timestamp, secret) {
  const content = `${timestamp}.${JSON.stringify(payload)}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(content)
    .digest('hex');

  const receivedSig = signature.replace('sha256=', '');

  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(receivedSig)
  );
}

app.post('/webhooks/afrigate', (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const timestamp = req.headers['x-webhook-timestamp'];

  // Vérifier que l'horodatage est récent (< 5 minutes)
  const age = Date.now() - parseInt(timestamp);
  if (age > 5 * 60 * 1000) {
    return res.status(400).json({ error: 'Timestamp too old' });
  }

  if (!verifyWebhookSignature(req.body, signature, timestamp, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const { event, data } = req.body;
  console.log(`Event: ${event}, Status: ${data.status}`);

  res.status(200).json({ received: true });
});

import hmac, hashlib, time, json

def verify_webhook(payload, signature, timestamp, secret):
    age = int(time.time() * 1000) - int(timestamp)
    if age > 5 * 60 * 1000:
        return False

    content = f"{timestamp}.{json.dumps(payload, separators=(',', ':'))}"
    expected = hmac.new(
        secret.encode(), content.encode(), hashlib.sha256
    ).hexdigest()

    received = signature.replace("sha256=", "")
    return hmac.compare_digest(expected, received)

Politique de retry

Chaque webhook est livré avec un POST initial plus jusqu'à 5 nouvelles tentatives (6 tentatives max). Le délai d'attente de la requête est de 10 secondes par tentative. Les nouvelles tentatives suivent un backoff exponentiel (2, 4, 8, 16, 32 secondes) :

Idempotence

Pour éviter les transactions en double, incluez un header X-Idempotency-Key unique.

X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Requis pour : POST /v1/payments et POST /v1/transfers

Rate limiting

Les requêtes sont limitées par marchand sur une fenêtre fixe de 60 secondes. La limite diffère selon l'environnement :

Headers de réponse

Dépassement 429

{
  "success": false,
  "data": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": { "limit": 2500, "window": 60, "retry_after": 60 }
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2024-01-15T15:00:00.000Z"
  }
}

Tests en sandbox

L'environnement sandbox (https://sandbox.afrigate.dev) accepte des numéros de téléphone de test qui simulent un paiement réussi ou échoué sans solliciter le véritable opérateur mobile money. Aucun fonds réel n'est déplacé et aucune action de l'utilisateur n'est requise.

Solde sandbox initial

À la création de votre compte marchand, votre portefeuille sandbox est crédité de 50 000 unités dans la devise de votre pays (ex. 50 000 XOF pour un marchand ivoirien, 50 000 NGN pour un marchand nigérian) afin que vous puissiez tester les transferts (disbursements) immédiatement, sans dépôt préalable. Ce solde simulé est décrémenté à chaque transfert simulé réussi et n'a aucun impact en production.

Numéros de test par pays

Pour déclencher un résultat simulé, utilisez ces numéros dans customer.phone (paiement) ou recipient.phone (transfert), avec le country correspondant.

Requête prête à l'emploi (par pays)

Pour chaque pays : un operator représentatif, le channel correspondant, la devise et le numéro succès pour customer.phone. Remplacez-le par le numéro échec (…002) pour simuler un échec. L'operator peut être n'importe lequel disponible pour le pays (voir GET /v1/payment-methods).

Exemple : paiement réussi

curl -X POST https://sandbox.afrigate.dev/v1/payments \
  -H "Authorization: Bearer pk_test_xxxxxxxxxxxxxxxxxxxxxxxx:sk_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "paymentMethod": "MOBILE_MONEY",
    "operator": "wave",
    "country": "SN",
    "customer": {
      "phone": "+221700000001",
      "name": "Test Success"
    },
    "successUrl": "https://mysite.com/payment/success",
    "failedUrl": "https://mysite.com/payment/failed",
    "callbackUrl": "https://mysite.com/webhooks/afrigate",
    "merchantTransactionId": "TEST-SUCCESS-001"
  }'

Renvoie 201 Created, identique à un paiement réel (status: "pending"). Après environ 5 secondes, votre callbackUrl reçoit le webhook :

{
  "event": "payment.completed",
  "data": {
    "token": "pay_xK9mN2pQ",
    "merchantId": "m_abc123",
    "amount": "5000",
    "currency": "XOF",
    "status": "success",
    "completedAt": "2026-05-03T15:00:05.000Z"
  },
  "timestamp": "2026-05-03T15:00:06.000Z"
}

GET /v1/payments/{token} renvoie alors status: "success".

Exemple : paiement échoué

Mêmes paramètres avec le numéro échec du pays (+221700000002 pour SN). Le webhook reçu après ~5 s :

{
  "event": "payment.completed",
  "data": {
    "token": "pay_xK9mN2pQ",
    "amount": "5000",
    "currency": "XOF",
    "status": "failed",
    "completedAt": "2026-05-03T15:00:05.000Z"
  },
  "timestamp": "2026-05-03T15:00:06.000Z"
}

Transferts

Mêmes numéros pour recipient.phone. Le webhook transfer.completed arrive après ~5 s avec status: "success" ou status: "failed".

Remboursements

Les remboursements sont synchrones et ne passent pas par un opérateur : il n'y a ni numéro de test ni délai. Pour tester, créez un paiement réussi (numéro succès ci-dessus), attendez le status: "success", puis appelez POST /v1/payments/{token}/refund. Le paiement passe immédiatement à refunded (total) ou partially_refunded (partiel), et un webhook payment.completed est émis. Le fonctionnement est identique pour tous les pays.

Canal REDIRECT

Avec channel: "REDIRECT", le simulateur ne génère pas d'URL de redirection. La session de checkout passe directement de pending à success ou failed après ~5 s. Un front-end qui interroge GET /v1/checkout/{token} recevra :

{
  "token": "pay_xK9mN2pQ",
  "status": "success",
  "successUrl": "https://mysite.com/payment/success"
}

Codes d'erreur

Format des erreurs

AfriGate renvoie deux formats d'erreur différents selon l'endroit où l'erreur est levée. Prenez les deux en compte lors du parsing des erreurs.

1. Erreurs gateway — authentification, rate limit, timeout, service indisponible

Levées par la gateway elle-même. error est un objet avec un code machine stable (majuscules), un message et des details optionnels, le tout dans l'enveloppe standard :

{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API key",
    "details": {}
  },
  "meta": {
    "request_id": "req_...",
    "timestamp": "2024-01-15T15:00:00.000Z"
  }
}

2. Erreurs métier — paiements, transferts, remboursements

Levées par le service de transactions et transmises telles quelles. C'est le format NestJS — pas de success, pas d'objet error, pas de details, seulement un statut HTTP et un message en texte brut :

{
  "statusCode": 400,
  "message": "Merchant not active",
  "error": "Bad Request"
}

Erreurs gateway

Codes machine en majuscules renvoyés dans le champ error.code de l'enveloppe gateway ci-dessus.

Erreurs paiement - POST /v1/payments

Erreurs annulation - POST /v1/payments/{token}/cancel

Erreurs transfert - POST /v1/transfers

Erreurs remboursement - POST /v1/payments/{token}/refund

Opérateurs par pays

Le champ operator est obligatoire. Utilisez le code unifié (minuscules) correspondant au pays et à l'opérateur ciblés. La combinaison operator + country détermine le fournisseur exact.

Côte d'Ivoire CI - XOF

Sénégal SN - XOF

Nigeria NG - NGN

Ghana GH - GHS

Botswana BW - BWP

Kenya KE - KES

Tanzanie TZ - TZS

Ouganda UG - UGX

Légende des codes unifiés

Canaux de paiement