API Reference v1.0

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. Vous trouverez vos clés dans votre tableau de bord → Paramètres → Clés API.

⚠

Ne partagez jamais votre clé secrète (sk_live_...). Stockez-la uniquement côté serveur, jamais dans du code frontend ou mobile.

bash

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 paiement

sk_live_...LiveProduction — paiements réels

Environnements

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 :

json

{
  "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.

json

{
  "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

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0

✓

Le header Retry-After indique le nombre de secondes à attendre avant de réessayer.

Health check

GET/api/v1/health

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).

json

// 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"
}

ℹ

uptime est exprimé en secondes depuis le démarrage du process Node.

Providers disponibles

GET/api/v1/payments/providers

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.

json

// Réponse
{
  "success": true,
  "data": [
    {
      "id": 1,
      "code": "wave_sn",
      "name": "Wave Sénégal",
      "type": "mobile_money",
      "countries": ["SN"],
      "currency": "XOF",
      "supports_collect": true,
      "supports_disburse": true
    },
    {
      "id": 2,
      "code": "orange_money_sn",
      "name": "Orange Money SN",
      "type": "mobile_money",
      "countries": ["SN"],
      "currency": "XOF",
      "supports_collect": true,
      "supports_disburse": true
    },
    {
      "id": 3,
      "code": "card",
      "name": "Paiement par carte",
      "type": "card",
      "countries": ["*"],
      "currency": "XOF",
      "supports_collect": true,
      "supports_disburse": false
    }
  ]
}

Référence rapide — Providers actuels

ℹ

Cette liste reflète les providers actuellement déployés. Elle peut évoluer — appelez toujours GET /payments/providers en temps réel pour obtenir la liste exacte des providers actifs sur votre compte.

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.

🇸🇳Sénégal+221SN

🌍Autres pays+XXX—selon providers disponibles

Collecter un paiement

Merchant API

POST/api/v1/payments/collect

Initie 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

providerCodestringrequis

Code du provider — voir GET /payments/providers pour la liste complète

amountintegerrequis

Montant en XOF (entier, sans décimales). Ex: 5000

phoneNumberstringrequis

Numéro de téléphone du payeur. Ex: 771234567

phoneCountryCodestring

Indicatif pays. Ex: +221 (par défaut: +221)

recipientNamestring

Nom du payeur

recipientEmailstring

Email du payeur pour le reçu

otpstring

Code OTP requis par certains providers

successUrlstring

URL de redirection après paiement réussi

cancelUrlstring

URL de redirection si le client annule

metadataobject

Métadonnées libres retournées dans les webhooks

bash

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" }
  }'

json

// 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
    "createdAt": "2026-03-31T10:00:00.000Z"
  }
}

ℹ

En mode test, paymentUrl pointe vers la page sandbox Paydeck. Vous pouvez simuler le résultat avec POST /sandbox/simulate.

Schémas des flux

Flux collect — Redirection client

Votre serveur

POST /collect

API Paydeck

paymentUrl

Client

page de paiement

← Webhook : transaction.collect.success / failed

Flux collect — OTP synchrone (certains providers)

Client

génère OTP

transmet à votre app

Votre serveur

POST /collect + otp

API Paydeck

→ provider

Résultat

sync

3.← Réponse synchrone : success / failed

Envoyer de l'argent

Merchant API

POST/api/v1/payments/disburse

Envoie des fonds vers un numéro mobile money (décaissement).

Corps de la requête

providerCodestringrequis

Code du provider — voir GET /payments/providers pour la liste complète

amountintegerrequis

Montant en XOF à envoyer

phoneNumberstringrequis

Numéro mobile money du destinataire

phoneCountryCodestring

Indicatif pays. Ex: +221

recipientNamestring

Nom du destinataire

metadataobject

Métadonnées libres

bash

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",
    "metadata": { "employeeId": "EMP-042" }
  }'

json

// 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"
  }
}

Lister les transactions

Merchant API

GET/api/v1/payments/transactions

Retourne la liste paginée de vos transactions avec filtres optionnels.

Paramètres de requête (query string)

pageinteger

Numéro de page (défaut: 1)

limitinteger

Résultats par page, max 100 (défaut: 20)

statusstring

Filtrer par statut: pending, processing, success, failed

operationstring

Filtrer par opération: collect, disburse

startDatestring

Date de début ISO 8601. Ex: 2026-01-01

endDatestring

Date de fin ISO 8601. Ex: 2026-03-31

bash

curl "https://api.getpaydeck.com/api/v1/payments/transactions?status=success&limit=10" \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"

json

// 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 API

GET/api/v1/payments/transactions/:ref

Récupère les détails complets d'une transaction par sa référence interne.

bash

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

confirmé

✓ success

refusé / expiré

✗ failed

Créer un lien de paiement

Merchant API

