Skip to main content

Webhooks

Your account can be configured so that when certain events occur on your account, a HTTP POST request containing JSON data pertaining to that event is sent to one or more URLs of your choosing. These URLs can be configured inside your settings making a request to our team. Notifications of all events listed below are sent to all the configured URLs.


Types of webhooks​

TypeDescription
PAYMENTWhen you send a pix payment.
PAYMENT FAILEDWhen you send a pix payment and it fails.
DEVOLUTIONWhen you send a pix devolution.
DEVOLUTION FAILEDWhen you send a pix devolution and it fails.
DEVOLUTION RECEIVEDWhen receive a pix devolution.
DEVOLUTION RECEIVED FAILEDWhen a received pix devolution fails.
DEPOSITWhen receive a pix deposit.
DEPOSIT RECEIVED FAILEDWhen a received pix deposit fails.
ONBOARDING FINISHEDWhen you create a new user onboarding and it is approved.
ONBOARDING REJECTEDWhen you create a new user onboarding and it is rejected.
ONBOARDING FAILEDWhen onboarding processing fails due to an internal or provider-side error.
ONBOARDING LEGAL REPRESENTATIVE LIVENESS RELEASEDWhen the liveness links of the legal representatives are created (link method only).
ONBOARDING LEGAL REPRESENTATIVE LIVENESS UPDATEDWhen a legal representative's liveness progresses (only APPROVED with the link; progress and results with video upload).
ONBOARDING NATURAL PERSON LIVENESS RELEASEDWhen the liveness link of a natural person onboarding is created (link method only).
ONBOARDING NATURAL PERSON LIVENESS UPDATEDWhen the account holder's liveness progresses (only APPROVED with the link; progress and results with video upload).
MERCHANT ONBOARDING KYC STATUSWhen merchant onboarding KYC status is updated.
COMPANY REGISTRATION ONBOARDING STATUS UPDATEDWhen company registration changes status, including states that require new documents or corrections.
COMPANY REGISTRATION ONBOARDING APPROVEDWhen company registration is approved and becomes active.
WALLET ACCOUNT BALANCE UPDATEDWhen the balance is updated.
PIX REFUND OPENWhen a Pix refund request is opened by the receiving PSP.
PIX REFUND PENDINGWhen a Pix refund request is pending processing.
PIX REFUND WAITINGWhen a Pix refund request is waiting for the PSP's response.
PIX REFUND CLOSEDWhen a Pix refund request is closed and the funds are returned.
PIX REFUND CANCELEDWhen a Pix refund request is canceled.
PIX REFUND FAILEDWhen a Pix refund request fails.
PIX FUND RECOVERY REQUEST CREATEDWhen a Pix fund recovery request is created.
PIX FUND RECOVERY REQUEST ANALYSEDWhen a Pix fund recovery request has been analysed.
PIX FUND RECOVERY REQUEST COMPLETED APPROVEDWhen a Pix fund recovery request is completed and approved.
PIX FUND RECOVERY REQUEST COMPLETED REJECTEDWhen a Pix fund recovery request is completed and rejected.
PIX FUND RECOVERY REQUEST CANCELEDWhen a Pix fund recovery request is canceled.
PIX FUND RECOVERY REQUEST FAILEDWhen a Pix fund recovery request fails.
PIX AUTOMATIC RECURRENCE CREATEDWhen a Pix automatic recurrence is created.
PIX AUTOMATIC RECURRENCE FAILEDWhen a Pix automatic recurrence creation fails.
PIX AUTOMATIC RECURRENCE APPROVEDWhen a Pix automatic recurrence is approved.
PIX AUTOMATIC RECURRENCE REJECTEDWhen a Pix automatic recurrence is rejected.
PIX AUTOMATIC RECURRENCE CANCELEDWhen a Pix automatic recurrence is canceled.
PIX AUTOMATIC RECURRENCE CANCELED FAILEDWhen a Pix automatic recurrence cancellation fails.
PIX AUTOMATIC RECURRENCE EXPIREDWhen a Pix automatic recurrence expires after the request expiration date.
PIX AUTOMATIC RECURRENCE FINISHEDWhen a Pix automatic recurrence reaches its end date.
PIX AUTOMATIC AUTHORIZATION PENDINGWhen a Pix automatic authorization is pending user approval.
PIX AUTOMATIC AUTHORIZATION APPROVEDWhen a Pix automatic authorization is approved.
PIX AUTOMATIC AUTHORIZATION REJECTEDWhen a Pix automatic authorization is rejected.
PIX AUTOMATIC AUTHORIZATION CANCELEDWhen a Pix automatic authorization is canceled.
PIX AUTOMATIC AUTHORIZATION FINISHEDWhen a Pix automatic authorization is finished.
PIX AUTOMATIC AUTHORIZATION APPROVED FAILEDWhen a Pix automatic authorization approval fails.
PIX AUTOMATIC AUTHORIZATION REJECTED FAILEDWhen a Pix automatic authorization rejection fails.
PIX AUTOMATIC AUTHORIZATION CANCELED FAILEDWhen a Pix automatic authorization cancellation fails.
PIX AUTOMATIC AUTHORIZATION UPDATED CONFIRMEDWhen a Pix automatic authorization max value update is confirmed.
PIX AUTOMATIC AUTHORIZATION UPDATED FAILEDWhen a Pix automatic authorization max value update fails.
PIX AUTOMATIC CHARGE CREATEDWhen a Pix automatic charge is created.
PIX AUTOMATIC CHARGE CREATED FAILEDWhen a Pix automatic charge creation fails.
PIX AUTOMATIC CHARGE PAIDWhen a Pix automatic charge is paid.
PIX AUTOMATIC CHARGE NOT PAIDWhen a Pix automatic charge is not paid.
PIX AUTOMATIC CHARGE CANCELEDWhen a Pix automatic charge is canceled.
PIX AUTOMATIC CHARGE CANCELED FAILEDWhen a Pix automatic charge cancellation fails.
PIX AUTOMATIC PAYMENT CREATEDWhen a Pix automatic payment is created.
PIX AUTOMATIC PAYMENT CANCELLATION FAILEDWhen a Pix automatic payment cancellation fails.
PIX AUTOMATIC PAYMENT CANCELEDWhen a Pix automatic payment is canceled.
BANKING BILLET PIX DEPOSIT CREATED CONFIRMEDWhen a Bolepix is created and the Pix QR code is confirmed.
BANKING BILLET PIX DEPOSIT CREATED FAILEDWhen a Bolepix creation fails during billet registration or QR code generation.
BANKING BILLET PIX DEPOSIT RECEIVEDWhen a Bolepix payment is received.
BANKING BILLET PIX DEPOSIT BATCH REJECTEDWhen a batch of Bolepix is rejected during validation.
BANKING BILLET PIX DEPOSIT BATCH GENERATEDWhen a batch of Bolepix is successfully generated.
BANKING BILLET PIX DEPOSIT BATCH FAILEDWhen a batch of Bolepix fails to process.
BANKING TED RECEIVEDWhen you receive a TED (bank transfer) into your account.
BANKING TED SENTWhen a TED you sent changes status (waiting, forwarded, failed).
BANKING TED RECEIVED FRAUD ANALYSISWhen a received TED enters antifraud manual review.
BANKING TED RECEIVED FRAUD DECLINEDWhen a received TED is declined by the antifraud analysis.
BANKING TED SENT FRAUD ANALYSISWhen a TED you sent enters antifraud manual review.
BANKING TED SENT FRAUD DECLINEDWhen a TED you sent is declined by the antifraud analysis.
BANKING BILLET PAYMENT FRAUD ANALYSISWhen a billet payment you made enters antifraud manual review.
BANKING BILLET PAYMENT FRAUD DECLINEDWhen a billet payment you made is declined by the antifraud analysis.
PIX DEPOSIT FRAUD ANALYSISWhen a received Pix deposit enters antifraud analysis.
PIX DEPOSIT FRAUD DECLINEDWhen a received Pix deposit is blocked by the antifraud analysis.
PIX PAYMENT FRAUD ANALYSISWhen a Pix payment you sent enters antifraud manual review.
PIX PAYMENT FRAUD DECLINEDWhen a Pix payment you sent is declined by the antifraud analysis.
JUDICIAL BLOCK ACCOUNTWhen a court order blocks the user's account entirely.
JUDICIAL BLOCK ACCOUNT BALANCEWhen a court order blocks a specific amount from the user's account balance.
JUDICIAL UNBLOCK ACCOUNTWhen a court order unblocks the user's account.
JUDICIAL UNBLOCK ACCOUNT BALANCEWhen a court order releases a previously blocked balance amount.


