Skip to navigation

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:

You have two equivalent, always-in-sync paths:

  • API — POST /v1/webhooks and 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

curl -X GET "https://tenant.api.corpx.com/v1/webhooks/events" \
-H "Authorization: Bearer YOUR_TOKEN"

Response (array of { event, description }; illustrative excerpt):

[
{ "event": "pix.in.completed", "description": "PIX received successfully" },
{ "event": "pix.out.completed", "description": "PIX sent successfully" },
{ "event": "accreditation.pf.created", "description": "PF accreditation created (async confirmation of POST)" },
{ "event": "accreditation.pj.created", "description": "PJ accreditation created (async confirmation of POST)" },
{ "event": "accreditation.biometry.link.created", "description": "Facial capture link issued (Unico flow; per person)" },
{ "event": "accreditation.acceptance.link.created", "description": "Terms acceptance link issued (per person; only in flows enabled on request)" },
{ "event": "accreditation.consent.link.created", "description": "Authorization link issued — CPF already has an account (per person)" },
{ "event": "accreditation.updated", "description": "Accreditation status transition" },
{ "event": "accreditation.active", "description": "Account ready to operate — accountId available" },
{ "event": "accreditation.failed", "description": "Accreditation ended without opening an account" },
{ "event": "account.shared_access.granted", "description": "Another tenant started operating an account you already operated" },
{ "event": "boleto.charge.batch.completed", "description": "Boleto Charge batch finished every issuance attempt" },
{ "event": "pix.batch.completed", "description": "PIX batch finished with success and failure statistics (each item also emits pix.out.*)" },
{ "event": "identity.verification.completed", "description": "Standalone identity verification completed" },
{ "event": "policy.violation", "description": "A policy rule was violated — operation rejected (BLOCK), merely reported (NOTIFY_ONLY / ALLOW_AND_NOTIFY), PIX refunded (AUTO_REFUND), amount locked (LOCK_BALANCE), or cash-out blocked (BLOCK_ACCOUNT)" },
{ "event": "limit_request.created", "description": "A limit-increase request was opened (not sent again on Idempotency-Key replay)" },
{ "event": "limit_request.updated", "description": "A limit-increase request changed status (approved, refused or cancelled)" },
{ "event": "account.limits.updated", "description": "An account or operator ceiling changed. Does not include a tenant default or an already scheduled relaxation taking effect" }
]

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

  1. An event occurs on our platform.
  2. We send a POST request to the registered URLs.
  3. Your application must process the notification and return a 2xx status.

Configuration Flexibility

Our webhook infrastructure supports various delivery methods:

  • Grouping: You can receive multiple event types (e.g., pix.in.completed and pix.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:

curl -X POST "https://tenant.api.corpx.com/v1/webhooks" \
-H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: tenant-yourcompany" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-domain.com/webhooks/acc-123",
"events": ["pix.in.completed", "pix.out.completed"],
"accountId": "acc-123",
"authType": "HMAC",
"secret": "..."
}'

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 accountId stops receiving the other accounts’ events. If you want everything in one place and a slice in another, create two subscriptions.
  • It cannot be edited. accountId is 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 accountId returns 422 account_id_required, and pointing at an account outside the subset returns 403 forbidden. 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 accountId does not receive other accounts’ events, even when the tenant has another subscription for the same event type. The envelope accountId is 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

MethodauthType valueDescription
HMAC SignatureHMACSigns each request body with your secret using HMAC-SHA256. The signature is sent in the X-Signature header. Recommended.
Platform defaultNONENo key of yours. Deliveries are still signed, but with our infrastructure’s own signature, which you do not control.

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 secret on a PUT keeps the current key. This is what lets you change only the URL without losing the signature.
  • Sending secret replaces 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:

expected = base64(HMAC_SHA256(your_secret, raw_request_body))

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:

const crypto = require("crypto");
function verifySignature(secret, rawBody, signatureHeader) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("base64");
return expected === signatureHeader;
}
// In your Express handler:
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
const signature = req.headers["x-signature"];
if (!verifySignature(WEBHOOK_SECRET, req.body, signature)) {
return res.status(403).send("Invalid signature");
}
const event = JSON.parse(req.body);
// Process event...
res.sendStatus(200);
});

Python:

import base64, hmac, hashlib
def verify_signature(secret: str, raw_body: bytes, signature_header: str) -> bool:
expected = base64.b64encode(hmac.new(secret.encode(), raw_body, hashlib.sha256).digest()).decode()
return hmac.compare_digest(expected, signature_header)

Go:

