Webhooks

Pix Processamento's webhook system sends real-time notifications about status changes for your transactions. When you create a transaction and provide a callbackUrl, our system sends updates to that URL every time the status changes.

What is a webhook (callback)

A webhook (also called a callback) is a POST request that Pix Processamento sends to your server when something happens. Unlike the regular API (where you call Pix Processamento), here it's the opposite: Pix Processamento calls you.

Think of a Pix charge. You created it, displayed the QR to the customer, and now you need to know when the customer pays. Two options:

Polling, keep asking every X seconds "paid yet? paid yet?" (costly, slow, unnecessary).
Webhook, let Pix Processamento notify you as soon as the payment arrives (instant, efficient, recommended).

How to configure

There is no separate endpoint to "register a webhook". The URL is provided on each transaction created, in the callbackUrl field of the body:

{
  "amount": 99.90,
  "callbackUrl": "https://yoursite.com/webhooks/pix",
  "clientReference": "order-2025-001"
}

Pix Processamento will send the callback to that URL every time that transaction changes status (PENDING → COMPLETED, COMPLETED → REFUNDED, etc).

Create a public endpoint on your server

Somewhere accessible over the internet that accepts POST with JSON. Examples: https://yoursite.com/webhooks/pix, https://api.yourcompany.com/pix/callback.

During local development, use tunnels like ngrok or Cloudflare Tunnel to expose localhost.

Pass the URL when creating the transaction

On every POST /pix, POST /withdraw, POST /internal-transfer, include the callbackUrl field. It can be the same URL for all of them.

Implement the handler

Receive the POST, read the JSON, process it and respond 2xx within 5 seconds. See examples in Receive Pix · step 3.

Required header on the POST sent by Pix Processamento: Content-Type: application/json.

Retry system

Pix Processamento's webhooks have a robust retry system that ensures delivery even during temporary failures. Pix Processamento resends up to 72 times the same callback with exponential backoff and jitter, better distributing the load and avoiding request spikes.

Response time: the webhook must respond with HTTP 200 OK within 5 seconds. If it exceeds this time, the system considers it a timeout and starts the retry process.

Field	Type	Description
`id`	string	Transaction ID
`clientReference`	string	External reference you provided
`virtualAccount`	string	Virtual subaccount (up to 50 characters). Returns in the callback to correlate stores, branches, marketplaces.
`callbackUrl`	string	URL configured to receive this webhook

Status and values

Field	Type	Description
`status`	string	`PENDING`, `COMPLETED`, `CANCELED`, `WAITING_FOR_REFUND`, `REFUNDED`, `EXPIRED`, `ERROR`
`type`	string	`DEPOSIT`, `WITHDRAW`
`method`	string	`PIX`, `BANK_SLIP`, `INTERNAL_TRANSFER`
`amount`	number	Amount in BRL
`serviceFeeCharged`	number	Fee charged

Generated charge (deposit)

Field	Type	Description
`qrCodeText`	string	Pix copy-and-paste code
`qrCodeUrl`	string	QR Code image URL
`qrCodeBase64`	string	QR Code image in Base64 format
`generatedName`	string	Reference name
`generatedDocument`	string	CPF or CNPJ
`generatedEmail`	string	Email linked to the transaction

Payer

Field	Type	Description
`payerName`	string	Payer's name
`payerDocument`	string	Payer's document
`payerInstitutionIspb`	string	ISPB of the payer's bank
`payerInstitutionName`	string	Payer's bank name
`payerAccountNumber`	string	Payer's Pix Processamento account (6 digits). Filled when the Pix Processamento account is the paying side: withdrawals and internal transfers.

Receiver

Field	Type	Description
`receiverName`	string	Receiver's name
`receiverDocument`	string	Receiver's document
`receiverInstitutionIspb`	string	ISPB of the receiver's bank
`receiverInstitutionName`	string	Receiver's bank name
`receiverAccountNumber`	string	Receiver's Pix Processamento account (6 digits). Filled when the Pix Processamento account is the receiving side: deposits and internal transfers.

On withdrawals, the other payer* fields describe the provider's settlement account, while payerAccountNumber is the Pix Processamento account that originated the withdrawal. To identify an internal transfer, use method: INTERNAL_TRANSFER, not the presence of these fields.

Withdrawal via Pix key

Field	Type	Description
`withdrawPixKey`	string	Pix key used in the withdrawal
`withdrawPixType`	string	`cpf`, `cnpj`, `phone`, `email`, `evp`

Settlement and refund

Field	Type	Description
`endToEndId`	string	Pix EndToEnd ID
`paidAt`	string	Payment timestamp (ISO 8601)
`cancellationReason`	string	Cancellation reason
`refundEndToEndId`	string	Refund EndToEnd ID
`refundAmount`	string	Refunded amount
`refundStatus`	string	`PENDING`, `COMPLETED`, `CANCELED`
`refundReason`	string	Refund reason
`refundDescription`	string	Refund description
`refundedAt`	string	Refund timestamp (ISO 8601)

Timestamps

Field	Type	Description
`createdAt`	string	Creation timestamp (ISO 8601)
`updatedAt`	string	Update timestamp (ISO 8601)

Infraction (Pix dispute)

Field	Type	Description
`infraction`	object	Infraction details when opened (see MED)

Best practices

Respond fast: return 2xx in under 5s. Process heavy work in queues/workers, not in the handler.
Idempotency: store id + status to deduplicate. The same callback may arrive more than once (retries, successive changes).
Use clientReference: pass an external identifier when creating the transaction. It returns in the callback and makes it easier to correlate with your order.
Restrict by IP: only accept callbacks from Pix Processamento's official IP.

Inspection and resend

The API exposes the full list of callbacks sent:

GET /user/callbacks, paginated list
GET /user/callbacks/{id}, details
POST /user/callbacks/resend/{transactionId}, resend callback for a transaction
POST /user/callbacks/resend, batch resend