Idempotency

Network failures and timeouts can cause uncertainty about whether a request reached the gateway. Without idempotency, retrying a failed request risks processing a duplicate charge.

To avoid this, include a unique value in the X-Request-ID header. If the gateway receives a second request with the same X-Request-ID, it returns the result of the original request instead of processing a new transaction.

How to use X-Request-ID

Generate a new X-Request-ID for each distinct payment attempt, for example:

curl -X POST https://api.centrobill.com/payment \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -d '{ ... }'

Reuse an X-Request-ID only when retrying the same request after a network failure, such as a timeout or a dropped connection. If you have already received a response (success or failure), treat the request as complete and use a new ID for any follow-up attempt.

Handling timeouts safely

The recommended flow for a payment with retry logic:

1. Generate a X-Request-ID and store it alongside the pending order in your database.
2. Submit the payment request.
3. If the request times out, wait briefly and retry with the same X-Request-ID.
4. If the retry also fails, do not attempt again. Instead, query the Feed API using your orderId or transactionId to determine whether the original charge succeeded before deciding how to proceed.

This flow ensures you never charge a customer twice for the same order, even under adverse network conditions.