func verifySignature(secret string, rawBody []byte, signatureHeader string) bool {
mac := hmac.New(sha256.New, []byte(secret))
mac.Write(rawBody)
expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

Informational Headers

In addition to the authentication headers above, our delivery infrastructure adds the following informational headers to every request:

HeaderDescription
x-hookdeck-event-idDelivery event ID (useful for debugging and support requests).
x-hookdeck-request-idOriginal request ID.
x-hookdeck-attempt-countDelivery attempt number (1 for the first attempt).

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.223
  • 34.138.161.100
  • 35.231.250.193
  • 35.196.71.29
  • 34.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:

statusmeaning
pendingaccepted for delivery, no attempt yet
retryingthe last attempt failed and another one is scheduled (nextAttemptAt)
deliveredyour endpoint answered 2xx (responseStatus)
failedattempts are exhausted
pausedthe subscription is paused
not_dispatchedthe event was never forwarded

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:

curl -X POST "https://tenant.api.corpx.com/v1/webhooks/{subscriptionId}/deliveries/{deliveryId}/retry" \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "X-Tenant-Id: your-tenant-id"

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

{
"id": "evt_123456789",
"type": "pix.in.completed",
"occurredAt": "2025-12-29T21:14:33.912Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": { }
}
Amounts are always BRL

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.

HTTP envelope vs. portal JSON

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:

FieldDescription
transactionIdTransaction identifier in the format used by our API. Matches what’s returned by GET /v1/accounts/{accountId}/statement and by the synchronous response of the endpoint that originated the transaction. Use it to fetch the transaction on our APIs.
coreIdUUID of the ledger line at the banking partner’s core. Same value exposed in the coreId field of the statement; remains stable across webhook and async statement sync. Use it to reconcile with partner exports.
endToEnd / endToEndIdCentral Bank PIX E2E ID (PIX events only).
statusTransaction state. Standardized vocabulary (see table below).

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:

StatusMeaningEvents
SUCCESSOperation completed successfully; balance debited/credited.pix.in.completed, pix.out.completed, pix.refund.completed, pix.refund.received, qrcode.paid, boleto.paid, transfer.internal.in, transfer.internal.out, fee.charged, fee.refunded
FAILEDOperation failed. Balance was not moved (or was returned). Check data.error for details.pix.out.failed, pix.refund.failed, boleto.failed
TIMEOUTPartner call was sent successfully but response timed out. Check the statement before retrying with a new idempotency key.pix.out.timeout
EXPIREDDynamic QR Code expired without being paid by the expirationDate requested at creation (24 hours when the field was omitted).qrcode.expired
CANCELLEDDynamic QR Code cancelled by an explicit integrator call (DELETE /v1/accounts/{accountId}/pix/qr-code?identifier=...).qrcode.cancelled
REVERSEDA previously completed PIX IN that has been reversed (e.g., full chargeback). Appears when late reconciliation overrides an already-delivered PIX IN.pix.in.completed (rare, post-reconciliation)

For MED (dispute) events, status uses its own vocabulary:

StatusMeaning
OPENDispute opened by the claimant, within the 48-hour window for your response.
PENDING_DECISIONYour response deadline has passed — the dispute is still alive, but the decision is no longer in your hands.
ACCEPTEDDispute accepted — funds returned (fully or partially).
REJECTEDDispute rejected — funds stay with the payee.
CANCELEDDispute canceled by whoever filed it.

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:

2026-04-29T23:53:55.001Z ← with milliseconds
2026-04-29T23:53:49.328720Z ← with microseconds
2026-04-30T18:04:36Z ← no fractional seconds

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; otherwise pix-in-{endToEnd}). Matches GET /v1/accounts/{accountId}/statement. The envelope id is pix-in-{endToEnd}.
  • endToEnd: Unique transaction ID at the Central Bank.
  • accountId / tenantId: repeated inside data (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) or MANUAL (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; accountNumber is a compatibility alias).
  • payee: Receiver (your account). Same keys, plus pixKey when available. Omitted if the settlement bank sent no payee data.

This event does not send reconciliationId.

Full Example:

{
"id": "pix-in-E0000000020251229211433912",
"type": "pix.in.completed",
"occurredAt": "2025-12-29T21:14:33.912Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"transactionId": "pix-in-E0000000020251229211433912",
"endToEnd": "E0000000020251229211433912",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"amount": 150.50,
"description": "",
"identifier": "SEV798c4a1f4b2e4d9c8a1b2c3d4",
"method": "STATIC_QR_CODE",
"status": "SUCCESS",
"receivedAt": "2025-12-29T21:14:33.900Z",
"payer": {
"name": "John Smith",
"document": "12345678900",
"bankCode": "001",
"bankIspb": "00000000",
"branch": "0001",
"account": "12345-6",
"accountNumber": "12345-6"
},
"payee": {
"name": "Test Company",
"document": "12345678000199",
"bankCode": "681",
"bankIspb": "50871921",
"branch": "0001",
"account": "98765-4",
"accountNumber": "98765-4"
}
}
}

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 as identifier).
  • 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 unknown type.
  • 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 carries name and document; static QR may also include bankCode, 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:

{
"id": "qrcode-paid-qr_abc123",
"type": "qrcode.paid",
"occurredAt": "2025-12-29T21:15:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"qrcodeId": "qr_abc123",
"identifier": "txid-qr-123",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"type": "dynamic",
"amount": 250.00,
"endToEnd": "E0000000020251229211500000",
"transactionId": "162982-pix",
"status": "SUCCESS",
"receivedAt": "2025-12-29T21:14:33.900Z",
"payer": {
"name": "Maria Oliveira",
"document": "98765432100"
}
}
}

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 the 202 response of the async POST). The envelope id is pix-out-{paymentId}.
  • tenantId, accountId: repeated inside data (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: true only when confirmation arrived after a pix.out.timeout for the same paymentId. Absent in the normal case. See Late confirmation.

This event does not send reconciliationId, method, or a payment object.

Full Example:

{
"id": "pix-out-9ccd1869-7593-4feb-9602-e525e818ab8e",
"type": "pix.out.completed",
"occurredAt": "2026-09-16T20:58:46.258668746Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"status": "SUCCESS",
"endToEnd": "E508719212026091620583702716219",
"transactionId": "162982-pix",
"amount": 50.00,
"currency": "BRL",
"description": "Supplier payment",
"identifier": "transfer-001",
"originalTransactionId": "",
"initiatedAt": "2026-09-16T20:58:42.646763686Z",
"completedAt": "2026-09-16T20:58:46.258668746Z",
"key": {
"type": "EMAIL",
"key": "destinatario@exemplo.com"
},
"payer": {
"name": "ACME LTDA",
"document": "12345678000199",
"bankCode": "208",
"bankIspb": "50871921",
"branch": "1",
"accountNumber": "3811084"
},
"payee": {
"name": "JOAO SILVA",
"document": "12345678900",
"bankCode": "077",
"bankIspb": "00416968",
"branch": "1",
"accountNumber": "0013887580"
}
}
}

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).

Terminal event

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 (error is the friendly alias).
  • partner: raw settlement-bank error, when available.
  • late: true only when the rejection arrived after a pix.out.timeout for the same paymentId. See Late confirmation.

This event does not send reconciliationId.

Full Example:

{
"id": "pix-out-9ccd1869-7593-4feb-9602-e525e818ab8e",
"type": "pix.out.failed",
"occurredAt": "2026-09-16T20:58:46.258668746Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"status": "FAILED",
"endToEnd": "E508719212026091620583702716219",
"transactionId": "162982-pix",
"amount": 1000.00,
"currency": "BRL",
"description": "Supplier payment",
"identifier": "transfer-002",
"originalTransactionId": "",
"initiatedAt": "2026-09-16T20:58:42.646763686Z",
"completedAt": "2026-09-16T20:58:46.258668746Z",
"error": "insufficient balance",
"errorCode": "insufficient_balance",
"errorReason": "insufficient balance",
"key": {
"type": "EMAIL",
"key": "destinatario@exemplo.com"
},
"payee": {
"name": "JOAO SILVA",
"document": "12345678900",
"bankCode": "077",
"bankIspb": "00416968",
"branch": "1",
"accountNumber": "0013887580"
}
}
}