Credentials (Not required)​

Each webhook registration can have one credential. You generate the credential value and share it with our team through a secure channel when you register the webhook. We send it in an HTTP header on every request to that webhook, exactly as registered.

TypeHeader we sendValue
Authorization BasicAuthorizationbase64 of username:password
Authorization BearerAuthorizationAPI key or token
Signature Verificationzro-signatureShared secret key
Custom headerHeader name of your choiceAPI key or token

No prefix such as Basic or Bearer is added. If your server expects one, include it in the value you register.



Verifying Webhook Requests​

When a credential is configured, webhook requests are authenticated only by its header:

  • The value is static: it is the same on every request and carries no timestamp or nonce.
  • No signature, such as an HMAC, is computed, and the payload is not signed. With the Signature Verification type, the zro-signature header carries the shared secret key itself.
  • The same mechanism applies to every webhook type. The credential is configured per webhook registration.

To verify a request, compare the header value with the credential you registered and reject the request if they differ:

const crypto = require('node:crypto');

const expected = Buffer.from(process.env.WEBHOOK_CREDENTIAL);

function isAuthenticWebhook(request) {
  // Node.js lowercases header names: use `zro-signature`, `authorization`
  // or your custom header name in lowercase.
  const received = Buffer.from(request.headers['zro-signature'] ?? '');

  return (
    received.length === expected.length &&
    crypto.timingSafeEqual(received, expected)
  );
}


