Idempotency

Idempotency ensures that no matter how many times you invoke the same operation with the same parameters, you are guaranteed the same end result. This is especially useful for sensitive operations that could involve potential money loss or a poor experience for customers in scenarios such as unintended duplicated charges or payouts to a bank account.

With Belvo's Direct Debit product, you can provide an Idempotency-Key in the headers of an HTTP request to mitigate the risk of duplicated calls to a resource. We recommend using a generated UUID as the key.

Supported methods

At present, the following API calls support idempotency keys:

• Create a payment request

Lifecycle of an idempotency key

After a successful API call (with a 200 or 201 HTTP status code), our system caches the response alongside its corresponding idempotency key. Any repeated requests using this key within a 24-hour window fetch the cached result instead of re-executing the operation.

Expiration policy

Idempotency keys have a 24-hour Time-To-Live (TTL) after the initial request timestamp. After this period has passed, a reused key is treated as a new request, invoking a fresh operation and storing the new response.

Idempotency error messages

You will receive an error related to your idempotency key in the following cases:

IP Whitelisting

At Belvo, keeping your data and operations safe is essential. As such, we offer an optional, but highly recommended, whitelisting feature for our Direct Debit API.

This feature adds an extra layer of security as it ensures that each API request originates from a pre-approved IP address, in conjunction with your API keys. Even if your API keys are compromised, the risk of unauthorized access is significantly reduced, as only requests from trusted IPs will be acknowledged.

📘

Requests from non-approved IP addresses

Requests made form non-approved IP addresses will receive a 401 Unauthorized error.

How to set up IP whitelisting

To set up IP whitelisting, please contact [email protected] with the following information:

• company name
• list of IPs you want whitelisted

Hello,

I would like to request the following IP addresses to be whitelisted for my Belvo Direct Debit integration:

- ip_address_1
- ip_address_2

Thank you,

your_company_name

Our team will then reach out if they need further information or once the IPs have been whitelisted.