Sign in

Idempotency

Every money-moving POST (/charges, /transfers, /treasury/payouts, /trades) requires an Idempotency-Key header. Use a fresh UUID per logical operation:

Idempotency-Key: 3f9a2b7c-1e8d-4a05-9b2c-7c1e8d4a0599
  • Replays are safe. Retrying with the same key and same body returns the original response — the operation runs once.
  • Conflicts are caught. Reusing a key with a different body returns 409 idempotency_conflict. A request still in flight under the same key also returns 409.
  • Keys are retained for 24 hours.

This lets you retry on network errors or timeouts without double-charging.

curl -X POST https://api.starpay.example/api/v1/charges \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: 3f9a2b7c-1e8d-4a05-9b2c-7c1e8d4a0599" \
  -H "Content-Type: application/json" \
  -d '{"amount":250000,"currency":"GHS","channel":"momo","msisdn":"0240000000"}'
Previous Authentication Next Pagination