Retry Policy​

A delivery succeeds when your endpoint responds with a 2xx status. A delivery fails when:

  • the response has any other status, including 4xx and 5xx;
  • no response arrives within the request timeout;
  • the connection fails (for example, DNS, TLS or connection refused).

Failed deliveries are retried only if a retry policy is configured for your webhook. Otherwise, each event is sent once. The policy defines:

  • Maximum attempts: the total number of deliveries, including the first one.
  • Initial interval and multiplier: each wait is the previous one multiplied by the multiplier, starting from the initial interval, with a random variation.
  • Maximum interval: the longest wait between two attempts. Once it is reached, the remaining attempts use this interval.

There is no setting for the total retry period. It results from the maximum attempts and the intervals.

Ask our team to set or confirm the retry policy and the request timeout when you register or update the webhook.

When the last attempt fails, the event is not sent again. Use the query endpoints to reconcile events you did not receive.

The same event can arrive more than once, for example when your endpoint processes it but responds after the timeout. Process webhooks idempotently.



Payloads (Version 1)​

{
  "id": "4b344f93-68fb-4ddc-83b4-6288eb7c63ce",
  "type": "PAYMENT",
  "end_to_end_id": "E26264220202404171729SrlHOwU3HqB",
  "txid": null,
  "operation_id": "0f0aca83-8ea1-5ecb-9fe9-d31782ef06fb",
  "amount": "270",
  "owner_name": "Z.ro Bolsao",
  "owner_person_type": "CNPJ",
  "owner_document": "00000000000000",
  "beneficiary_name": "Name",
  "beneficiary_person_type": "CPF",
  "beneficiary_document": "***000000**",
  "beneficiary_bank_name": "ZERO IP S/A",
  "beneficiary_bank_ispb": "26264220",
  "created_at": "2024-04-17T17:30:00.020Z"
}

Payloads (Version 2)​