5. payment.sent (removed)

Removed in v1.28.0 (2026-04-17)

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)

Removed in v1.28.0 (2026-04-17)

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:

{
"id": "pix-refund-9ccd1869-7593-4feb-9602-e525e818ab8e",
"type": "pix.refund.completed",
"occurredAt": "2025-12-29T21:14:53.900Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"status": "SUCCESS",
"endToEnd": "D0000000020251229211453900",
"transactionId": "162982-pix",
"amount": 150.50,
"currency": "BRL",
"description": "",
"identifier": "refund-999",
"originalTransactionId": "pix-in-E0000000020251229211433912",
"initiatedAt": "2025-12-29T21:14:33.900Z",
"completedAt": "2025-12-29T21:14:53.900Z",
"payer": {
"name": "Your Company",
"document": "12345678000199",
"bankCode": "999",
"branch": "0001",
"accountNumber": "98765-4"
},
"payee": {
"name": "John Smith",
"document": "12345678900",
"bankCode": "001",
"branch": "0001",
"accountNumber": "12345-6"
}
}
}

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 (error is the friendly alias).
  • partner: raw settlement-bank error, when available.

This event does not send originalEndToEnd, refundEndToEnd, or reconciliationId.

Full Example:

{
"id": "pix-refund-9ccd1869-7593-4feb-9602-e525e818ab8e",
"type": "pix.refund.failed",
"occurredAt": "2025-12-29T21:14:35.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"paymentId": "9ccd1869-7593-4feb-9602-e525e818ab8e",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"status": "FAILED",
"endToEnd": "E0000000020251229211433912",
"transactionId": "162982-pix",
"amount": 150.50,
"currency": "BRL",
"description": "",
"identifier": "refund-998",
"originalTransactionId": "pix-in-E0000000020251229211433912",
"initiatedAt": "2025-12-29T21:14:33.900Z",
"completedAt": "2025-12-29T21:14:35.000Z",
"error": "Original transaction has already been refunded",
"errorCode": "already_refunded",
"errorReason": "Original transaction has already been refunded",
"payer": {
"name": "Your Company",
"document": "12345678000199",
"bankCode": "999",
"branch": "0001",
"accountNumber": "98765-4"
},
"payee": {
"name": "John Smith",
"document": "12345678900",
"bankCode": "001",
"branch": "0001",
"accountNumber": "12345-6"
}
}
}

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:

{
"id": "evt_fee_123",
"type": "fee.charged",
"occurredAt": "2026-02-14T20:30:43.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"transactionId": "fee-9c1f...e2",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"amount": 2.99,
"description": "TARIFA",
"feeServiceType": "PIX",
"originalRef": "tx_38a1b2",
"transactionRef": "tx_38a1b2",
"occurredAt": "2026-02-14T20:30:43.000Z",
"status": "SUCCESS",
"kind": "CHARGED"
}
}

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).

{
"id": "evt_fee_456",
"type": "fee.refunded",
"occurredAt": "2026-02-15T13:42:11.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"transactionId": "fee-7c2a...11",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"amount": 2.99,
"description": "LANÇAMENTO DE CRÉDITO",
"feeServiceType": "PIX",
"originalRef": "fee-9c1f...e2",
"occurredAt": "2026-02-15T13:42:11.000Z",
"status": "SUCCESS",
"kind": "REFUNDED"
}
}

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: endToEndId of 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: OPEN on filing.

Full Example:

{
"id": "evt_med_123",
"type": "pix.med.opened",
"occurredAt": "2026-07-21T17:55:59.601Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"medId": "c40a8974-4b4c-47c5-9d4b-81376e9071c6",
"originalEndToEnd": "E0000000020251229211433912",
"amount": 150.50,
"reasonCode": "scam-or-fraud",
"claimMessage": "See contacts provided in FundsRecovery",
"openedAtIso": "2026-07-21T17:55:59.601Z",
"clientAnswerDeadlineIso": "2026-07-23T17:55:59.601Z",
"status": "OPEN"
}
}

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 as pix.med.opened).
  • originalEndToEnd: endToEndId of 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:

Settlement bank statusdata.status
under-client-analysis, receivedOPEN
client-analysis-delayPENDING_DECISION
closed-full-refund, closed-partial-refundACCEPTED
closed-no-refundREJECTED
canceledCANCELED

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:

{
"id": "evt_med_456",
"type": "pix.med.updated",
"occurredAt": "2026-07-24T01:15:03.410Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"medId": "c40a8974-4b4c-47c5-9d4b-81376e9071c6",
"originalEndToEnd": "E0000000020251229211433912",
"amount": 150.50,
"reasonCode": "scam-or-fraud",
"status": "CANCELED"
}
}

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: accept or refuse and the justification, from decided on.
  • infoRequest.message, infoDueAt: The review’s question and deadline, in info_requested.
  • lockStatus, lockedAmount: Current balance hold.
  • refund.amount, refund.endToEndId: The return of this event, in refund_*.
  • refundedTotal, remaining, refundPartial: Return totals.

Full example:

{
"id": "pix-med-review-c40a8974-4b4c-47c5-9d4b-81376e9071c6-refund_completed-1771598551000",
"type": "pix.med.review.updated",
"occurredAt": "2026-07-24T01:15:03.410Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"medId": "c40a8974-4b4c-47c5-9d4b-81376e9071c6",
"accountId": "acc_123456",
"reason": "refund_completed",
"reviewStatus": "in_execution",
"round": 1,
"decision": "accept",
"decisionMessage": "Pagador comprovou que não autorizou a transação.",
"infoRequest": null,
"infoDueAt": null,
"lockStatus": "unlocked",
"lockedAmount": 0,
"refund": { "amount": 150.50, "endToEndId": "D0000000020260724011503000000001" },
"refundedTotal": 150.50,
"remaining": 0,
"refundPartial": false
}
}

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 (format internal-{uuid}). Use it on GET /v1/accounts/{accountId}/statement.
  • amount: Amount received.
  • status: Always SUCCESS (internal transfers are atomic).
  • completedAt: Settlement timestamp.
  • identifier: Identifier the sender supplied on POST /transfers/internal* (when given). The same value arrives on both legs (transfer.internal.out and transfer.internal.in).
  • payerDescription / description: Description supplied by the sender.
  • source: The payer — name, taxId, providerAccountId and, when the account is managed by us, accountId and tenantId.
  • destination: The receiver, with the same fields.
  • payer / receiver: The same two parties, with document in place of taxId. They appear only when the transfer was initiated outside the API (the liquidator’s app or console). Kept for compatibility — prefer source/destination, which arrive from both origins.
