Webhooks
Webhooks are notifications sent by our API to your registered URL whenever a relevant event occurs (e.g., a PIX is received or a payment is completed).
Webhook Configuration
How you create and maintain subscriptions depends on your product:
BaaS (tenant)
Internet Banking (account)
You have two equivalent, always-in-sync paths:
- API —
POST /v1/webhooksand the other routes described on this page. This is how you automate the setup alongside the rest of your deployment. - Integrator Portal — besides creating and editing subscriptions, this is where you run day-to-day operations: resend failed deliveries, debug errors (HTTP status and body returned by your endpoint), browse the delivery history of every event and rotate the HMAC key without interrupting the flow.
Use the API to provision and the Portal to operate and investigate.
List Available Events
Response (array of { event, description }; illustrative excerpt):
The full list also includes PIX out/refund/MED, QR Code, boleto, TED, internal transfers, and fees. Onboarding events are documented in Onboarding Webhooks.
Receiving Flow
- An event occurs on our platform.
- We send a
POSTrequest to the registered URLs. - Your application must process the notification and return a
2xxstatus.
Configuration Flexibility
Our webhook infrastructure supports various delivery methods:
- Grouping: You can receive multiple event types (e.g.,
pix.in.completedandpix.out.completed) at the same URL. - Segregation: You can configure different URLs for each event type.
- Redundancy: We can send the same event to multiple independent URLs simultaneously.
- Per-account scoping: a subscription can receive only one account’s events — see below.
Per-account subscriptions (accountId)
By default a subscription belongs to the tenant: it receives events from all of your accounts. Passing accountId at creation time makes it receive only that account’s events:
The field comes back in GET /v1/webhooks (accountId: null for tenant-wide subscriptions).
Rules worth knowing before you use it:
- It is a filter, not extra routing. A subscription with
accountIdstops receiving the other accounts’ events. If you want everything in one place and a slice in another, create two subscriptions. - It cannot be edited.
accountIdis only accepted at creation. Changing the account of a live subscription would silently redirect one account’s event stream to the endpoint configured for another — creating a new subscription is explicit and leaves the old one auditable. - A credential restricted to accounts must provide it. If the credential only reaches a subset of accounts (the case for delegated credentials), omitting
accountIdreturns 422account_id_required, and pointing at an account outside the subset returns 403forbidden. Without this, a single-account credential could create a subscription for another account’s movement and read everything over the webhook, bypassing the control the read routes apply. - An account from another tenant returns 404
account_not_found. - Events with no account (accreditation events, before the account exists) are only delivered to tenant-wide subscriptions.
- The filter also applies at delivery time. A subscription with
accountIddoes not receive other accounts’ events, even when the tenant has another subscription for the same event type. The envelopeaccountIdis the account where the event happened.
Security (Destination Authentication)
When creating or updating a webhook subscription, you can choose how our delivery infrastructure authenticates requests to your endpoint. The authentication method is configured per subscription via the API or dashboard.
Available Authentication Methods
You configure the method when creating or updating a subscription, via the API or the Integrator Portal (Webhooks > Edit Subscription).
Rotating or removing the key
The secret is never returned in any response — the subscription only tells
you hmacSecretSet: true|false. Because of that:
- Omitting
secreton aPUTkeeps the current key. This is what lets you change only the URL without losing the signature. - Sending
secretreplaces the key (rotation). - Sending
authType: "NONE"deletes the key and stops signing with it. This is the only way to turn it off.
Any other authType value is rejected with 400 unsupported_auth_type.
HMAC Signature Verification
When authType is set to HMAC, each request includes an X-Signature header containing the HMAC-SHA256 of the raw request body as standard Base64, with padding, computed using your secret as the key.
Formula:
Compare the computed value with the X-Signature header. If they match, the request is authentic.
Always use the raw request body bytes for verification, not a re-parsed/re-serialized version. Re-serializing JSON may change field order or whitespace, which will invalidate the signature.
Verification Examples
Node.js:
Python:
Go:
Informational Headers
In addition to the authentication headers above, our delivery infrastructure adds the following informational headers to every request:
These headers are informational and do not need to be validated.
IP Whitelist
To increase the security of your integration, we recommend that your destination server validates the source IP address of incoming requests. Only accept notifications from our infrastructure’s official IPs:
34.138.140.22334.138.161.10035.231.250.19335.196.71.2934.138.56.192
We suggest adding these addresses to a whitelist in your firewall or web server.
Retries
If your application returns an error (status other than 2xx) or a timeout occurs, our system will attempt to resend the notification following an exponential backoff strategy:
- Attempts: Up to 6 times.
- Intervals: Progressively increasing.
After exhausting all attempts, the delivery stays at status: failed. You can request a manual retry of that specific delivery.
GET /v1/webhooks/{subscriptionId}/deliveries returns the result at your endpoint, not the acceptance by our delivery network:
dispatchStatus is the previous step (success = forwarded, exhausted = it never left). That is what status used to mean. The filter status=success is still accepted and means delivered; exhausted means not_dispatched.
Retrying a Delivery
To resend a failed delivery, use the per-delivery retry endpoint, passing the
subscriptionId and deliveryId (both visible in the subscription’s delivery
list):
Request Example:
The API queues a new delivery attempt for that deliveryId. If a burst of retries hits the delivery network’s rate limit, the response is 429 rate_limited with a Retry-After header — wait and try again. That is not a failed delivery.
Notification Format
All notifications follow a standard envelope format. The specific content of each event resides in the data object.
Standard Envelope
Monetary values (amount, paidAmount, etc.) are always in BRL. Decimals use a point (150.50), never a comma. PIX-out events (pix.out.completed, pix.out.failed, pix.out.timeout, and pix.refund.* from the same flow) include data.currency: "BRL". Other events may omit the field — the amount is still in reais.
The POST to your URL is the envelope (id, type, occurredAt, schemaVersion, environment, tenantId, accountId, data). In the integrator portal, the “webhook delivered” JSON shows only the data object (sometimes labeled deliveredData) — that is not the HTTP body.
Common fields inside data
A handful of fields appear in every event type that represents a ledger entry (PIX IN/OUT, refund, QR paid, internal transfer, fee). They are the recommended way to correlate webhooks with other API endpoints:
The first three fields can coexist in the same payload. If only one is present it means the other isn’t relevant for that event type (e.g., internal transfers carry transactionId + coreId but not endToEnd).
data.status values
The status field uses a standardized vocabulary across all events:
For MED (dispute) events, status uses its own vocabulary:
Events: pix.med.opened, pix.med.updated.
This status is the state at the instant of the event, and in that it is
reliable: it is the settlement bank’s own notification. That is why it does not
exist in GET /v1/accounts/{id}/pix/med — there it would be a stored value,
with no lookup to confirm it. If you need to track the state of a dispute,
accumulate these events: they are the only source.
status guarantee
status is always present in events that represent a ledger entry. If you receive a webhook missing the field (or with an empty value), it’s a purely informational event (e.g., account.balance_updated) — in that case use the type field itself to determine semantics.
Date and time format
Date/time fields use ISO 8601 / RFC 3339 with an explicit offset — read the offset, don’t assume. Webhooks (envelope occurredAt and fields inside data such as receivedAt, completedAt, initiatedAt, chargedAt, openedAt) are always UTC (Z). In REST responses, “our-side” fields (createdAt, updatedAt, reconciledAt, fetchedAt, balance) are UTC (Z) too; the transaction time in the statement and lookups — timestamp (/statement, /pix/transactions) and occurredAt (/pix/payments/lookup, boleto) — is in São Paulo time (-03:00).
Examples:
We never emit timestamps in Brazilian local time (BRT) nor “naive” timestamps (without timezone indicator). If you ever receive a date field without the Z suffix, treat it as a bug and report it — we will normalize as soon as we identify the source.
Event Types and Contents (data)
1. pix.in.completed
Sent when a PIX is successfully received (inbound) into the account.
Fields always present in data:
transactionId: Ledger transaction ID (the settlement-bank operation id when available; otherwisepix-in-{endToEnd}). MatchesGET /v1/accounts/{accountId}/statement. The envelopeidispix-in-{endToEnd}.endToEnd: Unique transaction ID at the Central Bank.accountId/tenantId: repeated insidedata(they are also on the envelope).amount: Transaction amount in reais.status:"SUCCESS".method: How the payer started the PIX —STATIC_QR_CODE,DYNAMIC_QR_CODE,DICT(PIX key) orMANUAL(bank details).receivedAt: Timestamp of receipt (RFC 3339 UTC).
Conditional fields:
identifier: When the credit came from a QR Code, this is the txid of the QR that was paid — use it to reconcile with the QR you created.description: Description from the settlement bank (may be an empty string).payer: Sender. Only keys with a value are included:name,document,bankCode,bankIspb,branch,account/accountNumber(same value;accountNumberis a compatibility alias).payee: Receiver (your account). Same keys, pluspixKeywhen available. Omitted if the settlement bank sent no payee data.
This event does not send reconciliationId.
Full Example:
2. qrcode.paid
Sent when a QR Code generated by you is paid. For the same credit you also receive pix.in.completed — this event is the QR-specific confirmation (identifier / qrcodeId).
Fields always present in data:
qrcodeId: Internal QR Code ID (for a static QR this is the same asidentifier).identifier: txid (identifier) of the QR Code you created.accountId/tenantId: Account that owns the charge.type: today"static","dynamic","due-date"or"location". The list is extensible and may gain values: do not reject the event on an unknowntype.amount: Amount paid. For due-date and Location QR codes this already includes any discount, interest or penalty.endToEnd: Unique transaction ID at the Central Bank.transactionId: Settlement-bank transaction ID, when available.status:"SUCCESS".receivedAt: Timestamp of receipt (RFC 3339 UTC).
Conditional fields:
payer: Payer. Dynamic QR typically carriesnameanddocument; static QR may also includebankCode,bankIspb,branch,accountNumber.payee: Receiver (your account). Present on static QR when the settlement bank sent those fields.
This event does not send reconciliationId.
Full Example:
3. pix.out.completed
Sent when an outbound PIX transfer is completed successfully.
The POST to your URL is the envelope (id, type, occurredAt, schemaVersion, environment, tenantId, accountId, data). In the integrator portal, the “webhook delivered” JSON shows only the data object (sometimes labeled deliveredData) — that is not the HTTP body.
Fields always present in data:
paymentId: Order ID (same as the202response of the async POST). The envelopeidispix-out-{paymentId}.tenantId,accountId: repeated insidedata(they are also on the envelope).status:"SUCCESS".endToEnd: BACEN E2E ID (empty string if the settlement bank has not issued one yet).transactionId: Settlement-bank transaction ID, when available.amount: Amount in reais.currency: always"BRL".description: Description sent on the POST (may be an empty string).identifier: Your reconciliation key.originalTransactionId: Original transaction ID on refunds; empty string on a regular PIX out.initiatedAt/completedAt: RFC 3339 UTC (Z), with fractional seconds (up to nanoseconds).
Conditional fields:
key:{ "type", "key" }when the transfer was sent to a PIX key.payee: Destination. Only keys with a value are included:name,document,bankCode,bankIspb,branch,accountNumber,pixKey,accountType.payer: Origin account. Present only when the settlement-bank webhook carried those fields — do not assume it always arrives.late:trueonly when confirmation arrived after apix.out.timeoutfor the samepaymentId. Absent in the normal case. See Late confirmation.
This event does not send reconciliationId, method, or a payment object.
Full Example:
4. pix.out.failed
Sent when an outbound PIX transfer fails definitively — the banking partner rejected the operation (insufficient funds, invalid key, anti-fraud, BACEN rejection etc.) and no balance was moved (or it was returned).
pix.out.failed is terminal: once received, no later pix.out.completed will arrive for the same order. Uncertainty scenarios (e.g. communication timeout with the partner, outcome unconfirmed) emit pix.out.timeout — never pix.out.failed.
data uses the same fields as pix.out.completed, plus:
status:"FAILED".error/errorCode/errorReason: rejection reason (erroris the friendly alias).partner: raw settlement-bank error, when available.late:trueonly when the rejection arrived after apix.out.timeoutfor the samepaymentId. See Late confirmation.
This event does not send reconciliationId.
Full Example:
5. payment.sent (removed)
This event was deprecated in v1.15.0 (2026-02-20) and has been permanently disabled in v1.28.0 (2026-04-17). Use pix.out.completed with method: PAYMENT and the payment object in the payload instead.
6. payment.refunded (removed)
This event was deprecated in v1.15.0 (2026-02-20) and has been permanently disabled in v1.28.0 (2026-04-17). Use pix.refund.completed instead. That event does not include originalEndToEnd or refundEndToEnd — the refund E2E is endToEnd, and the original transaction is originalTransactionId.
7. pix.refund.completed
Sent when a PIX refund we initiated is completed. Different from pix.refund.received, which is a return started by the original payee without us asking.
data uses the same fields as pix.out.completed, with:
- Envelope
id:pix-refund-{paymentId}. status:"SUCCESS".originalTransactionId: ID of the original PIX IN being refunded (not empty, unlike a regular PIX out).
This event does not send originalEndToEnd, refundEndToEnd, or reconciliationId. To correlate with the original credit, use originalTransactionId / identifier and the statement.
Full Example:
8. pix.refund.failed
Sent when a refund we initiated fails definitively.
data uses the same fields as pix.refund.completed / pix.out.failed, with:
status:"FAILED".error/errorCode/errorReason: rejection reason (erroris the friendly alias).partner: raw settlement-bank error, when available.
This event does not send originalEndToEnd, refundEndToEnd, or reconciliationId.
Full Example:
9. fee.charged
Sent when a banking fee is charged to the account (e.g., per-transaction PIX fee).
data structure:
transactionId: Deterministic ledger row id (fee-{coreId}).accountId/tenantId: Charged account and tenant.amount: Fee amount, always positive in the account currency.description: Fee description.feeServiceType: Underlying service that triggered the fee (PIX,BOLETO,P2P_CRYPTO, …) when the bank reports it.originalRef/transactionRef: Cross reference to the originating movement when available.occurredAt: Timestamp at which the bank booked the fee.status: Always"SUCCESS".kind:"CHARGED".
Full Example:
9.1. fee.refunded
Sent when the bank reverses a previously charged fee (cashback, adjustment). Same shape as fee.charged, with kind="REFUNDED". Funds are already credited to the account. The public description of any credit coming from the fee accounts is LANÇAMENTO DE CRÉDITO (the event type does not change).
10. pix.med.opened
Sent when a new MED (Special Return Mechanism) dispute is opened against a transaction credited to one of your accounts. It starts the 48-hour clock for your response — see the Disputes guide.
data Structure:
medId: Dispute identifier (infraction report). It is the{medId}used by the REST routes.originalEndToEnd:endToEndIdof the disputed PIX transaction.amount: Disputed amount.reasonCode: Reason reported by the scheme, raw (e.g.scam-or-fraud,unauthorized-transaction).claimMessage: Free-text details provided by the claimant (when present).openedAtIso: MED opening date (ISO 8601).clientAnswerDeadlineIso: Your response deadline —openedAtIso+ 48h.status:OPENon filing.
Full Example:
11. pix.med.updated
Sent when the status of a MED dispute changes. This is how you learn the outcome, and it is the only source of state: POST .../answer merely records your defense (which goes on for analysis outside the API), and the dispute also moves through action by BACEN and by the claimant’s bank.
A redelivery of the same status produces no new event, and a late event (settlement-bank timestamp older than what we already stored) is dropped — the status never moves backwards.
data Structure:
medId: Dispute identifier (same aspix.med.opened).originalEndToEnd:endToEndIdof the disputed PIX transaction.amount: Disputed amount.reasonCode: Reported reason.clientAnswerDeadlineIso: Your response deadline (the same as on filing).status: Current MED status — dedicated vocabulary (OPEN,PENDING_DECISION,ACCEPTED,REJECTED,CANCELED; see the status table above).
Settlement bank status mapping — the raw value never leaves in the event:
An unknown status becomes OPEN, not a closure: missing the filing of a dispute costs you your response window, while receiving one extra only costs a lookup.
Full Example:
12. pix.med.review.updated
Sent at each step of CorpX’s review of a dispute: defense received, clarification requested, decision, balance hold and release, account block and release, returns, and closure. It is the event that tracks the reviewStatus from the MED guide; pix.med.updated keeps covering the settlement bank’s status.
data is always the current snapshot of the dispute; reason says what just happened. You do not need to accumulate events to know where it stands.
data structure:
medId,accountId: Dispute and account identifiers.reason:submitted,info_requested,decided,balance_locked,account_blocked,balance_unlocked,refund_sent,refund_completed,refund_failed,remainder_locked,account_unblocked,closed.reviewStatus:awaiting_defense,pending_review,info_requested,in_execution,awaiting_funds,refunded,refused.round: Return round the step belongs to (empty outside execution).decision,decisionMessage:acceptorrefuseand the justification, fromdecidedon.infoRequest.message,infoDueAt: The review’s question and deadline, ininfo_requested.lockStatus,lockedAmount: Current balance hold.refund.amount,refund.endToEndId: The return of this event, inrefund_*.refundedTotal,remaining,refundPartial: Return totals.
Full example:
13. transfer.internal.in
Sent to the account that receives an internal transfer between accounts of the same banking ecosystem. Internal transfers are instant and settled at the same bank — they do not travel through the PIX SPI, so they have no endToEndId.
data structure:
transactionId: Transaction ID in our system (formatinternal-{uuid}). Use it onGET /v1/accounts/{accountId}/statement.amount: Amount received.status: AlwaysSUCCESS(internal transfers are atomic).completedAt: Settlement timestamp.identifier: Identifier the sender supplied onPOST /transfers/internal*(when given). The same value arrives on both legs (transfer.internal.outandtransfer.internal.in).payerDescription/description: Description supplied by the sender.source: The payer —name,taxId,providerAccountIdand, when the account is managed by us,accountIdandtenantId.destination: The receiver, with the same fields.payer/receiver: The same two parties, withdocumentin place oftaxId. They appear only when the transfer was initiated outside the API (the liquidator’s app or console). Kept for compatibility — prefersource/destination, which arrive from both origins.
When the receiver is an account at another bank, destination carries name and taxId (the ones you supplied in the request) without accountId/tenantId. In that case only transfer.internal.out exists.
When the identifier belongs to a P2P Crypto order (p2p-{orderId}, fee-p2p-{orderId} or fee-p2p-{orderId}-r), the payload gains p2pOrderId and p2pKind (payment, fee or fee_refund), the description becomes the statement one (COMPRA P2P CRIPTO, VENDA P2P CRIPTO, TAXA INTERMEDIAÇÃO KYC P2P CRIPTO, …) and the counterparty (source on a credit, destination on a debit, and payer/receiver when present) is reduced to { "name": "ORDEM P2P CRIPTO" }. The same applies to fee.charged and fee.refunded.
Full Example:
14. transfer.internal.out
Sent to the account that sends an internal transfer. Same shape as transfer.internal.in, with two differences:
identifieris populated on both legs when you passedidentifierin the original request (POST /v1/accounts/{accountId}/transfers/internal*). Use it to reconcile the transfer on your side.description— if you passeddescriptionin the request, that same text comes back here (instead of the defaultTransferência Interna).
Example:
When calling POST /v1/accounts/{accountId}/transfers/internal (or the by-document / by-bank-account variants), send your own unique identifier. The API response returns that identifier together with transactionId. The transfer.internal.out webhook arrives afterwards with the same identifier + transactionId, so you can close the transaction on your side without querying the statement.
15. pix.out.timeout
Sent when the order outcome is indeterminate at the end of the confirmation window: the partner call was dispatched but the response/final confirmation did not arrive in time (this includes communication timeouts on the submit call itself). Not a definitive failure — a late pix.out.completed or pix.out.failed may still arrive afterwards. Check the statement before retrying with a new idempotency key; retrying with the same key is safe.
data structure (fields specific to this event):
status: Always"TIMEOUT".errorCode/errorReason/warning/error: What to do next (confirmation_timeout).hold: Present when the order is being held at the settlement bank. Carriesowner: "partner"andreason(partner_authorization= the settlement bank’s internal authorisation queue;partner_risk_analysis= risk review;partner_unspecified= held, queue unknown). When this object is present, there is nothing to approve on your side or on ours — the decision belongs to the settlement bank.partnerStatus/partnerStatusId: Raw snapshot of the state at the settlement bank, useful to attach to a support ticket. These are the settlement bank’s values, not our canonical vocabulary: do not use them in status comparisons.
Late confirmation (late: true)
TIMEOUT is an indeterminate state, not a final one. When the order is held at the settlement bank, we keep polling it for up to 7 days, and if it settles (or rejects) within that window you receive the matching terminal event:
pix.out.completedwithlate: true— the money left the account.pix.out.failedwithlate: true— the settlement bank rejected it.
The late event carries the same paymentId as the pix.out.timeout you already received: it corrects that outcome, it is not a second payment. Treat it as the order’s definitive outcome.
After 7 days without news no further event is sent and the order stays TIMEOUT — which literally means “we do not know”. Check the statement (GET /v1/accounts/{accountId}/statement) before reissuing. Reissuing with the same Idempotency-Key is safe; a new key may result in a duplicate payment.
16. pix.refund.received
Sent when the receiver of a PIX out returns the funds on their own initiative (without us asking). Different from pix.refund.completed, which confirms a refund we triggered.
data structure:
transactionId: Deterministic ID of the received refund row (pix-refund-received-{refundEndToEnd}).refundEndToEnd: Refund D-code (BACEN).originalEndToEnd: E-code of the original PIX out being reversed.originalIdentifier: Identifier of the original PIX out (echo of the value sent at payment creation), when available.accountId/tenantId: Account that received the refund.amount: Reversed amount.description: Description from the partner.receivedAt: Refund timestamp.payer: Party that returned the funds (counterparty / original PIX out recipient): name, document, bank, branch, account.payee: Party that received the credit (our account / original PIX out payer): name, document, bank, branch, account.status: Always"SUCCESS".
17. qrcode.expired
Sent when a dynamic QR Code expires without being paid, at the expirationDate requested at creation (24 hours later when the field was omitted). Due-date QR codes and confirmed Location QR codes expire at the end of dueDate + daysAfterDueDate (Brasília time).
data structure:
qrcodeId: Internal QR Code ID.identifier: txid of the QR Code you created.accountId/tenantId: Account that owns the charge.type: today"dynamic","due-date"or"location"(static QR Codes do not expire). Extensible list, as inqrcode.paid.amount: Amount that was awaiting payment.status: Always"EXPIRED".
18. qrcode.cancelled
Sent when the integrator explicitly cancels a dynamic QR Code via DELETE /v1/accounts/{accountId}/pix/qr-code?identifier={txid} before payment.
data structure:
qrcodeId: Internal QR Code ID.identifier: txid of the QR Code you created.accountId/tenantId: Account that owns the charge.type: QR Code type. Extensible list, as inqrcode.paid.status: Always"CANCELLED".reason/cancelledBy: Present when the cancellation carries a reason and who cancelled it.
19. boleto.paid
Sent when a boleto paid via POST /v1/accounts/{accountId}/boleto/pay is confirmed by the issuing bank.
data structure:
paymentId: Canonical boleto id (bol_{uuid}) — same value returned byPOST /boleto/pay. Use this to correlate. The envelopeidisboleto-{paymentId}.boletoId: Alias ofpaymentId(same value).partnerId: Settlement-bank reference (operationReferenceId), for support/reconciliation.accountId/tenantId: Payer account.amount: Amount paid.line: Digitable line / barcode.status: Always"SUCCESS".
This event does not send transactionId.
20. boleto.failed
Sent when the issuer rejects the payment. data.error is a string with the reason (not an object). The same text is also in data.errorReason; data.errorCode is present when the settlement bank sent a code.
21. ted.out.requested
Sent immediately after POST /v1/accounts/{id}/ted/out is accepted. Status PROCESSING — TED registered at the settlement bank, waiting for the BACEN window to settle. See the TED guide.
22. ted.out.confirmed
Settlement confirmed by the settlement bank (terminal — success).
Deprecated alias: the
ted.paymentevent is dispatched in parallel withted.out.confirmedwith the same payload, kept only for compatibility with legacy subscriptions. New integrators should subscribe toted.out.confirmedonly.ted.paymentwill be removed in v3.0.
23. ted.out.failed
Settlement rejected/expired (terminal — failure). data.errorReason carries the canonical reason.
Possible errorReason values: invalid_bank_code, insufficient_funds, outside_banking_hours, bank_unreachable, limit_exceeded, or timeout aguardando confirmação do parceiro (>48h) (defensive polling exhausted).
24. ted.in.received
A TED was received in your account (originated by a third party). Includes data.payer with the originator’s name, document, bank (bankCode, bankIspb, bankName), branch and account — use them to reconcile with your books. The originator’s bank details come from the settlement bank’s statement; in the rare case the line is not there yet when we notify, the event carries only name and document. data.payee is the receiving account as the settlement bank identifies it: bank 681 / ISPB 50871921, branch, account and holder. When a holder is shared by more than one tenant, each receives its own event with the same payee.
Remember: for third parties to send a TED to your account, they must use bank 681 (the settlement bank) — see the TED guide.
25. policy.violation
A policy rule configured for your account or tenant was violated. The event covers every policy section — PIX out, cash-in, QR Code, keys, and refunds — and is sent both when the operation is rejected (action: "BLOCK") and when it only produces a warning or a post-credit action (NOTIFY_ONLY, ALLOW_AND_NOTIFY, AUTO_REFUND, LOCK_BALANCE, BLOCK_ACCOUNT). Use blocked to tell whether the operation was rejected. On a cash-in, blocked is always false.
When blocked is true on a PIX out, you also receive the matching pix.out.failed, with errorCode: policy_denied. They are two events with distinct ids: this one is the rule warning, that one is the payment outcome.
In monitor mode (NOTIFY_ONLY) the payment goes through normally and will have its own outcome (pix.out.completed, for example) — this event is only a heads-up that the transaction would have been rejected had the rule been set to BLOCK.
Violation on a cash-in (phase: "pix_in", "ted_in", "internal_in", or "boleto_in")
A cash-in cannot be refused: the settlement bank credits the account and only then tells us. The violation always comes after the credit. The payload swaps paymentId for transactionId and the credit reference, and adds refunded, balanceLocked, and accountBlocked. refunded is true only for a PIX refund. AUTO_REFUND on TED, internal transfer, and boleto only notifies, and the money stays.
The credit webhook (pix.in.completed, ted.in.received, transfer.internal.in, or boleto.charge.settled) is delivered before this event. With refunded: true, the PIX refund then produces the usual PIX out events (pix.out.completed or pix.out.failed). LOCK_BALANCE reduces the available balance at the settlement bank. BLOCK_ACCOUNT only cuts cash-out on our API. Neither one undoes the credit, and acknowledging the case does not unlock the balance or reopen the account.
Violation by MED rate (phase: "med")
Fired when a new dispute received against the account pushes the MED rate of the window above the ceiling of the med section. The only action is BLOCK_ACCOUNT. The reference is the dispute’s medId; the window numbers come in the payload so the integrator can rebuild the math. The pix.med.opened for that same dispute goes out with accountBlocked: true.
Rule and configuration details are in the Policies and Rules guide.
26. boleto.charge.registered
The issued slip was registered at the central base. chargeId is the same id returned by POST /v1/accounts/{accountId}/boleto/charge.
27. boleto.charge.registration_failed
Registration of the slip was rejected. statusReason carries the reason when the bank provides one.
28. boleto.charge.settled
The slip was paid. The credit also shows on the statement as BOLETO.
29. boleto.charge.overdue
The due date passed and the slip is still open. This is not a terminal state.
30. boleto.charge.written_off
The slip was written off.
31. boleto.charge.cancelled
The slip was cancelled.
32. boleto.charge.expired
The payment window ended.
33. boleto.charge.failed
Reserved in the catalog. This version does not send the event: a registration rejection is boleto.charge.registration_failed, and a beneficiary registration failure is the 502 on the POST.
34. boleto.charge.batch.completed
Sent when every issuance attempt in a batch has finished. status is
COMPLETED, PARTIAL_FAILED, or FAILED. This ends batch processing, not the
individual lifecycle: registration, payment, overdue, and expiration continue
for generated boletos.
statistics carries total, issued, and failed, the terminal snapshot of
issuance attempts. Payment continues afterwards: read the batch for
statistics.payment and current conversion (paid / issued × 100).
Subscribe with authType: HMAC. The delivery carries X-Signature; verify
the HMAC-SHA256 over the raw body bytes and deduplicate on id.
34.1. boleto.charge.beneficiary.approved
The settlement bank confirmed the account’s boleto beneficiary registration (or reactivated a closed relationship, with reactivated: true). The account can issue. operationId is the one returned by the registration 202. The four beneficiary events share accountId, beneficiaryId, operation (INCLUSION, UPDATE, STATUS_UPDATE or TERMINATION), result (CONFIRMED or REJECTED), operationId and occurredAt. See the boleto issuance guide.
34.2. boleto.charge.beneficiary.rejected
The settlement bank rejected a beneficiary operation. operation says which one; rejectionCode and rejectionReason come from the bank. After a rejected registration (INCLUSION), issuance returns 502 boleto_charge_beneficiary_registration_failed for 24 hours without registering again; POST .../boleto/charge/beneficiary registers again right away.
34.3. boleto.charge.beneficiary.updated
An update was applied. UPDATE (registration data) carries updatedAt. STATUS_UPDATE (eligibility) also carries previousStatus and currentStatus, with the same values as status in GET .../beneficiary.
34.4. boleto.charge.beneficiary.closed
The beneficiary relationship was closed. The account cannot issue new boletos until it is registered again. closedAgreementsCount is how many agreements were closed and issuanceBlocked confirms issuance is blocked.
35. identity.verification.completed
Sent when a standalone identity verification reaches a terminal state:
APPROVED, FAILED, or EXPIRED. PENDING never produces this event. The
verification belongs to the tenant rather than a bank account, so the envelope
has no accountId.
Every delivery includes X-Signature. Verify it against the raw request body
bytes before parsing JSON, and deduplicate on the envelope id.
Fields in data:
verificationId: ID returned byPOST /v1/identity-verifications;status:APPROVED,FAILED, orEXPIRED;purposeandreferenceId: exact binding supplied at creation;document: 11-digit CPF;failureReason: normalized failure/expiry reason;nullon approval;completedAt: terminal instant in UTC;consumableUntil: approval consumption deadline; omitted for other states;method:link(hosted page) orfacetec_sdk(SDK embedded in the app);referenceMatchandchecks: only forfacetec_sdk.checks.livenessis the liveness result andchecks.faceMatch.resultthe 1:1 face match result (not_performedwhenreferenceMatchisnone— the approval only proves a live person was present, not who they are).
The webhook notifies; it does not consume the proof. After validating the
event, call POST /v1/identity-verifications/{verificationId}/consume with the
same purpose and referenceId. See the complete flow in
Identity verification.
36. pix.batch.completed
Sent when every item of a PIX batch reached
an outcome. status is COMPLETED, PARTIAL_FAILED, or FAILED. Each item
is a regular PIX out and has already emitted its own pix.out.completed,
pix.out.failed, or pix.out.timeout; this event closes the batch and does
not replace the per-item events.
statistics carries counts (total, completed, failed) and BRL sums as
decimal strings (totalAmount, completedAmount, failedAmount). For the
item list, GET .../pix/batches/{batchId}; for the correction CSV of failed
rows, GET .../items/export?status=failed; for the receipts ZIP,
POST .../receipts.
Subscribe with authType: HMAC. The delivery carries X-Signature; verify
the HMAC-SHA256 over the raw body bytes and deduplicate on id.
37. limit_request.updated
A limit-increase request changed status. Sent on approval (the ceiling is already applied), refusal and cancellation. It is not sent when the request opens: that is limit_request.created. Approval also sends account.limits.updated, with no guaranteed order between the two. actingDocument is the CPF or CNPJ of the person who asked — use it to notify the right person. approvedLimitBrl may be lower than the request when the reviewer adjusts the amount, never higher. A null effectiveAt means the new ceiling is already in force. For a multi-operation request, bundleId identifies the bundle and items carries each operation’s status and amounts.
38. limit_request.created
A limit increase was opened. Sent on INSERT, whether it came from the API (channel: api, integrator token) or the backoffice (channel: backoffice, panel user token). It is not sent again on a replay of the same Idempotency-Key. The envelope id is lr-{id}-pending_review.
data has the same shape as limit_request.updated, plus currentLimitBrl (the effective ceiling at open, including the previous register; 0 only if the window was open), justification and channel. For a bundle, bundleId and items include every operation opened together.
A subscription with an empty event list receives the event. An explicit list receives it only if limit_request.created is on the list. Deduplicate by id.
39. account.limits.updated
An account or operator ceiling actually changed. Sent after a staff PATCH, an internal-credential PATCH, approval of a request (including windows materialized from the previous register) and operator ceiling PUT/DELETE.
It is not sent when a tenant or global default changes, nor when an already scheduled operator relaxation (6 h) takes effect: the scheduling event already carried effectiveAt.
The envelope id is the limit-audit event id. A dispatch retry does not open another delivery. On approval it sits next to limit_request.updated, with no order. Deduplicate by id and, when the amount matters, read GET /limits/available again.
Pix Automático events
pix.automatic.* events are sent for the receiving account of the recurrence. recurrenceId is the UUID returned by POST /v1/accounts/{accountId}/pix/automatic/recurrences (or by the composite QR issuance); recurrenceIdentifier is the RR…/RN… identifier assigned in the Pix scheme and appears as soon as it is known. The envelope id is deterministic per recurrence, event and status: deduplicate by it. Full guide in Pix Automático.
40. pix.automatic.recurrence.authorized
The payer authorized the recurrence in their bank app. From now on you can schedule charges.
41. pix.automatic.recurrence.rejected
The payer or their bank rejected the recurrence. rejectionReason is present when the bank provides a reason.
42. pix.automatic.recurrence.expired
The authorization request expired without an answer from the payer, or the recurrence was canceled. data.status tells which (expired or canceled).
43. pix.automatic.recurrence.failed
The authorization request failed before reaching the payer (request_failed) or when the authorization was confirmed (authorization_failed). Review the payer data and create a new recurrence.
44. pix.automatic.scheduling.confirmed
The payer’s bank confirmed the charge scheduling. schedulingId is the id returned by POST .../recurrences/{recurrenceId}/schedulings.
45. pix.automatic.scheduling.rejected
The payer’s bank rejected the scheduling. errorCode and errorMessage are present when provided.
46. pix.automatic.scheduling.failed
The scheduling was not confirmed: the payer’s bank did not answer in time (expired) or the confirmation failed (confirmation_failed). The payload is the same as pix.automatic.scheduling.rejected.
47. pix.automatic.settlement.completed
The scheduled charge was settled into your account. settlementStatus is settled or settled_with_error. The account credit also emits pix.in.completed with the same endToEndId; do not add both up. purpose is retry when the settlement came from a retry.
48. pix.automatic.settlement.failed
The charge was not settled. settlementStatus is insufficient_balance, not_settled or not_settled_with_error. Use settlementId to query the retry dates (GET .../settlements/{settlementId}/retry-dates) and request a retry. The payload is the same as pix.automatic.settlement.completed.
49. pix.automatic.qrcode.paid
The composite QR (immediate or due-date charge + recurrence authorization) was paid. The payment also emits pix.in.completed; this event exists so you can link the payment to the recurrence, which then goes to authorization and later emits pix.automatic.recurrence.*.
Best Practices
- Idempotency: Your application should be prepared to receive the same webhook more than once. Use the envelope
idto avoid duplicate processing. - Quick Response: Return a
200 OKstatus as soon as you receive the webhook and process the business logic asynchronously to avoid timeouts. - Timestamp Validation: Check that the
occurredAtis not too old (we recommend a 5-minute tolerance) to prevent replay attacks.