{
  "id": "4b344f93-68fb-4ddc-83b4-6288eb7c63ce",
  "type": "PAYMENT",
  "end_to_end_id": "E26264220202404171729SrlHOwU3HqB",
  "txid": null,
  "operation_id": "0f0aca83-8ea1-5ecb-9fe9-d31782ef06fb",
  "amount": "270",
  "owner_name": "Z.ro Bolsao",
  "owner_person_type": "CNPJ",
  "owner_document": "00000000000000",
  "beneficiary_name": "Name",
  "beneficiary_person_type": "CPF",
  "beneficiary_document": "***000000**",
  "beneficiary_bank_name": "ZERO IP S/A",
  "beneficiary_bank_ispb": "26264220",
  "beneficiary_account_type": "CACC",
  "beneficiary_account_number": "000000",
  "beneficiary_branch_number": "0000",
  "created_at": "2024-04-17T17:30:00.020Z"
}

Payloads (Version 3)​

{
  "id": "a839f358-0e39-409e-b9a5-5a56b18ba3f2",
  "type": "DEPOSIT",
  "end_to_end_id": "E26264220202404171333Hq7F9SWyvUE",
  "txid": null,
  "operation_id": "7da84c17-d40c-5bc1-9b69-867d1460736b",
  "amount": "63",
  "owner_name": "Z.ro Bolsao",
  "owner_person_type": "CNPJ",
  "owner_document": "00000000000000",
  "owner_bank_name": "ZERO IP S/A",
  "owner_bank_ispb": "26264220",
  "owner_branch_number": "0000",
  "owner_account_number": "000000",
  "beneficiary_name": "Name",
  "beneficiary_account_number": "000000",
  "beneficiary_branch_number": "0000",
  "beneficiary_person_type": "CPF",
  "beneficiary_document": "***000000**",
  "beneficiary_bank_name": "ZERO IP S/A",
  "beneficiary_bank_ispb": "26264220",
  "created_at": "2024-04-17T13:33:41.071Z"
}

Payloads (Version 4)​

{
  "id": "a839f358-0e39-409e-b9a5-5a56b18ba3f2",
  "type": "DEPOSIT",
  "end_to_end_id": "E26264220202404171333Hq7F9SWyvUE",
  "txid": null,
  "operation_id": "7da84c17-d40c-5bc1-9b69-867d1460736b",
  "amount": "63",
  "owner_name": "Z.ro Bolsao",
  "owner_person_type": "CNPJ",
  "owner_document": "00000000000000",
  "owner_bank_name": "ZERO IP S/A",
  "owner_bank_ispb": "26264220",
  "owner_branch_number": "0000",
  "owner_account_number": "000000",
  "owner_account_type": "CACC",
  "beneficiary_name": "Name",
  "beneficiary_account_number": "000000",
  "beneficiary_branch_number": "0000",
  "beneficiary_person_type": "CPF",
  "beneficiary_document": "***000000**",
  "beneficiary_bank_name": "ZERO IP S/A",
  "beneficiary_bank_ispb": "26264220",
  "created_at": "2024-04-17T13:33:41.071Z"
}

Payloads (Version 5)​

{
  "id": "a839f358-0e39-409e-b9a5-5a56b18ba3f2",
  "user_id": "9d77c248-c5b5-4f6d-9d12-d1463dc49bd9",
  "type": "DEPOSIT",
  "end_to_end_id": "E26264220202404171333Hq7F9SWyvUE",
  "txid": null,
  "operation_id": "7da84c17-d40c-5bc1-9b69-867d1460736b",
  "amount": "63",
  "owner_name": "Z.ro Bolsao",
  "owner_person_type": "CNPJ",
  "owner_document": "00000000000000",
  "owner_bank_name": "ZERO IP S/A",
  "owner_bank_ispb": "26264220",
  "owner_branch_number": "0000",
  "owner_account_number": "000000",
  "owner_account_type": "CACC",
  "beneficiary_name": "Name",
  "beneficiary_account_number": "000000",
  "beneficiary_branch_number": "0000",
  "beneficiary_person_type": "CPF",
  "beneficiary_document": "***000000**",
  "beneficiary_bank_name": "ZERO IP S/A",
  "beneficiary_bank_ispb": "26264220",
  "created_at": "2024-04-17T13:33:41.071Z"
}

Pix Refund Webhooks​

