Idempotency

Where API idempotency is supported

For supported create/side-effect endpoints such as payment intent and payout creation, send a stable Idempotency-Key header. 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

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

Payout creation

Create payout once with a stable idempotency key. The key + request body fingerprint is what guarantees deduplication.

Choosing keys

• Use one key per business action, such as an order ID or payout request ID.
• Use a new key for a genuinely new payment intent or payout.
• Do not reuse a key with a different request body.
• Do not assume every write endpoint is idempotent, check this page.

Conflicts and in-progress retries

Reusing a key with a different body returns a 409 with the original result reference. Treat 409 as a hint to look up the prior resource by your business key, not as a hard failure.

Webhook idempotency