Idempotency
Network failures and timeouts make it impossible to tell whether a request reached Forter. Idempotency lets you retry such requests safely: sending the same request twice with the same key has the same effect as sending it once, so a customer is never charged twice.
Sending an Idempotency Key
Every POST request to the Orchestration API must include an Idempotency-Key header. Requests without one are rejected with 400 Bad Request.
curl https://payments-sandbox.checkouttools.com/api/payments \
-u "$FORTER_SITE_ID:$FORTER_SITE_SECRET" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c8a8e-3b9c-4c4e-9a43-2a1f6a7d9e10" \
-d '{ ... }'Use a value with enough randomness to never collide, such as a V4 UUID. GET requests don't change anything and don't need a key.
How Keys Are Matched
- Keys are scoped to your site and to the endpoint. The same key on POST /api/payments and on POST /api/payments/{id}/capture is treated as two different keys.
- When a request succeeds, Forter stores its response for 7 days. Any later request with the same key on the same endpoint returns the stored response without running the operation again.
- Forter replays the stored response even if the new request has a different body. A key identifies one operation: never reuse it for a different request.
Generate a new key for every distinct operation, including the same operation on a different payment. For example, use a different key for each capture and for each partial refund. Reusing a key returns the response of the earlier request instead of performing the new operation.
What Is Stored
Only requests that complete are stored. A declined payment counts as completed: it returns status failed, and retrying it with the same key returns the same declined payment. To try the authorization again, use a new key. See Declines and Retries.
Requests that return an error, such as a validation error (4xx) or a server error (5xx), are not stored. You can fix the request and retry it with the same key.
Concurrent Requests
If a request arrives while another request with the same key is still being processed, Forter rejects it with 409 Conflict instead of running the operation twice. Wait briefly and retry with the same key. Once the first request completes, the retry returns its result.
Recommended Retry Strategy
Outcome | What to do |
|---|---|
Timeout or network error | Retry with the same key and exponential back-off. |
409 Conflict | The original request is still in progress. Retry with the same key after a short delay. If the errorCode is PAYMENT_IDEMPOTENCY_CONFLICT, the key is held by a pending refund of a different capture: retry with a new key. |
5xx | Retry with the same key and exponential back-off. |
4xx (other than 409) | Don't retry unchanged. Fix the request first. See Errors. |
Success with payment status failed | The payment was declined. Retry only with a new key. |
Store the idempotency key alongside the order in your system before sending the request. That way you can reuse it if your own process restarts mid-request.