Webhooks¶
Payard notifies your URL with a signed POST when a transaction, payout or refund moves. Treat each webhook as a trigger: verify it, answer 2xx fast, then re-read the entity through the API and act on what you read.
Register a webhook¶
One registration binds one event type to one URL for one merchant application. To receive several types, create one registration per type; they may share a URL. Needs a CLIENT_ACCESS key or higher.
POST /merchant-callback/create
{
"callbackType": "PAYOUT_STATUS_CHANGED",
"callbackUrl": "https://merchant.example.com/webhooks/payard",
"callbackSecret": "q8Vt3xZ1mK9pL2sR7wYb"
}
callbackUrlmust behttp(s)and resolve to a public address; private, loopback and link-local hosts are refused. Register the final URL: redirects are not followed.callbackSecretis yours; if you omit it, Payard generates one and returns it in the answer. Store it.merchantApplicationIddefaults to the application of the calling key.
Manage registrations with POST /merchant-callback/get-all, PATCH /merchant-callback/:id (a PATCH without callbackSecret keeps the secret; set disabledAt to disable, null to re-enable) and DELETE /merchant-callback/:id. Avoid duplicate registrations for the same type: each one receives its own copy of every event.
Events to subscribe to¶
| Event | When | Key fields in data |
|---|---|---|
TRANSACTION_STATUS_CHANGED |
A processing step of a transaction was handled | internalTransactionId, internalTransactionCode, reference, stage, status, paymentProviderId, paymentSystemId, paymentMethod |
TRANSACTION_CREATED, TRANSACTION_CHANGED |
A transaction was created / any update of it | transaction (the full record) |
CASCADE_NEW_PAYMENT_PROVIDER_ASSIGNED |
A failed transaction moved to the next provider | transaction and provider ids |
PAYOUT_STATUS_CHANGED |
A processing step of a payout was handled | internalPayoutId, internalPayoutCode, reference, stage (= payout status), status (= status reason), paymentProviderId, paymentSystemId |
REFUND_STATUS_CHANGED |
A refund step was handled (some providers only, see Refunds) | refundOperationId, refundedPaymentOrderId, transactionId, refundedAmount, stage (= refund status), status (= status reason) |
A typical integration subscribes to TRANSACTION_STATUS_CHANGED and PAYOUT_STATUS_CHANGED. Subscribe only to the event types listed above.
Delivery¶
POST https://merchant.example.com/webhooks/payard
content-type: application/json
signature: k3N9...Q==
X-Timestamp: 1763285004512
X-Nonce: 3b1f0c6e-8a2d-4c7e-b0f9-6a5d2e4c1b7a
{
"eventId": "0a7b3e5c-1d2f-4a6b-9c8e-7f0d1b2a3c4d",
"type": "PAYOUT_STATUS_CHANGED",
"data": {
"providerId": "7d2e4b1a-5c3f-4e8d-9a6b-2f1c0e7d8a94",
"paymentProviderId": "T365",
"paymentSystemId": "PAY_ID",
"internalPayoutId": "6c3d8e1f-9a2b-4e5c-8d7f-1b0a3c6e9f52",
"internalPayoutCode": "POUT7K3M9Q2XBD",
"originalPayoutId": null,
"payoutCreatedAt": "2026-11-16T09:20:03.114Z",
"reference": "INV-2026-0412",
"stage": "IN_PROGRESS",
"status": null,
"callbackCreatedAt": "2026-11-16T09:20:05.001Z"
}
}
stage and status are the values the entity holds after the step that raised the event. A later event, or a read, may already show a newer state.
Verify the signature¶
Payard signs with its RSA private key, RSA-SHA256 (PKCS#1 v1.5), base64, over:
Use the raw body bytes as received, never re-serialised JSON, and no separators. Verify with Payard's public key (PEM), which Payard sends you for each environment during onboarding.
// Node.js / Express
app.post('/webhooks/payard', express.raw({ type: 'application/json' }), (req, res) => {
const ts = req.get('X-Timestamp'), nonce = req.get('X-Nonce'), sig = req.get('signature');
if (!ts || !nonce || !sig) return res.status(401).end();
const signed = Buffer.concat([req.body, Buffer.from(ts), Buffer.from(nonce), Buffer.from(CALLBACK_SECRET)]);
const ok = crypto.verify('RSA-SHA256', signed, PAYARD_PUBLIC_KEY, Buffer.from(sig, 'base64'));
if (!ok || Math.abs(Date.now() - Number(ts)) > 5 * 60 * 1000) return res.status(401).end();
enqueue(JSON.parse(req.body.toString('utf8'))); // process asynchronously
res.status(200).end(); // acknowledge fast
});
# Python (cryptography)
signed = raw_body + ts.encode() + nonce.encode() + CALLBACK_SECRET.encode()
PUBLIC_KEY.verify(base64.b64decode(sig), signed, padding.PKCS1v15(), hashes.SHA256())
Reject attempts whose X-Timestamp is more than about 5 minutes off (it is fresh on every retry), and remember seen X-Nonce values for that window.
Retries, order and duplicates¶
- Success is any
2xxwithin 20 seconds. Anything else, including a3xx, a timeout or a TLS error, is a failure. - Retries follow a fixed schedule: 1 min, 5 min, 15 min, 30 min, 1 h, 3 h, then 6 h four times. After the 11th failure (about 29 hours after the first attempt) the event is dropped. There is no resend API.
- Order is not guaranteed. Never derive state from the order of webhooks.
- Duplicates happen, and
eventIdchanges on every attempt. De-duplicate ontype+ entity id +data.callbackCreatedAt, and make processing idempotent. - Answer non-2xx only when you want a retry. For an event you can never process, log it and answer
200.
Test a webhook¶
POST /merchant-callback/test with { "merchantCallbackId": "<registration id>" } sends one signed sample event of that registration's type, with "test": true in the envelope and in data. { "success": true } means your endpoint answered 2xx within 20 seconds. Make your handler acknowledge test deliveries and never act on them.