API Reference v1.0

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.

⚠
Never share your secret key (sk_live_...). Store it only server-side, never in frontend or mobile code.
bash
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 payments
sk_live_...LiveProduction — real payments

Environments

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:

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

json
{
  "success": false,
  "message": "Insufficient balance",
  "errors": [         // only for validation errors
    { "field": "amount", "message": "Amount must be a positive integer" }
  ]
}
HTTP CodeMeaning
200OK — Request successful
201Created — Resource created
400Bad Request — Missing or invalid parameters
401Unauthorized — Missing or invalid API key
403Forbidden — Account not activated or blocked
404Not Found — Resource not found
422Unprocessable Entity — Validation error
429Too Many Requests — Rate limit exceeded
500Internal Server Error — Server-side error

Rate Limiting

Public payment endpoints are protected against abuse by an IP-based rate limiter.

EndpointLimitWindow
POST /checkout/pay100 requests1 minute
GET /checkout/providers200 requests1 minute
GET /checkout/status/:ref300 requests1 minute
Merchant API (sk_…)Unlimited—

When exceeded, the API returns HTTP 429 with the following headers:

http
HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0
✓
The Retry-After header indicates the number of seconds to wait before retrying.

Health Check

GET/api/v1/health

Public endpoint without authentication — checks that the server and database are operational. Useful for monitoring probes (uptime robot, load balancer, CI/CD).

json
// 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"
}
ℹ
uptime is expressed in seconds since the Node process started.

Available Providers

GET/api/v1/payments/providers

Returns the list of active payment providers and their capabilities. Use this endpoint to build your payment method selector.

json
// 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
    }
  ]
}
ℹ
Each payment method states what it can do: supportsPayerRestriction (it accepts the restrictPayerToPhone option) and returnsVerifiedPayer (payer_phone_verified will be filled in after a successful payment). Read these fields at runtime rather than assuming a behaviour for a given payment method: new methods are added without any change on your side.

Quick Reference — Current Providers

ℹ
This list reflects currently deployed providers. It may evolve — always call GET /payments/providers in real-time to get the exact list of active providers on your account.
CodeNameTypeCollectDisburseCountry
wave_snWave SénégalMobile Money✓✓SN
orange_money_snOrange Money SNMobile Money✓✓SN
cardPaiement par carteCarte✓—*

Quick Reference — Country Dial Codes

Used in the phoneCountryCode parameter during a collection or disbursement.

🇸🇳Senegal+221SN
🌍Other countries+XXX—depending on available providers

Collect a Payment

Merchant API
POST/api/v1/payments/collect

Initiates a collection (the customer pays you). Depending on the provider, the response includes a redirect paymentUrl or a direct synchronous result.

Request body

providerCodestringrequis

Provider code — see GET /payments/providers for the full list

amountintegerrequis

Amount in XOF (integer, no decimals). Ex: 5000

phoneNumberstringrequis

Payer's phone number. Ex: 771234567

phoneCountryCodestring

Country dial code. Ex: +221 (default: +221)

recipientNamestring

Payer's name

recipientEmailstring

Payer's email for the receipt

otpstring

Code required by some payment methods: see collectFields in GET /payments/providers

successUrlstring

Redirect URL after successful payment

cancelUrlstring

Redirect URL if the customer cancels

metadataobject

Free metadata returned in webhooks

restrictPayerToPhoneboolean

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

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
// 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.
⚠
In test mode nothing is checked against a real provider: the option is stored and echoed (payer_restricted) but payer_phone_verified stays null. Test your handling of a refused payment with a real small payment in production.
ℹ
In test mode, paymentUrl points to the Paydeck sandbox page. You can simulate the result with POST /sandbox/simulate.

Flow diagrams

Collect flow — Client redirect

Votre serveur

POST /collect

API Paydeck

paymentUrl

Client

page de paiement

← Webhook : transaction.collect.success / failed

Collect flow — Synchronous OTP (some providers)

