Idempotency

Some API endpoints support idempotency, allowing you to safely retry requests without duplicating actions.

To use this feature, include an X-Idempotency-Key header in your request. The key must be a unique, UUID-formatted 36-character alphanumeric value.

A request with a new idempotency key will be processed. If you resend the same request with identical credentials and idempotency key, BVNK returns a 400 Bad Request status and indicates that a request with this ID already exists. This feature is especially useful for critical operations such as transferring funds, creating payment orders, or updating resources.

Exceptions

For certain endpoints, a second API call with the same X-Idempotency-Key and an identical request body may return 200 OK with the same reference.

For example, this behavior can be observed in the platform/v1/customers/* and platform/v1/customers/agreement/* endpoints.

For example, if a payment order request times out due to a network issue, you can repeat the call with the same idempotency key to ensure only one payment order is created. Only successful requests are cached. Failed requests are not stored, so you can retry them without risk of conflict.

curl --request POST \
     --url https://api.sandbox.bvnk.com/ledger/v1/wallets \
     --header 'X-Idempotency-Key: 1e74002e-74a1-48fd-b707-147c3187a3e1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '

For v.2 endpoints, use Idempotency-Key header instead of X-Idempotency-Key.

curl --request POST \
     --url https://api.sandbox.bvnk.com/payment/v2/transfers \
     --header 'Idempotency-Key: 1e74002e-74a1-48fd-b707-147c3187a3e1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
   --data '