Idempotency
Payment operations (/v1/execute and /v1/pay) require an Idempotency-Key header to ensure exactly-once execution.
How it works
Sending the same request twice with the same idempotency key produces the same result — the payment is only executed once.
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": "PIX:example",
"payer_name": "Maria Silva",
"payer_account": "0001234567",
"payer_tax_id": "12345678909"
}'Rules
| Scenario | Result |
|---|---|
| New key | Request is processed normally |
| Same key + same body | Cached response returned (no re-execution) |
| Same key, first still processing | 409 IdempotencyInProgress — retry after a short delay |
| Same key + different body | 400 IdempotencyConflict |
Key expiry
Idempotency keys expire after 24 hours. After expiry, the same key can be reused with any body.
Best practices
- Use a descriptive format:
${operation}-${unique_id}(e.g.,pay-order-12345) - Generate the key client-side before the first attempt
- Retry with the same key on network failures — the response is safely cached
- Use a different key for genuinely different operations
Conflict error
If you see IdempotencyConflict, it means the key was already used with a different request body. Generate a new key for the new request.
In-flight duplicate
A 409 IdempotencyInProgress means a request with the same key is still being processed (for example, a concurrent retry). Wait briefly and retry the same request — once the original finishes you receive its cached response.