Intégrer ePaieLink sur votre site

Ce guide vous accompagne pas à pas : création d'un paiement, checkout client, confirmation par webhook. Environnement actif : Production

Démarrage rapide — votre premier paiement

Histoire concrète : Marie achète un article à 5 000 CDF sur votre site. Votre serveur crée le paiement, votre page ouvre la modale ePaieLink, Marie paie en Mobile Money, vous recevez une notification sur votre webhook_url.

[Site marchand] [API ePaieLink] [Checkout] [Votre webhook] Bouton « Payer » → POST payment-intent → Modale iframe → POST status=succeeded ↓ ↓ checkout_url Client confirme sur son téléphone

Avant de coder — checklist

Compte marchand actif + clés API (key_id + secret_key)
webhook_url configurée (notification serveur fiable)
callback_url (optionnel — redirection navigateur après paiement)
mobile_money_receiver_phone pour les ventes directes en RDC
Domaine de votre site autorisé pour l'iframe checkout (demande à l'équipe ePaieLink)

Les 4 étapes (vue d'ensemble)

Votre backend — POST /api/v1/payment-intents/ → vous obtenez checkout_url
Votre frontend — ouvrir la modale avec ePaieLink.open(checkout_url)
Le client — choisit Mobile Money ou carte, paie dans l'iframe (ePaieLink route vers l'agrégateur actif)
Votre backend — reçoit le webhook status: succeeded et valide la commande

Vous n'avez pas à choisir ni coder un agrégateur de paiement : ePaieLink s'en charge côté plateforme.

Architecture — qui fait quoi ?

Acteur	Rôle	Vous codez ?
Votre backend	Crée le `PaymentIntent`, vérifie les webhooks	Oui
Votre frontend	Ouvre le checkout (modale ou redirect)	Oui
Checkout ePaieLink	UI paiement, appels `verify` / `process`	Non (hébergé)
Plateforme ePaieLink	Routage agrégateur, webhooks providers, répartition marketplace	Non
Agrégateur	Exécution Mobile Money / carte (configuré par ePaieLink)	Non

Principe clé : votre intégration parle uniquement à l'API ePaieLink et au SDK checkout. Les agrégateurs sont un détail d'infrastructure géré par la plateforme.

Agrégateurs multiples & bascule automatique

Point fort ePaieLink : plusieurs agrégateurs de paiement peuvent être configurés en parallèle (Mobile Money, carte bancaire, etc.). Si l'un est indisponible, la plateforme peut activer un autre sans modifier votre code.

En tant que marchand :

Vous créez un PaymentIntent avec un montant et une devise — c'est tout.
Le checkout propose les moyens de paiement disponibles pour votre marché.
Le champ provider dans le webhook indique quel agrégateur a traité le paiement (information, pas une dépendance).

Ne conditionnez jamais votre logique métier à un nom d'agrégateur précis. Fiez-vous à status et transaction_id.

Moyens de paiement côté client (checkout)

Ce que voit le client	Comportement
Mobile money	Saisie du numéro → confirmation USSD sur le téléphone
Carte bancaire	Redirection vers une page sécurisée de l'agrégateur carte actif

SDK JavaScript — `epaielink.js`

Modale type « in-context » : overlay + iframe compact (~420 px). Le client reste sur votre site.

Télécharger le SDK

Important : le SDK n'est pas sur le domaine API (server-*.epaie.link). Il est hébergé sur le checkout (checkout-*.epaie.link).

Recommandé — script toujours à jour (domaine checkout) :

https://checkout.epaie.link/epaielink.js

Télécharger depuis le checkout

Alternative — copie sur ce site (documentation) :

./assets/epaielink.js

En production, chargez plutôt <script src="{{CHECKOUT_BASE}}/epaielink.js"> depuis le checkout.

Inclusion dans votre page

API du SDK

Le SDK ajoute embed=1 à l'URL. En cas de succès, la modale se ferme automatiquement.

Guide A — Vente directe avec modale ★

Objectif : encaisser pour votre propre compte. L'argent Mobile Money est versé au numéro mobile_money_receiver_phone configuré sur votre marchand.