1.

Customer

generates OTP

passes it to your app

Votre serveur

2.

Votre serveur

POST /collect + otp

API Paydeck

→ provider

Result

sync

3.← Synchronous response: success / failed

Payment sessions (secured amount)

Merchant API
POST/api/v1/payments/sessions

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

✓
Recommended for any payment that triggers a delivery or a payout. With the public key + amount widget, the amount is chosen in the browser and can be altered by the payer; with a session, that is impossible. In “API & Settings” you can make sessions mandatory for your account.

Request body

amountintegerrequis

Amount in XOF (integer), within the platform limits

currencystring

Currency (XOF, default)

descriptionstring

Text shown to the payer (255 characters at most)

metadataobject

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

expiresInMinutesinteger

Validity in minutes: 1 to 1440 (default 30)

restrictPayerToPhoneboolean

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

customerobject

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

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

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

javascript
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 one
SESSION_NOT_FOUND404Unknown session identifier
SESSION_AMOUNT_MISMATCH422Browser amount differs from the session's
SESSION_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 method
SESSION_KEY_MISMATCH403Public key of another merchant
SESSION_REQUIRED403Your account requires a session (“mandatory sessions” setting)
GET/api/v1/payments/sessions/:id

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 API
POST/api/v1/payments/disburse

Sends funds to a mobile money number (disbursement).

Request body

providerCodestringrequis

Provider code — see GET /payments/providers for the full list

amountintegerrequis

Amount in XOF to send

phoneNumberstringrequis

Recipient's mobile money number

phoneCountryCodestring

Country dial code. Ex: +221

recipientNamestring

Recipient's name

recipientEmailstring

Recipient email (optional): they get a notice once the transfer has succeeded

metadataobject

Free metadata

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

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" }'
  • 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 API
GET/api/v1/payments/transactions

Returns a paginated list of your transactions with optional filters.

Query parameters

pageinteger

Page number (default: 1)

limitinteger

Results per page, max 100 (default: 20)

statusstring

Filter by status: pending, processing, success, failed

operationstring

Filter by operation: collect, disburse

startDatestring

Start date ISO 8601. Ex: 2026-01-01

endDatestring

End date ISO 8601. Ex: 2026-03-31

searchstring

Search in the reference, number or recipient name

metadata[key]string

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

bash
# 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"
bash
curl "https://api.getpaydeck.com/api/v1/payments/transactions?status=success&limit=10" \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"
json
// 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 API
GET/api/v1/payments/transactions/:ref

Retrieves the full details of a transaction by its internal reference.

bash
curl https://api.getpaydeck.com/api/v1/payments/transactions/pd_col_a1b2c3d4e5f6 \
  -H "Authorization: Bearer sk_live_VOTRE_CLE"
StatusDescription
pendingInitiated, awaiting customer confirmation
processingBeing processed by the provider
successPayment confirmed and credited
failedPayment declined or expired

Transaction lifecycle

États possibles

pending

initiated

processing

in progress at the provider

confirmed

✓ success

declined / expired

✗ failed

Refund a collection

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

Fully 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

reasonstring

Refund reason (optional, kept in 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
// Response 200
{
  "success": true,
  "message": "Remboursement effectué avec succès",
  "data": {
    "ref": "PDK-20261110-5B21C9D0",
    "status": "success",
    "amount": 5000
  }
}
ℹ
The refund transaction has operation = refund and its parentTransactionId points to the original collection, whose status becomes refunded once the refund succeeds. If the provider definitively rejects the refund, your balance is restored and a transaction.refund.failed event is sent.

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.

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

Create a Bulk Payment

Merchant API
POST/api/v1/mass-payments

Creates a disbursement batch (salaries, refunds, commissions). The batch is first created in draft state, then executed manually.

Request body

labelstringrequis

Batch name. Ex: March 2026 Payroll

providerCodestringrequis

Provider used for all disbursements

itemsarrayrequis

List of recipients

items[].phoneNumberstringrequis

Recipient's phone number

items[].amountintegerrequis

Amount in XOF

items[].namestring

Recipient's name

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
// 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 API
GET/api/v1/mass-payments/:id

To execute a batch, use POST /mass-payments/:id/execute.

StatusDescription
draftBatch created but not yet launched
processingDisbursements in progress
doneAll disbursements completed (success or failure)

Configure Webhooks

Merchant API

Webhooks allow Paydeck to notify your server in real-time on each transaction status change.

POST/api/v1/webhooks

Request body

urlstringrequis

HTTPS URL of your endpoint (must return 2xx)

eventsstring[]requis

List of events to listen to (see below)

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"
    ]
  }'