Triggered when a Pix refund request changes status. All states share the same payload structure; optional fields (analysis_result, rejection_reason, failed_code, failed_message) are only present when applicable to the current state.

Possible reason values: FRAUD, PSP_ERROR, PIX_AUTOMATIC.
Possible analysis_result values: TOTALLY_APPROVED, PARTIALLY_APPROVED, REJECTED.
Possible rejection_reason values: NO_BALANCE, ACCOUNT_CLOSURE, OTHER, INVALID_REQUEST, INFRACTION_DISAGREED.

Payloads (Version 1)​

Triggered when a refund request is opened by the receiving PSP.

{
  "id": "3d4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a",
  "status": "OPEN",
  "previous_status": null,
  "contested": false,
  "reason": "FRAUD",
  "amount": 10000,
  "returned_amount": 0,
  "description": "Transação contestada pelo usuário.",
  "solicitation_psp_id": "RR26264220202404171333Hq7F9SWyvUE",
  "analysis_result": null,
  "rejection_reason": null,
  "transaction_end_to_end_id": "E26264220202404171333Hq7F9SWyvUE",
  "failed_code": null,
  "failed_message": null,
  "wallet_id": "f08e96c8-b659-40bf-a1bd-5225ef4e5632",
  "event_timestamp": "2024-04-17T17:30:00.020Z",
  "event_id": "3d4e5f6a-7b8c-9d0e-1f2a-3b4c5d6e7f8a_OPEN_1713375000020"
}

Pix Fund Recovery Request Webhooks​

Triggered when a Pix fund recovery request changes status. A fund recovery request is used to recover funds in cases of fraud or erroneous transactions.

Possible reason values: FRAUD, CANCEL_DEVOLUTION, PIX_AUTOMATIC_FRAUD, PIX_AUTOMATIC_PSP_ERROR.
Possible fraud_reason values: SCAM, MULE, SCAM_MULE, OTHER. Present only when reason is FRAUD and the analysis identifies the fraud type.

Payloads (Version 1)​

Triggered when a fund recovery request is created.

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "CREATED",
  "previous_status": null,
  "reason": "FRAUD",
  "description": "Solicitação de devolução por suspeita de fraude.",
  "transaction_end_to_end_id": "E26264220202404171333Hq7F9SWyvUE",
  "fraud_reason": null,
  "wallet_id": "f08e96c8-b659-40bf-a1bd-5225ef4e5632",
  "event_timestamp": "2024-04-17T17:30:00.020Z",
  "event_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890_CREATED_1713375000020"
}

Pix Automatic Recurrence Webhooks​

Triggered when a Pix automatic recurrence (recurring payment agreement) changes status. The recurrence represents the contract between payer and receiver for recurring Pix payments.

Possible status values: CREATED, FAILED, APPROVED, REJECTED, CANCELED, EXPIRED, FINISHED.
Possible state values: CREATED_CONFIRMED, CREATED_FAILED, APPROVED_CONFIRMED, REJECTED_CONFIRMED, CANCELED_CONFIRMED, CANCELED_FAILED, EXPIRED_CONFIRMED, FINISHED_CONFIRMED.
Possible frequency values: WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY.
Possible journey values: JOURNEY_1, JOURNEY_2, JOURNEY_3, JOURNEY_4, JOURNEY_4_STATIC.
Possible cancellation.reason values: ACCOUNT_CANCELED, RECEIVER_COMPANY_CLOSURE, OWNER_DEATH, CONFIRMATION_ERROR, FRAUD_SUSPICION, RECURRENCE_ALREADY_CONFIRMED, RECEIVER_REQUEST, PAYER_REQUEST, RECEIVER_PSP_REQUEST.

Payloads (Version 1)​

