Sur cette page

Intégrer le paiement

Trois étapes, une trentaine de lignes de code. Votre client paie sur une page hébergée chez nous : vous n'avez jamais à manipuler ses coordonnées bancaires ni son numéro mobile money.

PHP, cURL ou tout client HTTP Environnement de test inclus Webhooks signés

Créer une sessionVotre serveur appelle l'API et reçoit une URL.
Rediriger le clientIl paie sur la page hébergée, depuis son téléphone.
Recevoir le résultatUn webhook signé confirme le paiement.

Le principe

Votre serveur crée une session de paiement et reçoit une URL. Vous y redirigez votre client, il paie, puis nous notifions votre serveur par un webhook signé. Le retour du client sur votre site n'arrive qu'après, et ne sert qu'à l'affichage.

Le webhook part avant le retour du client : c'est lui, et non la redirection, qui fait foi.

1Créer une session

Depuis votre serveur, avec votre clé secrète.

Jamais depuis le navigateurUne clé sk_ placée dans du JavaScript ou une application mobile permet à n'importe qui de créer des paiements et de lire vos transactions en votre nom.

$hub = new Hub\Client('sk_test_…');

$session = $hub->sessions->creer([
    'montant'    => 25000,          // en francs, sans décimale
    'devise'     => 'XOF',
    'reference'  => $commande->numero,
    'url_succes' => 'https://boutique.ci/merci',
]);

curl https://ad-novapay-ci.agence-nconcept.com/v1/sessions \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: commande-4711" \
  -d '{"montant": 25000, "devise": "XOF", "reference": "CMD-4711"}'

Le montant est exprimé en unité mineure entière. Le franc CFA n'ayant pas de décimale, 1 000 F s'écrit simplement 1000.

2Rediriger le client

PHP

header('Location: ' . $session['url']);
exit;

Votre client choisit son moyen de paiement, confirme sur son téléphone, puis revient sur votre url_succes. La page hébergée gère l'attente de validation, les échecs et les nouvelles tentatives.

3Recevoir le résultat

Déclarez un endpoint depuis votre espace développeur. Vérifiez toujours la signature avant de traiter l'événement, et répondez 200 rapidement.

$evenement = Hub\Webhooks::depuisRequete('whsec_…');

if ($evenement['type'] === 'paiement.reussi') {
    $reference = $evenement['donnees']['paiement']['reference'];
    // Livrez la commande.
}

http_response_code(200);

$horodatage = $_SERVER['HTTP_X_HORODATAGE'] ?? '';
$signature  = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$charge     = file_get_contents('php://input');

// Au-delà de 5 minutes, une charge interceptée pourrait être rejouée.
$attendue = hash_hmac('sha256', $horodatage . '.' . $charge, $secret);

if (abs(time() - (int) $horodatage) > 300 || ! hash_equals($attendue, $signature)) {
    http_response_code(400);
    exit;
}

$evenement = json_decode($charge, true);

Votre endpoint doit répondre 200 en moins de 15 secondes. Pour un traitement long (email, facture, stock), enregistrez l'événement et traitez-le dans une file d'attente.

Trois pièges à éviter

Ce sont les erreurs que nous voyons le plus souvent, et les plus coûteuses.

Le retour navigateur ne prouve rien

Un client peut fermer son onglet avant la redirection : vous ne saurez jamais qu'il a payé. Il peut aussi ouvrir votre URL de succès sans avoir payé, en la devinant ou en revenant en arrière.

Ne validez une commande que sur webhook, ou sur interrogation du statut. L'URL de succès sert à afficher un message, rien de plus.

Le statut indéterminé existe

En mobile money, un paiement peut rester sans réponse : l'opérateur ne confirme ni ne refuse, et le payeur a peut-être été débité. Nous ne le déclarons jamais en échec. Il passe en a_revoir, et notre réconciliation tranche sous 24 heures à partir du relevé opérateur.

Ne livrez pas, mais ne considérez pas la commande annulée. Et surtout, ne demandez pas au client de repayer : c'est ainsi qu'on crée un double débit et une réclamation.

L'idempotence n'est pas optionnelle

Un timeout ne vous dit pas si la requête a abouti. Sans clé d'idempotence, la rejouer crée un doublon.

En-tête HTTP

# Une clé stable dérivée de votre commande, pas un aléatoire :
# sinon le rejeu ne sert à rien.
Idempotency-Key: commande-4711

Tester

Avec une clé sk_test_, aucun mouvement réel n'est produit. Les scénarios se pilotent par les quatre derniers chiffres du numéro du payeur.

Numéro finissant par	Résultat
…0000	Succès immédiat
…0002	Solde insuffisant
…0004	Opérateur indisponible
…0005	Statut indéterminé À tester en priorité
…0006	Aucune réponse, expirera

Liste complète, cartes de test et avance du temps sur la page ressources.

Commencez par 0005C'est le cas que la plupart des intégrations gèrent mal, et celui qui produit les réclamations.

Passer en production

Cochez chaque point au fur et à mesure. Votre progression reste enregistrée dans ce navigateur.

Avant la mise en ligne 0/7

Le scénario 0005 ne livre pas la commande et ne propose pas de repayer
Une expiration est testée, via l'avance du temps du bac à sable
Votre endpoint répond 200 en moins de 15 secondes
Rejouer un webhook ne livre pas la commande deux fois
Votre URL de succès ne valide rien à elle seule
Vos clés sk_test_ sont remplacées par sk_live_
Votre endpoint de production est déclaré, avec son propre secret

Votre espace développeur affiche vos derniers événements et vos tentatives de livraison, avec le code HTTP renvoyé par votre serveur. La plupart des problèmes de réception s'y diagnostiquent sans nous écrire.