Idempotency and retries
Avoid duplicate payment attempts.
Create without a key
Idempotency-Key is optional for all payment creation endpoints. You can omit it and send your orderId. The HMAC signature uses timestamp-dot-body regardless of whether this header is supplied.
Without a key, a duplicate order returns 409 Conflict rather than the previous QR. TEST blocks orders with pending or successful payments; LIVE also blocks amount-mismatch and expired payments. These checks apply within the merchant platform and environment. They do not reject every historical order: a confirmed eligible failure or cancellation can allow another attempt.
If both the key and order ID are omitted where the endpoint allows it, each call can create a separate payment. After a timeout, reconcile the original order in the portal or check the saved transaction status before creating another payment. Do not change the order ID just to bypass a duplicate error.
Optional key for replaying creation results
If you want retries to return the saved creation result, persist a unique Idempotency-Key alongside the order before calling a create endpoint. Keys must contain 1–200 printable non-space ASCII characters. Scope is merchant platform + TEST/LIVE environment + creation operation + key.
A retry with the same key and equivalent request parameters returns the saved creation result. It does not return the latest payment status. A changed request body with the same key returns 409. JSON object key order is normalized for the idempotency comparison, but HMAC still signs the exact transmitted body.
Ambiguous outcomes
When using a key, if a request times out, do not create another payment with a new key. Retry with the saved key and parameters plus a fresh timestamp/signature. A 409 unresolved outcome means the first attempt has not produced a saved result. A 502 bank-outcome-unresolved response reserves the payment for reconciliation; preserve its transaction ID, check its status, and involve support rather than reissuing it. Saved failures can be replayed on subsequent retries.
The backend also prevents reuse of an order with a pending or successful TEST payment. LIVE additionally reserves orders in amount-mismatch or expired states. A retry strategy must consider the actual outcome, not just HTTP transport failure.
New attempts
If using idempotency keys, after a confirmed eligible failure/cancellation, a new attempt needs a new key. There is no documented automatic idempotency retention expiry; do not assume a key becomes reusable after 24 hours.