Retry requests safely
Use an idempotency key for every payment-changing request that requires one. The key identifies a single intended command, including retries after a lost response.
Save the request before sending it
Persist the business order reference, idempotency key, request body, and target endpoint together. Generate the key once for that command. UUIDs or stable application-generated command identifiers are suitable; keys are limited to 191 characters.
Retry with the same credential identity, method, request target, body bytes, and idempotency key. Reordering JSON fields or changing query encoding can change the request fingerprint. Reusing a key with different content returns a conflict.
Handle an uncertain outcome
| What happened | Recovery |
|---|---|
| The connection timed out | Query the original order or operation, then retry the same command if appropriate. |
The response contains operation_id or status_path | Follow the existing operation. |
REQUEST_IN_PROGRESS | Wait and inspect the original command's status. |
IDEMPOTENCY_CONFLICT | Compare the stored request with the retry. Do not replace the key to force a new charge. |
VERSION_CONFLICT | Read current state and decide whether the action still makes sense. |
429 with Retry-After | Wait as directed; keep the existing command identity. |
A 5xx response or provider unknown result | Treat the business outcome as unresolved until queried. |
For payment creation, query by app_id and exact external_order_id if you did not receive an order ID. For refunds, keep the original refund and operation references.
Distinguish acceptance from completion
HTTP 202 Accepted means the service accepted the request for processing. The response may contain a session, refund, verification, or operation, depending on the endpoint. Read that resource's status. When supplied, follow Location and Retry-After on the same trusted service.
Operations use pending, running, succeeded, failed, or manual_review. A completed operation can mean a command completed; inspect its linked resource to learn the payment or refund outcome.
Keep durable business deduplication
Idempotency response retention is not a permission to repeat an old financial command. Your business-order uniqueness and fulfillment records must outlive a transient response cache.
A normal key rotation preserves its credential identity. Creating an entirely new credential can change the idempotency scope. Resolve pending work using the original resource references before submitting it under a replacement identity.
For receiving events safely, see Webhooks.