Payment Webhooks (Mexico)

A webhook is a web callback that Belvo uses to send notifications about a specific link. You will need to set up webhooks in order to use Belvo's APIs.

Setting up your webhooks

To set up your webhook URL:

Log in to your Direct Debit Portal. (Sandbox Login | Production Login)
Go to Developers -> Webhooks. (Sandbox Webhooks | Production Webhooks)
Enter your URL.
Click Set.

✅ Your webhook URL is successfully added.

Webhook Payload

Webhook Payload Example (Success)

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5",
    "reference": "your_reference_here",
    "status": "successful",
    "failedReason": null,
    "failedMessage": null
  }
}

Parameter	Type	Description
`eventType`	string	The type of the API resource event. Can be one of: `customer_update`, `payment_method_update`, or `payment_request_update`.
`eventCode`	string	The code of the webhook event. For details regarding the possible values, please see the Webhook Event Codes section below.
`datetime`	string	The ISO-8601 timestamp when the event was sent.
`details`	object	An object containing specific data about the event.
`details.id`	string	The Belvo ID of the API resource (Customer, Payment Method, or Payment Request) that the event is related to.
`details.reference`	string	If you provided a `reference` when creating the resource, an optional description of the object.
`details.status`	string	The status of the resource.
`details.failedReason`	string	If the status is `failed`, this field contains a failure code. This field is `null` if the `status` is not `failed`. For details regarding the expected `failedReason` and `failedMessage` (including the list of possible values), please see our Direct Debit Bank Errors guide.
`details.failedMessage`	string	If the status is `failed`, this field contains a description of the failure. This field is `null` if the `status` is not `failed`. For details regarding the expected `failedReason` and `failedMessage` (including the list of possible values), please see our Direct Debit Bank Errors guide.
`details.documentNumber`	string	If the event is related to a customer, this field contains the RFC or CURP of the customer related to the direct debit payment method. This field is only available for customer-related events.

For information about specific payloads for a given API resource and webhook code, just click on the webhook Event Code in the table below.

Webhook Event Codes

Resource	Event Type	Event Code	Sent whenever...
Customers	`customer_update`	`customer_blocked`	the customer related to the direct debit payment method was blocked due to suspicious activity.
Customers	`customer_update`	`customer_unblocked`	the customer related to the direct debit payment method was unblocked after review by relevant parties.
Payment Methods	`payment_method_update`	`payment_method_registration_successful`	the registration of the direct debit payment method was successful.
Payment Methods	`payment_method_update`	`payment_method_registration_failed`	the registration of the direct debit payment method failed.
Payment Methods	`payment_method_update`	`payment_method_registration_canceled`	the direct debit registration was canceled (usually by the owner).
Payment Requests	`payment_request_update`	`payment_request_successful`	the payout was successful and we received confirmation from the payment infrastructure provider.
Payment Requests	`payment_request_update`	`payment_request_failed`	an error is reported by the payment infrastructure provider.
Payment Requests	`payment_request_update`	`payment_request_chargeback`	a chargeback has been made by your customer.

Best Practices

When you receive a webhook from Belvo, make sure that you respond with a 2XX status code (for example, a 200). If Belvo's system does not receive a 200 response from your server, we will automatically retry to send the request. For more detailed, please see our Retry policy section.

Retry policy

When Belvo does not receive a 2XX response from your server, we retry sending the webhook every 60 minutes for up to 10 attempts.

For example, if the first (initial) attempt fails, our system waits for 60 minutes before trying again and will continue this pattern until it either receives a successful response or reaches the maximum of 10 retries.