Destination outside CorpX

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.

P2P order transfers

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:

{
"id": "evt_int_in_001",
"type": "transfer.internal.in",
"occurredAt": "2026-04-23T14:21:05.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "773107de-139e-48d1-9462-f4e88f251891",
"data": {
"transactionId": "internal-9d4a5b7c-1234-4abc-9876-abc123456789",
"amount": 500.00,
"status": "SUCCESS",
"completedAt": "2026-04-23T14:21:05.000Z",
"identifier": "int-transfer-12345",
"payerDescription": "Pagamento salário",
"source": {
"providerAccountId": "a1b2c3d4-...",
"tenantId": "tenant-acme",
"accountId": "e5f6g7h8-...",
"name": "EMPRESA ORIGEM LTDA",
"taxId": "12345678000199"
},
"destination": {
"providerAccountId": "b2c3d4e5-...",
"tenantId": "tenant-acme",
"accountId": "773107de-139e-48d1-9462-f4e88f251891",
"name": "MARIA SILVA",
"taxId": "12345678900"
}
}
}

14. transfer.internal.out

Sent to the account that sends an internal transfer. Same shape as transfer.internal.in, with two differences:

  • identifier is populated on both legs when you passed identifier in the original request (POST /v1/accounts/{accountId}/transfers/internal*). Use it to reconcile the transfer on your side.
  • description — if you passed description in the request, that same text comes back here (instead of the default Transferência Interna).

Example:

{
"id": "evt_int_out_001",
"type": "transfer.internal.out",
"occurredAt": "2026-04-23T14:21:05.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
"data": {
"transactionId": "internal-9d4a5b7c-1234-4abc-9876-abc123456789",
"amount": 500.00,
"status": "SUCCESS",
"completedAt": "2026-04-23T14:21:05.000Z",
"identifier": "int-transfer-12345",
"description": "Pagamento salário",
"source": {
"providerAccountId": "a1b2c3d4-...",
"tenantId": "tenant-acme",
"accountId": "a1b2c3d4-aaaa-bbbb-cccc-111122223333",
"name": "EMPRESA ORIGEM LTDA",
"taxId": "12345678000199"
},
"destination": {
"providerAccountId": "b2c3d4e5-...",
"tenantId": "tenant-acme",
"accountId": "773107de-139e-48d1-9462-f4e88f251891",
"name": "MARIA SILVA",
"taxId": "12345678900"
}
}
}
How to reconcile an internal transfer

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. Carries owner: "partner" and reason (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.
{
"id": "evt_pix_out_timeout_001",
"type": "pix.out.timeout",
"occurredAt": "2026-05-04T10:42:11.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"paymentId": "pay_9ccd1869-7593-4feb-9602-e525e818ab8e",
"transactionId": "162982-pix",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"endToEnd": "E0000000020260504104211",
"amount": 250.00,
"currency": "BRL",
"status": "TIMEOUT",
"errorCode": "confirmation_timeout",
"errorReason": "partner response timed out. The call to send the money was accepted, but the final status confirmation has not arrived yet.",
"error": "partner response timed out. The call to send the money was accepted, but the final status confirmation has not arrived yet.",
"warning": "partner response timed out. The call to send the money was accepted, but the final status confirmation has not arrived yet.",
"identifier": "order-12345",
"partnerStatus": "awaiting-authorization",
"partnerStatusId": 7,
"hold": {
"owner": "partner",
"reason": "partner_authorization"
}
}
}

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.completed with late: true — the money left the account.
  • pix.out.failed with late: 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".
{
"id": "evt_pix_refund_recv_001",
"type": "pix.refund.received",
"occurredAt": "2026-05-04T11:11:43.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"transactionId": "pix-refund-received-D2026050420260504...",
"refundEndToEnd": "D2026050420260504000000001",
"originalEndToEnd": "E0000000020260503100000001",
"originalIdentifier": "client-refund-key-001",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"amount": 320.00,
"description": "PIX refund",
"receivedAt": "2026-05-04T11:11:43.000Z",
"payer": {
"name": "João Silva",
"document": "12345678901",
"bankCode": "341",
"bankIspb": "60701190",
"branch": "0001",
"accountNumber": "12345-6"
},
"payee": {
"name": "Acme Corp LTDA",
"document": "12345678000199",
"bankCode": "681",
"bankIspb": "50871921",
"branch": "0001",
"accountNumber": "98765-4"
},
"status": "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 in qrcode.paid.
  • amount: Amount that was awaiting payment.
  • status: Always "EXPIRED".
{
"id": "qrcode-expired-qr_abc123",
"type": "qrcode.expired",
"occurredAt": "2026-05-04T12:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"qrcodeId": "qr_abc123",
"identifier": "qr_abc123",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"type": "dynamic",
"amount": 99.90,
"status": "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 in qrcode.paid.
  • status: Always "CANCELLED".
  • reason / cancelledBy: Present when the cancellation carries a reason and who cancelled it.
{
"id": "qrcode-cancelled-qr_abc123",
"type": "qrcode.cancelled",
"occurredAt": "2026-05-04T11:45:30.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"qrcodeId": "qr_abc123",
"identifier": "qr_abc123",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"type": "dynamic",
"status": "CANCELLED",
"reason": "cancelled_by_integrator",
"cancelledBy": "integrator"
}
}

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 by POST /boleto/pay. Use this to correlate. The envelope id is boleto-{paymentId}.
  • boletoId: Alias of paymentId (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.

{
"id": "boleto-bol_aabbccdd",
"type": "boleto.paid",
"occurredAt": "2026-05-04T15:00:11.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"paymentId": "bol_aabbccdd",
"boletoId": "bol_aabbccdd",
"partnerId": "op-ref-99887766",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"amount": 1234.50,
"line": "00190.00009 03450.000004 47018.500003 1 88880000123450",
"status": "SUCCESS"
}
}

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.

{
"id": "boleto-bol_eeffgghh",
"type": "boleto.failed",
"occurredAt": "2026-05-04T15:00:11.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"paymentId": "bol_eeffgghh",
"boletoId": "bol_eeffgghh",
"partnerId": "op-ref-99887766",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"amount": 1234.50,
"line": "00190.00009 03450.000004 47018.500003 1 88880000123450",
"status": "FAILED",
"error": "Boleto vencido — emitir nova cobrança",
"errorReason": "Boleto vencido — emitir nova cobrança"
}
}

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.