Exemple : commande order-12345, 5 000 CDF, article « T-shirt ».

Étape 1 / 5 Créer le paiement (backend)

POST https://server.epaie.link/api/v1/payment-intents/

Headers : authentification par clé API (voir Authentification).

Réponse attendue (201)

Conservez checkout_url — c'est la seule URL à transmettre au frontend. Ne pas inclure metadata.marketplace: true.

Étape 2 / 5 Ouvrir la modale (frontend)

Étape 3 / 5 Le client paie (automatique)

Dans l'iframe, le client :

Choisit Mobile money ou Carte bancaire
Mobile money : saisit son numéro → confirme sur son téléphone
Carte : est redirigé vers la page sécurisée de l'agrégateur actif, puis revient sur le checkout

Vous ne codez rien à cette étape — ePaieLink route vers l'agrégateur configuré.

Étape 4 / 5 Recevoir le webhook (backend — source de vérité)

Même en modale, validez toujours le paiement via webhook (le callback JS est pour l'UX uniquement).

Vérifiez X-Signature avec votre secret_key (JSON trié par clés + timestamp).

Étape 5 / 5 Vérifier que tout fonctionne

Modale s'ouvre sans iframe vide
Webhook reçu avec status: succeeded
Transaction visible dans le dashboard marchand
Commande marquée payée dans votre base (external_reference)

App de test : le dépôt epaylink-tester-app reproduit ce flux complet (modale + webhook).

Guide B — Vente directe avec redirect

Même scénario que le Guide A, mais le client quitte votre site pour le checkout pleine page.

	Modale (Guide A)	Redirect (Guide B)
Client reste sur votre site	Oui	Non
SDK requis	`epaielink.js`	Non
Résultat immédiat JS	`onSuccess`	Non
Retour navigateur	Optionnel	`callback_url`
Confirmation fiable	Webhook	Webhook

Étape 1 / 3 Créer le PaymentIntent

Identique au Guide A — même requête, même réponse avec checkout_url.

Étape 2 / 3 Rediriger le navigateur

Étape 3 / 3 Retour sur votre site

Après paiement, le client est renvoyé sur votre callback_url :

Important : traitez la commande uniquement après validation du webhook, pas seulement sur les paramètres URL ( falsifiables côté client ).

Guide C — Marketplace

Objectif : le client paie un montant total ; ePaieLink collecte sur le wallet plateforme, puis répartit automatiquement entre vous et un vendeur tiers.

Exemple : vente 10 000 CDF — 2 000 pour la plateforme, 8 000 pour le vendeur au 0971234567.

Client paie 10 000 CDF ↓ Collecte wallet ePaieLink (agrégateur actif) ↓ Webhook provider → tâche de répartition ↓ Dépôt vendeur (8 000) + dépôt plateforme (2 000) ↓ Webhook marchand (status succeeded)

Étape 1 / 4 Créer le PaymentIntent marketplace

Règle : merchant_amount + seller_amount = amount (validé à la création).

Étape 2 / 4 Checkout client

Identique au Guide A ou B : modale ePaieLink.open() ou redirect vers checkout_url. La collecte Mobile Money va sur le wallet ePaieLink (pas directement sur votre numéro).

Étape 3 / 4 Répartition automatique

Après confirmation du paiement, ePaieLink déclenche les dépôts vers le vendeur et la plateforme. Consultez GET /api/v1/payouts/ (dashboard) pour l'historique.

Étape 4 / 4 Webhook marchand

Identique au Guide A — POST sur votre webhook_url quand la collecte est succeeded (en parallèle ou avant la fin des dépôts vendeur/plateforme).

Métadonnées marketplace

Clé	Obligatoire	Description
`marketplace`	Oui	`true`
`merchant_amount`	Au moins un*	Part plateforme / marchand
`seller_amount`	Au moins un*	Part vendeur
`seller_phone`	Si seller_amount > 0	Numéro Mobile Money vendeur (RDC)

* Au moins merchant_amount ou seller_amount doit être > 0.

URLs & environnements

Environnement	API (base)	Checkout
Production	`https://server.epaie.link`	`https://checkout.epaie.link`
UAT	`https://server-uat.epaie.link`	`https://checkout-uat.epaie.link`

URL active (sélecteur sidebar) :

API : https://server.epaie.link/api/v1/

Checkout : https://checkout.epaie.link

SDK : https://checkout.epaie.link/epaielink.js

Authentification API (détail)

Chaque requête serveur → serveur vers l'API marchand inclut :

Header	Description
`X-API-Key-Id`	Identifiant public (`key_id`)
`X-Signature`	HMAC-SHA256 hex du corps signé
`X-Timestamp`	Horodatage Unix (secondes) ou millisecondes
`Content-Type`	`application/json`

Corps signé : fusion du JSON de la requête + timestamp (même valeur que le header). Tri des clés de premier niveau, JSON.stringify, HMAC avec secret_key.

Référence des endpoints

Méthode	Chemin	Auth	Description
GET	`/api/v1/health/`	Non	Santé API
POST	`/api/v1/payment-intents/`	Clé API	Créer un paiement → `checkout_url`
GET	`/api/v1/payment-intents/{id}/`	Token marchand	Détail intent
POST	`/api/v1/checkout/verify/`	Public	Checkout — valider URL signée
POST	`/api/v1/payment-intents/{id}/process/`	Public	Checkout — lancer paiement (interne)
GET	`/api/v1/transactions/{id}/`	Public	Statut transaction (polling checkout)
GET	`/api/v1/payouts/`	Token marchand	Historique versements (marketplace)

Les endpoints verify et process sont appelés par le checkout hébergé, pas par votre backend marchand.

Dépannage

Symptôme	Cause probable	Action
401 Unauthorized	Signature ou timestamp invalide	Vérifier HMAC, horloge serveur, tri des clés JSON
400 external_reference	Référence déjà utilisée	Utiliser une référence unique par commande
400 metadata marketplace	Somme des parts ≠ montant total	`merchant_amount + seller_amount = amount`
410 Gone	PaymentIntent expiré	Recréer un intent
Modale / iframe vide	Domaine non autorisé	Demander l'ajout de votre origine (CSP `frame-ancestors`)
epaielink.js introuvable	URL sur `server-` au lieu de `checkout-`	Utiliser https://checkout.epaie.link/epaielink.js ou copie locale
Paiement OK en UI, commande non validée	Webhook non reçu ou non vérifié	Tester `webhook_url`, logs serveur, signature webhook
Échec agrégateur	Indisponibilité temporaire	ePaieLink peut basculer — contacter le support si persistant

Embarquer cette documentation

Affichez ce guide dans votre dashboard ou site :

Intégrer ePaieLink sur votre site

Démarrage rapide — votre premier paiement

Avant de coder — checklist

Les 4 étapes (vue d'ensemble)

Architecture — qui fait quoi ?

Agrégateurs multiples & bascule automatique

Moyens de paiement côté client (checkout)

SDK JavaScript — epaielink.js

Télécharger le SDK

Inclusion dans votre page

API du SDK

Guide A — Vente directe avec modale ★

Étape 1 / 5 Créer le paiement (backend)

Réponse attendue (201)

Étape 2 / 5 Ouvrir la modale (frontend)

Étape 3 / 5 Le client paie (automatique)

Étape 4 / 5 Recevoir le webhook (backend — source de vérité)

Étape 5 / 5 Vérifier que tout fonctionne

Guide B — Vente directe avec redirect

Étape 1 / 3 Créer le PaymentIntent

Étape 2 / 3 Rediriger le navigateur

Étape 3 / 3 Retour sur votre site

Guide C — Marketplace

Étape 1 / 4 Créer le PaymentIntent marketplace

Étape 2 / 4 Checkout client

Étape 3 / 4 Répartition automatique

Étape 4 / 4 Webhook marchand

Métadonnées marketplace

URLs & environnements

Authentification API (détail)

Référence des endpoints

Dépannage

Embarquer cette documentation

SDK JavaScript — `epaielink.js`