POST/api/v1/paylinks

Cré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

titlestringrequis

Nom du lien de paiement (2-255 caractères)

descriptionstring

Description affichée au payeur

amountinteger

Montant fixe en XOF (si isFixedAmount = true)

isFixedAmountboolean

Montant fixe ou libre (défaut: true si amount fourni)

minAmountinteger

Montant minimum si montant libre

maxAmountinteger

Montant maximum si montant libre

currencystring

Devise (défaut: XOF)

redirectUrlstring

URL de redirection après paiement

maxUsesinteger

Nombre maximum d'utilisations

expiresAtstring

Date d'expiration ISO 8601

allowedProvidersstring[]

Providers autorisés. Ex: ["wave_sn", "orange_money_sn"]

bash

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"]
  }'

json

// 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"
  }
}

✓

Le champ redirectUrl contrôle où le payeur est redirigé après un paiement réussi. Pour les providers avec redirection (Wave), le client est renvoyé vers cette URL par le provider. Pour les providers synchrones (Orange Money), la page de paiement Paydeck effectue la redirection automatiquement. Le webhook transaction.collect.success est toujours déclenché indépendamment de la redirection.

Lister les liens de paiement

Merchant API

GET/api/v1/paylinks

bash

curl "https://api.getpaydeck.com/api/v1/paylinks?status=active" \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"

Payer via un lien

Public

Endpoint public — pas d'authentification requise. Utilisé par la page de paiement Paydeck.

GET/api/v1/paylinks/:token

bash

// Récupérer les infos du lien (public)
curl https://api.getpaydeck.com/api/v1/paylinks/AbCdEfGhIjKlMnOpQrStUvWx

POST/api/v1/paylinks/:token/pay

bash

// 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 API

POST/api/v1/mass-payments

Cré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

labelstringrequis

Nom du batch. Ex: Salaires Mars 2026

providerCodestringrequis

Provider utilisé pour tous les décaissements

itemsarrayrequis

Liste des destinataires

items[].phoneNumberstringrequis

Numéro de téléphone du destinataire

items[].amountintegerrequis

Montant en XOF

items[].namestring

Nom du destinataire

bash

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" }
    ]
  }'

json

// 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 API

GET/api/v1/mass-payments/:id

Pour 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 API

Les webhooks permettent à Paydeck de notifier votre serveur en temps réel lors de chaque changement de statut d'une transaction.

POST/api/v1/webhooks

Corps de la requête

urlstringrequis

URL HTTPS de votre endpoint (doit retourner 2xx)

eventsstring[]requis

Liste des événements à écouter (voir ci-dessous)

bash

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"
    ]
  }'

⚠

Le secret de webhook est retourné une seule fois à la création. Stockez-le immédiatement — il ne peut pas être récupéré ensuite.

json

// 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

POST + HMAC-SHA256

Votre serveur

200 OK ?

✓ livré

Si pas de 200 → retry automatique :

retry 1 · 1 minretry 2 · 5 minretry 3 · 30 minretry 4 · 2 hretry 5 · 24 h

É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é

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

text

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

javascript

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

json

{
  "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": 4925,
    "currency": "XOF",
    "phone_number": "771234567",
    "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"
  }
}

✓

Le champ metadata contient exactement les données libres que vous avez passées lors de la création de la transaction. Utilisez-le pour retrouver l'identifiant de commande, l'utilisateur, ou tout autre contexte métier.

Historique & retry

Merchant API

Paydeck retente automatiquement les webhooks en échec selon le calendrier : 1min → 5min → 30min → 2h → 24h (5 tentatives max).

GET/api/v1/webhooks/:id/events

POST/api/v1/webhooks/:webhookId/events/:eventId/retry

bash

// 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 API

GET/api/v1/auth/me

Retourne les informations de votre compte, incluant votre solde par provider.

bash

curl https://api.getpaydeck.com/api/v1/auth/me \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"

json

{
  "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 Auth

Ces endpoints nécessitent un token JWT (obtenu via POST /auth/login), pas une clé API marchande.

GET/api/v1/auth/api-keys

POST/api/v1/auth/api-keys/rotate

✓

La rotation génère une nouvelle clé et invalide immédiatement l'ancienne. Mettez à jour votre configuration serveur avant de rotationner.

Mode Sandbox

Test uniquement

Le 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.

ℹ

En mode test, les collectes Wave retournent une paymentUrl vers la page sandbox Paydeck au lieu de la vraie app Wave.

Comportement en sandbox

• Toutes les collectes démarrent en statut processing
• Les vrais providers (Wave, Orange) ne sont jamais appelés
• 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

Simuler un résultat

Test uniquement

POST/api/v1/sandbox/simulate

Simule le résultat d'une transaction en cours (processing). Déclenche les webhooks comme si le paiement avait vraiment été confirmé ou refusé.

bash

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"
  }'