Triggered when a recurrence agreement is successfully created after registration with the PSP.

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
  "contract_number": "CONTRACT-001",
  "status": "CREATED",
  "previous_status": "PENDING",
  "state": "CREATED_CONFIRMED",
  "journey": "JOURNEY_1",
  "frequency": "MONTHLY",
  "start_date": "2024-05-01",
  "end_date": "2025-05-01",
  "request_expiration_date": "2024-04-24T17:30:00.020Z",
  "value": 10000,
  "floor_max_value": null,
  "beneficiary": {
    "ispb": "26264220",
    "document": "00000000000000",
    "name": "Z.ro Bolsao"
  },
  "owner": {
    "ispb": "26264220",
    "document": "***000000**",
    "name": "Name",
    "person_type": "CPF",
    "bank_branch": "0001",
    "bank_account": "000001"
  },
  "debtor": {
    "document": "***000000**",
    "person_type": "CPF",
    "name": "Name"
  },
  "next_charge": {
    "due_date": "2024-05-01",
    "value": 10000
  },
  "contract_description": "Assinatura mensal",
  "tags": ["tag1"],
  "created_at": "2024-04-17T17:30:00.020Z",
  "updated_at": "2024-04-17T17:30:00.020Z",
  "event_timestamp": "2024-04-17T17:30:00.020Z",
  "event_id": "b2c3d4e5-f6a7-8901-bcde-f01234567890_CREATED_1713375000020"
}

Pix Automatic Authorization Webhooks​

Triggered when a Pix automatic authorization changes status. The authorization represents the payer's consent to allow recurring Pix debits from their account.

Possible status values: PENDING, APPROVED, REJECTED, CANCELED, FINISHED.
Possible state values: PENDING_CONFIRMED, APPROVED_CONFIRMED, REJECTED_CONFIRMED, APPROVED_FAILED, REJECTED_FAILED, CANCELED_CONFIRMED, CANCELED_FAILED, FINISHED_CONFIRMED, UPDATED_CONFIRMED, UPDATED_FAILED.
Possible frequency values: WEEKLY, MONTHLY, QUARTERLY, SEMI_ANNUALLY, ANNUALLY.
Possible journey values: JOURNEY_1, JOURNEY_2, JOURNEY_3, JOURNEY_4.
Possible rejection_reason values: UNRECOGNIZED_RECEIVER, NOT_INTERESTED, UNAVAILABLE_FOR_LEGAL_PERSON.

Payloads (Version 1)​

Triggered when an authorization request is pending user approval.

{
  "id": "c3d4e5f6-a7b8-9012-cdef-012345678901",
  "user_id": "9d77c248-c5b5-4f6d-9d12-d1463dc49bd9",
  "wallet_id": "f08e96c8-b659-40bf-a1bd-5225ef4e5632",
  "status": "PENDING",
  "previous_status": null,
  "state": "PENDING_CONFIRMED",
  "previous_state": null,
  "journey": "JOURNEY_1",
  "frequency": "MONTHLY",
  "start_date": "2024-05-01",
  "end_date": "2025-05-01",
  "value": 10000,
  "floor_max_value": null,
  "payment_max_value": 15000,
  "beneficiary": {
    "ispb": "26264220",
    "document": "00000000000000",
    "name": "Z.ro Bolsao"
  },
  "owner": {
    "document": "***000000**",
    "name": "Name"
  },
  "contract_number": "CONTRACT-001",
  "contract_description": "Assinatura mensal",
  "recurrence_id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
  "request_expiration_date": "2024-04-24T17:30:00.020Z",
  "rejection_reason": null,
  "created_at": "2024-04-17T17:30:00.020Z",
  "updated_at": "2024-04-17T17:30:00.020Z",
  "event_timestamp": "2024-04-17T17:30:00.020Z",
  "event_id": "c3d4e5f6-a7b8-9012-cdef-012345678901_PENDING_1713375000020"
}

Pix Automatic Charge Webhooks​

Triggered when a Pix automatic charge (individual debit attempt within a recurrence) changes status.

Possible status values: CREATED, CREATED_FAILED, PAID, NOT_PAID, CANCELED, CANCELED_FAILED.
Possible scheduling_purpose values: SCHEDULING (first attempt), NEW_ATTEMPT (after expiration), RESEND (after settlement error).
Possible cancellation_reason values: ACCOUNT_CLOSED, ACCOUNT_BLOCKED, RECURRENCE_CANCELED, SETTLEMENT_FAILURE, OTHER_REASON_BY_PARTICIPANT, REQUESTED_BY_PAYER, REQUESTED_BY_RECEIVER.

