API Documentation
Integrate Wave, Orange Money and card payments in a few hours. The Paydeck API is designed to be simple, predictable and well-documented.
Introduction
The Paydeck API is a REST API that accepts JSON request bodies and returns JSON responses. All requests must be made over HTTPS.
Base URL
https://api.getpaydeck.com/api/v1
Format
JSON · REST
Auth
API Key (Bearer)
Authentication
All API requests must include your secret key in the Authorization header. Generate your keys in your dashboard → API & Settings → API Keys ("Generate a test key" button). The full secret key is shown only once: copy it right away.
curl https://api.getpaydeck.com/api/v1/payments/providers \
-H "Authorization: Bearer sk_live_VOTRE_CLE_SECRETE"Key types
sk_test_...TestSandbox only — no real paymentssk_live_...LiveProduction — real paymentsEnvironments
Paydeck offers two environments: Test (Sandbox) and Live (Production). The active environment depends on the API key used.
Test
api.getpaydeck.com/api/v1
sk_test_...
No real payments made
Live
api.getpaydeck.com/api/v1
sk_live_...
Real payments — activated by admin
Response Format
All responses follow the same structure:
{
"success": true,
"data": { ... },
"message": "Operation successful",
"meta": { // present only for paginated lists
"currentPage": 1,
"lastPage": 5,
"total": 92,
"perPage": 20
}
}Error Handling
On error, success is false and message describes the error.
{
"success": false,
"message": "Insufficient balance",
"errors": [ // only for validation errors
{ "field": "amount", "message": "Amount must be a positive integer" }
]
}| HTTP Code | Meaning |
|---|---|
| 200 | OK — Request successful |
| 201 | Created — Resource created |
| 400 | Bad Request — Missing or invalid parameters |
| 401 | Unauthorized — Missing or invalid API key |
| 403 | Forbidden — Account not activated or blocked |
| 404 | Not Found — Resource not found |
| 422 | Unprocessable Entity — Validation error |
| 429 | Too Many Requests — Rate limit exceeded |
| 500 | Internal Server Error — Server-side error |
Rate Limiting
Public payment endpoints are protected against abuse by an IP-based rate limiter.
| Endpoint | Limit | Window |
|---|---|---|
| POST /checkout/pay | 100 requests | 1 minute |
| GET /checkout/providers | 200 requests | 1 minute |
| GET /checkout/status/:ref | 300 requests | 1 minute |
| Merchant API (sk_…) | Unlimited | — |
When exceeded, the API returns HTTP 429 with the following headers:
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0Health Check
Public endpoint without authentication — checks that the server and database are operational. Useful for monitoring probes (uptime robot, load balancer, CI/CD).
// Response — all OK (HTTP 200)
{
"status": "ok",
"db": "connected",
"uptime": 3600,
"timestamp": "2026-04-29T12:00:00.000Z"
}
// Response — DB unavailable (HTTP 503)
{
"status": "degraded",
"db": "error",
"uptime": 120,
"timestamp": "2026-04-29T12:00:00.000Z"
}Available Providers
Returns the list of active payment providers and their capabilities. Use this endpoint to build your payment method selector.
// Response
{
"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
}
]
}Quick Reference — Current Providers
| Code | Name | Type | Collect | Disburse | Country |
|---|---|---|---|---|---|
| wave_sn | Wave Sénégal | Mobile Money | ✓ | ✓ | SN |
| orange_money_sn | Orange Money SN | Mobile Money | ✓ | ✓ | SN |
| card | Paiement par carte | Carte | ✓ | — | * |
Quick Reference — Country Dial Codes
Used in the phoneCountryCode parameter during a collection or disbursement.
+221SN+XXX—depending on available providersCollect a Payment
Merchant APIInitiates a collection (the customer pays you). Depending on the provider, the response includes a redirect paymentUrl or a direct synchronous result.
Request body
providerCodestringrequisProvider code — see GET /payments/providers for the full list
amountintegerrequisAmount in XOF (integer, no decimals). Ex: 5000
phoneNumberstringrequisPayer's phone number. Ex: 771234567
phoneCountryCodestringCountry dial code. Ex: +221 (default: +221)
recipientNamestringPayer's name
recipientEmailstringPayer's email for the receipt
otpstringCode required by some payment methods: see collectFields in GET /payments/providers
successUrlstringRedirect URL after successful payment
cancelUrlstringRedirect URL if the customer cancels
metadataobjectFree metadata returned in webhooks
restrictPayerToPhonebooleanOptional (default false). If true, ONLY the number in phoneNumber can pay. Only for payment methods with supportsPayerRestriction (GET /payments/providers); refused (422) otherwise. See “Who paid? Restrict the payment to one number” below.
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" }
}'// Response 201
{
"success": true,
"data": {
"id": 142,
"ref": "pd_col_a1b2c3d4e5f6",
"status": "processing",
"amount": 5000,
"feeAmount": 75,
"netAmount": 5000,
"paymentUrl": "https://pay.getpaydeck.com/xxx", // present if the provider requires a client redirect
"payerRestricted": false, // true if restrictPayerToPhone was requested
"createdAt": "2026-03-31T10:00:00.000Z"
}
}Who paid? Restrict the payment to one number
By default, phoneNumber is the number YOU (or the payer) entered. It is not proof of who actually paid: depending on the payment method, an account other than the one entered can pay. If you know your payer in advance (subscription, contribution…), you can turn on an option so that only their number can pay.
- Turn it on with "restrictPayerToPhone": true on POST /payments/collect, or on POST /payments/sessions (together with customer.phone). Off by default: nothing changes if you do not use it.
- Available for payment methods whose supportsPayerRestriction is true in GET /payments/providers. With any other method the request is refused (422), never silently accepted. Payment links and static QR codes do not use it.
- With a session, the number is locked: the payment window shows it read-only, only compatible payment methods are offered, and the server refuses any other number (error SESSION_PAYER_MISMATCH).
- A payment from another number is refused and the transaction fails (failureReason PAYER_MOBILE_MISMATCH when the payment method reports this reason). The payer must pay from the expected number.
- Who actually paid: payer_phone_verified (webhook and transaction) contains the payer's number when the payment method reports it (returnsVerifiedPayer), otherwise null. A null value does not mean the payer was different.
- Safety net: if a payment from a different number still goes through, it is NOT credited automatically. It is held for review by Paydeck and no balance moves.
Flow diagrams
Collect flow — Client redirect
Votre serveur
API Paydeck
Client
page de paiement
Collect flow — Synchronous OTP (some providers)
Customer
generates OTP
Votre serveur
Votre serveur
API Paydeck
Result
sync
Payment sessions (secured amount)
Merchant APIA payment session is created by YOUR platform's SERVER with your secret key: the amount, description and metadata are locked in it. The payer's browser only receives an opaque identifier (ps_…) and cannot change anything.
Request body
amountintegerrequisAmount in XOF (integer), within the platform limits
currencystringCurrency (XOF, default)
descriptionstringText shown to the payer (255 characters at most)
metadataobjectYour data (e.g. order identifier), locked in the session then copied into the transaction and webhooks. 20 keys, 2 KB, simple values; Paydeck's reserved keys are ignored.
expiresInMinutesintegerValidity in minutes: 1 to 1440 (default 30)
restrictPayerToPhonebooleanOptional (default false). If true, customer.phone becomes the ONLY number allowed to pay (required with this option). The payment window shows it read-only and only offers payment methods with supportsPayerRestriction. See “Who paid?” in the Collect section.
customerobjectOptional. Payer details used to PRE-FILL the payment window: phone (digits), phoneCountryCode (e.g. +221), email. The payer can change them; the number they finally use is the one stored on the transaction. The window only handles +221 numbers: a number with another country code is not pre-filled. In test mode the details are displayed, not editable.
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" }
}'// Response 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..."
}
}Open the payment
// 1. Your SERVER creates the session (secret key), then sends only data.id to the page
PayDeck.open({
session: "ps_Zk3q8wX2mB7nR1tVd5LpYc9HfGa4JeUo",
onSuccess: function (data) {
// signal for your interface only — confirm with the signed webhook / GET /payments/transactions/:ref
console.log(data.ref, data.session)
},
})Simplest integration: createSession (automatic renewal)
Give the widget a function that calls YOUR server and returns the ps_… identifier. The widget calls it at each opening, and once more by itself if the session expired while the page stayed open: you have nothing to manage.
PayDeck.open({
createSession: async function () {
// your route creates the session with the secret key (POST /payments/sessions) and returns 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) },
})Without the widget, redirect the payer to checkoutUrl: it is the same payment page, hosted by Paydeck. The environment (test or live) is that of the secret key that created the session.
Behavior
- The amount is the session's. A different amount sent by the browser is rejected.
- Only one live attempt at a time. A failure (wrong code, insufficient balance) frees the session: the payer can try again.
- If the payer closes then reopens the page: an in-progress payment with the same payment method is resumed as is; an already successful payment is simply returned (never a second charge).
- If a payment is in progress with another method, the payer gets a clear message; they can wait for the first attempt to finish or expire, or you create a new session.
- A session expires (30 minutes by default). With createSession the widget renews it automatically; otherwise (session passed directly, or checkoutUrl) the payer gets a clear message and you create a new one (error 410). A payment that already succeeded stays viewable.
- The transaction metadata contains the session's plus sessionId (the ps_… identifier): you find the session in webhooks and in GET /payments/transactions/:ref.
Error codes
SESSION_EXPIRED410Expired session: create a new oneSESSION_NOT_FOUND404Unknown session identifierSESSION_AMOUNT_MISMATCH422Browser amount differs from the session'sSESSION_PAYER_MISMATCH422Number sent by the browser differs from the one imposed by the session (restrictPayerToPhone)SESSION_PAYMENT_IN_PROGRESS409A payment is already in progress with another payment methodSESSION_KEY_MISMATCH403Public key of another merchantSESSION_REQUIRED403Your account requires a session (“mandatory sessions” setting)Returns the session state: status is open, processing, paid or expired, and transactionRef gives the reference of the in-progress or successful attempt.
Send Money
Merchant APISends funds to a mobile money number (disbursement).
Request body
providerCodestringrequisProvider code — see GET /payments/providers for the full list
amountintegerrequisAmount in XOF to send
phoneNumberstringrequisRecipient's mobile money number
phoneCountryCodestringCountry dial code. Ex: +221
recipientNamestringRecipient's name
recipientEmailstringRecipient email (optional): they get a notice once the transfer has succeeded
metadataobjectFree metadata
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" }
}'// Response 201
{
"success": true,
"data": {
"id": 143,
"ref": "pd_dis_x7y8z9a0b1c2",
"status": "processing",
"amount": 25000,
"feeAmount": 250,
"createdAt": "2026-03-31T10:05:00.000Z"
}
}Idempotency — avoid a double payout
If your call times out (network cut before the response), you don't know whether the payout went through. Add the Idempotency-Key header: by re-sending exactly the same request with the same key, you get the payout already created instead of a second one.
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" }'- You choose the key: 1 to 255 visible characters, no spaces (payout identifier, UUID…). It is unique per merchant account.
- Same key and same parameters: 200 response with the Idempotent-Replayed: true header — no new debit, no new transfer. The status returned is the payout's current status.
- Same key but different parameters (amount, number, provider): 422 error. Use a new key for a new payout.
- Without the header, behavior is unchanged: every call creates a payout. You can also find a payout by your own data (see “List Transactions”, metadata filter).
List Transactions
Merchant APIReturns a paginated list of your transactions with optional filters.
Query parameters
pageintegerPage number (default: 1)
limitintegerResults per page, max 100 (default: 20)
statusstringFilter by status: pending, processing, success, failed
operationstringFilter by operation: collect, disburse
startDatestringStart date ISO 8601. Ex: 2026-01-01
endDatestringEnd date ISO 8601. Ex: 2026-03-31
searchstringSearch in the reference, number or recipient name
metadata[key]stringFinds transactions whose metadata holds this exact value (e.g. metadata[payment_id]=abc, or metadata.payment_id=abc). Up to 5 combined filters; key name of 1 to 64 characters (letters, digits, _ or -).
# Find a transaction by your own identifier (order, payment…)
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"// Response 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
}
}Transaction Status
Merchant APIRetrieves the full details of a transaction by its internal reference.
curl https://api.getpaydeck.com/api/v1/payments/transactions/pd_col_a1b2c3d4e5f6 \
-H "Authorization: Bearer sk_live_VOTRE_CLE"| Status | Description |
|---|---|
| pending | Initiated, awaiting customer confirmation |
| processing | Being processed by the provider |
| success | Payment confirmed and credited |
| failed | Payment declined or expired |
Transaction lifecycle
États possibles
pending
initiated
processing
in progress at the provider
✓ success
✗ failed
Refund a collection
Merchant APIFully refunds a successful collection, through the same payment method, to the number recorded on the transaction (phoneNumber).
- Full refunds only: partial refunds are not available.
- The payer receives the collection amount (amount); Paydeck fees are not refunded.
- The collection must have the success status, and your Paydeck balance must cover the amount: it is debited on request, then sent to the payer.
- With a test key (sk_test_), the refund is simulated and instant; a test key never refunds a real payment.
- The delay depends on the provider. Until it answers, the status stays processing; if the outcome is uncertain, the balance is neither restored nor re-credited blindly: Paydeck checks with the provider and then settles automatically.
Request body
reasonstringRefund reason (optional, kept in 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" }'// Response 200
{
"success": true,
"message": "Remboursement effectué avec succès",
"data": {
"ref": "PDK-20261110-5B21C9D0",
"status": "success",
"amount": 5000
}
}Refund webhooks
Two events: transaction.refund.success and transaction.refund.failed. The message describes the refund itself (operation refund, its own reference); the reference of the refunded collection is in 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" }
}
}Create a Payment Link
Merchant APICreates a shareable payment link. Ideal for invoices, online stores, or collection campaigns.
Request body
titlestringrequisPayment link name (2-255 characters)
descriptionstringDescription displayed to the payer
amountintegerFixed amount in XOF (if isFixedAmount = true)
isFixedAmountbooleanFixed or free amount (default: true if amount provided)
minAmountintegerMinimum amount if free amount
maxAmountintegerMaximum amount if free amount
currencystringCurrency (default: XOF)
redirectUrlstringRedirect URL after payment
maxUsesintegerMaximum number of uses
expiresAtstringExpiry date ISO 8601
allowedProvidersstring[]Allowed providers. E.g. ["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"]
}'// Response 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"
}
}List Payment Links
Merchant APIcurl "https://api.getpaydeck.com/api/v1/paylinks?status=active" \
-H "Authorization: Bearer sk_live_VOTRE_CLE"Pay via a Link
PublicPublic endpoint — no authentication required. Used by the Paydeck payment page.
// Get link info (public)
curl https://api.getpaydeck.com/api/v1/paylinks/AbCdEfGhIjKlMnOpQrStUvWx// Initiate payment (public)
curl -X POST https://api.getpaydeck.com/api/v1/paylinks/AbCdEfGhIjKlMnOpQrStUvWx/pay \
-H "Content-Type: application/json" \
-d '{
"providerCode": "wave_sn",
"phoneNumber": "771234567"
}'Create a Bulk Payment
Merchant APICreates a disbursement batch (salaries, refunds, commissions). The batch is first created in draft state, then executed manually.
Request body
labelstringrequisBatch name. Ex: March 2026 Payroll
providerCodestringrequisProvider used for all disbursements
itemsarrayrequisList of recipients
items[].phoneNumberstringrequisRecipient's phone number
items[].amountintegerrequisAmount in XOF
items[].namestringRecipient's name
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" }
]
}'// Response 201
{
"success": true,
"data": {
"id": 8,
"label": "Salaires Mars 2026",
"status": "draft",
"totalAmount": 470000,
"itemCount": 3,
"createdAt": "2026-03-31T09:00:00.000Z"
}
}Batch Status
Merchant APITo execute a batch, use POST /mass-payments/:id/execute.
| Status | Description |
|---|---|
| draft | Batch created but not yet launched |
| processing | Disbursements in progress |
| done | All disbursements completed (success or failure) |
Configure Webhooks
Merchant APIWebhooks allow Paydeck to notify your server in real-time on each transaction status change.
Request body
urlstringrequisHTTPS URL of your endpoint (must return 2xx)
eventsstring[]requisList of events to listen to (see below)
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"
]
}'// Response 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....", // ← Store immediately!
"isActive": true
}
}Delivery & retry schedule
Flux webhook
Transaction
confirmed
API Paydeck
Votre serveur
✓ delivered
Si pas de 200 → retry automatique :
Events
| Event | Triggered when |
|---|---|
| transaction.collect.success | An incoming payment is confirmed |
| transaction.collect.failed | An incoming payment is declined or expired |
| transaction.disburse.success | A disbursement is confirmed |
| transaction.disburse.failed | A disbursement has failed |
| transaction.refund.success | A refund is confirmed |
| transaction.refund.failed | A refund is rejected by the provider |
Verify Signature
Every webhook sent by Paydeck includes a Paydeck-Signature header. Verify it to ensure the request genuinely comes from Paydeck.
Signature format
Paydeck-Signature: t=1711879200,v1=a3f9b2c1d0e8f7...The signed payload is: {timestamp}.{body}. The signature is an HMAC-SHA256 computed with your webhook secret.
Verification in 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']
// Reject webhooks older than 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)
// Process the event...
res.sendStatus(200)
})Payload format
{
"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", // number ENTERED at creation: not proof of the payer
"payer_restricted": false, // true if restrictPayerToPhone was requested
"payer_phone_verified": null, // payer confirmed by the payment method (returnsVerifiedPayer), otherwise 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"
}
}History & Retry
Merchant APIPaydeck automatically retries failed webhooks on the schedule: 1min → 5min → 30min → 2h → 24h (5 max attempts).
// List delivery attempts
curl https://api.getpaydeck.com/api/v1/webhooks/3/events \
-H "Authorization: Bearer sk_live_VOTRE_CLE"
// Manually retry an event
curl -X POST https://api.getpaydeck.com/api/v1/webhooks/3/events/87/retry \
-H "Authorization: Bearer sk_live_VOTRE_CLE"Account Balance
Merchant APIReturns your account information, including your balance per 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" }
]
}
}Manage API Keys
JWT AuthThese endpoints require a JWT token (obtained via POST /auth/login), not a merchant API key.
Sandbox Mode
Test onlySandbox mode lets you test your integration without making real payments. Use your sk_test_... key to automatically activate test mode.
Sandbox behavior
- • An API collection (POST /payments/collect) starts in processing status: choose its result with POST /sandbox/simulate. In the payment window (widget / modal), the test payment is settled immediately: success, or failure with the number 700000000.
- • No real payment method is ever called
- • You choose the result: success or failed
- • Webhooks are triggered normally (test your endpoint)
- • The balance is not debited
- • The key decides the environment: sk_test_ and pk_test_ always simulate, even if your account is live. sk_live_ and pk_live_ are refused while the account is in test mode.
- • A key only sees transactions from its own environment: GET /payments/transactions and /payments/transactions/:ref never return the other mode.
- • Webhooks only receive events from their environment (mode field at creation).
- • Disbursement (POST /payments/disburse): a payout to 700000000 fails (status failed, transaction.disburse.failed webhook), so you can test your failure handling. Any other number succeeds immediately. For a collection, choose the outcome with POST /sandbox/simulate.
- • Live only (403 LIVE_MODE_REQUIRED): paylinks, QR codes, recurring payments, mass payments and collections, withdrawals, top-ups and invoices.
Simulate a Result
Test onlySimulates the result of an in-progress (processing) transaction. Triggers webhooks as if the payment had actually been confirmed or declined.
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"
}'// Response 200
{
"success": true,
"message": "Transaction pd_col_a1b2c3d4e5f6 simulated as success",
"data": {
"ref": "pd_col_a1b2c3d4e5f6",
"status": "success"
}
}Test Page
Test onlyEach collection in test mode generates a link to the Paydeck sandbox page. This page simulates a payment: choose the result, enter a dummy code, and it automatically calls /sandbox/simulate.
https://getpaydeck.com/sandbox/checkout/{ref}?t={sk_test_votre_cle}
// Parameters:
// - ref : internal transaction reference (pd_col_xxx)
// - t : your test key (optional — enables auto-simulation)JavaScript Widget
Web integrationEmbed a payment window directly on your site in a single line of code. The widget appears in an isolated iframe hosted on the Paydeck domain — payment data never transits through your server.
Architecture
How the widget works
Third-party site (your domain)
<script src="https://getpaydeck.com/paydeck.js"></script>
PayDeck.open({ pk: "pk_live_...", amount: 5000 })
getpaydeck.com/modal
- • Shows the payment methods enabled on your account
- • Collects payer information
- • Calls POST /api/v1/payments/collect
Your site
1 — Include the script
<!-- Place before </body> -->
<script src="https://getpaydeck.com/paydeck.js"></script>2 — Open the modal
PayDeck.open({
pk: "pk_live_YOUR_PUBLIC_KEY", // required
amount: 5000, // XOF, optional (free if omitted)
currency: "XOF", // default: XOF
description: "Order #2026-042", // displayed to payer
merchantName: "Your Store", // displayed in modal
// Free data returned in onSuccess and in the webhook
metadata: { orderId: "CMD-2026-042", userId: "USR-99" },
// Optional redirects (useful if your site cannot handle JS callbacks)
successUrl: "https://yoursite.com/thanks", // redirected after successful payment (?ref=...&status=success)
cancelUrl: "https://yoursite.com/cancel", // redirected if payer closes modal
onSuccess: function(data) {
// data = { ref: "pd_col_...", status: "success", metadata: { orderId, userId } }
console.log("Payment successful:", data.ref, "| Order:", data.metadata.orderId)
confirmOrder(data.metadata.orderId)
},
onClose: function() {
console.log("Modal closed")
},
onError: function(err) {
// err = { message: "...", data: { metadata: { orderId, userId } } }
console.error("Error:", err.message)
},
})Complete example — Buy button
<!DOCTYPE html>
<html>
<head><title>My Store</title></head>
<body>
<button onclick="pay('ARTICLE-007', 'USR-42')">Buy — 15,000 XOF</button>
<script src="https://getpaydeck.com/paydeck.js"></script>
<script>
function pay(articleId, userId) {
PayDeck.open({
pk: "pk_live_YOUR_PUBLIC_KEY",
amount: 15000,
description: "Premium design chair",
merchantName: "My Store",
// This data will be returned in onSuccess AND in the webhook
metadata: { articleId: articleId, userId: userId },
onSuccess: function(data) {
// data.metadata contains { articleId, userId }
alert("Thank you! Order " + data.metadata.articleId + " confirmed.")
},
onError: function(err) {
alert("Error: " + err.message)
},
})
}
</script>
</body>
</html>Displayed providers
The modal automatically displays the payment methods you have enabled in your account. No additional configuration required.
pk_test_...TestSandbox — no real payment, demo providerspk_live_...LiveProduction — providers enabled on your accountMerchant logo in the modal
The modal automatically displays your company logo at the top of the payment window. Configure it in Dashboard → Settings → Company Logo.
Technically, the logo is resolved via the GET /checkout/providers?pk=… endpoint which returns a merchant field:
{
"success": true,
"data": [ /* active providers */ ],
"merchant": {
"name": "My Store",
"logoUrl": "/uploads/merchants/merchant_1.png"
}
}PayDeck.open() parameters
pkstringrequisMerchant public key (pk_live_... or pk_test_...)
amountintegerAmount in XOF. If omitted, the payer enters the amount themselves.
currencystringCurrency — default: XOF
descriptionstringDescription displayed in the modal
merchantNamestringYour store/company name displayed at the top of the modal
metadataobjectFree data returned in onSuccess and in the webhook.
successUrlstringRedirect URL after successful payment. Receives ?ref=...&status=success as query string.
cancelUrlstringRedirect URL if the payer closes the modal without paying.
onSuccessfunctionCallback after successful payment. Receives { ref, status, metadata }. Triggered before successUrl.
onClosefunctionCallback when the payer closes the modal. Triggered before cancelUrl.
onErrorfunctionCalled on error. Receives { message, data: { metadata } }.
Official SDKs
Official SDKs are available for major languages. Each SDK handles authentication, serialization, errors and webhook verification. Zero external dependencies except Java (Jackson Databind).
Node.js Example
import Paydeck from '@paydeck/node';
const paydeck = new Paydeck('sk_live_YOUR_KEY');
// Collect a payment
const tx = await paydeck.collect({
amount: 5000,
providerCode: 'wave_sn',
phoneNumber: '771234567',
});
if (tx.paymentUrl) {
// Redirect client or display QR
}
// Verify a 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);
});Python Example
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)E-commerce Plugins
Ready-to-use plugins are available for major e-commerce platforms. Each plugin uses GET /payments/providers at runtime to automatically display available providers.
Webhook configuration
For each plugin, register the following webhook URL in your PayDeck dashboard:
https://your-site.com/?wc-api=paydeck_webhookhttps://your-site.com/module/paydeck/webhookhttps://your-site.com/modules/gateways/callback/paydeck.phpQuestions? Write to us at support@getpaydeck.com
Paydeck API v1.0 · Last updated: May 2026