Afrosell · Documentation Créer un compte

Intégrer les paiements Afrosell

Encaissez par Mobile Money en Afrique depuis votre site ou votre application : créez un paiement avec l'API, suivez son statut et recevez une notification signée (webhook) à chaque résultat.

Démarrage

Adresse de base de l'API :

https://congopaymedia.shop/api/v1

Les requêtes et réponses sont en JSON (Content-Type: application/json). Toutes les adresses utilisent HTTPS.

Étapes : 1) Créez un compte et faites votre demande dans Espace marchand. 2) Une fois approuvé, générez vos clés dans API et webhooks. 3) Créez un encaissement avec POST /payins. 4) Recevez le résultat par webhook ou consultez-le avec GET /payins/{reference}.

Authentification

Chaque appel doit contenir votre clé secrète dans l'en-tête Authorization et votre clé publique dans X-Afrosell-Public-Key.

Authorization: Bearer afs_sk_VOTRE_CLE_SECRETE
X-Afrosell-Public-Key: afs_pk_VOTRE_CLE_PUBLIQUE
La clé secrète n'est affichée qu'une seule fois, à sa génération. Gardez-la côté serveur : jamais dans une application mobile, un navigateur ou un dépôt public.

Pays et opérateurs

GET/countries liste les pays actifs, leur devise, les montants minimum et maximum, et les frais. GET/payment-methods?country=CI liste les opérateurs d'un pays.

PaysCodeDeviseFrais d'encaissement
BéninBJXOF0 %
Burkina FasoBFXOF0 %
CamerounCMXAF0 %
Congo-BrazzavilleCGXAF0 %
Côte d'IvoireCIXOF0 %
GabonGAXAF0 %
GhanaGHGHS0 %
Guinée ConakryGNGNF0 %
KenyaKEKES0 %
MaliMLXOF0 %
NigerNEXOF0 %
NigériaNGNGN0 %
OugandaUGUGX0 %
République démocratique du CongoCDCDF0 %
RwandaRWRWF0 %
SénégalSNXOF0 %
TanzanieTZTZS0 %
TogoTGXOF0 %

Payin : créer un encaissement

POST/payins

ChampTypeDescription
amountnombreMontant à débiter, dans la devise locale du pays. Obligatoire.
currencytexteDevise du pays (ex. XOF). Doit correspondre au pays. Obligatoire.
countrytexteCode pays à 2 lettres (ex. CI). Obligatoire.
customer.nametexteNom du client. Obligatoire.
customer.mobiletexteNuméro Mobile Money du client, avec ou sans indicatif. Obligatoire pour un paiement sans redirection.
customer.emailtexteE-mail du client (facultatif).
payment_methodtexteOpérateur choisi (voir /payment-methods).
otptexteCode OTP Orange Money, obligatoire pour Orange Money en Côte d'Ivoire et au Sénégal.
referencetexteVotre propre référence (ex. numéro de commande). Une même référence ne crée jamais deux encaissements : si elle existe déjà, le paiement existant est renvoyé.
descriptiontexteLibellé du paiement.
metadataobjetInformations libres, renvoyées dans les webhooks.

Exemple : cURL

curl -X POST https://congopaymedia.shop/api/v1/payins \
  -H "Authorization: Bearer afs_sk_VOTRE_CLE_SECRETE" \
  -H "X-Afrosell-Public-Key: afs_pk_VOTRE_CLE_PUBLIQUE" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "XOF",
    "country": "CI",
    "payment_method": "MTN MoMo",
    "reference": "COMMANDE-1042",
    "description": "Commande 1042",
    "customer": { "name": "Awa Kone", "email": "awa@example.com", "mobile": "0707070707" }
  }'

Exemple : PHP

<?php
$payload = [
    'amount'   => 5000,
    'currency' => 'XOF',
    'country'  => 'CI',
    'payment_method' => 'MTN MoMo',
    'reference' => 'COMMANDE-1042',
    'customer' => ['name' => 'Awa Kone', 'mobile' => '0707070707'],
];

$ch = curl_init('https://congopaymedia.shop/api/v1/payins');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('AFS_SECRET_KEY'),
        'X-Afrosell-Public-Key: ' . getenv('AFS_PUBLIC_KEY'),
        'Content-Type: application/json',
    ],
]);
$result = json_decode(curl_exec($ch), true);
echo $result['data']['reference'] ?? $result['error']['message'];

Exemple : JavaScript (Node.js)

const res = await fetch('https://congopaymedia.shop/api/v1/payins', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ' + process.env.AFS_SECRET_KEY,
    'X-Afrosell-Public-Key': process.env.AFS_PUBLIC_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 5000, currency: 'XOF', country: 'CI',
    payment_method: 'MTN MoMo', reference: 'COMMANDE-1042',
    customer: { name: 'Awa Kone', mobile: '0707070707' },
  }),
});
const json = await res.json();
console.log(json.data?.reference ?? json.error.message);

Réponse (201)

