Idempotency

Idempotency protects your customers from duplicate payment attempts and protects your system from retry uncertainty. Use a stable idempotency key for every request that creates or mutates payment state.

When To Use It

Use idempotency for:

• checkout or payment-session creation
• repayment, disbursement, or refund-style requests when enabled
• webhook processing in your own system
• retrying after timeouts or network failures

Key Shape

Choose a key that maps to your own durable business reference. Good keys come from order IDs, invoice IDs, member transaction IDs, or payment-attempt IDs.

Avoid timestamp-only keys. They make retries look like new requests.

Retry Pattern

1. Create the request with a stable key.
2. Persist your own reference and the SenteRail reference.
3. If the request times out, retry with the same key.
4. If the response conflicts, inspect the original request and reconcile state.

Webhook Dedupe

Webhook idempotency is your responsibility. Store event IDs before applying state changes. If the same event arrives again, acknowledge it without running the business mutation twice.

Read Webhooks for the full event-handling pattern.