Payloads (Version 1)​

Triggered when a charge is created and registered with the PSP.

{
  "id": "d4e5f6a7-b8c9-0123-defa-123456789012",
  "user_id": "9d77c248-c5b5-4f6d-9d12-d1463dc49bd9",
  "pix_automatic_recurrence_id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
  "pix_automatic_recurrence_user_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "contract_number": "CONTRACT-001",
  "type": "PIX_AUTOMATIC_CHARGE_CREATED",
  "status": "CREATED",
  "scheduling_purpose": "SCHEDULING",
  "due_date": "2024-05-01",
  "value": 10000,
  "created_at": "2024-04-17T17:30:00.020Z",
  "updated_at": "2024-04-17T17:30:00.020Z"
}

Pix Automatic Payment Webhooks​

Triggered when a Pix automatic payment (settled transaction within an authorization) changes status. Unlike the charge, the payment represents the actual financial movement.

Possible status values: CREATED, CANCELLATION_FAILED, CANCELED.
Possible scheduling_purpose values: SCHEDULING, NEW_ATTEMPT, RESEND.

Payloads (Version 1)​

Triggered when a payment is successfully created and settled.

{
  "id": "e5f6a7b8-c9d0-1234-efab-234567890123",
  "user_id": "9d77c248-c5b5-4f6d-9d12-d1463dc49bd9",
  "pix_automatic_authorization_id": "c3d4e5f6-a7b8-9012-cdef-012345678901",
  "type": "PIX_AUTOMATIC_PAYMENT_CREATED",
  "status": "CREATED",
  "previous_status": null,
  "scheduling_purpose": "SCHEDULING",
  "due_date": "2024-05-01",
  "value": 10000,
  "end_to_end_id": "E26264220202405011730XyzAbc12345",
  "conciliation_receiver_id": "RR26264220202405011730XyzAbc12345",
  "recurrence_id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
  "cancellation_id": null,
  "created_at": "2024-05-01T17:30:00.020Z",
  "updated_at": "2024-05-01T17:30:00.020Z",
  "event_timestamp": "2024-05-01T17:30:00.020Z",
  "event_id": "e5f6a7b8-c9d0-1234-efab-234567890123_CREATED_1714583400020"
}

Bolepix Deposit Webhooks​

Triggered when a Bolepix (banking billet with embedded Pix QR code) changes state. A Bolepix is a bank slip that also contains an embedded Pix QR code, allowing the payer to settle it via either method.

Possible state values: CREATED_CONFIRMED, CREATED_FAILED, RECEIVED.
Possible status values: CREATED_BILLET_PENDING, CREATED_BILLET_WAITING, CREATED_BILLET_CONFIRMED, CREATED_BILLET_FAILED, CREATED_QRCODE_PENDING, CREATED_QRCODE_CONFIRMED, CREATED_QRCODE_FAILED.
Possible qr_code_type values: PIX_AUTOMATIC, PIX_QRCODE_DYNAMIC.

Payloads (Version 1)​

Triggered when a Bolepix is successfully created and the Pix QR code is confirmed.

