Idempotency
Every request that moves money needs an Idempotency-Key header: /v1/execute, /v1/pay and /v1/collect. The key makes retries safe. If your connection drops and you send the same request again, Borderli returns the first response instead of paying twice.
curl -X POST https://apidocs.borderli.io/v1/pay \
-H "Content-Type: application/json" \
-H "x-api-key: brly_test_key_001" \
-H "Idempotency-Key: pay-order-12345" \
-d '{ "qr_string": "...", "payer_name": "Maria Silva", "payer_account": "0001234567", "payer_tax_id": "12345678909" }'What happens
| You send | You get |
|---|---|
| A new key | The request runs. |
| A key you used before, with the same body | The first response, replayed. Nothing runs again. |
| A key whose first request is still running | 409 IdempotencyInProgress. Wait a moment and send the same request again. |
| A key you used before, with a different body | 400 IdempotencyConflict. Use a new key. |
A key is only kept when the request succeeds. If the request fails with an error, the key is free again and you can retry with it. Keys expire after 24 hours. After that the same key can be used again with any body.
How to pick a key
- Use something unique to the operation on your side, such as your order id:
pay-order-12345. - Create the key before the first attempt and store it with the order, so a retry after a crash reuses it.
- Never reuse a key for a different payment.