Skip to content

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"
}
  • callbackUrl must be http(s) and resolve to a public address; private, loopback and link-local hosts are refused. Register the final URL: redirects are not followed.
  • callbackSecret is yours; if you omit it, Payard generates one and returns it in the answer. Store it.
  • merchantApplicationId defaults 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:

rawBody + X-Timestamp + X-Nonce + callbackSecret

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 2xx within 20 seconds. Anything else, including a 3xx, 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 eventId changes on every attempt. De-duplicate on type + 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.