Transfer webhook

This page describes the webhook payload sent by the platform whenever a PIX transfer (withdrawal) status is updated.

Description

The transfer webhook is automatically sent whenever the withdrawal status changes, allowing the integrator system to track the entire transfer lifecycle from creation to completion or failure.

Notifications are sent via HTTP requests using the POST method and JSON format.

Timezone Standard

All date and time fields sent in webhooks use the standard ISO 8601 in the timezone UTC (UTC+00:00), ensuring consistency regardless of the integrator's timezone. To avoid discrepancies caused by local time or daylight saving time, it is recommended to keep values in UTC for storage and processing, converting to the local timezone only at the presentation layer.

Optional Webhook Validation

To increase security, webhooks registered directly in the dashboard may include a signature sent in the header X-Signature: <base64-signature>, allowing validation of the authenticity of the received notification. This signature is generated by the platform using HMAC with SHA-256 over the webhook body, in JSON format, using a shared secret WEBHOOK_SECRET and encoded in Base64. The integrator can reproduce the same calculation in their system using the same secret and the received payload. If the generated signature matches the one sent in the header, the webhook is considered legitimate and intact. If they differ, the request may have been altered or not sent by the platform.

This validation is available only for webhooks registered in the dashboard. Webhooks sent to a URL provided dynamically through notificationUrl do not include the X-Signature.

Signature validation is optional, but strongly recommended whenever the webhook is configured through the dashboard to ensure greater communication security.

Notification Endpoint

If provided, the webhook will be sent to the URL configured in the notificationUrl field.

The endpoint must be publicly accessible and respond with HTTP 200 to confirm receipt.

Additionally, transfer notifications may also occur through in-bound webhooks, configured directly in the gateway dashboard. In this model, the endpoint is pre-registered and automatically triggered on every transfer status change.

Transfer Status

Possible values for the status field are:

• IN_QUEUE – Transfer created and waiting for processing.
• IN_ANALYSIS – Transfer under analysis.
• APPROVED – Transfer approved (not paid).
• PROCESSING – Transfer being processed.
• COMPLETED – Transfer successfully completed (paid).
• REFUSED – Transfer refused.
• FAILED – Transfer processing failed.

PIX Data

The destination PIX key information is available in the data object:

• pixKey – PIX key used for the transfer.
• pixKeyType – PIX key type (CPF, CNPJ, EMAIL, PHONE, EVP, COPYPASTE).

Payload Format

Below is an example of the webhook payload sent for a PIX transfer.

{
  "id": "pay_test_8f3k2m9xq7a1b4c6",
  "amount": 5000,
  "method": "PIX",
  "currency": "BRL",
  "status": "IN_QUEUE",
  "message": "",
  "externalRef": "order_test_1234",
  "notificationUrl": "https://example-webhook.test/notifications",
  "approvedAt": null,
  "refusedAt": null,
  "cancelledAt": null,
  "paidAt": null,
  "createdAt": "2026-01-19T17:17:34.295Z",
  "updatedAt": "2026-01-19T17:17:34.295Z",
  "data": {
    "method": "PIX",
    "pixKey": "pix_test_123e4567-e89b-12d3-a456-426614174000",
    "pixKeyType": "EVP",
    "e2e": null
  }
}