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 rule callback_url_invalid, callback_url_scheme or callback_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 callbackUrl is refused with 409 callback_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.

HeaderWhat it holds
webhook-idThe event ID, the same as id in the body
webhook-timestampWhen this attempt was sent, Unix seconds
webhook-signaturev1, 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.

verify-webhook.mjs
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

FieldTypePresentDescription
idstringalwaysEvent ID. The same on every delivery retry: use it to recognise a retry.
typestringpayment.updatedalwaysEvent type: payment.updated.
createdAtstringalwaysWhen the event was recorded, in UTC.
sequenceintegeralwaysEvent number of this object: grows by one with each event. Delivery order is not guaranteed, compare by it.
paymentobjectalwaysThe payment as reading returns it, without action, pageUrl, customer, metadata, returnUrl, callbackUrl and refundedMinor.
payment.idstringalwaysPayment ID: pr_ followed by 22 characters. Use it to read the payment.
payment.referencestringalwaysThe order number sent at creation.
payment.servicestringor nullalwaysCode of the service the payment was created with.
payment.environmentstringTEST LIVEalwaysThe payment's environment: the environment of the key that created it.
payment.statusstringCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTEDalwaysPayment status: Payment statuses.
payment.reasonstringor nullalwaysReason for the status as a code; null when there is nothing to name: Reasons.
payment.inReviewbooleanalwaysThe 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.amountMinorstringalwaysThe requested amount as a string, in minor units of the payment currency.
payment.currencystringalwaysPayment currency: the service currency.
payment.networkstringor nullalwaysNetwork, if the currency has several. null: no network.
payment.paidMinorstringor nullalwaysThe 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.feeMinorstringor nullalwaysThe merchant's fee for the payment, in minor units of the payment currency, calculated at creation.
payment.createdAtstringalwaysWhen the payment was created, in UTC.
payment.expiresAtstringor nullalwaysPayment deadline, in UTC: Payment deadline.
payment.finalizedAtstringor nullalwaysWhen the payment got a final status, in UTC. null: not yet.
Example response. The values are made up.
{
  "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

FieldTypePresentDescription
idstringalwaysEvent ID. The same on every delivery retry: use it to recognise a retry.
typestringrefund.updatedalwaysEvent type: refund.updated.
createdAtstringalwaysWhen the event was recorded, in UTC.
sequenceintegeralwaysEvent number of this object: grows by one with each event. Delivery order is not guaranteed, compare by it.
refundobjectalwaysThe refund as reading returns it, without description, metadata and callbackUrl.
refund.idstringalwaysRefund ID: rf_ followed by 22 characters.
refund.paymentstringalwaysID of the payment whose money is returned.
refund.referencestringalwaysThe refund number sent at creation.
refund.environmentstringTEST LIVEalwaysThe refund's environment: the payment's environment.
refund.statusstringPENDING SUCCEEDED FAILEDalwaysPENDING 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.reasonstringor nullrefund_declined technical_failure operator_declinedalwaysReason for a failure: refund_declined the provider declined, technical_failure a technical failure, operator_declined an employee declined. null for other statuses.
refund.inReviewbooleanalwaysThe 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.amountMinorstringalwaysThe refund amount in minor units of the payment currency.
refund.currencystringalwaysRefund currency: the payment currency.
refund.feeMinorstringalwaysThe refund fee in minor units of the payment currency, on top of the refund amount.
refund.providerRefundIdstringor nullalwaysThe provider's refund operation number, if it named one: quote it to the payer's bank.
refund.createdAtstringalwaysWhen the refund was created, in UTC.
refund.finalizedAtstringor nullalwaysWhen the refund got its outcome, in UTC. null: not yet.
Example response. The values are made up.
{
  "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

FieldTypePresentDescription
idstringalwaysEvent ID. The same on every delivery retry: use it to recognise a retry.
typestringpayout.updatedalwaysEvent type: payout.updated.
createdAtstringalwaysWhen the event was recorded, in UTC.
sequenceintegeralwaysEvent number of this object: grows by one with each event. Delivery order is not guaranteed, compare by it.
payoutobjectalwaysThe payout as reading returns it, without metadata and callbackUrl.
payout.idstringalwaysPayout ID: po_ followed by 22 characters. Use it to read and cancel the payout.
payout.referencestringalwaysThe withdrawal number sent at creation.
payout.servicestringalwaysThe service code the payout was created with.
payout.environmentstringTEST LIVEalwaysThe payout's environment: the environment of the key it was created with.
payout.statusstringCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLEDalwaysCREATED 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.reasonstringor nullcustomer_blocked rejected_by_operator cancelled_by_merchantalwaysWhy 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.approvalstringPENDING APPROVED REJECTED WITHDRAWNalwaysModeration decision: APPROVED approved, PENDING waiting for an employee, REJECTED rejected, WITHDRAWN withdrawn by your cancellation.
payout.inReviewbooleanalwaysThe 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.amountMinorstringalwaysWhat the player receives, in minor units of the payout currency.
payout.currencystringalwaysPayout currency: the service currency.
payout.feeMinorstringalwaysThe payout fee in minor units of the payout currency, on top of the amount.
payout.createdAtstringalwaysWhen the payout was created, in UTC.
payout.finalizedAtstringor nullalwaysWhen the payout closed, in UTC. null: not yet.
Example response. The values are made up.
{
  "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 id and the order by sequence.
  • Paydex staff see the delivery log: if notifications do not arrive, give them the payment or payout ID.

Rules for the merchant's code

  1. Check the signature and the timestamp before parsing the body.
  2. 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.
  3. Process an event so that a repeat with the same id changes nothing, and skip an event whose sequence is lower than one already processed.
  4. Read the payment before crediting: When to credit. Read the payout before returning the balance to the player: Payout statuses.
  5. 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.

API v1 · built 2026-11-18 · release f13e6bf

The API reference is built from the server code: it never describes an endpoint that does not exist.