Idempotency and retries
Two idempotency layers let you retry after timeouts without creating duplicate payments, refunds, or side effects.
Key points
- out_trade_no and out_refund_no provide permanent business-level uniqueness for orders and refunds.
- Idempotency-Key works on all write endpoints for 24 hours. Reusing a key with a different request body is an error.
- Successful 2xx and definitive 4xx responses are replayed; 5xx responses are not cached. Deduplicate webhook handling separately by event ID.
Example
json
{
"out_trade_no": "ORDER_20260921_0001",
"amount": 2990,
"currency": "USD"
}