{
"id": "evt_ted_out_requested_001",
"type": "ted.out.requested",
"occurredAt": "2026-05-23T09:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"tedId": "ted-fornecedor-acme-001",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"identifier": "ted-fornecedor-acme-001",
"partnerId": "",
"amount": 5000.00,
"destination": {
"bankCode": "001",
"branch": "1234",
"account": "56789",
"accountType": "CHECKING",
"taxNumber": "12345678900",
"holderName": "JOAO DA SILVA"
},
"description": "Pagamento de fornecedor NF 12345"
}
}

22. ted.out.confirmed

Settlement confirmed by the settlement bank (terminal — success).

{
"id": "evt_ted_out_confirmed_001",
"type": "ted.out.confirmed",
"occurredAt": "2026-05-23T09:32:15.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"tedId": "ted-fornecedor-acme-001",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"identifier": "ted-fornecedor-acme-001",
"partnerId": "fornecedor-acme-001",
"amount": 5000.00,
"destination": { "bankCode": "001", "branch": "1234", "account": "56789", "accountType": "CHECKING", "taxNumber": "12345678900", "holderName": "JOAO DA SILVA" },
"description": "Pagamento de fornecedor NF 12345"
}
}

Deprecated alias: the ted.payment event is dispatched in parallel with ted.out.confirmed with the same payload, kept only for compatibility with legacy subscriptions. New integrators should subscribe to ted.out.confirmed only. ted.payment will be removed in v3.0.

23. ted.out.failed

Settlement rejected/expired (terminal — failure). data.errorReason carries the canonical reason.

{
"id": "evt_ted_out_failed_001",
"type": "ted.out.failed",
"occurredAt": "2026-05-23T09:40:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"tedId": "ted-fornecedor-acme-001",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"identifier": "ted-fornecedor-acme-001",
"partnerId": "fornecedor-acme-001",
"amount": 5000.00,
"destination": { "bankCode": "999", "branch": "1234", "account": "56789", "accountType": "CHECKING", "taxNumber": "12345678900", "holderName": "JOAO DA SILVA" },
"description": "Pagamento de fornecedor NF 12345",
"errorReason": "invalid_bank_code",
"error": "invalid_bank_code"
}
}

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.

{
"id": "evt_ted_in_received_001",
"type": "ted.in.received",
"occurredAt": "2026-05-23T14:15:22.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"transactionId": "abc123def",
"identifier": "TED-9876",
"partnerTxId": "abc123def",
"accountId": "acc_123456",
"tenantId": "tenant-acme",
"amount": 1200.00,
"description": "Pagamento recebido",
"receivedAt": "2026-05-23T14:15:22Z",
"payer": {
"name": "EMPRESA XYZ LTDA",
"document": "98765432000110",
"bankCode": "237",
"bankIspb": "60746948",
"bankName": "BANCO BRADESCO S.A.",
"branch": "0001",
"account": "123456",
"accountNumber": "123456"
},
"payee": {
"name": "YOUR COMPANY LTDA",
"document": "12345678000195",
"bankCode": "681",
"bankIspb": "50871921",
"branch": "0001",
"account": "6371893",
"accountNumber": "6371893"
}
}
}

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.

{
"id": "evt_policy_violation_001",
"type": "policy.violation",
"occurredAt": "2026-05-23T22:41:10.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"phase": "counterparty",
"action": "BLOCK",
"blocked": true,
"paymentId": "pay_9f2c...",
"accountId": "acc_123456",
"identifier": "ORDER-1234",
"mode": "KEY",
"amount": 5000.00,
"violations": [
{ "rule": "cpfCnpjBlacklist", "message": "recipient document is blacklisted by policy" }
],
"counterparty": { "document": "12345678900", "name": "JOHN DOE" }
}
}
FieldDescription
phaseedge (rejected in the response, HTTP 422), counterparty (after resolving the recipient, during processing), pix_in, ted_in, internal_in, boleto_in (after the credit), med (a received dispute pushed the MED rate above the ceiling), or dict_lookup (key lookup rejected by limit)
actionBLOCK, NOTIFY_ONLY, ALLOW_AND_NOTIFY, AUTO_REFUND, LOCK_BALANCE, or BLOCK_ACCOUNT, as configured in the policy
blockedtrue when the operation was actually rejected. Always false on a cash-in
balanceLockedOn a cash-in, true when that credit’s amount was locked at the settlement bank. false if the action was requested and did not complete
accountBlockedOn a cash-in, true when this violation set the account to blocked. false if the action was requested and did not complete
modeKEY, BANK_ACCOUNT, QRCODE, or REFUND on PIX out; the operation subtype in the other sections (static/dynamic for QR, the key type, the incoming PIX method)
violations[].rulePIX out rules carry no prefix (pixOutDisabled, cpfCnpjBlacklist, sameOwnershipOnly, operatingHours, allowedPersonTypes); the other sections are prefixed (pixIn.*, qrCode.*, keys.*, refund.*) or dictLookup.*. PIX out maxAmount and nightMaxAmount are no longer emitted — an amount refusal is limit_exceeded_transaction
counterpartyThe recipient (PIX out) or the payer (PIX in), when known

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.

{
"phase": "pix_in",
"action": "AUTO_REFUND",
"blocked": false,
"refunded": true,
"transactionId": "tx_8a1b...",
"accountId": "acc_123456",
"endToEnd": "E18236120202607291230abcdef1234",
"amount": 5000.00,
"mode": "DICT",
"violations": [
{ "rule": "pixIn.cpfCnpjBlacklist", "message": "payer document is blacklisted by policy" }
],
"counterparty": { "document": "12345678900", "name": "JOHN DOE", "bankCode": "260" }
}

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.

