Payments Webhooks (Brazil)

A webhook is a web callback that Belvo uses to send notifications about a specific link.

Set up webhooks

To set up a new webhook:

1. In your Belvo dashboard, go to the payment webhooks section.

2. In the Payments Webhooks tab, click +New webhook.

   

3. Fill in the New webhook form with the required information.

   • URL: the URL to receive the webhook notifications.
   • Authorization: an optional bearer token to use if your URL is protected.

4. Click Create webhook.

   

Webhook Schemas and Types

Belvo offers two webhook schema versions for Payments Brazil webhooks:

• Schema Version 1 (Legacy): The original webhook format used for CHARGES, PAYMENT_INTENTS, and TRANSACTIONS webhooks. This schema continues to work for existing integrations.
• Schema Version 2 (New): A newer webhook format introduced for enhanced functionality. This schema is used for BANK_ACCOUNTS (V2), CUSTOMERS (V2), and PAYMENT_AUTHORIZATIONS webhooks.

Webhook outbound IP addresses

You can receive webhook events from the following IP addresses:

• 3.130.254.46
• 18.220.61.186
• 18.223.45.212

Client-side webhook response best practice

We highly recommend that once you receive a webhook you reply to Belvo with a 2XX status code within five seconds to confirm that you have received the webhook. Otherwise, our API will retry the request.

Webhook retry policy

If our system does not receive 2XX status code, it automatically tries to send the request again. This retry process will happen up to three times, with each attempt spaced 60 seconds apart. For example, if the first attempt fails, our system waits for 60 seconds before trying again and will continue this pattern until it either receives a successful response or reaches the maximum of three retries.

Webhook Events (Version 2)

Whenever there is an event related to a Bank Account, Charge, Customer, or Payment Authorization you will receive the following webhook:

{
  "schema_version": "2",
  "resource": "BANK_ACCOUNT",
  "resource_id": "7d01c4cf-57ed-4ed9-b109-a5bfb2d8c42b",
  "resource_version": "v2",
  "timestamp": "2025-01-16T10:30:45.123456Z"
}

Where:

Once you receive the notification, you will have to get details of the resource by making the following request:

curl --request GET 'https://api.belvo.com/payments/br/{resource}/{id}/' \
  -u [Secret Key ID]:[Secret Key PASSWORD] \
  -H 'X-Belvo-API-Resource-Version: Payments-BR.V2'

Where:

• resource is the type of resource you want to retrieve (bank-accounts, charges, customers, or payment-authorizations).
• id is the resource_id of the bank account (which you receive in the webhook event).

Webhook Events (Legacy)

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "PAYMENT_INTENTS",
  "webhook_code": "STATUS_UPDATE",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "external_id": "c3c51aaf-aaa3-400c-926d-87ab62e195fd",
  "data": {
    "status": "FAILED",
    "metadata": {"internal_reference_id": "GGq12345w2"},
    "failure_code": "consent_expired",
    "failure_message": "The payment consent was not accepted in time.",
    "end_to_end_id": "E432158152024081610416f2b595b056",
  }
}

For information about the data specific to a given webhook, click on the webhook type in the table below.

Once you receive the notification, you will have to get details of the resource by making the following request:

curl --request GET 'https://api.belvo.com/payments/br/{resource}/{id}/' \
  -u [Secret Key ID]:[Secret Key PASSWORD] \

Where:

• resource is the type of resource you want to retrieve (bank-accounts, charges, customers, payment-intents, or transactions).
• id is the object_id of the resource (which you receive in the webhook event).

Failure Codes and Messages

Below is a list of failure_codes and failure_messages that you can receive in a Charge or Payment Intents webhook: