Reliability

Idempotency

Use stable idempotency keys for create operations so retries do not create duplicate payment intents or payouts.

Where API idempotency is supported

POST /v1/payment-intents requires an Idempotency-Key header.
POST /v1/payouts requires an Idempotency-Key header.
POST /checkout/quotes/{quoteId}/accept accepts an optional body field named idempotency_key; if omitted, the backend uses a deterministic quote-acceptance key.

Do not assume every write endpoint is idempotent

Other routes may be safe to retry at the business-rule layer, but this docs page only covers idempotency behavior evidenced by the backend API implementation.

Payment intent creation

POST/v1/payment-intentsCreate payment intent

curl "$XPEND_BASE/v1/payment-intents" \
  -H "Authorization: Bearer $XPEND_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_8421" \
  -d '{
    "amount": "150.00",
    "chain": "ethereum",
    "token": "USDC",
    "metadata": {
      "order_id": "order_8421"
    }
  }'

Choosing keys

Use one key per business action, such as an order ID or payout request ID.
Reuse the same key when retrying the same request after a timeout or transient failure.
Use a new key for a genuinely new payment intent or payout.
Do not reuse a key with a different request body.

Conflicts and in-progress retries

If a key is already being processed, the API can ask you to retry later. If the same key is reused with a different request fingerprint, treat the response as a client integration error and do not keep retrying blindly.

Webhook idempotency

Webhook deliveries are at-least-once. Store processed event IDs or delivery IDs before applying side effects, then acknowledge duplicate deliveries without repeating the side effect.

Ready to build?

Get an API key

Sandbox-only credentials, no card required.

Stuck on something?

Talk to a human

DevRel responds in office hours.