{
"phase": "med",
"action": "BLOCK_ACCOUNT",
"blocked": false,
"accountBlocked": true,
"balanceLocked": false,
"refunded": false,
"accountId": "acc_123456",
"medId": "med_7f3a...",
"identifier": "med_7f3a...",
"windowDays": 30,
"medCount": 12,
"criticalMedCount": 4,
"pixInCount": 800,
"ratePercent": 1.5,
"criticalRatePercent": 0.5,
"violations": [
{ "rule": "med.critical.maxRatePercent", "message": "critical MED rate 0.50% (4 of 800 PIX in) reached the policy limit of 0.30%" }
]
}

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.

{
"id": "bankslip-slip-1-registered",
"type": "boleto.charge.registered",
"occurredAt": "2026-09-23T18:05:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"chargeId": "slip-1",
"identifier": "pedido-1001",
"accountId": "acc_123456",
"status": "open",
"registrationCondition": "registered",
"nominalAmount": 150.0,
"updatedAmount": 150.0,
"barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
"digitableLine": "23793381286000000000300000000400184340000015000",
"dueDate": "2026-10-15"
}
}

27. boleto.charge.registration_failed

Registration of the slip was rejected. statusReason carries the reason when the bank provides one.

{
"id": "bankslip-slip-1-registration_failed",
"type": "boleto.charge.registration_failed",
"occurredAt": "2026-09-23T18:06:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"chargeId": "slip-1",
"identifier": "pedido-1001",
"accountId": "acc_123456",
"status": "open",
"registrationCondition": "rejected",
"statusReason": "invalid payer",
"nominalAmount": 150.0,
"updatedAmount": 150.0,
"barcode": "",
"digitableLine": "",
"dueDate": "2026-10-15"
}
}

28. boleto.charge.settled

The slip was paid. The credit also shows on the statement as BOLETO.

{
"id": "bankslip-slip-1-settled",
"type": "boleto.charge.settled",
"occurredAt": "2026-10-10T14:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"chargeId": "slip-1",
"identifier": "pedido-1001",
"accountId": "acc_123456",
"status": "settled",
"registrationCondition": "registered",
"nominalAmount": 150.0,
"updatedAmount": 150.0,
"barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
"digitableLine": "23793381286000000000300000000400184340000015000",
"dueDate": "2026-10-15",
"payment": { "amount": 150.0, "settledAt": "2026-10-10T14:00:00Z" }
}
}

29. boleto.charge.overdue

The due date passed and the slip is still open. This is not a terminal state.

{
"id": "bankslip-slip-1-overdue",
"type": "boleto.charge.overdue",
"occurredAt": "2026-10-16T03:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"chargeId": "slip-1",
"identifier": "pedido-1001",
"accountId": "acc_123456",
"status": "overdue",
"registrationCondition": "registered",
"nominalAmount": 150.0,
"updatedAmount": 152.5,
"barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
"digitableLine": "23793381286000000000300000000400184340000015000",
"dueDate": "2026-10-15"
}
}

30. boleto.charge.written_off

The slip was written off.

{
"id": "bankslip-slip-1-written_off",
"type": "boleto.charge.written_off",
"occurredAt": "2026-10-20T12:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"chargeId": "slip-1",
"identifier": "pedido-1001",
"accountId": "acc_123456",
"status": "writtenOff",
"registrationCondition": "registered",
"nominalAmount": 150.0,
"updatedAmount": 150.0,
"barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
"digitableLine": "23793381286000000000300000000400184340000015000",
"dueDate": "2026-10-15"
}
}

31. boleto.charge.cancelled

The slip was cancelled.

{
"id": "bankslip-slip-1-cancelled",
"type": "boleto.charge.cancelled",
"occurredAt": "2026-10-12T12:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"chargeId": "slip-1",
"identifier": "pedido-1001",
"accountId": "acc_123456",
"status": "cancelled",
"registrationCondition": "registered",
"nominalAmount": 150.0,
"updatedAmount": 150.0,
"barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
"digitableLine": "23793381286000000000300000000400184340000015000",
"dueDate": "2026-10-15"
}
}

32. boleto.charge.expired

The payment window ended.

{
"id": "bankslip-slip-1-expired",
"type": "boleto.charge.expired",
"occurredAt": "2026-10-20T03:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"chargeId": "slip-1",
"identifier": "pedido-1001",
"accountId": "acc_123456",
"status": "expired",
"registrationCondition": "registered",
"nominalAmount": 150.0,
"updatedAmount": 150.0,
"barcode": "23793.38128 60000.000003 00000.000400 1 84340000015000",
"digitableLine": "23793381286000000000300000000400184340000015000",
"dueDate": "2026-10-15"
}
}

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.

{
"id": "bankslip-slip-1-failed",
"type": "boleto.charge.failed",
"occurredAt": "2026-09-23T18:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"chargeId": "slip-1",
"identifier": "pedido-1001",
"accountId": "acc_123456",
"status": "open",
"registrationCondition": "pendingRegistration",
"nominalAmount": 150.0,
"updatedAmount": 0,
"barcode": "",
"digitableLine": "",
"dueDate": "2026-10-15"
}
}

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.

{
"id": "bchg-batch-bcb_01J8Y7C8D9E0F1G2H3J4-completed",
"type": "boleto.charge.batch.completed",
"occurredAt": "2026-09-24T14:12:40.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"batchId": "bcb_01J8Y7C8D9E0F1G2H3J4",
"accountId": "acc_123456",
"status": "PARTIAL_FAILED",
"statistics": {
"total": 100,
"issued": 97,
"failed": 3
}
}
}

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.

{
"id": "bchg-beneficiary-d4a1f2b3-6c9e-4a11-9f0d-7e5c1a2b3c4d",
"type": "boleto.charge.beneficiary.approved",
"occurredAt": "2026-11-01T15:32:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"accountId": "acc_123456",
"beneficiaryId": "9c858901-8a57-4791-81fe-4c455b099bc9",
"operation": "INCLUSION",
"result": "CONFIRMED",
"operationId": "b3f1a2d4-6c9e-4a11-9f0d-7e5c1a2b3c4d",
"occurredAt": "2026-11-01T15:32:00Z",
"identifier": "0000123456",
"reactivated": false
}
}

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.