{
  "status": "success",
  "data": {
    "reference": "AFSR-9F2C41A7B3D05E6C8A11",
    "merchant_reference": "COMMANDE-1042",
    "status": "pending",
    "country": "CI",
    "currency": "XOF",
    "amount": 5000,
    "fee": 0.45,
    "net_amount": 8.55,
    "credit_currency": "USD",
    "payment_method": "MTN MoMo",
    "customer": { "name": "Awa Kone", "email": "awa@example.com", "mobile": "707070707" },
    "created_at": "2026-11-16T10:21:07+00:00",
    "paid_at": null,
    "mode": "direct"
  }
}
Paiement sans redirection : le client reçoit une demande de confirmation sur son téléphone et valide avec son code PIN. Le statut reste pending jusqu'à sa confirmation. Pour certains pays (Nigéria, crypto), la réponse contient payment_link : redirigez alors le client vers ce lien.

Montants : amount est le montant débité au client (devise locale). fee et net_amount sont exprimés en USD, la devise de votre solde : net_amount est le montant crédité sur votre solde après les frais.

Consulter un encaissement

GET/payins/{reference} renvoie le même objet que la création, avec le statut à jour.

StatutSignification
pendingEn attente de confirmation du client.
successPayé. Votre solde est crédité.
failedÉchoué, refusé ou annulé. Rien n'est crédité.

Solde

GET/balance renvoie {"status":"success","data":{"balance":125.4,"currency":"USD"}}.

Webhooks

Enregistrez l'adresse HTTPS de votre serveur dans API et webhooks. À chaque paiement réussi ou échoué, nous envoyons un POST JSON avec ces en-têtes :

En-têteContenu
X-Afrosell-Eventpayin.succeeded ou payin.failed
X-Afrosell-TimestampHorodatage Unix de l'envoi.
X-Afrosell-Signaturesha256= suivi du HMAC-SHA256 de timestamp + "." + corps brut, calculé avec votre secret webhook (whsec_...).

Corps reçu

{
  "event": "payin.succeeded",
  "data": {
    "reference": "AFSR-9F2C41A7B3D05E6C8A11",
    "merchant_reference": "COMMANDE-1042",
    "status": "success",
    "country": "CI",
    "currency": "XOF",
    "amount": 5000,
    "fee": 0.45,
    "net_amount": 8.55,
    "credit_currency": "USD",
    "customer": { "name": "Awa Kone", "email": "awa@example.com", "mobile": "707070707" },
    "paid_at": "2026-11-16T10:22:31+00:00"
  }
}

Vérifier la signature : PHP

<?php
$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_AFROSELL_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_AFROSELL_SIGNATURE'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $raw, getenv('AFS_WEBHOOK_SECRET'));
if (!hash_equals($expected, $sig) || abs(time() - (int) $ts) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($raw, true);
if ($event['event'] === 'payin.succeeded') {
    // Marquez la commande $event['data']['merchant_reference'] comme payée (de façon idempotente)
}
http_response_code(200);

Vérifier la signature : Node.js

import crypto from 'node:crypto';
import express from 'express';

const app = express();
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.header('X-Afrosell-Timestamp') ?? '';
  const sig = req.header('X-Afrosell-Signature') ?? '';
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.AFS_WEBHOOK_SECRET)
    .update(ts + '.' + req.body).digest('hex');

  const ok = sig.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
    && Math.abs(Date.now() / 1000 - Number(ts)) < 300;
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body.toString());
  if (event.event === 'payin.succeeded') {
    // Marquez la commande event.data.merchant_reference comme payée (de façon idempotente)
  }
  res.sendStatus(200);
});
Répondez avec un code 2xx dès que la signature est validée. Traitez chaque événement de façon idempotente (la même référence peut être renvoyée) et vérifiez toujours la signature avant d'agir. Vous pouvez renvoyer un webhook depuis la page Transactions.

Payout : envoyer de l'argent

L'envoi d'argent vers Mobile Money par l'API arrive dans une prochaine version. En attendant, vous pouvez retirer le solde de votre compte vers Mobile Money depuis votre Portefeuille, ou le transférer à un autre utilisateur.

Liens de paiement

Sans écrire de code, créez un lien dans Liens de paiement : montant fixe ou libre, pays au choix. Partagez-le par WhatsApp, SMS ou réseaux sociaux. Votre client ouvre la page, choisit son opérateur et valide sur son téléphone. Vous recevez les mêmes webhooks que pour l'API.

Erreurs

En cas d'erreur, la réponse a ce format :

{ "status": "error", "error": { "code": "invalid_request", "message": "Montant invalide." } }
HTTPCodeSignification
401unauthorizedClés manquantes, invalides ou révoquées.
403merchant_inactiveCompte marchand non approuvé ou suspendu.
404not_foundEncaissement introuvable.
422invalid_requestDonnées invalides (le champ details précise lesquelles).
429-Trop de requêtes : patientez quelques secondes.
502provider_errorL'opérateur de paiement n'a pas pu traiter la demande.

Bonnes pratiques de sécurité

Gardez vos clés dans des variables d'environnement. Ne journalisez jamais la clé secrète ni le secret webhook. Vérifiez la signature de chaque webhook et refusez les horodatages de plus de 5 minutes. Régénérez vos clés si vous pensez qu'elles ont fuité : les anciennes cessent de fonctionner immédiatement.