⚠
The webhook secret is returned only once at creation. Store it immediately — it cannot be retrieved afterwards.
json
// 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

POST + HMAC-SHA256

Votre serveur

200 OK ?

✓ delivered

Si pas de 200 → retry automatique :

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

Events

EventTriggered when
transaction.collect.successAn incoming payment is confirmed
transaction.collect.failedAn incoming payment is declined or expired
transaction.disburse.successA disbursement is confirmed
transaction.disburse.failedA disbursement has failed
transaction.refund.successA refund is confirmed
transaction.refund.failedA refund is rejected by the provider
✓
For a refund, the webhook describes the refund itself: operation is "refund", ref is the refund reference and metadata.originalRef gives the reference of the refunded collection. The refunded amount is the collection amount, without the fees (not refunded).

Verify Signature

Every webhook sent by Paydeck includes a Paydeck-Signature header. Verify it to ensure the request genuinely comes from Paydeck.

Signature format

text
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

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

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

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",         // 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"
  }
}
✓
The metadata field contains exactly the free data you passed when creating the transaction. Use it to find the order ID, user, or any other business context.
⚠
phone_number is the number entered when the payment was created, not proof of who paid. payer_phone_verified is the payer confirmed by the payment method, when it reports it (returnsVerifiedPayer in GET /payments/providers); null means “not reported”, not “different”.

History & Retry

Merchant API

Paydeck automatically retries failed webhooks on the schedule: 1min → 5min → 30min → 2h → 24h (5 max attempts).

GET/api/v1/webhooks/:id/events
POST/api/v1/webhooks/:webhookId/events/:eventId/retry
bash
// 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 API
GET/api/v1/auth/me

Returns your account information, including your balance per 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" }
    ]
  }
}

Manage API Keys

JWT Auth

These endpoints require a JWT token (obtained via POST /auth/login), not a merchant API key.

GET/api/v1/auth/api-keys
POST/api/v1/auth/api-keys/rotate
✓
Rotation generates a new key and immediately invalidates the old one. Update your server configuration before rotating.

Sandbox Mode

Test only

Sandbox mode lets you test your integration without making real payments. Use your sk_test_... key to automatically activate test mode.

ℹ
In test mode, an API collection returns a paymentUrl to the Paydeck test page instead of the payment method’s own page.

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 only
POST/api/v1/sandbox/simulate

Simulates the result of an in-progress (processing) transaction. Triggers webhooks as if the payment had actually been confirmed or declined.

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
// Response 200
{
  "success": true,
  "message": "Transaction pd_col_a1b2c3d4e5f6 simulated as success",
  "data": {
    "ref": "pd_col_a1b2c3d4e5f6",
    "status": "success"
  }
}
✓
You can also simulate directly from the sandbox checkout page by passing ?t=sk_test_... in the URL.

Test Page

Test only

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

text
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)
ℹ
The ?t= parameter is optional. Without it, the page displays the result visually but does not call the API.

JavaScript Widget

Web integration

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

ℹ
The widget uses your public key (pk_live_... or pk_test_...), visible in API & Settings → API Keys. No backend required.

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

isolated iframe

getpaydeck.com/modal

  • • Shows the payment methods enabled on your account
  • • Collects payer information
  • • Calls POST /api/v1/payments/collect