{
"id": "bchg-beneficiary-5e2b3c4d-7d0f-4b22-8a1e-8f6d2b3c4d5e",
"type": "boleto.charge.beneficiary.rejected",
"occurredAt": "2026-11-01T15:40:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"accountId": "acc_123456",
"beneficiaryId": "9c858901-8a57-4791-81fe-4c455b099bc9",
"operation": "INCLUSION",
"result": "REJECTED",
"operationId": "b3f1a2d4-6c9e-4a11-9f0d-7e5c1a2b3c4d",
"occurredAt": "2026-11-01T15:40:00Z",
"rejectionCode": "BENEFICIARY_DATA_MISMATCH",
"rejectionReason": "Beneficiary data does not match the provider's records."
}
}

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.

{
"id": "bchg-beneficiary-6f3c4d5e-8e1a-4c33-9b2f-9a7e3c4d5e6f",
"type": "boleto.charge.beneficiary.updated",
"occurredAt": "2026-11-02T10:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"accountId": "acc_123456",
"beneficiaryId": "9c858901-8a57-4791-81fe-4c455b099bc9",
"operation": "STATUS_UPDATE",
"result": "CONFIRMED",
"operationId": "c4a2b3e5-7d0f-4b22-8a1e-8f6d2b3c4d5e",
"occurredAt": "2026-11-02T10:00:00Z",
"previousStatus": "ELIGIBLE",
"currentStatus": "UNDER_REVIEW",
"updatedAt": "2026-11-02T10:00:00Z"
}
}

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.

{
"id": "bchg-beneficiary-7a4d5e6f-9f2b-4d44-8c3a-0b8f4d5e6f7a",
"type": "boleto.charge.beneficiary.closed",
"occurredAt": "2026-11-03T12:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"accountId": "acc_123456",
"beneficiaryId": "9c858901-8a57-4791-81fe-4c455b099bc9",
"operation": "TERMINATION",
"result": "CONFIRMED",
"operationId": "d5b3c4f6-8e1a-4c33-9b2f-9a7e3c4d5e6f",
"occurredAt": "2026-11-03T12:00:00Z",
"relationshipStatus": "CLOSED",
"closedAgreementsCount": 2,
"issuanceBlocked": true,
"closedAt": "2026-11-03T12:00:00Z"
}
}

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 by POST /v1/identity-verifications;
  • status: APPROVED, FAILED, or EXPIRED;
  • purpose and referenceId: exact binding supplied at creation;
  • document: 11-digit CPF;
  • failureReason: normalized failure/expiry reason; null on approval;
  • completedAt: terminal instant in UTC;
  • consumableUntil: approval consumption deadline; omitted for other states;
  • method: link (hosted page) or facetec_sdk (SDK embedded in the app);
  • referenceMatch and checks: only for facetec_sdk. checks.liveness is the liveness result and checks.faceMatch.result the 1:1 face match result (not_performed when referenceMatch is none — the approval only proves a live person was present, not who they are).
{
"id": "idv-idv_01J8Y7C8D9E0F1G2H3J4-completed",
"type": "identity.verification.completed",
"occurredAt": "2026-09-24T14:08:12.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"data": {
"verificationId": "idv_01J8Y7C8D9E0F1G2H3J4",
"status": "APPROVED",
"purpose": "password_reset",
"referenceId": "usr_01J8Y6N7M8P9Q0R1S2T3",
"document": "12345678909",
"failureReason": null,
"completedAt": "2026-09-24T14:08:12.000Z",
"consumableUntil": "2026-09-24T14:18:12.000Z",
"method": "facetec_sdk",
"referenceMatch": "dracma",
"checks": {
"liveness": "passed",
"faceMatch": { "result": "passed", "reference": "dracma" }
}
}
}

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.

{
"id": "pix-batch-pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8-completed",
"type": "pix.batch.completed",
"occurredAt": "2026-09-30T13:12:40.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"batchId": "pxb_3f9c2a1b7d4e5f60718293a4b5c6d7e8",
"accountId": "acc_123456",
"status": "PARTIAL_FAILED",
"statistics": {
"total": 100,
"completed": 97,
"failed": 3,
"totalAmount": "143685.00",
"completedAmount": "139380.50",
"failedAmount": "4304.50"
}
}
}

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.

{
"id": "lr-lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V-approved",
"type": "limit_request.updated",
"occurredAt": "2026-10-02T19:10:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"id": "lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V",
"accountId": "acc_123456",
"status": "approved",
"operation": "pix_out",
"window": "daytime",
"requestedLimitBrl": 50000,
"approvedLimitBrl": 40000,
"decisionMessage": "Approved in part.",
"effectiveAt": null,
"actingDocument": "39053344705",
"identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21"
}
}

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.

{
"id": "lr-lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V-pending_review",
"type": "limit_request.created",
"occurredAt": "2026-10-02T18:00:01.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"id": "lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V",
"accountId": "acc_123456",
"status": "pending_review",
"operation": "pix_out",
"window": "daytime",
"requestedLimitBrl": 50000,
"approvedLimitBrl": null,
"decisionMessage": null,
"effectiveAt": null,
"actingDocument": "39053344705",
"identifier": "3f1c0b6e-9a2d-4c71-8e55-1b7a0d4c9e21",
"currentLimitBrl": 20000,
"justification": "Monthly payroll.",
"channel": "api"
}
}
FieldMeaning
currentLimitBrlEffective ceiling of the window when the request opened.
justificationText from the requester, up to 500 characters.
channelapi or backoffice.

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.

{
"id": "alev_01J9XQ9LIMITAUDIT0001",
"type": "account.limits.updated",
"occurredAt": "2026-10-02T19:10:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"accountId": "acc_123456",
"subject": { "type": "account" },
"source": "limit_request",
"limitRequestId": "lr_01J9XQ8K2M3N4P5Q6R7S8T9U0V",
"changes": [
{
"operation": "pix_out",
"window": "daytime",
"beforeBrl": 20000,
"afterBrl": 40000,
"effectiveAt": null,
"materializedFromLegacy": false
},
{
"operation": "pix_out",
"window": "nighttime",
"beforeBrl": 0,
"afterBrl": 5000,
"effectiveAt": null,
"materializedFromLegacy": true
}
]
}
}
FieldMeaning
subject.typeaccount or operator. For an operator, subject.document is the CPF.
sourcestaff, internal, limit_request or owner.
limitRequestIdPresent only when the change came from a request.
changes[].windowsingle_transfer, daytime, nighttime or monthly.
beforeBrl / afterBrlOwn ceiling before and after. 0 before means the cell did not exist.
effectiveAtnull when it already applies. Set when an operator increase waits 6 h.
materializedFromLegacytrue when the window was copied from the previous register in the same write.

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.

