Documentation API
Intégrez Wave, Orange Money et le paiement par carte en quelques heures. L'API Paydeck est conçue pour être simple, prévisible et bien documentée.
Introduction
L'API Paydeck est une API REST qui accepte des corps de requête JSON et renvoie des réponses JSON. Toutes les requêtes doivent être effectuées en HTTPS.
Base URL
https://api.getpaydeck.com/api/v1
Format
JSON · REST
Auth
API Key (Bearer)
Authentification
Toutes les requêtes API doivent inclure votre clé secrète dans l'en-tête Authorization. Générez vos clés dans votre tableau de bord → API & Paramètres → Clés API (bouton « Générer une clé test »). La clé secrète complète n'est affichée qu'une seule fois : copiez-la immédiatement.
curl https://api.getpaydeck.com/api/v1/payments/providers \
-H "Authorization: Bearer sk_live_VOTRE_CLE_SECRETE"Types de clés
sk_test_...TestSandbox uniquement — aucun vrai paiementsk_live_...LiveProduction — paiements réelsEnvironnements
Paydeck propose deux environnements : Test (Sandbox) et Live (Production). L'environnement actif dépend de la clé API utilisée.
Test
api.getpaydeck.com/api/v1
sk_test_...
Aucun vrai paiement effectué
Live
api.getpaydeck.com/api/v1
sk_live_...
Paiements réels — activé par l'admin
Format des réponses
Toutes les réponses suivent la même structure :
{
"success": true,
"data": { ... },
"message": "Operation successful",
"meta": { // présent uniquement pour les listes paginées
"currentPage": 1,
"lastPage": 5,
"total": 92,
"perPage": 20
}
}Gestion des erreurs
En cas d'erreur, success vaut false et message décrit l'erreur.
{
"success": false,
"message": "Insufficient balance",
"errors": [ // uniquement pour les erreurs de validation
{ "field": "amount", "message": "Amount must be a positive integer" }
]
}| Code HTTP | Signification |
|---|---|
| 200 | OK — Requête réussie |
| 201 | Created — Ressource créée |
| 400 | Bad Request — Paramètres manquants ou invalides |
| 401 | Unauthorized — Clé API manquante ou invalide |
| 403 | Forbidden — Compte non activé ou bloqué |
| 404 | Not Found — Ressource introuvable |
| 422 | Unprocessable Entity — Erreur de validation |
| 429 | Too Many Requests — Limite de débit dépassée |
| 500 | Internal Server Error — Erreur côté serveur |
Rate limiting
Les endpoints publics de paiement sont protégés contre les abus par un limiteur de débit par adresse IP.
| Endpoint | Limite | Fenêtre |
|---|---|---|
| POST /checkout/pay | 100 requêtes | 1 minute |
| GET /checkout/providers | 200 requêtes | 1 minute |
| GET /checkout/status/:ref | 300 requêtes | 1 minute |
| Merchant API (sk_…) | Non limité | — |
En cas de dépassement, l'API retourne HTTP 429 avec les headers suivants :
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0Health check
Endpoint public sans authentification — vérifie que le serveur et la base de données sont opérationnels. Utile pour les sondes de monitoring (uptime robot, load balancer, CI/CD).
// Réponse — tout OK (HTTP 200)
{
"status": "ok",
"db": "connected",
"uptime": 3600,
"timestamp": "2026-04-29T12:00:00.000Z"
}
// Réponse — DB indisponible (HTTP 503)
{
"status": "degraded",
"db": "error",
"uptime": 120,
"timestamp": "2026-04-29T12:00:00.000Z"
}Providers disponibles
Retourne la liste des providers de paiement actifs et leurs capacités. Utilisez cet endpoint pour construire votre sélecteur de méthode de paiement.
// Réponse
{
"success": true,
"data": [
{
"id": 1,
"code": "wave_sn",
"name": "Wave Sénégal",
"type": "mobile_money",
"countries": ["SN"],
"currency": "XOF",
"supportsCollect": true,
"supportsDisburse": true,
"supportsPayerRestriction": true,
"returnsVerifiedPayer": false
},
{
"id": 2,
"code": "orange_money_sn",
"name": "Orange Money SN",
"type": "mobile_money",
"countries": ["SN"],
"currency": "XOF",
"supportsCollect": true,
"supportsDisburse": true,
"supportsPayerRestriction": true,
"returnsVerifiedPayer": true
},
{
"id": 3,
"code": "card",
"name": "Paiement par carte",
"type": "card",
"countries": ["*"],
"currency": "XOF",
"supportsCollect": true,
"supportsDisburse": false,
"supportsPayerRestriction": false,
"returnsVerifiedPayer": false
}
]
}Référence rapide — Providers actuels
| Code | Nom | Type | Collect | Disburse | Pays |
|---|---|---|---|---|---|
| wave_sn | Wave Sénégal | Mobile Money | ✓ | ✓ | SN |
| orange_money_sn | Orange Money SN | Mobile Money | ✓ | ✓ | SN |
| card | Paiement par carte | Carte | ✓ | — | * |
Référence rapide — Indicatifs pays
Utilisé dans le paramètre phoneCountryCode lors d'une collecte ou d'un décaissement.
+221SN+XXX—selon providers disponiblesCollecter un paiement
Merchant APIInitie une collecte (le client vous paie). Selon le provider, la réponse inclut un paymentUrl de redirection ou un résultat synchrone direct.
Corps de la requête
providerCodestringrequisCode du provider — voir GET /payments/providers pour la liste complète
amountintegerrequisMontant en XOF (entier, sans décimales). Ex: 5000
phoneNumberstringrequisNuméro de téléphone du payeur. Ex: 771234567
phoneCountryCodestringIndicatif pays. Ex: +221 (par défaut: +221)
recipientNamestringNom du payeur
recipientEmailstringEmail du payeur pour le reçu
otpstringCode demandé par certains moyens de paiement : voir collectFields dans GET /payments/providers
successUrlstringURL de redirection après paiement réussi
cancelUrlstringURL de redirection si le client annule
metadataobjectMétadonnées libres retournées dans les webhooks
restrictPayerToPhonebooleanFacultatif (défaut false). Si true, SEUL le numéro de phoneNumber peut payer. Uniquement pour les moyens de paiement qui ont supportsPayerRestriction (GET /payments/providers) ; refusé (422) sinon. Voir « Qui a payé ? Restreindre le paiement à un numéro » ci-dessous.
curl -X POST https://api.getpaydeck.com/api/v1/payments/collect \
-H "Authorization: Bearer sk_test_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"providerCode": "wave_sn",
"amount": 5000,
"phoneNumber": "771234567",
"phoneCountryCode": "+221",
"recipientName": "Amadou Diallo",
"successUrl": "https://votresite.com/merci",
"metadata": { "orderId": "CMD-2026-001" }
}'// Réponse 201
{
"success": true,
"data": {
"id": 142,
"ref": "pd_col_a1b2c3d4e5f6",
"status": "processing",
"amount": 5000,
"feeAmount": 75,
"netAmount": 5000,
"paymentUrl": "https://pay.getpaydeck.com/xxx", // présent si le provider requiert une redirection client
"payerRestricted": false, // true si restrictPayerToPhone a été demandé
"createdAt": "2026-03-31T10:00:00.000Z"
}
}Qui a payé ? Restreindre le paiement à un numéro
Par défaut, phoneNumber est le numéro que VOUS (ou le payeur) avez saisi. Ce n'est pas une preuve de qui a réellement payé : selon le moyen de paiement, un autre compte que celui saisi peut régler. Si vous connaissez votre payeur à l'avance (abonnement, cotisation…), vous pouvez activer une option pour que seul son numéro puisse payer.
- Activez-la avec "restrictPayerToPhone": true sur POST /payments/collect, ou sur POST /payments/sessions (avec customer.phone). Désactivée par défaut : rien ne change si vous ne l'utilisez pas.
- Disponible pour les moyens de paiement dont supportsPayerRestriction vaut true dans GET /payments/providers. Avec un autre moyen, la demande est refusée (422), jamais acceptée en silence. Les liens de paiement et les QR statiques ne l'utilisent pas.
- Avec une session, le numéro est verrouillé : la fenêtre de paiement l'affiche en lecture seule, seuls les moyens compatibles sont proposés et le serveur refuse tout autre numéro (erreur SESSION_PAYER_MISMATCH).
- Un paiement depuis un autre numéro est refusé et la transaction échoue (failureReason PAYER_MOBILE_MISMATCH quand le moyen de paiement indique ce motif). Le payeur doit payer depuis le numéro attendu.
- Qui a vraiment payé : payer_phone_verified (webhook et transaction) contient le numéro du payeur quand le moyen de paiement le communique (returnsVerifiedPayer), sinon null. Un null ne signifie pas que le payeur est différent.
- Filet de sécurité : si un paiement depuis un autre numéro passe malgré tout, il n'est PAS crédité automatiquement. Il est mis en attente de vérification par Paydeck et aucun solde ne bouge.
Schémas des flux
Flux collect — Redirection client
Votre serveur
API Paydeck
Client
page de paiement
Flux collect — OTP synchrone (certains providers)
Client
génère OTP
Votre serveur
Votre serveur
API Paydeck
Résultat
sync
Sessions de paiement (montant sécurisé)
Merchant APIUne session de paiement est créée par le SERVEUR de votre plateforme avec votre clé secrète : le montant, la description et le metadata y sont figés. Le navigateur du payeur ne reçoit qu'un identifiant opaque (ps_…) et ne peut rien modifier.
Corps de la requête
amountintegerrequisMontant en XOF (entier), dans les limites de la plateforme
currencystringMonnaie (XOF, défaut)
descriptionstringTexte affiché au payeur (255 caractères au plus)
metadataobjectVos données (ex. identifiant de commande), figées dans la session puis copiées dans la transaction et les webhooks. 20 clés, 2 Ko, valeurs simples ; les clés réservées de Paydeck sont ignorées.
expiresInMinutesintegerDurée de validité en minutes : de 1 à 1440 (défaut 30)
restrictPayerToPhonebooleanFacultatif (défaut false). Si true, customer.phone devient le SEUL numéro autorisé à payer (obligatoire avec cette option). La fenêtre l'affiche en lecture seule et ne propose que les moyens de paiement qui ont supportsPayerRestriction. Voir « Qui a payé ? » dans la section Collecter.
customerobjectFacultatif. Coordonnées du payeur pour PRÉ-REMPLIR la fenêtre de paiement : phone (chiffres), phoneCountryCode (ex. +221), email. Le payeur peut les modifier ; le numéro qu'il utilise finalement est celui enregistré dans la transaction. La fenêtre ne gère que les numéros +221 : un numéro d'un autre indicatif n'est pas prérempli. En mode test, ces informations sont affichées et non modifiables.
curl -X POST https://api.getpaydeck.com/api/v1/payments/sessions \
-H "Authorization: Bearer sk_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"amount": 10000,
"description": "Cagnotte de Awa",
"metadata": { "payment_id": "01m734rfhbm2y3rvn18x52z2t3" }
}'// Réponse 201
{
"success": true,
"data": {
"id": "ps_Zk3q8wX2mB7nR1tVd5LpYc9HfGa4JeUo",
"status": "open",
"mode": "live",
"amount": 10000,
"currency": "XOF",
"description": "Cagnotte de Awa",
"metadata": { "payment_id": "01m734rfhbm2y3rvn18x52z2t3" },
"expiresAt": "2026-11-10T10:30:00.000Z",
"transactionRef": null,
"checkoutUrl": "https://getpaydeck.com/modal?session=ps_Zk3q8w..."
}
}Ouvrir le paiement
// 1. Votre SERVEUR crée la session (clé secrète), puis ne transmet à la page que data.id
PayDeck.open({
session: "ps_Zk3q8wX2mB7nR1tVd5LpYc9HfGa4JeUo",
onSuccess: function (data) {
// simple signal pour l'interface — confirmez avec le webhook signé / GET /payments/transactions/:ref
console.log(data.ref, data.session)
},
})Intégration la plus simple : createSession (renouvellement automatique)
Donnez au widget une fonction qui appelle VOTRE serveur et renvoie l'identifiant ps_…. Le widget l'appelle à chaque ouverture, et une fois de plus tout seul si la session a expiré pendant que la page restait ouverte : vous n'avez rien à gérer.
PayDeck.open({
createSession: async function () {
// votre route crée la session avec la clé secrète (POST /payments/sessions) et renvoie data.id
const r = await fetch('/api/pay-session', { method: 'POST' })
return (await r.json()).id
},
onSuccess: function (data) { console.log(data.ref) },
onError: function (message) { console.error(message) },
})Sans widget, redirigez le payeur vers checkoutUrl : c'est la même page de paiement, hébergée par Paydeck. L'environnement (test ou production) est celui de la clé secrète qui a créé la session.
Comportement
- Le montant est celui de la session. Un montant différent envoyé par le navigateur est refusé.
- Une seule tentative vivante à la fois. Un échec (mauvais code, solde insuffisant) libère la session : le payeur peut réessayer.
- Si le payeur ferme puis rouvre la page : un paiement en cours avec le même moyen de paiement est repris tel quel ; un paiement déjà réussi est simplement renvoyé (jamais de second débit).
- Si un paiement est en cours avec un autre moyen, le payeur reçoit un message clair ; il peut attendre la fin ou expiration de la première tentative, ou vous créez une nouvelle session.
- Une session expire (30 minutes par défaut). Avec createSession, le widget la renouvelle automatiquement ; sinon (session transmise directement, ou checkoutUrl) le payeur voit un message clair et vous en créez une nouvelle (erreur 410). Un paiement déjà réussi reste consultable.
- Le metadata de la transaction contient celui de la session plus sessionId (l'identifiant ps_…) : vous retrouvez la session dans les webhooks et dans GET /payments/transactions/:ref.
Codes d'erreur
SESSION_EXPIRED410Session expirée : créez-en une nouvelleSESSION_NOT_FOUND404Identifiant de session inconnuSESSION_AMOUNT_MISMATCH422Montant du navigateur différent de celui de la sessionSESSION_PAYER_MISMATCH422Numéro envoyé par le navigateur différent de celui imposé par la session (restrictPayerToPhone)SESSION_PAYMENT_IN_PROGRESS409Un paiement est déjà en cours avec un autre moyen de paiementSESSION_KEY_MISMATCH403Clé publique d'un autre marchandSESSION_REQUIRED403Votre compte exige une session (réglage « sessions obligatoires »)Renvoie l'état de la session : status vaut open, processing, paid ou expired, et transactionRef donne la référence de la tentative en cours ou réussie.
Envoyer de l'argent
Merchant APIEnvoie des fonds vers un numéro mobile money (décaissement).
Corps de la requête
providerCodestringrequisCode du provider — voir GET /payments/providers pour la liste complète
amountintegerrequisMontant en XOF à envoyer
phoneNumberstringrequisNuméro mobile money du destinataire
phoneCountryCodestringIndicatif pays. Ex: +221
recipientNamestringNom du destinataire
recipientEmailstringEmail du destinataire (facultatif) : il reçoit un avis quand le virement a réussi
metadataobjectMétadonnées libres
curl -X POST https://api.getpaydeck.com/api/v1/payments/disburse \
-H "Authorization: Bearer sk_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"providerCode": "wave_sn",
"amount": 25000,
"phoneNumber": "781234567",
"recipientName": "Fatou Ndiaye",
"recipientEmail": "fatou@exemple.sn",
"metadata": { "employeeId": "EMP-042" }
}'// Réponse 201
{
"success": true,
"data": {
"id": 143,
"ref": "pd_dis_x7y8z9a0b1c2",
"status": "processing",
"amount": 25000,
"feeAmount": 250,
"createdAt": "2026-03-31T10:05:00.000Z"
}
}Idempotence — éviter un double virement
Si votre appel expire (réseau coupé avant la réponse), vous ne savez pas si le virement est parti. Ajoutez l'en-tête Idempotency-Key : en renvoyant exactement la même requête avec la même clé, vous obtenez le virement déjà créé au lieu d'en créer un second.
curl -X POST https://api.getpaydeck.com/api/v1/payments/disburse \
-H "Authorization: Bearer sk_live_VOTRE_CLE" \
-H "Idempotency-Key: payout-2026-11-10-EMP042" \
-H "Content-Type: application/json" \
-d '{ "providerCode": "wave_sn", "amount": 25000, "phoneNumber": "781234567" }'- La clé est choisie par vous : 1 à 255 caractères visibles, sans espace (identifiant du versement, UUID…). Elle est unique par compte marchand.
- Même clé et mêmes paramètres : réponse 200 avec l'en-tête Idempotent-Replayed: true — aucun nouveau débit, aucun nouvel envoi. Le statut renvoyé est le statut actuel du virement.
- Même clé mais paramètres différents (montant, numéro, provider) : erreur 422. Utilisez une nouvelle clé pour un nouveau virement.
- Sans en-tête, le comportement est inchangé : chaque appel crée un virement. Vous pouvez aussi retrouver un virement par vos propres données (voir « Lister les transactions », filtre metadata).
Lister les transactions
Merchant APIRetourne la liste paginée de vos transactions avec filtres optionnels.
Paramètres de requête (query string)
pageintegerNuméro de page (défaut: 1)
limitintegerRésultats par page, max 100 (défaut: 20)
statusstringFiltrer par statut: pending, processing, success, failed
operationstringFiltrer par opération: collect, disburse
startDatestringDate de début ISO 8601. Ex: 2026-01-01
endDatestringDate de fin ISO 8601. Ex: 2026-03-31
searchstringRecherche dans la référence, le numéro ou le nom du bénéficiaire
metadata[key]stringRetrouve les transactions dont metadata contient cette valeur exacte (ex. metadata[payment_id]=abc, ou metadata.payment_id=abc). Jusqu'à 5 filtres cumulables ; nom de clé de 1 à 64 caractères (lettres, chiffres, _ ou -).
# Retrouver une transaction par votre propre identifiant (commande, paiement…)
curl -G "https://api.getpaydeck.com/api/v1/payments/transactions" \
-H "Authorization: Bearer sk_live_VOTRE_CLE" \
--data-urlencode "metadata[payment_id]=01m734rfhbm2y3rvn18x52z2t3"curl "https://api.getpaydeck.com/api/v1/payments/transactions?status=success&limit=10" \
-H "Authorization: Bearer sk_live_VOTRE_CLE"// Réponse 200
{
"success": true,
"data": [
{
"id": 142,
"internalRef": "pd_col_a1b2c3d4e5f6",
"operation": "collect",
"status": "success",
"amount": 5000,
"feeAmount": 75,
"netAmount": 4925,
"currency": "XOF",
"phoneNumber": "771234567",
"mode": "live",
"createdAt": "2026-03-31T10:00:00.000Z"
}
],
"meta": {
"currentPage": 1,
"lastPage": 3,
"total": 47,
"perPage": 20
}
}Statut d'une transaction
Merchant APIRécupère les détails complets d'une transaction par sa référence interne.
curl https://api.getpaydeck.com/api/v1/payments/transactions/pd_col_a1b2c3d4e5f6 \
-H "Authorization: Bearer sk_live_VOTRE_CLE"| Statut | Description |
|---|---|
| pending | Initiée, en attente de confirmation du client |
| processing | En cours de traitement par le provider |
| success | Paiement confirmé et crédité |
| failed | Paiement refusé ou expiré |
Cycle de vie d'une transaction
États possibles
pending
initiée
processing
en cours chez le provider
✓ success
✗ failed
Rembourser une collecte
Merchant APIRembourse intégralement une collecte réussie, par le même moyen de paiement, vers le numéro enregistré sur la transaction (phoneNumber).
- Remboursement total uniquement : il n'existe pas de remboursement partiel.
- Le payeur reçoit le montant de la collecte (amount) ; les frais Paydeck ne sont pas remboursés.
- La collecte doit être au statut success, et votre solde Paydeck doit couvrir le montant : il est débité à la demande, puis envoyé au payeur.
- Avec une clé de test (sk_test_), le remboursement est simulé et instantané ; une clé de test ne rembourse jamais un vrai paiement.
- Le délai dépend du provider. Tant qu'il n'a pas répondu, le statut reste processing ; si l'issue est incertaine, le solde n'est ni restitué ni recrédité à l'aveugle : Paydeck vérifie auprès du provider puis règle automatiquement.
Corps de la requête
reasonstringMotif du remboursement (facultatif, conservé dans metadata.reason)
curl -X POST https://api.getpaydeck.com/api/v1/payments/transactions/PDK-20261110-AF8CCE7E/refund \
-H "Authorization: Bearer sk_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{ "reason": "Commande annulée" }'// Réponse 200
{
"success": true,
"message": "Remboursement effectué avec succès",
"data": {
"ref": "PDK-20261110-5B21C9D0",
"status": "success",
"amount": 5000
}
}Webhooks de remboursement
Deux événements : transaction.refund.success et transaction.refund.failed. Le message décrit le remboursement lui-même (operation refund, sa propre référence) ; la référence de la collecte remboursée est dans metadata.originalRef.
{
"event": "transaction.refund.success",
"created_at": "2026-11-10T10:05:00.000Z",
"data": {
"id": 143,
"ref": "PDK-20261110-5B21C9D0",
"operation": "refund",
"status": "success",
"amount": 5000,
"currency": "XOF",
"mode": "live",
"metadata": { "originalRef": "PDK-20261110-AF8CCE7E", "reason": "Commande annulée" }
}
}Créer un lien de paiement
Merchant APICrée un lien de paiement partageable. Idéal pour les factures, les boutiques en ligne, ou les campagnes de collecte.
Corps de la requête
titlestringrequisNom du lien de paiement (2-255 caractères)
descriptionstringDescription affichée au payeur
amountintegerMontant fixe en XOF (si isFixedAmount = true)
isFixedAmountbooleanMontant fixe ou libre (défaut: true si amount fourni)
minAmountintegerMontant minimum si montant libre
maxAmountintegerMontant maximum si montant libre
currencystringDevise (défaut: XOF)
redirectUrlstringURL de redirection après paiement
maxUsesintegerNombre maximum d'utilisations
expiresAtstringDate d'expiration ISO 8601
allowedProvidersstring[]Providers autorisés. Ex: ["wave_sn", "orange_money_sn"]
curl -X POST https://api.getpaydeck.com/api/v1/paylinks \
-H "Authorization: Bearer sk_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"title": "Commande #2026-042",
"amount": 15000,
"redirectUrl": "https://votresite.com/merci",
"allowedProviders": ["wave_sn", "orange_money_sn"]
}'// Réponse 201
{
"success": true,
"data": {
"id": 17,
"token": "AbCdEfGhIjKlMnOpQrStUvWx",
"title": "Commande #2026-042",
"amount": 15000,
"redirectUrl": "https://votresite.com/merci",
"status": "active",
"url": "https://getpaydeck.com/pay/AbCdEfGhIjKlMnOpQrStUvWx",
"usesCount": 0,
"createdAt": "2026-03-31T11:00:00.000Z"
}
}Lister les liens de paiement
Merchant APIcurl "https://api.getpaydeck.com/api/v1/paylinks?status=active" \
-H "Authorization: Bearer sk_live_VOTRE_CLE"Payer via un lien
PublicEndpoint public — pas d'authentification requise. Utilisé par la page de paiement Paydeck.
// Récupérer les infos du lien (public)
curl https://api.getpaydeck.com/api/v1/paylinks/AbCdEfGhIjKlMnOpQrStUvWx// Lancer le paiement (public)
curl -X POST https://api.getpaydeck.com/api/v1/paylinks/AbCdEfGhIjKlMnOpQrStUvWx/pay \
-H "Content-Type: application/json" \
-d '{
"providerCode": "wave_sn",
"phoneNumber": "771234567"
}'Créer un paiement en masse
Merchant APICrée un batch de décaissements (salaires, remboursements, commissions). Le batch est d'abord créé en état draft, puis exécuté manuellement.
Corps de la requête
labelstringrequisNom du batch. Ex: Salaires Mars 2026
providerCodestringrequisProvider utilisé pour tous les décaissements
itemsarrayrequisListe des destinataires
items[].phoneNumberstringrequisNuméro de téléphone du destinataire
items[].amountintegerrequisMontant en XOF
items[].namestringNom du destinataire
curl -X POST https://api.getpaydeck.com/api/v1/mass-payments \
-H "Authorization: Bearer sk_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"label": "Salaires Mars 2026",
"providerCode": "wave_sn",
"items": [
{ "phoneNumber": "771234567", "amount": 150000, "name": "Amadou Diallo" },
{ "phoneNumber": "781234568", "amount": 120000, "name": "Fatou Ndiaye" },
{ "phoneNumber": "701234569", "amount": 200000, "name": "Moussa Ba" }
]
}'// Réponse 201
{
"success": true,
"data": {
"id": 8,
"label": "Salaires Mars 2026",
"status": "draft",
"totalAmount": 470000,
"itemCount": 3,
"createdAt": "2026-03-31T09:00:00.000Z"
}
}Statut d'un batch
Merchant APIPour exécuter un batch, utilisez POST /mass-payments/:id/execute.
| Statut | Description |
|---|---|
| draft | Batch créé mais pas encore lancé |
| processing | Décaissements en cours |
| done | Tous les décaissements terminés (succès ou échec) |
Configurer les webhooks
Merchant APILes webhooks permettent à Paydeck de notifier votre serveur en temps réel lors de chaque changement de statut d'une transaction.
Corps de la requête
urlstringrequisURL HTTPS de votre endpoint (doit retourner 2xx)
eventsstring[]requisListe des événements à écouter (voir ci-dessous)
curl -X POST https://api.getpaydeck.com/api/v1/webhooks \
-H "Authorization: Bearer sk_live_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"url": "https://votresite.com/webhooks/paydeck",
"events": [
"transaction.collect.success",
"transaction.collect.failed",
"transaction.disburse.success"
]
}'// Réponse 201
{
"success": true,
"message": "Webhook created. Store the secret — it is shown only once.",
"data": {
"id": 3,
"url": "https://votresite.com/webhooks/paydeck",
"events": ["transaction.collect.success", "transaction.collect.failed"],
"secret": "a1b2c3d4e5f6....", // ← À stocker immédiatement !
"isActive": true
}
}Schéma d'envoi & retry
Flux webhook
Transaction
confirmée
API Paydeck
Votre serveur
✓ livré
Si pas de 200 → retry automatique :
Événements
| Événement | Déclenché quand |
|---|---|
| transaction.collect.success | Un paiement entrant est confirmé |
| transaction.collect.failed | Un paiement entrant est refusé ou expiré |
| transaction.disburse.success | Un décaissement est confirmé |
| transaction.disburse.failed | Un décaissement a échoué |
| transaction.refund.success | Un remboursement est confirmé |
| transaction.refund.failed | Un remboursement est refusé par le provider |
Vérifier la signature
Chaque webhook envoyé par Paydeck inclut un en-tête Paydeck-Signature. Vérifiez-le pour vous assurer que la requête provient bien de Paydeck.
Format de la signature
Paydeck-Signature: t=1711879200,v1=a3f9b2c1d0e8f7...Le payload signé est : {timestamp}.{body}. La signature est un HMAC-SHA256 calculé avec votre secret de webhook.
Vérification en Node.js
const crypto = require('crypto')
function verifyWebhook(rawBody, signature, secret) {
const parts = Object.fromEntries(
signature.split(',').map(p => p.split('='))
)
const ts = parts['t']
const v1 = parts['v1']
// Rejeter les webhooks de plus de 5 minutes
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
throw new Error('Webhook too old')
}
const expected = crypto
.createHmac('sha256', secret)
.update(`${ts}.${rawBody}`)
.digest('hex')
if (!crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))) {
throw new Error('Invalid signature')
}
}
// Express.js
app.post('/webhooks/paydeck', express.raw({ type: 'application/json' }), (req, res) => {
try {
verifyWebhook(req.body, req.headers['paydeck-signature'], process.env.WEBHOOK_SECRET)
} catch (e) {
return res.status(400).send('Bad signature')
}
const event = JSON.parse(req.body)
console.log('Event received:', event.event, event.data.ref)
// Traiter l'événement...
res.sendStatus(200)
})Format du payload
{
"event": "transaction.collect.success",
"created_at": "2026-03-31T10:00:00.000Z",
"data": {
"id": 142,
"ref": "pd_col_a1b2c3d4e5f6",
"operation": "collect",
"status": "success",
"amount": 5000,
"fee_amount": 75,
"net_amount": 5000,
"currency": "XOF",
"phone_number": "771234567", // numéro SAISI à la création : pas une preuve du payeur
"payer_restricted": false, // true si restrictPayerToPhone a été demandé
"payer_phone_verified": null, // payeur confirmé par le moyen de paiement (returnsVerifiedPayer), sinon null
"mode": "live",
"metadata": { "orderId": "CMD-2026-001", "customerId": "USR-42" },
"created_at": "2026-03-31T10:00:00.000Z",
"updated_at": "2026-03-31T10:00:05.000Z"
}
}Historique & retry
Merchant APIPaydeck retente automatiquement les webhooks en échec selon le calendrier : 1min → 5min → 30min → 2h → 24h (5 tentatives max).
// Lister les tentatives de livraison
curl https://api.getpaydeck.com/api/v1/webhooks/3/events \
-H "Authorization: Bearer sk_live_VOTRE_CLE"
// Réessayer manuellement un événement
curl -X POST https://api.getpaydeck.com/api/v1/webhooks/3/events/87/retry \
-H "Authorization: Bearer sk_live_VOTRE_CLE"Balance du compte
Merchant APIRetourne les informations de votre compte, incluant votre solde par provider.
curl https://api.getpaydeck.com/api/v1/auth/me \
-H "Authorization: Bearer sk_live_VOTRE_CLE"{
"success": true,
"data": {
"id": 1,
"firstName": "Amadou",
"lastName": "Diallo",
"email": "amadou@acme.sn",
"companyName": "Acme Sénégal",
"mode": "live",
"balances": [
{ "provider": "wave_sn", "balance": 1250000, "currency": "XOF" },
{ "provider": "orange_money_sn", "balance": 850000, "currency": "XOF" }
]
}
}Gérer les clés API
JWT AuthCes endpoints nécessitent un token JWT (obtenu via POST /auth/login), pas une clé API marchande.
Mode Sandbox
Test uniquementLe mode sandbox vous permet de tester votre intégration sans effectuer de vrais paiements. Utilisez votre clé sk_test_... pour activer automatiquement le mode test.
Comportement en sandbox
- • Une collecte par l'API (POST /payments/collect) démarre en statut processing : choisissez son résultat avec POST /sandbox/simulate. Dans la fenêtre de paiement (widget / modal), le paiement de test est réglé tout de suite : succès, ou échec avec le numéro 700000000.
- • Aucun moyen de paiement réel n'est jamais appelé
- • Vous choisissez le résultat : success ou failed
- • Les webhooks sont déclenchés normalement (testez votre endpoint)
- • La balance n'est pas débitée
- • La clé décide de l'environnement : sk_test_ et pk_test_ simulent toujours, même si votre compte est en production. sk_live_ et pk_live_ sont refusées tant que le compte est en test.
- • Une clé ne voit que les transactions de son environnement : GET /payments/transactions et /payments/transactions/:ref ne renvoient jamais l'autre mode.
- • Les webhooks ne reçoivent que les événements de leur environnement (champ mode à la création).
- • Décaissement (POST /payments/disburse) : un envoi vers le numéro 700000000 échoue (statut failed, webhook transaction.disburse.failed), pour tester votre gestion des échecs. Tout autre numéro réussit immédiatement. Pour une collecte, choisissez le résultat avec POST /sandbox/simulate.
- • Réservés à la production (403 LIVE_MODE_REQUIRED) : paylinks, QR, paiements récurrents, paiements et encaissements de masse, retraits, recharges et factures.
Simuler un résultat
Test uniquementSimule le résultat d'une transaction en cours (processing). Déclenche les webhooks comme si le paiement avait vraiment été confirmé ou refusé.
curl -X POST https://api.getpaydeck.com/api/v1/sandbox/simulate \
-H "Authorization: Bearer sk_test_VOTRE_CLE" \
-H "Content-Type: application/json" \
-d '{
"ref": "pd_col_a1b2c3d4e5f6",
"outcome": "success"
}'// Réponse 200
{
"success": true,
"message": "Transaction pd_col_a1b2c3d4e5f6 simulated as success",
"data": {
"ref": "pd_col_a1b2c3d4e5f6",
"status": "success"
}
}Page de test
Test uniquementChaque collecte en mode test génère un lien vers la page sandbox Paydeck. Cette page simule un paiement : choix du résultat, saisie d'un code fictif, et appel automatique à /sandbox/simulate.
https://getpaydeck.com/sandbox/checkout/{ref}?t={sk_test_votre_cle}
// Paramètres :
// - ref : référence interne de la transaction (pd_col_xxx)
// - t : votre clé test (optionnel — permet l'auto-simulation)Widget JavaScript
Intégration webIntégrez une fenêtre de paiement directement sur votre site en une seule ligne de code. Le widget s'affiche dans une iframe isolée hébergée sur le domaine Paydeck — les données de paiement ne transitent jamais par votre serveur.
Architecture
Comment fonctionne le widget
Site tiers (votre domaine)
<script src="https://getpaydeck.com/paydeck.js"></script>
PayDeck.open({ pk: "pk_live_...", amount: 5000 })
getpaydeck.com/modal
- • Affiche les moyens de paiement activés sur votre compte
- • Collecte les infos du payeur
- • Appelle POST /api/v1/payments/collect
Site tiers
1 — Inclure le script
<!-- À placer avant </body> -->
<script src="https://getpaydeck.com/paydeck.js"></script>2 — Ouvrir le modal
PayDeck.open({
pk: "pk_live_VOTRE_CLE_PUBLIQUE", // obligatoire
amount: 5000, // XOF, optionnel (libre si omis)
currency: "XOF", // défaut: XOF
description: "Commande #2026-042", // affiché au payeur
merchantName: "Votre Boutique", // affiché dans le modal
// Données libres retournées dans onSuccess et dans le webhook
metadata: { orderId: "CMD-2026-042", userId: "USR-99" },
// Redirections optionnelles (utile si votre site ne peut pas gérer les callbacks JS)
successUrl: "https://votresite.com/merci", // redirigé après paiement réussi (?ref=...&status=success)
cancelUrl: "https://votresite.com/annule", // redirigé si le payeur ferme le modal
onSuccess: function(data) {
// data = { ref: "pd_col_...", status: "success", metadata: { orderId, userId } }
console.log("Paiement réussi :", data.ref, "| Commande:", data.metadata.orderId)
validerCommande(data.metadata.orderId)
},
onClose: function() {
console.log("Modal fermé")
},
onError: function(err) {
// err = { message: "...", data: { metadata: { orderId, userId } } }
console.error("Erreur :", err.message)
},
})Exemple complet — bouton Acheter
<!DOCTYPE html>
<html>
<head><title>Ma Boutique</title></head>
<body>
<button onclick="payer('ARTICLE-007', 'USR-42')">Acheter — 15 000 XOF</button>
<script src="https://getpaydeck.com/paydeck.js"></script>
<script>
function payer(articleId, userId) {
PayDeck.open({
pk: "pk_live_VOTRE_CLE_PUBLIQUE",
amount: 15000,
description: "Chaise design premium",
merchantName: "Ma Boutique",
// Ces données vous seront retournées dans onSuccess ET dans le webhook
metadata: { articleId: articleId, userId: userId },
onSuccess: function(data) {
// data.metadata contient { articleId, userId }
alert("Merci ! Commande " + data.metadata.articleId + " validée.")
},
onError: function(err) {
alert("Erreur : " + err.message)
},
})
}
</script>
</body>
</html>Providers affichés
Le modal affiche automatiquement les moyens de paiement que vous avez activés dans votre compte. Aucune configuration supplémentaire requise.
pk_test_...TestSandbox — aucun vrai paiement, providers de démopk_live_...LiveProduction — providers activés sur votre compteLogo marchand dans le modal
Le modal affiche automatiquement le logo de votre entreprise en haut de la fenêtre de paiement. Configurez-le dans Tableau de bord → Paramètres → Logo de l'entreprise.
Techniquement, le logo est résolu via l'endpoint GET /checkout/providers?pk=… qui retourne un champ merchant :
{
"success": true,
"data": [ /* providers actifs */ ],
"merchant": {
"name": "Ma Boutique",
"logoUrl": "/uploads/merchants/merchant_1.png"
}
}Paramètres de PayDeck.open()
pkstringrequisClé publique du marchand (pk_live_... ou pk_test_...)
amountintegerMontant en XOF. Si omis, le payeur saisit lui-même le montant.
currencystringDevise — défaut : XOF
descriptionstringDescription affichée dans le modal
merchantNamestringNom de votre boutique/entreprise affiché en haut du modal
metadataobjectDonnées libres retournées dans onSuccess et dans le webhook.
successUrlstringURL de redirection après paiement réussi. Reçoit ?ref=...&status=success en query string.
cancelUrlstringURL de redirection si le payeur ferme le modal sans payer.
onSuccessfunctionCallback après paiement réussi. Reçoit { ref, status, metadata }. Déclenché avant successUrl.
onClosefunctionCallback quand le payeur ferme le modal. Déclenché avant cancelUrl.
onErrorfunctionAppelée en cas d'erreur. Reçoit { message, data: { metadata } }.
SDKs officiels
Des SDKs officiels sont disponibles pour les principaux langages. Chaque SDK gère l'authentification, la sérialisation, les erreurs et la vérification des webhooks. Zéro dépendance externe sauf Java (Jackson Databind).
Exemple Node.js
import Paydeck from '@paydeck/node';
const paydeck = new Paydeck('sk_live_YOUR_KEY');
// Collecter un paiement
const tx = await paydeck.collect({
amount: 5000,
providerCode: 'wave_sn',
phoneNumber: '771234567',
});
if (tx.paymentUrl) {
// Rediriger le client ou afficher le QR
}
// Vérifier un webhook
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
const event = paydeck.verifyWebhook(
req.body,
req.headers['paydeck-signature'],
process.env.PAYDECK_WEBHOOK_SECRET,
);
if (event.event === 'payment.success') fulfill(event.ref);
res.sendStatus(200);
});Exemple Python
from paydeck import Paydeck
paydeck = Paydeck("sk_live_YOUR_KEY")
tx = paydeck.collect(
amount=5000,
provider_code="wave_sn",
phone_number="771234567",
)
print(tx.payment_url)Plugins e-commerce
Des plugins prêts-à-l'emploi sont disponibles pour les principales plateformes e-commerce. Chaque plugin utilise GET /payments/providers à l'exécution pour afficher automatiquement les providers disponibles.
| Plateforme | Version min. | Télécharger |
|---|---|---|
| WooCommerce | WC 7+ / WP 6+ | .zip |
| PrestaShop | PS 8.0+ | .zip |
| WHMCS | WHMCS 8.0+ | .zip |
Configuration webhook
Pour chaque plugin, enregistrez l'URL webhook suivante dans votre tableau de bord PayDeck :
https://votre-site.com/?wc-api=paydeck_webhookhttps://votre-site.com/module/paydeck/webhookhttps://votre-site.com/modules/gateways/callback/paydeck.phpQuestions ? Écrivez-nous à support@getpaydeck.com
API Paydeck v1.0 · Dernière mise à jour : mai 2026