Documentation Développeur & Guide d'Intégration

1 Présentation & Architecture

SunPayment est une plateforme de paiement automatisée pour la zone UEMOA (Burkina Faso, Côte d'Ivoire, Sénégal, Mali) permettant d'accepter des paiements Orange Money, Moov Money, Telecel et Wave avec validation instantanée grâce à un moteur d'ingestion SMS temps réel et un grand livre comptable immuable.

                 Flux Transactionnel en 4 étapes :
                Votre backend appelle POST /api/v1/payments/initiate/ avec le montant et l'opérateur.
Le client est redirigé vers l'interface de paiement hébergée (Hosted Checkout) avec le numéro destinataire et un code de transaction.
Le client valide le transfert Mobile Money depuis son téléphone ou son portefeuille USSD.
La passerelle Android SunPayment intercepte le SMS opérateur : la transaction est validée en moins de 300 ms et un webhook HMAC est expédié à votre serveur.

              

2 Espaces & Portails Marchands

SunPayment fournit une suite d'interfaces dédiées pour chaque profil utilisateur :

Espace Marchand SaaS

Portail personnel pour consulter vos encaissements, votre net à reverser, configurer vos webhooks et régénérer vos clés API.

Connexion Espace Marchand →

Dashboard Super-Admin

Surveillance globale des transactions de la plateforme, supervision de la télémétrie des passerelles Android et journal d'audit IA.

Accéder au Dashboard →

3 Authentification & Clés API

Chaque marchand dispose de deux identifiants uniques générés depuis son espace :

X-Api-Key : Clé publique marchand (ex: pk_live_...).
X-Api-Secret : Clé secrète utilisée pour signer les requêtes et vérifier les webhooks (ex: sk_live_...).

X-Api-Key: pk_live_votre_cle_publique X-Api-Secret: sk_live_votre_cle_secrete Content-Type: application/json

4 Protection Anti-Doublons & Idempotence

Pour empêcher qu'un client ne soit débité deux fois en cas de double-clic ou de perte de réseau, fournissez l'en-tête Idempotency-Key avec votre identifiant de commande interne :

Idempotency-Key: CMD-2026-99812

Si une session avec le même identifiant est déjà active en statut pending ou partially_paid, SunPayment réutilise automatiquement la session active (session_reused: true).

5 Initier un Paiement (API)

POST https://sunpayment.sunlinebf.com/api/v1/payments/initiate/

Paramètres de la requête (JSON) :

Champ	Type	Obligatoire	Description
`amount`	Number	Oui	Montant en Francs CFA (ex: `10000`)
`operator`	String	Oui	`orange`, `moov`, `telecel` ou `wave`
`customer_phone`	String	Oui	Numéro du client (ex: `+22670001122`)
`currency`	String	Non	Par défaut : `XOF`
`external_id`	String	Non	Votre identifiant de commande interne (ex: `CMD-842`)
`webhook_url`	String	Non	URL HTTPS de notification de paiement

Exemple de Réponse :

{ "success": true, "payment_id": "pay_98a72b1c4d5e", "status": "pending", "amount": 10000, "expected_amount": 10000, "amount_paid": 0, "remaining_amount": 10000, "currency": "XOF", "operator": "orange", "match_reference": "OM-88421", "checkout_url": "https://sunpayment.sunlinebf.com/pay/pay_98a72b1c4d5e", "session_reused": false }

6 Redirection du Client (Hosted Checkout)

Dès réception de la réponse, redirigez simplement l'acheteur vers :

https://sunpayment.sunlinebf.com/pay/{payment_id}

La page de paiement affiche les instructions USSD directes, le numéro de transfert, un bouton de copie rapide et actualise son état automatiquement sans que le client n'ait à rafraîchir.

7 Paiements Partiels par Acomptes (Stratégie A)

Si un client effectue un versement partiel (ex: 6 000 FCFA sur 10 000 FCFA attendus), le paiement passe au statut partially_paid.

                Un événement webhook payment.partially_paid est expédié avec amount_paid: 6000 et remaining_amount: 4000.
Le client est invité à verser les 4 000 FCFA restants sur la même session.
Dès que le total atteint 10 000 FCFA, le paiement passe automatiquement en completed.
Si le délai expire avant le versement du solde, la transaction bascule en needs_review pour arbitrage ou remboursement de l'acompte.

              

8 Vérifier le Statut d'un Paiement

GET https://sunpayment.sunlinebf.com/api/v1/payments/{payment_id}/status/

{ "success": true, "payment_id": "pay_98a72b1c4d5e", "status": "completed", "amount": 10000, "amount_paid": 10000, "remaining_amount": 0, "installments": [ { "amount": 6000, "received_at": "2026-09-20T17:05:12.000Z", "reference": "CI260920.1705.A10293" }, { "amount": 4000, "received_at": "2026-09-20T17:12:44.000Z", "reference": "CI260920.1712.B99142" } ], "completed_at": "2026-09-20T17:12:44.000Z" }

9 Réconciliation Kiosque & Reçus Opérateur

En cas de paiement en point de vente physique / kiosque, le client peut soumettre la référence de son reçu :

POST https://sunpayment.sunlinebf.com/api/v1/payments/{payment_id}/claim

{ "reference": "OM260920.5544.B123", "phone_number": "+22670123456", "note": "Paiement kiosque Orange Money" }

10 Webhooks & Sécurité HMAC-SHA256

Chaque notification envoyée par SunPayment inclut l'en-tête X-SunPayment-Signature. Pour valider que la requête émane bien de SunPayment :

// Vérification HMAC-SHA256 en Node.js import crypto from 'node:crypto'; export function verifyWebhook(rawBody, signatureHeader, apiSecret) { const signingKey = crypto.createHash('sha256').update(apiSecret).digest(); const computedHash = 'sha256=' + crypto.createHmac('sha256', signingKey).update(rawBody).digest('hex'); return crypto.timingSafeEqual(Buffer.from(computedHash), Buffer.from(signatureHeader || '')); }

11 Exemple d'Intégration en PHP / Laravel

<?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, "webhook_url" => "https://votre-site.com/api/webhooks/sunpayment" ]; $ch = curl_init("https://sunpayment.sunlinebf.com/api/v1/payments/initiate/"); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_POST, true); curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload)); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "Content-Type: application/json", "X-Api-Key: " . $apiKey, "X-Api-Secret: " . $apiSecret, "Idempotency-Key: " . $orderId ]); $response = curl_exec($ch); $result = json_decode($response, true); curl_close($ch); if ($result["success"]) { // Redirection directe vers la page de paiement SunPayment header("Location: " . $result["checkout_url"]); exit; } else { echo "Erreur : " . $result["error"]; } ?>

12 Exemple d'Intégration en Node.js / JavaScript

11 Extensions E-Commerce Prêtes à l'Emploi

Intégrez SunPayment sans écrire de code grâce à nos modules officiels pour CMS e-commerce.

WooCommerce (WordPress)

v2.0.0

Passerelle officielle pour WooCommerce 6.x à 9.x. Prise en charge Orange Money, Moov Money et Telecel, redirection hosted checkout et webhooks automatiques.

Télécharger sunpayment-woocommerce.zip

PrestaShop

v2.0.0

Module complet pour PrestaShop 1.7 et 8.x. Intégration conforme au standard PaymentModule avec notification IPN instantanée.

Télécharger sunpayment-prestashop.zip

P Payouts — décaissements API

Demandez un transfert sortant vers Orange Money, Moov Money ou Telecel. Les payouts sont limités à XOF (montant entier, minimum 1 000) et réservent immédiatement le solde disponible.

POST /api/v1/payouts/
GET /api/v1/payouts/?status=pending&limit=20
GET /api/v1/payouts/po_...
POST /api/v1/payouts/po_.../cancel/

Authentifiez les requêtes avec X-Api-Key et X-Api-Secret. Activez les droits Créer et annuler des payouts et Lire les payouts dans l’onglet Clés API du portail marchand. Utilisez Idempotency-Key pour éviter les doublons.

Cycle : pending → approved → processing → completed. Annulation, rejet et échec confirmé libèrent la réservation. À la clôture, le ledger est débité et les événements payout.* partent par webhook signé. Référence API complète : API_DOCUMENTATION.md.

12 Reçus & Factures PDF Certifiés

Chaque transaction SunPayment bénéficie d'un reçu numérique officiel infalsifiable comportant un QR code d'authentification et l'empreinte cryptographique du Grand Livre SHA-256.

Action	Méthode & URL	Description
Télécharger PDF	`GET /api/v1/payments/:payment_id/receipt.pdf`	Flux binaire `application/pdf` du reçu officiel certifié avec sceau Grand Livre.
Page Web Reçu	`GET /receipt/:payment_id`	Quittance web responsive publique avec bouton d'impression et validation en direct.
Bordereau Virement	`GET /api/v1/payouts/:payout_id/invoice.pdf`	Facture et bordereau de reversement financier pour les marchands.

Démarrage Rapide

Cycle Transactionnel

Extensions & Documents

Exemples d'Intégration