data.statusWhere it appears
awaiting_authorization, authorization_received, authorized, rejected, request_failed, authorization_failed, canceled, expiredRecurrence
created, received, awaiting_confirmation, confirmed, rejected, confirmation_failed, settled, canceled, expiredScheduling
balance_reserved, insufficient_balance, settled, settled_with_error, not_settled, not_settled_with_errorSettlement data.settlementStatus

40. pix.automatic.recurrence.authorized

The payer authorized the recurrence in their bank app. From now on you can schedule charges.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-recurrence.authorized-authorized",
"type": "pix.automatic.recurrence.authorized",
"occurredAt": "2026-11-03T14:02:11.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
"accountId": "acc_123456",
"status": "authorized",
"frequency": "monthly",
"occurredAt": "2026-11-03T14:02:11Z"
}
}

41. pix.automatic.recurrence.rejected

The payer or their bank rejected the recurrence. rejectionReason is present when the bank provides a reason.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-recurrence.rejected-rejected",
"type": "pix.automatic.recurrence.rejected",
"occurredAt": "2026-11-03T14:02:11.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
"accountId": "acc_123456",
"status": "rejected",
"frequency": "monthly",
"rejectionReason": "payer_rejected",
"occurredAt": "2026-11-03T14:02:11Z"
}
}

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).

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-recurrence.expired-expired",
"type": "pix.automatic.recurrence.expired",
"occurredAt": "2026-11-10T03:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"accountId": "acc_123456",
"status": "expired",
"frequency": "monthly",
"occurredAt": "2026-11-10T03:00:00Z"
}
}

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.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-recurrence.failed-request_failed",
"type": "pix.automatic.recurrence.failed",
"occurredAt": "2026-11-03T14:00:40.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"accountId": "acc_123456",
"status": "request_failed",
"frequency": "monthly",
"occurredAt": "2026-11-03T14:00:40Z"
}
}

44. pix.automatic.scheduling.confirmed

The payer’s bank confirmed the charge scheduling. schedulingId is the id returned by POST .../recurrences/{recurrenceId}/schedulings.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-scheduling.confirmed-E5087192120261123100000000000001-confirmed",
"type": "pix.automatic.scheduling.confirmed",
"occurredAt": "2026-11-21T10:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
"accountId": "acc_123456",
"schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
"endToEndId": "E5087192120261123100000000000001",
"dueDate": "2026-11-25",
"amount": 149.9,
"status": "confirmed",
"purpose": "scheduling",
"occurredAt": "2026-11-21T10:00:00Z"
}
}

45. pix.automatic.scheduling.rejected

The payer’s bank rejected the scheduling. errorCode and errorMessage are present when provided.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-scheduling.rejected-E5087192120261123100000000000001-rejected",
"type": "pix.automatic.scheduling.rejected",
"occurredAt": "2026-11-21T10:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"accountId": "acc_123456",
"schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
"endToEndId": "E5087192120261123100000000000001",
"dueDate": "2026-11-25",
"amount": 149.9,
"status": "rejected",
"errorCode": "AM05",
"errorMessage": "Cobrança duplicada no ciclo",
"occurredAt": "2026-11-21T10:00:00Z"
}
}

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.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-scheduling.failed-E5087192120261123100000000000001-expired",
"type": "pix.automatic.scheduling.failed",
"occurredAt": "2026-11-24T03:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
"accountId": "acc_123456",
"schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
"endToEndId": "E5087192120261123100000000000001",
"dueDate": "2026-11-25",
"amount": 149.9,
"status": "expired",
"purpose": "scheduling",
"occurredAt": "2026-11-24T03:00:00Z"
}
}

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.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-settlement.completed-E5087192120261123100000000000001-settled",
"type": "pix.automatic.settlement.completed",
"occurredAt": "2026-11-25T09:12:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
"accountId": "acc_123456",
"schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
"settlementId": "5a2c9e10-8b7d-4f0e-a1c3-6d2b9f4e7a01",
"endToEndId": "E5087192120261123100000000000001",
"dueDate": "2026-11-25",
"amount": 149.9,
"status": "settled",
"settlementStatus": "settled",
"purpose": "scheduling",
"occurredAt": "2026-11-25T09:12:00Z"
}
}

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.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-settlement.failed-E5087192120261123100000000000001-insufficient_balance",
"type": "pix.automatic.settlement.failed",
"occurredAt": "2026-11-25T09:12:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
"accountId": "acc_123456",
"schedulingId": "0b1e7d6c-2f43-4c1a-9d55-3c1f0e2a7b88",
"settlementId": "5a2c9e10-8b7d-4f0e-a1c3-6d2b9f4e7a01",
"endToEndId": "E5087192120261123100000000000001",
"dueDate": "2026-11-25",
"amount": 149.9,
"status": "confirmed",
"settlementStatus": "insufficient_balance",
"purpose": "scheduling",
"occurredAt": "2026-11-25T09:12:00Z"
}
}

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.*.

{
"id": "pixauto-f6c7cb5e-7dca-4195-bbbc-edda5c3868d9-qrcode.paid-E0000000020261103140000000000001",
"type": "pix.automatic.qrcode.paid",
"occurredAt": "2026-11-03T14:00:00.000Z",
"schemaVersion": "1.0",
"environment": "production",
"tenantId": "tenant-acme",
"accountId": "acc_123456",
"data": {
"recurrenceId": "f6c7cb5e-7dca-4195-bbbc-edda5c3868d9",
"recurrenceIdentifier": "RR5087192120261103a1b2c3d4e5f",
"accountId": "acc_123456",
"status": "awaiting_authorization",
"qrIdentifier": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"endToEndId": "E0000000020261103140000000000001",
"amount": 49.9,
"paidAt": "2026-11-03T14:00:00Z"
}
}

Best Practices

  • Idempotency: Your application should be prepared to receive the same webhook more than once. Use the envelope id to avoid duplicate processing.
  • Quick Response: Return a 200 OK status as soon as you receive the webhook and process the business logic asynchronously to avoid timeouts.
  • Timestamp Validation: Check that the occurredAt is not too old (we recommend a 5-minute tolerance) to prevent replay attacks.