Skip to main content
Use Idempotency-Key on write operations:
  • POST /transactions
  • POST /transactions/{id}/cancel

​
Required Header

Idempotency-Key: <unique-key-per-business-action>

​
Retention Window

Idempotency responses are retained for 24 hours. Keep keys in your logs/trace context to support replay diagnostics.

​
Rules

  1. New business action => new idempotency key.
  2. Retry same business action => same idempotency key.
  3. Reusing a key with a different payload returns 409 Conflict.

​
Conflict Matrix

  • Same key + same payload + completed prior response: returns cached success.
  • Same key + same payload + in-flight request: returns conflict/in-progress signal.
  • Same key + different payload: returns 409.

​
Merchant Reference Interaction

merchant_reference is a separate canonical uniqueness key. If the same reference is reused with conflicting intent, transaction creation returns 409 even with a different idempotency key.