json

// Réponse 200
{
  "success": true,
  "message": "Transaction pd_col_a1b2c3d4e5f6 simulated as success",
  "data": {
    "ref": "pd_col_a1b2c3d4e5f6",
    "status": "success"
  }
}

✓

Vous pouvez aussi simuler directement depuis la page de checkout sandbox en passant ?t=sk_test_... dans l'URL.

Page de test

Test uniquement

Chaque collecte en mode test génère un lien vers la page sandbox Paydeck. Cette page simule l'interface Wave : choix du résultat, saisie d'un OTP fictif, et appel automatique à /sandbox/simulate.

text

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)

ℹ

Le paramètre ?t= est optionnel. Sans lui, la page affiche le résultat visuellement mais n'appelle pas l'API.

Widget JavaScript

Intégration web

Inté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.

ℹ

Le widget utilise votre clé publique (pk_live_... ou pk_test_...), visible dans Paramètres → Clés API. Ne nécessite aucun backend.

Architecture

Comment fonctionne le widget

Site tiers (votre domaine)

PayDeck.open({ pk: "pk_live_...", amount: 5000 })

iframe isolée

getpaydeck.com/modal

• Affiche les providers activés (Wave, Orange Money, Carte)
• Collecte les infos du payeur
• Appelle POST /api/v1/payments/collect

postMessage → onSuccess(data) / onError(msg)

Site tiers

1 — Inclure le script

html

<!-- À placer avant </body> -->
<script src="https://getpaydeck.com/paydeck.js"></script>

2 — Ouvrir le modal

javascript

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

html

<!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émo

pk_live_...LiveProduction — providers activés sur votre compte

Logo 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 :

json

{
  "success": true,
  "data": [ /* providers actifs */ ],
  "merchant": {
    "name": "Ma Boutique",
    "logoUrl": "/uploads/merchants/merchant_1.png"
  }
}

✓

Si aucun logo n'est configuré, le modal affiche l'initiale du nom de votre entreprise dans un avatar généré automatiquement.

Paramètres de PayDeck.open()

pkstringrequis

Clé publique du marchand (pk_live_... ou pk_test_...)

amountinteger

Montant en XOF. Si omis, le payeur saisit lui-même le montant.

currencystring

Devise — défaut : XOF

descriptionstring

Description affichée dans le modal

merchantNamestring

Nom de votre boutique/entreprise affiché en haut du modal

metadataobject

Données libres retournées dans onSuccess et dans le webhook.

successUrlstring

URL de redirection après paiement réussi. Reçoit ?ref=...&status=success en query string.

cancelUrlstring

URL de redirection si le payeur ferme le modal sans payer.

onSuccessfunction

Callback après paiement réussi. Reçoit { ref, status, metadata }. Déclenché avant successUrl.

onClosefunction

Callback quand le payeur ferme le modal. Déclenché avant cancelUrl.

onErrorfunction

Appelée en cas d'erreur. Reçoit { message, data: { metadata } }.

ℹ

Statut en temps réel : le modal interroge automatiquement le statut de la transaction toutes les 3 secondes. successUrl vs onSuccess : les deux peuvent coexister. Préférez onSuccess pour les SPA.

⚠

Utilisez toujours votre clé publique (pk_...) côté client — jamais votre clé secrète (sk_...).

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).

Node.js / TypeScriptnpm

npm install @paydeck/nodeTélécharger .zip

PythonPyPI

pip install paydeckTélécharger .zip

PHPPackagist

composer require paydeck/paydeck-phpTélécharger .zip

RubyRubyGems

gem install paydeckTélécharger .zip

.NET / C#NuGet

dotnet add package PaydeckTélécharger .zip

JavaMaven

com.paydeck:paydeck-java:1.0.0Télécharger .zip

iOS / SwiftSPM

Swift Package Manager (SPM)Télécharger .zip

Android / KotlinGradle

Kotlin + Gradle (API 21+)Télécharger .zip

Exemple Node.js

javascript

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['x-paydeck-signature'],
    process.env.PAYDECK_WEBHOOK_SECRET,
  );
  if (event.event === 'payment.success') fulfill(event.ref);
  res.sendStatus(200);
});

Exemple Python

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

✓

Les archives ZIP contiennent le plugin complet avec le SDK PHP intégré. Aucune autre dépendance requise.

Configuration webhook

Pour chaque plugin, enregistrez l'URL webhook suivante dans votre tableau de bord PayDeck :

WooCommercehttps://votre-site.com/?wc-api=paydeck_webhook

PrestaShophttps://votre-site.com/module/paydeck/webhook

WHMCShttps://votre-site.com/modules/gateways/callback/paydeck.php

Questions ? Écrivez-nous à support@getpaydeck.com

API Paydeck v1.0 · Dernière mise à jour : mai 2026