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

⚠
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 HTTPSignification
200OK — Requête réussie
201Created — Ressource créée
400Bad Request — Paramètres manquants ou invalides
401Unauthorized — Clé API manquante ou invalide
403Forbidden — Compte non activé ou bloqué
404Not Found — Ressource introuvable
422Unprocessable Entity — Erreur de validation
429Too Many Requests — Limite de débit dépassée
500Internal 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.

EndpointLimiteFenêtre
POST /checkout/pay100 requêtes1 minute
GET /checkout/providers200 requêtes1 minute
GET /checkout/status/:ref300 requêtes1 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",
      "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
    }
  ]
}
ℹ
Chaque moyen de paiement indique ce qu'il permet : supportsPayerRestriction (il accepte l'option restrictPayerToPhone) et returnsVerifiedPayer (payer_phone_verified sera renseigné après un paiement réussi). Lisez ces champs à l'exécution plutôt que de supposer un comportement pour un moyen de paiement donné : de nouveaux moyens sont ajoutés sans changement de votre côté.

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.
CodeNomTypeCollectDisbursePays
wave_snWave SénégalMobile Money✓✓SN
orange_money_snOrange Money SNMobile Money✓✓SN
cardPaiement par carteCarte✓—*

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 demandé par certains moyens de paiement : voir collectFields dans GET /payments/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

restrictPayerToPhoneboolean

Facultatif (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.

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
    "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.
⚠
En mode test, rien n'est vérifié auprès d'un vrai provider : l'option est enregistrée et renvoyée (payer_restricted) mais payer_phone_verified reste null. Testez votre gestion d'un paiement refusé avec un petit paiement réel en production.
ℹ
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)

1.

Client

génère OTP

transmet à votre app

Votre serveur

2.

Votre serveur

POST /collect + otp

API Paydeck

→ provider

Résultat

sync

3.← Réponse synchrone : success / failed

Sessions de paiement (montant sécurisé)

Merchant API
POST/api/v1/payments/sessions

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

✓
Recommandé pour tout paiement qui déclenche une livraison ou un versement. Avec le widget à clé publique + montant, le montant est choisi dans le navigateur et peut être modifié par le payeur ; avec une session, c'est impossible. Dans « API & Paramètres », vous pouvez rendre les sessions obligatoires pour votre compte.

Corps de la requête

amountintegerrequis

Montant en XOF (entier), dans les limites de la plateforme

currencystring

Monnaie (XOF, défaut)

descriptionstring

Texte affiché au payeur (255 caractères au plus)

metadataobject

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

expiresInMinutesinteger

Durée de validité en minutes : de 1 à 1440 (défaut 30)

restrictPayerToPhoneboolean

Facultatif (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.

customerobject

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

bash
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" }
  }'
json
// 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

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

javascript
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 nouvelle
SESSION_NOT_FOUND404Identifiant de session inconnu
SESSION_AMOUNT_MISMATCH422Montant du navigateur différent de celui de la session
SESSION_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 paiement
SESSION_KEY_MISMATCH403Clé publique d'un autre marchand
SESSION_REQUIRED403Votre compte exige une session (réglage « sessions obligatoires »)
GET/api/v1/payments/sessions/:id

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

recipientEmailstring

Email du destinataire (facultatif) : il reçoit un avis quand le virement a réussi

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",
    "recipientEmail": "fatou@exemple.sn",
    "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"
  }
}

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.

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

searchstring

Recherche dans la référence, le numéro ou le nom du bénéficiaire

metadata[key]string

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

bash
# 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"
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"
StatutDescription
pendingInitiée, en attente de confirmation du client
processingEn cours de traitement par le provider
successPaiement confirmé et crédité
failedPaiement 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

Rembourser une collecte

Merchant API
POST/api/v1/payments/transactions/:ref/refund

Rembourse 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

reasonstring

Motif du remboursement (facultatif, conservé dans metadata.reason)

bash
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" }'
json
// Réponse 200
{
  "success": true,
  "message": "Remboursement effectué avec succès",
  "data": {
    "ref": "PDK-20261110-5B21C9D0",
    "status": "success",
    "amount": 5000
  }
}
ℹ
La transaction de remboursement a operation = refund et son parentTransactionId pointe vers la collecte d'origine, dont le statut devient refunded une fois le remboursement réussi. Si le provider refuse définitivement le remboursement, votre solde est restitué et un événement transaction.refund.failed est envoyé.

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.

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

StatutDescription
draftBatch créé mais pas encore lancé
processingDécaissements en cours
doneTous 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énementDéclenché quand
transaction.collect.successUn paiement entrant est confirmé
transaction.collect.failedUn paiement entrant est refusé ou expiré
transaction.disburse.successUn décaissement est confirmé
transaction.disburse.failedUn décaissement a échoué
transaction.refund.successUn remboursement est confirmé
transaction.refund.failedUn remboursement est refusé par le provider
✓
Pour un remboursement, le webhook décrit le remboursement lui-même : operation vaut « refund », ref est la référence du remboursement et metadata.originalRef rappelle la référence de la collecte remboursée. Le montant remboursé est le montant de la collecte, sans les frais (non remboursés).

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": 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"
  }
}
✓
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.
⚠
phone_number est le numéro saisi à la création du paiement, pas une preuve de qui a payé. payer_phone_verified est le payeur confirmé par le moyen de paiement, quand il le communique (returnsVerifiedPayer dans GET /payments/providers) ; null signifie « non communiqué », pas « différent ».

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, une collecte par l'API renvoie une paymentUrl vers la page de test Paydeck au lieu de la page du moyen de paiement.

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 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 un paiement : choix du résultat, saisie d'un code 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 API & Paramètres → Clés API. Ne nécessite aucun backend.

Architecture

Comment fonctionne le widget

Site tiers (votre domaine)

<script src="https://getpaydeck.com/paydeck.js"></script>

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

iframe isolée

getpaydeck.com/modal

  • • Affiche les moyens de paiement activés sur votre compte
  • • Collecte les infos du payeur
  • • Appelle POST /api/v1/payments/collect
postMessage → onSuccess(data) / onError(msg)

Site tiers

✓
Le metadata passé à PayDeck.open() est copié dans la transaction : vous le retrouvez dans GET /payments/transactions/:ref et dans les webhooks transaction.collect.*. Limites : 20 clés au maximum, 2 Ko, valeurs simples (texte de 500 caractères au plus, nombre, booléen). Les clés source, demoshop, massPaymentId, withdrawalId, withdrawalRequestId, rechargeRequestId, bulkCollectItemId, refundRef, originalRef, paydeck_ref et celles commençant par __ sont réservées à Paydeck et ignorées.
⚠
onSuccess(data) est un signal pour votre interface, pas une preuve de paiement : data contient ref, status et le metadata que vous avez passé (renvoyé tel quel par le navigateur). Avant de livrer un bien ou valider une commande, vérifiez toujours le paiement côté serveur avec votre clé secrète (GET /payments/transactions/:ref) ou par le webhook signé. Pour que le montant ne puisse pas être modifié par le payeur, utilisez une session de paiement (section « Sessions de paiement »).

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['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.

PlateformeVersion min.Télécharger
WooCommerceWC 7+ / WP 6+.zip
PrestaShopPS 8.0+.zip
WHMCSWHMCS 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