Idempotency

How to use it

Send an Idempotency-Key header on every POST, PUT, PATCH and DELETE:

• Use a fresh UUID v4 for each new operation, such as "create order 10001" or "refund 100.00 on order X".
• Reuse the same key and the same body when you retry that operation.
• Store the key with the operation before you send it, so a retry after a crash or restart can reuse it.

curl -X POST https://api-uat.qasimha.com/api/v1/pay/session/create \
  -H "X-Api-Key: $QASIMHA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4e8a-9c41-2d5f8b0e7a13" \
  -d @order.json

The header is optional. A request without it runs every time. GET requests ignore it; they are always safe to repeat.

How a key is matched

• Scope: a key belongs to your merchant account, the HTTP method and the path. The same key on a different endpoint, or from another merchant, is a different key. Retries through a different API key of the same merchant still match.
• Body: the first request's method, path and body are fingerprinted. A retry must send the byte-for-byte same body. Re-serialising the JSON with different spacing or key order counts as a different body.
• Lifetime: keys are kept for 24 hours. After that, the same key is treated as new.

What happens on a repeat

Things to know:

• Errors are stored too. If the first request got a 4xx from the endpoint, such as 400 VALIDATION_ERROR, 403 FORBIDDEN or 409 DUPLICATE_ORDER_REFERENCE, a retry with the same key and body replays that same error. Fix the request and send it with a new key; the same key with the corrected body returns 422 IDEMPOTENCY_KEY_REUSED.
• Rejected before the endpoint, not stored. 401 (bad key) and 429 (rate limit) happen before the key is recorded. After fixing the key, or after waiting, retry with the same key.
• The replay is the first answer. A replayed create returns the order as it was at creation, for example status: "AwaitingCheckout". Read the order to see where it is now.

Which calls to protect

A retry loop

import { randomUUID } from 'node:crypto';

async function createSession(body: object) {
  const key = randomUUID();                       // one key for every attempt of this operation
  const payload = JSON.stringify(body);           // serialise once, send the same bytes each time

  for (let attempt = 0; attempt < 4; attempt++) {
    let res: Response;
    try {
      res = await fetch('https://api-uat.qasimha.com/api/v1/pay/session/create', {
        method: 'POST',
        headers: { 'X-Api-Key': process.env.QASIMHA_API_KEY!, 'Content-Type': 'application/json', 'Idempotency-Key': key },
        body: payload,
      });
    } catch {
      await sleep(backoff(attempt));              // network error: retry with the same key
      continue;
    }
    if (res.status === 429 || res.status === 409 && (await peekCode(res)) === 'REQUEST_IN_PROGRESS'
        || res.status === 502 || res.status === 503 || res.status === 504) {
      await sleep(retryAfterMs(res) ?? backoff(attempt));
      continue;
    }
    return res;                                    // success, a replay, or an error to handle
  }
  throw new Error('Qasimha unavailable, try again later');
}

const backoff = (n: number) => Math.min(2 ** n * 500, 8000) + Math.random() * 250;

// The SDK sends a UUID v4 Idempotency-Key on every POST and reuses it across its own retries.
const session = await qasimha.checkout.createSession(request);
session.replayed;                                  // true when the answer was a replay

// Supply your own key, for example one stored with your order attempt:
await qasimha.orders.refund(orderId, { amount: 100.00, reason: 'Return' }, { idempotencyKey: storedKey });

peekCode, retryAfterMs and sleep are your own helpers: read code from a clone of the response body, read the Retry-After header, and wait.

Your own reference helps too

Give every order a unique orderReferenceId. Even with a new idempotency key, a second create with the same reference returns 409 DUPLICATE_ORDER_REFERENCE. On a payment session, when the order is yours, data includes its installmentId and paymentUrl, so you can resume the open checkout. See Choose a checkout flow.

The server SDKs use both layers: if a retried createSession gets 409 DUPLICATE_ORDER_REFERENCE naming your order, the SDK returns that order as the session, because the earlier attempt succeeded.

Troubleshooting

Related