Skip to main content
Webhooks let your application receive asynchronous notifications when relevant events happen (for example, a payment settlement or a KYC status change).
Event names and the exact payload format depend on your account configuration. Confirm the available fields in the PagFinance dashboard or with support before going to production.

​
How it works

1

Configure the endpoint

Register an HTTPS URL of your application to receive the events.
2

Receive the event

PagFinance sends a POST request with the event payload to your URL.
3

Respond quickly

Respond 2xx as fast as possible. Process heavy logic asynchronously.
4

Handle retries

On failure or timeout, the event may be resent. Handle events idempotently.

​
Event types

​
event
A payment was created.
​
event
The payment’s on-chain transaction was submitted.
​
event
The payment was settled in local currency (PIX, boleto, or gift card).
​
event
The payment failed or was rejected.
​
event
The status of a KYC verification changed.

​
Payload example

​
Best practices

Idempotency

Use the event identifier to avoid duplicate processing on retries.

Verification

Validate the authenticity of the request (signature or shared secret) before trusting the payload.

Fast response

Respond 2xx immediately and process in the background.

HTTPS

Only expose HTTPS endpoints to receive events.
This section describes the typical behavior of PagFinance webhooks. The exact events and fields must be confirmed against your account’s operational documentation.