Payment Webhooks (Mexico)

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.

✅ You're webhook URL is successfully added.

Webhook events

{
  "eventType": "payment_request_update", // API resource event type
  "eventCode": "payment_request_successful", // Webhook event code
  "datetime": "2022-01-01T12:34:56.789Z", // The ISO-8601 timestamp when the event was sent.
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // Object ID of the API resource.
    "reference": "your_reference_here", // Optional description of the object
    "status": "failed", // The status of the resource
    "failedReason": "BANK_CODE", // If status=failed, a failure code
    "failedMessage": "A description of the error" // If status=failed, a description of the failure.
  }
}

failedReason and failedMessage fields

For details regarding the expected failedReason and failedMessage (including the list of possible values), please see our Direct Debit Bank Errors guide.

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

Resource	Event Code	Sent whenever...
Payment Methods	`payment_method_registration_successful`	the registration of the direct debit payment method was successful.
Payment Methods	`payment_method_registration_failed`	the registration of the direct debit payment method failed.
Payment Methods	`payment_method_registration_canceled`	the direct debit registration was canceled (usually by the owner).
Payment Requests	`payment_request_successful`	the payout was successful and we received confirmation from the payment infrastructure provider.
Payment Requests	`payment_request_failed`	an error is reported by the payment infrastructure provider.
Payment Requests	`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.

Payment Methods

payment_method_registration_failed

You can receive a payment_method_registration_failed webhook when the registration of the direct debit payment method failed for a given paymentMethodId.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // The paymentMethodId
    "reference": "your_reference_here",
    "status": "error",
    "failedReason": "BANK_CODE",
    "failedMessage": "A description of the error"
  }
}

We provide additional information regarding the failure in the failedReason and failedMessage keys.

payment_method_registration_canceled

You can receive a payment_method_registration_canceled webhook when the registration of the direct debit payment method was canceled (usually by the owner) for a given paymentMethodId.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_canceled",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // The paymentMethodId
    "reference": "your_reference_here",
    "status": "canceled",
    "failedReason": null,
    "failedMessage": null
  }
}

payment_method_registration_successful

You receive a payment_method_registration_successful webhook when the registration of the direct debit payment method is successful for a given paymentMethodId.

{
  "eventType": "payment_method_update",
  "eventCode": "payment_method_registration_successful",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // The paymentMethodId
    "reference": "your_reference_here",
    "status": "active",
    "failedReason": null,
    "failedMessage": null
  }
}

Payment Requests

payment_request_failed

You can receive a payment_request_failed webhook when an error is reported by the payment infrastructure provider for a given paymentRequestId.

{
  "eventType": "payment_request_update",
  "eventCode": "payment_request_failed",
  "datetime": "2022-01-01T12:34:56.789Z",
  "details": {
    "id": "3118128a-6792-4b06-bd61-4acf6f6ad6b5", // The paymentRequestId
    "reference": "your_reference_here",
    "status": "failed",
    "failedReason": "BANK_CODE",
    "failedMessage": "A description of the error"
  }
}

payment_request_successful

You receive a payment_request_successful webhook when the payment infrastructure provider confirms that the payment was successful for a given paymentRequestId.

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

payment_request_canceled

You receive a payment_request_canceled webhook when the payment request was cancelled by the customer.

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

payment_request_chargeback

You receive a payment_request_chargeback webhook when the payment infrastructure provider reports that the payment resulted in a chargeback by the customer.

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