postMessage → onSuccess(data) / onError(msg)

Your site

✓
The metadata passed to PayDeck.open() is copied into the transaction: you get it back in GET /payments/transactions/:ref and in the transaction.collect.* webhooks. Limits: 20 keys at most, 2 KB, simple values (text up to 500 characters, number, boolean). The keys source, demoshop, massPaymentId, withdrawalId, withdrawalRequestId, rechargeRequestId, bulkCollectItemId, refundRef, originalRef, paydeck_ref and those starting with __ are reserved for Paydeck and ignored.
⚠
onSuccess(data) is a signal for your interface, not proof of payment: data contains ref, status and the metadata you passed (returned as-is by the browser). Before delivering goods or confirming an order, always verify the payment server-side with your secret key (GET /payments/transactions/:ref) or through the signed webhook. To make sure the payer cannot change the amount, use a payment session (“Payment sessions” section).

1 — Include the script

html
<!-- Place before </body> -->
<script src="https://getpaydeck.com/paydeck.js"></script>

2 — Open the modal

javascript
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

html
<!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 providers
pk_live_...LiveProduction — providers enabled on your account

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

json
{
  "success": true,
  "data": [ /* active providers */ ],
  "merchant": {
    "name": "My Store",
    "logoUrl": "/uploads/merchants/merchant_1.png"
  }
}
✓
If no logo is configured, the modal displays the initial of your company name in an automatically generated avatar.

PayDeck.open() parameters

pkstringrequis

Merchant public key (pk_live_... or pk_test_...)

amountinteger

Amount in XOF. If omitted, the payer enters the amount themselves.

currencystring

Currency — default: XOF

descriptionstring

Description displayed in the modal

merchantNamestring

Your store/company name displayed at the top of the modal

metadataobject

Free data returned in onSuccess and in the webhook.

successUrlstring

Redirect URL after successful payment. Receives ?ref=...&status=success as query string.

cancelUrlstring

Redirect URL if the payer closes the modal without paying.

onSuccessfunction

Callback after successful payment. Receives { ref, status, metadata }. Triggered before successUrl.

onClosefunction

Callback when the payer closes the modal. Triggered before cancelUrl.

onErrorfunction

Called on error. Receives { message, data: { metadata } }.

ℹ
Real-time status: the modal automatically checks the transaction status every 3 seconds after payment initiation. successUrl vs onSuccess: both can coexist. Prefer onSuccess for SPAs, successUrl for multi-page sites.
⚠
Always use your public key (pk_...) client-side — never your secret key (sk_...).

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 / TypeScriptnpm
npm install @paydeck/nodeDownload .zip
PythonPyPI
pip install paydeckDownload .zip
PHPPackagist
composer require paydeck/paydeck-phpDownload .zip
RubyRubyGems
gem install paydeckDownload .zip
.NET / C#NuGet
dotnet add package PaydeckDownload .zip
JavaMaven
com.paydeck:paydeck-java:1.0.0Download .zip
iOS / SwiftSPM
Swift Package Manager (SPM)Download .zip
Android / KotlinGradle
Kotlin + Gradle (API 21+)Download .zip

Node.js Example

javascript
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

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)

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.

PlateformeVersion min.Download
WooCommerceWC 7+ / WP 6+.zip
PrestaShopPS 8.0+.zip
WHMCSWHMCS 8.0+.zip
✓
ZIP archives contain the complete plugin with the PHP SDK integrated. No other dependencies required.

Webhook configuration

For each plugin, register the following webhook URL in your PayDeck dashboard:

WooCommercehttps://your-site.com/?wc-api=paydeck_webhook
PrestaShophttps://your-site.com/module/paydeck/webhook
WHMCShttps://your-site.com/modules/gateways/callback/paydeck.php

Questions? Write to us at support@getpaydeck.com

Paydeck API v1.0 · Last updated: May 2026