Notifications
Signed notifications about payments, refunds and payouts: the environment address or an address in the request, the secret, checking the signature, the body and the delivery order.
When a payment, a refund or a payout changes, a notification arrives at the merchant's address: a POST with a JSON body and a signature. A notification is a reason to read the object, not a replacement for reading: the state in the read response wins.
Address and secret
- Notifications are signed with the environment secret of the form
whsec_…: there is one per environment, and it is shown once. Keep it on the server, next to the API key. - The environment address, if you need one, is one per environment. A Paydex administrator sets it up at your request, or you do it yourself in the merchant cabinet: https with a host name open to the internet and the default port, 443, 8443, 80 or 8080; the test environment also allows http. Internal addresses are not accepted. The secret is issued together with the address.
- You can also send the address in every request: Address in the request. Then the environment address is optional, and the secret is issued with an API key.
- After a secret rotation, the previous secret keeps signing alongside the new one for one more day: the header carries two signatures, and either one passes the check. Change the secret on your side within that day.
Address in the request
Like Corefy's callback_url: the callbackUrl field in the body of POST /api/v1/payments, POST /api/v1/payments/:id/refunds and POST /api/v1/payouts. Notifications about that payment, refund or payout go to it instead of the environment address. The create and read responses return callbackUrl; the notification body does not carry it.
- The requirements are those of the environment address: https up to 2048 characters, http also allowed in the test environment; a full internet host name (not
localhost, not a name without a dot, not.local,.internal,.lan,.localdomain,.home.arpa), the default port, 443, 8443, 80 or 8080; without a user name or password, without a fragment. Otherwise a 400 refusal with the rulecallback_url_invalid,callback_url_schemeorcallback_url_internal. - The host name is checked on every delivery: if it leads to an internal, private, loopback or link-local network, the notification is not sent.
- The address is set at creation and never changes afterwards: all of the object's notifications go to it.
- The signature is the same: the environment secret. If the environment has no secret, creating with
callbackUrlis refused with 409callback_secret_missing; for a refund and a payout this refusal takes the retry key, so repeat with a new key. - The address is part of the request body for the retry key: a retry with the same key and a different address gets 409
idempotency_key_reused, as with any other changed field. - If an administrator has turned off the environment's notifications, nothing goes to the address in the request either, and creation still succeeds.
A secret without an administrator
If there is no environment address, the secret is issued with an API key, once:
curl -X POST https://api.paydex.co.uk/notifications/secret -H "Authorization: Bearer $PAYDEX_API_KEY"The 201 response with the secret field comes once. A repeated call answers 409 notify_secret_exists: the secret already exists and is not shown again. A lost secret is changed in the merchant cabinet (the Notifications page, with a code from the authenticator app) or by an administrator; an API key cannot change it, so that a leaked key does not let anyone sign notifications. The endpoint in the reference: Issue the secret.
Signature
The signature follows the Standard Webhooks specification, so a ready-made library for it works too.
| Header | What it holds |
|---|---|
webhook-id | The event ID, the same as id in the body |
webhook-timestamp | When this attempt was sent, Unix seconds |
webhook-signature | v1, and the signature in base64; during a secret rotation two of them, separated by a space |
The signature is HMAC-SHA-256 of the string <webhook-id>.<webhook-timestamp>.<body>, where the body is taken exactly as it arrived, and the key is the base64 after whsec_. Reject a request without a signature, with a foreign signature or with a timestamp older than five minutes.
import { createHmac, timingSafeEqual } from 'node:crypto';
// secret: whsec_...; headers: request headers in lower case; body: the raw request body as received.
export function verifyWebhook(secret, headers, body, toleranceSeconds = 300, nowSeconds = Math.floor(Date.now() / 1000)) {
const id = headers['webhook-id'];
const timestamp = headers['webhook-timestamp'];
const signatures = headers['webhook-signature'];
if (!id || !timestamp || !signatures) return false;
const sent = Number(timestamp);
if (!Number.isInteger(sent) || Math.abs(nowSeconds - sent) > toleranceSeconds) return false;
const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(`${id}.${timestamp}.${body}`).digest();
return signatures.split(' ').some((part) => {
const [version, value] = part.split(',');
if (version !== 'v1' || !value) return false;
const given = Buffer.from(value, 'base64');
return given.length === expected.length && timingSafeEqual(given, expected);
});
}Events
payment.updated: one of the fields of the notification body has changed, for example the status, the reason, the review or the paid amount. The first notification about a payment arrives about a minute after creation, earlier if the payment changed in that time.refund.updated: the refund went through, did not go through or went under review.payout.updated: one of the fields of the notification body has changed, for example the status, the reason, the moderation decision or the review. The first notification about a payout arrives about a minute after creation, sooner if the payout changed in that time (for example, you cancelled it). If the address was enabled after the payout was created, the first notification comes when the payout changes.
payment.updated body
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Event ID. The same on every delivery retry: use it to recognise a retry. |
type | stringpayment.updated | always | Event type: payment.updated. |
createdAt | string | always | When the event was recorded, in UTC. |
sequence | integer | always | Event number of this object: grows by one with each event. Delivery order is not guaranteed, compare by it. |
payment | object | always | The payment as reading returns it, without action, pageUrl, customer, metadata, returnUrl, callbackUrl and refundedMinor. |
payment.id | string | always | Payment ID: pr_ followed by 22 characters. Use it to read the payment. |
payment.reference | string | always | The order number sent at creation. |
payment.service | stringor null | always | Code of the service the payment was created with. |
payment.environment | stringTEST LIVE | always | The payment's environment: the environment of the key that created it. |
payment.status | stringCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTED | always | Payment status: Payment statuses. |
payment.reason | stringor null | always | Reason for the status as a code; null when there is nothing to name: Reasons. |
payment.inReview | boolean | always | The outcome is still being settled on our side: by a provider inquiry or by a person. While it is true, the payment is not credited. |
payment.amountMinor | string | always | The requested amount as a string, in minor units of the payment currency. |
payment.currency | string | always | Payment currency: the service currency. |
payment.network | stringor null | always | Network, if the currency has several. null: no network. |
payment.paidMinor | stringor null | always | The amount confirmed by the provider, in minor units of the payment currency. This is the amount you credit, and only with SUCCEEDED. null: no money confirmed. |
payment.feeMinor | stringor null | always | The merchant's fee for the payment, in minor units of the payment currency, calculated at creation. |
payment.createdAt | string | always | When the payment was created, in UTC. |
payment.expiresAt | stringor null | always | Payment deadline, in UTC: Payment deadline. |
payment.finalizedAt | stringor null | always | When the payment got a final status, in UTC. null: not yet. |
{
"id": "evt_8k3m2q7w9x4t6v5n2b8c4d_3",
"type": "payment.updated",
"createdAt": "2026-11-13T09:17:40.598Z",
"sequence": 3,
"payment": {
"id": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "order-1001",
"service": "pix_brl_redirect",
"environment": "TEST",
"status": "SUCCEEDED",
"reason": null,
"inReview": false,
"amountMinor": "1250",
"currency": "BRL",
"network": null,
"paidMinor": "1250",
"feeMinor": "24",
"createdAt": "2026-11-13T09:15:02.481Z",
"expiresAt": "2026-11-13T09:45:02.481Z",
"finalizedAt": "2026-11-13T09:17:40.112Z"
}
}refund.updated body
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Event ID. The same on every delivery retry: use it to recognise a retry. |
type | stringrefund.updated | always | Event type: refund.updated. |
createdAt | string | always | When the event was recorded, in UTC. |
sequence | integer | always | Event number of this object: grows by one with each event. Delivery order is not guaranteed, compare by it. |
refund | object | always | The refund as reading returns it, without description, metadata and callbackUrl. |
refund.id | string | always | Refund ID: rf_ followed by 22 characters. |
refund.payment | string | always | ID of the payment whose money is returned. |
refund.reference | string | always | The refund number sent at creation. |
refund.environment | stringTEST LIVE | always | The refund's environment: the payment's environment. |
refund.status | stringPENDING SUCCEEDED FAILED | always | PENDING the refund is in progress or its outcome is unknown, SUCCEEDED the money went out, FAILED there was no refund. Read an unknown status as PENDING. |
refund.reason | stringor nullrefund_declined technical_failure operator_declined | always | Reason for a failure: refund_declined the provider declined, technical_failure a technical failure, operator_declined an employee declined. null for other statuses. |
refund.inReview | boolean | always | The refund outcome is in question. With PENDING a provider inquiry or an employee decision names it, or a manual correction if the provider returned a different amount; with FAILED and SUCCEEDED this is a late disputed answer from the provider, and it is not lifted by itself. While it is true, do not return the same money. |
refund.amountMinor | string | always | The refund amount in minor units of the payment currency. |
refund.currency | string | always | Refund currency: the payment currency. |
refund.feeMinor | string | always | The refund fee in minor units of the payment currency, on top of the refund amount. |
refund.providerRefundId | stringor null | always | The provider's refund operation number, if it named one: quote it to the payer's bank. |
refund.createdAt | string | always | When the refund was created, in UTC. |
refund.finalizedAt | stringor null | always | When the refund got its outcome, in UTC. null: not yet. |
{
"id": "evt_rf_5n7q2w8x4k3m9t6v2b8c4d_1",
"type": "refund.updated",
"createdAt": "2026-11-14T10:03:12.871Z",
"sequence": 1,
"refund": {
"id": "rf_5n7q2w8x4k3m9t6v2b8c4d",
"payment": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "refund-1001-1",
"environment": "TEST",
"status": "SUCCEEDED",
"reason": null,
"inReview": false,
"amountMinor": "500",
"currency": "BRL",
"feeMinor": "0",
"providerRefundId": "RF-88213",
"createdAt": "2026-11-14T10:02:11.904Z",
"finalizedAt": "2026-11-14T10:03:12.550Z"
}
}payout.updated body
| Field | Type | Present | Description |
|---|---|---|---|
id | string | always | Event ID. The same on every delivery retry: use it to recognise a retry. |
type | stringpayout.updated | always | Event type: payout.updated. |
createdAt | string | always | When the event was recorded, in UTC. |
sequence | integer | always | Event number of this object: grows by one with each event. Delivery order is not guaranteed, compare by it. |
payout | object | always | The payout as reading returns it, without metadata and callbackUrl. |
payout.id | string | always | Payout ID: po_ followed by 22 characters. Use it to read and cancel the payout. |
payout.reference | string | always | The withdrawal number sent at creation. |
payout.service | string | always | The service code the payout was created with. |
payout.environment | stringTEST LIVE | always | The payout's environment: the environment of the key it was created with. |
payout.status | stringCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLED | always | CREATED created and waiting for a decision or sending, PROCESSING sent, SUCCEEDED the money went out, FAILED it did not, REJECTED rejected, CANCELLED cancelled before sending. Read an unknown status as PROCESSING. |
payout.reason | stringor nullcustomer_blocked rejected_by_operator cancelled_by_merchant | always | Why it closed: customer_blocked the customer or requisite is blocked, rejected_by_operator an employee rejected it, cancelled_by_merchant you cancelled it. null otherwise. |
payout.approval | stringPENDING APPROVED REJECTED WITHDRAWN | always | Moderation decision: APPROVED approved, PENDING waiting for an employee, REJECTED rejected, WITHDRAWN withdrawn by your cancellation. |
payout.inReview | boolean | always | The payout outcome is being decided on our side. While it is true, do not return the balance to the player and do not count the payout as done. |
payout.amountMinor | string | always | What the player receives, in minor units of the payout currency. |
payout.currency | string | always | Payout currency: the service currency. |
payout.feeMinor | string | always | The payout fee in minor units of the payout currency, on top of the amount. |
payout.createdAt | string | always | When the payout was created, in UTC. |
payout.finalizedAt | stringor null | always | When the payout closed, in UTC. null: not yet. |
{
"id": "evt_po_3m8q2w7k9x4t6v5n2b8c4d_2",
"type": "payout.updated",
"createdAt": "2026-11-17T09:43:52.041Z",
"sequence": 2,
"payout": {
"id": "po_3m8q2w7k9x4t6v5n2b8c4d",
"reference": "withdrawal-2001",
"service": "payout_pix_brl_direct",
"environment": "TEST",
"status": "CANCELLED",
"reason": "cancelled_by_merchant",
"approval": "APPROVED",
"inReview": false,
"amountMinor": "15000",
"currency": "BRL",
"feeMinor": "250",
"createdAt": "2026-11-17T09:41:07.312Z",
"finalizedAt": "2026-11-17T09:43:52.018Z"
}
}Delivery
- A 2xx response within 10 seconds counts as delivered; the connection must be established within 5. Redirects are not followed.
- One merchant's notifications go out one at a time: while a delivery to a slow address is in progress, the merchant's other notifications wait their turn.
- Otherwise the notification is sent again: after 5 seconds, then twice as rarely each time, but no less often than once an hour. 30 attempts in all, about 20 hours; after them delivery stops.
- If the payment, refund or payout has a newer event, the old one is no longer sent.
- The delivery order is not guaranteed, and repeats are possible. Recognize a repeat by
idand the order bysequence. - Paydex staff see the delivery log: if notifications do not arrive, give them the payment or payout ID.
Rules for the merchant's code
- Check the signature and the timestamp before parsing the body.
- Store the event on your side and answer 2xx; do the processing after the response. After a 2xx the event does not come again. Also answer 2xx to an event of a type you do not process: otherwise it is sent 30 times.
- Process an event so that a repeat with the same
idchanges nothing, and skip an event whosesequenceis lower than one already processed. - Read the payment before crediting: When to credit. Read the payout before returning the balance to the player: Payout statuses.
- Read unfinished and expired payments, unfinished refunds and payouts yourself as well: what is not delivered in 30 attempts is never resent, and while the address is disabled no events are recorded.