{
  "id": "a7b8c9d0-e1f2-3456-abcd-ef0123456789",
  "user_id": "9d77c248-c5b5-4f6d-9d12-d1463dc49bd9",
  "wallet_id": "f08e96c8-b659-40bf-a1bd-5225ef4e5632",
  "operation_id": "cb835846-47b2-4bad-abd3-56e8b0d65ffe",
  "tx_id": "TX0001234567890",
  "state": "CREATED_CONFIRMED",
  "previous_state": "CREATED_WAITING",
  "status": "CREATED_QRCODE_CONFIRMED",
  "emv": "00020101021226890014br.gov.bcb.pix2567qrcode.example.com/v2/a7b8c9d0-e1f2-3456-abcd-ef01234567895204000053039865802BR5913Z.ro Bolsao6009Sao Paulo62070503***6304ABCD",
  "payment_link_url": "https://pay.example.com/bolepix/a7b8c9d0",
  "due_date": "2024-05-10T00:00:00.000Z",
  "limit_due_date": "2024-05-20T00:00:00.000Z",
  "amount": 15000,
  "amount_received": null,
  "interest_perc_value": 1.0,
  "fine_value": 200,
  "discount_value": null,
  "beneficiary": {
    "name": "Z.ro Bolsao",
    "document": "00000000000000",
    "city": "São Paulo"
  },
  "pix_key": {
    "key": "00000000000000"
  },
  "payer": {
    "person_type": "CPF",
    "document": "***000000**",
    "name": "Name"
  },
  "qr_code_id": "b2c3d4e5-f6a7-8901-bcde-f01234567890",
  "qr_code_type": "PIX_QRCODE_DYNAMIC",
  "description": "Fatura Maio 2024",
  "recipient_city": "São Paulo",
  "external_id": "EXT-001",
  "transaction_tag": "TAG-001",
  "allow_update": true,
  "allow_update_change": false,
  "allow_update_withdrawal": false,
  "failure": null,
  "confirmed_at": null,
  "event_timestamp": "2024-04-17T17:30:00.020Z"
}

Bolepix Deposit Batch Webhooks​

Triggered when a batch of Bolepix (banking billet with embedded Pix QR code) changes status. A batch groups multiple billets for bulk generation and distribution by email.

Possible status values: REJECTED, GENERATED, FAILED.

Payloads (Version 1)​

Triggered when a batch is successfully processed and all billets are generated.

{
  "id": "c9d0e1f2-a3b4-5678-cdef-012345678901",
  "batch_name": "Lote Maio 2024",
  "status": "GENERATED",
  "previous_status": "VALIDATED",
  "items_count": 150,
  "personalized": false,
  "email_send_date": "2024-05-01T08:00:00.000Z",
  "event_timestamp": "2024-04-30T17:30:00.020Z"
}

Antifraud Webhooks​

Triggered when a transaction enters antifraud analysis or is declined by it. FRAUD_ANALYSIS events mean the transaction is on hold for review; the transaction then either proceeds through its normal status flow (if approved) or a FRAUD_DECLINED event follows. Payload versions 1 and 2 are identical.

Optional fields are only present when the information is available for the transaction.

Payloads (Version 1)​

{
  "id": "10b66e97-c747-4dcb-92ad-da1420a0a6b9",
  "user_id": "9d77c248-c5b5-4f6d-9d12-d1463dc49bd9",
  "operation_id": "7da84c17-d40c-5bc1-9b69-867d1460736b",
  "type": "BANKING_TED_RECEIVED_FRAUD_ANALYSIS",
  "status": "ANTIFRAUD_ANALYSIS_REVIEW",
  "amount": 150000,
  "owner_name": "Name",
  "owner_document": "***000000**",
  "owner_bank_code": "237",
  "owner_bank_name": "BANCO BRADESCO S/A",
  "owner_bank_ispb": "60746948",
  "owner_bank_account": "000000",
  "owner_bank_branch": "0000",
  "owner_account_type": "CACC",
  "transaction_id": "STR20260417173300000000000000001",
  "finality_code": 10,
  "created_at": "2024-04-17T13:33:41.071Z",
  "updated_at": "2024-04-17T13:33:41.071Z"
}

owner_* fields, transaction_id and finality_code are optional.

Judicial Webhooks​

Judicial webhooks are triggered by court-ordered operations on user accounts. You can register multiple URLs for the same event type — all registered URLs will receive the notification independently. This is useful if you operate multiple products (e.g., PaaS and Gateway) and need each one to receive the event.

Payloads (Version 1)​

Triggered when a court order blocks the user's account entirely.

{
  "id_judicial_block_account": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "user_id": "9d77c248-c5b5-4f6d-9d12-d1463dc49bd9",
  "account_number": "000001",
  "branch_number": "0001",
  "process_number": "0001234-56.2026.8.26.0100",
  "court_name": "1ª Vara Cível de São Paulo",
  "created_at": "2024-04-17T17:30:00.020Z"
}

process_number and court_name are optional — they are only present when provided in the court order.