Sommaire
Référence développeur
Accepter Mobile Money avec l’API SunPayment
Créez un paiement, redirigez le client vers la page hébergée, recevez un webhook signé quand l’argent arrive. Tout tient en trois appels.
1Présentation
SunPayment permet d’accepter des paiements Orange Money dans la zone UEMOA. Chaque transfert est validé automatiquement grâce aux SMS de l’opérateur reçus par un téléphone passerelle, et inscrit dans un grand livre infalsifiable.
Le parcours d’un paiement
1Votre serveur crée le paiement
Appel à
POST /api/v1/paymentsavec le montant, l’opérateur et le numéro du client.2Le client ouvre la page de paiement
Redirection vers le
checkout_urlrenvoyé : numéro à créditer, code USSD, suivi en direct.3Le client envoie l’argent
Depuis son téléphone (USSD ou application Mobile Money).
4SunPayment valide et vous notifie
Le téléphone passerelle reçoit le SMS de l’opérateur, le paiement est validé et un webhook signé part vers votre serveur.
Adresse de l’API
https://sunpayment.sunlinebf.com/api/v12Authentification
Chaque marchand dispose de deux identifiants, générés dans son espace (onglet Intégration). Les deux en-têtes sont toujours obligatoires : une requête sans secret répond 401.
| En-tête | Contenu |
|---|---|
X-Api-Key | Clé publique du marchand (pk_live_…). |
X-Api-Secret | Clé secrète (sk_live_…). À garder sur votre serveur, jamais dans une application ou un site. |
X-Api-Key: pk_live_votre_cle_publique X-Api-Secret: sk_live_votre_cle_secrete Content-Type: application/json
GET /api/v1/payments/{payment_id}/status/est publique (voir Vérifier le statut).- Les réclamations du payeur acceptent aussi le jeton
X-Claim-Token(voir Réclamations). - La création de compte par API (
POST /api/v1/merchants/register) est réservée à l’administrateur. Les marchands s’inscrivent depuis l’Espace marchand, dont la session passe uniquement par un cookieHttpOnly.
400 : { "success": false, "error": "Données invalides : <champ> — <message>", "details": [{ "field", "message" }] }.3Protection contre les doublons
Pour qu’un double clic ou une coupure réseau ne débite jamais deux fois un client, envoyez l’en-tête Idempotency-Key avec votre identifiant de commande :
Idempotency-Key: CMD-2026-99812
- Rejeu : une clé déjà utilisée par votre compte (en-tête ou champ
idempotency_key, 1 à 128 caractères) renvoie le paiement d’origine en200, avec l’en-têteIdempotent-Replay: trueetidempotent_replay: true. - Session réutilisée : si un paiement
pendingoupartially_paidnon expiré existe déjà avec le même opérateur, le même montant et le même numéro, il est renvoyé en200(Active-Session-Reused: true,session_reused: true) au lieu d’en créer un second.
external_id : c’est lui qui rattache une session réutilisée, et chaque webhook, à votre commande.4Créer un paiement
/api/v1/paymentsAlias historique équivalent : POST /api/v1/payments/initiate/. Limite : 60 appels par minute.
Corps de la requête (JSON)
| Champ | Type | Requis | Description |
|---|---|---|---|
amount | nombre ou texte | oui | Montant positif, 2 décimales maximum (10000 ou "10000.00"). Un texte non numérique est refusé. |
operator | texte | oui | orange : seuls les opérateurs activés sur le serveur sont acceptés (sinon 400). Wave et MTN ne sont pas pris en charge. |
customer_phone | texte | oui | Numéro du client, 8 à 15 chiffres (+22670001122). |
currency | texte | non | XOF uniquement (franc CFA UEMOA, par défaut). Toute autre devise répond 400. |
external_id | texte | non | Votre identifiant de commande (128 caractères max), renvoyé dans le statut, la liste et les webhooks. |
idempotency_key | texte | non | Équivalent de l’en-tête Idempotency-Key. |
description | texte | non | Produit ou service payé, affiché au client sur la page de paiement (500 caractères max). |
webhook_url | texte | non | URL HTTPS de notification. Sans elle, aucun événement payment.* n’est envoyé pour ce paiement. |
return_url | texte | non | Retour vers votre boutique. Le client y est redirigé 5 s après la validation. |
cancel_url | texte | non | Bouton « Retour » en cas d’échec ou d’expiration (return_url à défaut). |
Si le marchand a mis en pause tous ses téléphones de l’opérateur demandé (Espace Marchand → Téléphones → Pause), la création répond 503 avec "error_code": "PAYMENTS_PAUSED" et paused_until (reprise prévue, null si reprise manuelle). Proposez un autre opérateur ou réessayez plus tard.
Réponse 201 Created
{
"success": true,
"payment_id": "pay_98a72b1c4d5e6f70",
"status": "pending",
"idempotent_replay": false,
"amount": "10000.00",
"expected_amount": "10000.00",
"amount_paid": 0,
"remaining_amount": 10000,
"amount_to_send": 10000,
"currency": "XOF",
"operator": "orange",
"external_id": "CMD-842",
"description": "Abonnement Premium - Octobre",
"match_reference": "A3F1C9E2B7D04E5F8A6B1C2D3E4F5A6B",
"checkout_url": "https://sunpayment.sunlinebf.com/pay/pay_98a72b1c4d5e6f70#ct=9f2c7a1e4b8d3f60a1b2c3d4e5f60718",
"claim_token": "9f2c7a1e4b8d3f60a1b2c3d4e5f60718",
"return_url": "https://votre-site.com/commande/CMD-842/confirmation",
"cancel_url": "https://votre-site.com/panier",
"expires_at": "2026-09-21T05:00:00.000Z",
"instructions": "Invitez votre client à envoyer exactement 10000.00 XOF via orange."
}checkout_url: page de paiement à ouvrir telle quelle, avec son fragment#ct=(voir Page de paiement).claim_token: jeton de réclamation du payeur, renvoyé une seule fois, à la création.expires_at: création +PAYMENT_EXPIRY_MINUTES(720 minutes, soit 12 h, par défaut). Ensuite le paiement passeexpired, ouneeds_reviewsi un acompte a été reçu.- Sur la page de paiement, le client dispose de
CHECKOUT_WINDOW_MINUTES(10 minutes par défaut) à partir de sa première ouverture du lien, jamais au-delà deexpires_at. Passé ce délai, la page l'invite à patienter s'il a déjà payé ou à relancer 10 minutes ; le paiement reste ouvert et un transfert tardif est rapproché normalement. - Un rejeu ou une session réutilisée répondent
200, sansclaim_token.
5Page de paiement hébergée
Redirigez le client vers le checkout_url reçu, sans le modifier :
https://sunpayment.sunlinebf.com/pay/{payment_id}#ct={claim_token}Le fragment #ct= donne à la page le droit de valider un paiement fait depuis un autre numéro que customer_phone, ou en kiosque avec la référence du SMS. Il n’est jamais envoyé au serveur. Une URL reconstruite sans lui affiche la page, mais ces validations y sont refusées.
La page rappelle le numéro déclaré. Sans confirmation au bout de 3 minutes, elle propose au client de saisir le numéro réellement utilisé : les transferts reçus depuis ce numéro après la création du paiement y sont rattachés.
SMS de l’opérateur jamais reçu (Orange Money)
Si le transfert a eu lieu mais que l’opérateur n’envoie pas le SMS de crédit, SunPayment lit le relevé Max it du marchand depuis son téléphone passerelle (dès 60 s d’attente, puis à intervalles croissants pendant 2 h) et valide le paiement s’il y figure. La route de statut porte alors un objet verification (state : scheduled, running, checked, failed, paused ou unavailable, avec checked_at et une phrase message). Le marchand authentifié reçoit en plus failure_code, failure_label, device_name et hold_until.
Chaque ligne du relevé porte la référence opérateur réelle (ex. PP260923.0920.2949831). Le Trans ID saisi par le client, ou transmis via POST /api/v1/payments/{payment_id}/report-paid/, retrouve donc le transfert même sans SMS.
Retour vers votre boutique
| Situation | Comportement |
|---|---|
Paiement validé (completed) | Avec un return_url : reçu affiché, puis redirection au bout de 5 s. Le client peut rester sur le reçu pour l’imprimer. |
Sans return_url | Aucune redirection : le client reste sur le reçu. |
| Échec ou expiration | Pas de redirection automatique ; un bouton « Retour » pointe vers cancel_url (ou return_url). |
Acompte (partially_paid) | Le client reste sur la page pour verser le solde. |
return_url est appelé tel quel, sans paramètre ajouté. Un retour du client sur cette URL ne prouve pas le paiement : validez toujours la commande par le webhook ou la route de statut. Astuce : mettez votre référence dans l’URL (…/commande/CMD-842/confirmation).6Paiements par acomptes
Si le client verse moins que prévu (par exemple 6 000 FCFA sur 10 000), le paiement passe partially_paid :
- Un webhook
payment.partially_paidpart avecamount_paid: 6000etremaining_amount: 4000. - Le client verse le solde sur la même page.
- Quand le total atteint 10 000 FCFA, le paiement passe
completed. - Si le délai expire avant, il passe
needs_reviewpour arbitrage ou remboursement de l’acompte.
7Vérifier le statut
/api/v1/payments/{payment_id}/status/C’est la route de statut, et elle est publique (la page de paiement l’interroge en boucle). Il n’existe pas de GET /api/v1/payments/{payment_id}. Sans authentification, customer_phone est masqué et installments absent ; avec les clés du marchand propriétaire, la réponse est complète. Jamais mise en cache.
{
"success": true,
"payment_id": "pay_98a72b1c4d5e6f70",
"status": "completed",
"amount": "10000.00",
"expected_amount": "10000.00",
"amount_paid": 10000,
"remaining_amount": 0,
"currency": "XOF",
"operator": "orange",
"customer_phone": "+22670123456",
"external_id": "CMD-842",
"description": "Abonnement Premium - Octobre",
"review_reason": "",
"review_requested_at": null,
"open_claims": 0,
"verification": null,
"created_at": "2026-09-20T17:00:00.000Z",
"expires_at": "2026-09-21T05:00:00.000Z",
"completed_at": "2026-09-20T17:12:44.000Z",
"installments": [
{ "id": 8812, "amount": "6000.00", "operator": "orange", "received_at": "2026-09-20T17:05:12.000Z", "reference": "CI260920.1705.A10293" },
{ "id": 8817, "amount": "4000.00", "operator": "orange", "received_at": "2026-09-20T17:12:44.000Z", "reference": "CI260920.1712.B99142" }
]
}Statuts possibles : pending, partially_paid, completed, needs_review, expired, cancelled, failed. Liste paginée : GET /api/v1/payments/?status=completed&limit=20 (filtres operator, external_id, from, to ; pagination cursor).
8Réclamations du payeur
Paiement en kiosque, SMS tardif ou transfert depuis un autre numéro : la page de paiement appelle ces routes pour le client, et votre serveur peut aussi les appeler. Autorisation : le marchand propriétaire (X-Api-Key + X-Api-Secret) ou le porteur du jeton de réclamation (X-Claim-Token ou champ claim_token). Le porteur du jeton a 5 tentatives par paiement (puis 429). Limite : 30 appels par minute.
Référence de la transaction
/api/v1/payments/{payment_id}/claim/X-Claim-Token: 9f2c7a1e4b8d3f60a1b2c3d4e5f60718
Content-Type: application/json
{
"operator_reference": "PP260923.0920.2949831"
}operator_reference (obligatoire) : Trans ID du SMS ou du reçu, 3 à 64 caractères (lettres, chiffres, ., _, -), ou le SMS de débit complet collé par le client (1 000 caractères max) : seule la référence en est extraite, le reste n'est pas conservé. Si le SMS est déjà reçu, le paiement est validé immédiatement ({ "success": true, "status": "completed" }). Sinon la route répond 400 et déclenche la lecture du relevé Max it : réessayez ou consultez le statut un peu plus tard.
Numéro réellement utilisé
/api/v1/payments/{payment_id}/claim-phone/{
"payer_phone": "+22676543210"
}Les transferts reçus depuis ce numéro après la création du paiement y sont rattachés. Réponse { "success": true, "matched": true, "status": "completed" } ; matched: false signifie que le paiement sera validé dès réception du SMS. Côté marchand, POST /api/v1/payments/{payment_id}/report-paid/ (montant, téléphone, operator_reference, paid_at, note) ouvre une réclamation et passe le paiement en needs_review si la référence n’est pas retrouvée.
9Webhooks et signature
SunPayment notifie votre serveur par un POST JSON signé. Les événements payment.* et claim.* partent vers le webhook_url donné à la création du paiement : sans lui, rien n’est envoyé. Les payout.* utilisent l’URL de la demande de payout, sinon celle du profil marchand ; les refund.* demandés par l’API utilisent l’URL du profil marchand.
Événements envoyés
| Événement | Quand |
|---|---|
payment.completed | Le montant attendu est entièrement reçu : livrez la commande. |
payment.partially_paid | Un acompte est reçu ; il reste remaining_amount à payer. |
payment.overpaid | Le client a trop versé : surplus_amount et refund_id (remboursement du surplus, suivi de refund.created). |
payment.expired | expires_at dépassé sans aucun versement. |
payment.partially_paid_expired | Délai écoulé avec un acompte : le paiement passe needs_review. |
payment.cancelled | Paiement annulé via POST …/cancel/. |
claim.rejected | Réclamation (report-paid) rejetée après arbitrage. |
payout.created … payout.cancelled | Cycle de vie d’un payout (created, approved, processing, completed, failed, rejected, cancelled). |
refund.created … refund.cancelled | Cycle de vie d’un remboursement (created, approved, completed, rejected, cancelled). |
webhook.test | Bouton de test de l’Espace marchand (envoi unique, sans nouvelle tentative). |
payment.needs_review, payment.failed, payment.refunded, payment.quarantined, payment.processing, claim.accepted. Un passage en needs_review se constate sur la route de statut ; une réclamation acceptée donne payment.completed.En-têtes
| En-tête | Contenu |
|---|---|
User-Agent | SunPayment-Webhook/2.0 |
X-SunPayment-Event | Type d’événement (payment.completed…) |
X-SunPayment-Event-Id | Identifiant unique, identique d’une tentative à l’autre : servez-vous-en pour dédoublonner. |
X-SunPayment-Timestamp | Horodatage Unix (secondes) de l’envoi. |
X-SunPayment-Signature | t=<timestamp>,v1=<signature hex> |
Exemple : payment.completed
{
"event": "payment.completed",
"payment_id": "pay_98a72b1c4d5e6f70",
"external_id": "CMD-842",
"description": "Abonnement Premium - Octobre",
"status": "completed",
"total_expected_amount": 10000,
"amount_received": 4000,
"amount_paid": 10000,
"remaining_amount": 0,
"currency": "XOF",
"operator": "orange",
"customer_phone": "+22670123456",
"reference": "CI260920.1712.B99142",
"timestamp": "2026-09-20T17:12:44.000Z",
"completed_at": "2026-09-20T17:12:44.000Z"
}amount_received est le versement qui déclenche l’événement (ici le solde de 4 000 après 6 000 d’acompte), amount_paid le cumul et total_expected_amount le montant attendu. Certains champs manquent selon le mode de rapprochement : en cas de doute, la route de statut fait foi.
Vérifier la signature
La signature est un HMAC-SHA256 de <timestamp>.<corps brut>. La clé est votre secret webhook (whsec_…), généré dans l’Espace marchand (onglet Intégration) ; il n’est affiché qu’une fois. Tant qu’aucun secret n’est généré, la clé est l’empreinte SHA-256 (hexadécimale) de votre clé secrète sk_…. Calculez la signature sur le corps brut, avant tout parsing, et refusez un horodatage de plus de 5 minutes.
import crypto from 'node:crypto';
export function verifyWebhook(rawBody, signatureHeader, webhookSecret, apiSecret) {
const parts = Object.fromEntries((signatureHeader || '').split(',').map((p) => p.split('=')));
const t = parts.t;
const v1 = parts.v1 || '';
if (!t || Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
// Secret whsec_... ; à défaut, empreinte SHA-256 du secret API
const key = webhookSecret || crypto.createHash('sha256').update(apiSecret).digest('hex');
const expected = crypto.createHmac('sha256', key).update(t + '.' + rawBody).digest('hex');
return v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}$raw = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_SUNPAYMENT_SIGNATURE'] ?? ''), $sig);
$t = $sig['t'] ?? '';
// Secret whsec_... ; à défaut, empreinte SHA-256 du secret API
$key = $webhookSecret !== '' ? $webhookSecret : hash('sha256', $apiSecret);
$expected = hash_hmac('sha256', $t . '.' . $raw, $key);
if (!$t || abs(time() - (int) $t) > 300 || !hash_equals($expected, $sig['v1'] ?? '')) {
http_response_code(401);
exit;
}Accusé de réception et nouvelles tentatives
- Répondez HTTP 2xx en moins de 10 secondes ; faites les traitements longs en arrière-plan.
- Sinon, 5 tentatives au total, espacées de 2, 4, 8 puis 16 minutes.
- Un événement peut arriver plusieurs fois et dans le désordre : dédoublonnez avec
X-SunPayment-Event-Idet ne livrez jamais deux fois une commande.
10Payouts (décaissements)
Demandez un transfert sortant vers Orange Money. Les payouts sont en XOF (montant entier, 100 minimum) et réservent immédiatement le solde disponible.
| Méthode | Route | Rôle |
|---|---|---|
| POST | /api/v1/payouts/ | Créer une demande (avec Idempotency-Key). |
| GET | /api/v1/payouts/?status=pending&limit=20 | Lister les demandes. |
| GET | /api/v1/payouts/po_… | Détail d’une demande. |
| POST | /api/v1/payouts/po_…/cancel/ | Annuler une demande en attente. |
Activez les droits « Créer et annuler des retraits » et « Lire les retraits » de la clé dans l’Espace marchand (onglet Intégration). L’annulation accepte aussi la session de l’Espace marchand.
Cycle : pending → approved → processing → completed. Annulation, rejet et échec libèrent la réservation. À la clôture, le grand livre est débité et les événements payout.* partent par webhook signé.
11Exemples de code
Création d’un paiement puis redirection du client vers la page de paiement, dans votre langage :
curl -X POST https://sunpayment.sunlinebf.com/api/v1/payments \
-H "Content-Type: application/json" \
-H "X-Api-Key: pk_live_votre_cle_publique" \
-H "X-Api-Secret: sk_live_votre_cle_secrete" \
-H "Idempotency-Key: CMD-842" \
-d '{
"amount": 10000,
"operator": "orange",
"customer_phone": "+22670123456",
"external_id": "CMD-842",
"description": "Commande CMD-842",
"webhook_url": "https://votre-site.com/api/webhooks/sunpayment",
"return_url": "https://votre-site.com/commande/CMD-842/confirmation",
"cancel_url": "https://votre-site.com/panier"
}'<?php
$apiKey = "pk_live_votre_cle_publique";
$apiSecret = "sk_live_votre_cle_secrete";
$orderId = "CMD-" . time();
$payload = [
"amount" => 10000,
"operator" => "orange",
"customer_phone" => "+22670123456",
"external_id" => $orderId,
"description" => "Commande " . $orderId,
"webhook_url" => "https://votre-site.com/api/webhooks/sunpayment",
"return_url" => "https://votre-site.com/commande/" . $orderId . "/confirmation",
"cancel_url" => "https://votre-site.com/panier",
];
$ch = curl_init("https://sunpayment.sunlinebf.com/api/v1/payments");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: " . $apiKey,
"X-Api-Secret: " . $apiSecret,
"Idempotency-Key: " . $orderId,
],
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if ($result["success"]) {
header("Location: " . $result["checkout_url"]); // page de paiement SunPayment
exit;
}
echo "Erreur : " . $result["error"];const orderId = 'CMD-' + Date.now();
const response = await fetch('https://sunpayment.sunlinebf.com/api/v1/payments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Api-Key': process.env.SUNPAYMENT_API_KEY,
'X-Api-Secret': process.env.SUNPAYMENT_API_SECRET,
'Idempotency-Key': orderId,
},
body: JSON.stringify({
amount: 10000,
operator: 'orange',
customer_phone: '+22670123456',
external_id: orderId,
description: 'Commande ' + orderId,
webhook_url: 'https://votre-site.com/api/webhooks/sunpayment',
return_url: 'https://votre-site.com/commande/' + orderId + '/confirmation',
cancel_url: 'https://votre-site.com/panier',
}),
});
const data = await response.json();
if (data.success) {
// Côté serveur : renvoyez data.checkout_url au navigateur pour la redirection
console.log(data.checkout_url);
}import json, os, time, urllib.request
order_id = f"CMD-{int(time.time())}"
payload = {
"amount": 10000,
"operator": "orange",
"customer_phone": "+22670123456",
"external_id": order_id,
"description": f"Commande {order_id}",
"webhook_url": "https://votre-site.com/api/webhooks/sunpayment",
"return_url": f"https://votre-site.com/commande/{order_id}/confirmation",
"cancel_url": "https://votre-site.com/panier",
}
request = urllib.request.Request(
"https://sunpayment.sunlinebf.com/api/v1/payments",
data=json.dumps(payload).encode(),
method="POST",
headers={
"Content-Type": "application/json",
"X-Api-Key": os.environ["SUNPAYMENT_API_KEY"],
"X-Api-Secret": os.environ["SUNPAYMENT_API_SECRET"],
"Idempotency-Key": order_id,
},
)
with urllib.request.urlopen(request) as response:
data = json.load(response)
print(data["checkout_url"]) # redirigez le client vers cette pageDes SDK officiels (PHP, Node.js, Python) sont téléchargeables depuis l’Espace marchand, onglet Intégration.
12Plugins e-commerce
Encaissez sans écrire de code avec les modules officiels.
WooCommerce
v2.0.0WordPress 5.8+, WooCommerce 6 à 9. Orange Money, page de paiement hébergée et webhooks automatiques.
sunpayment-woocommerce.zipPrestaShop
v2.0.0PrestaShop 1.7 et 8. Module de paiement natif, commande validée dès la confirmation de l’opérateur.
sunpayment-prestashop.zip13Reçus et factures PDF
Chaque transaction dispose d’un reçu officiel avec QR code d’authentification et empreinte du grand livre.
| Document | Route | Contenu |
|---|---|---|
| Reçu PDF | GET /api/v1/payments/{payment_id}/receipt.pdf | Fichier application/pdf du reçu. |
| Reçu en ligne | GET /receipt/{payment_id} | Page publique imprimable, vérifiable. |
| Bordereau de retrait | GET /api/v1/payouts/{payout_id}/invoice.pdf | Facture de reversement pour le marchand. |
14OpenAPI et Postman
/api/openapi.ymlDescription OpenAPI 3 complète (YAML public, mis en cache 5 minutes) : routes, corps, erreurs et, dans x-webhooks, le contenu de chaque événement. Importez-la dans Postman, Insomnia ou Swagger UI, ou générez un client avec openapi-generator.
Une collection Postman (postman/SunPayment.postman_collection.json) accompagne le dépôt : renseignez base_url, api_key et api_secret.