Idempotency, retries and status checks

Why idempotency matters

Networks lose responses: the platform may have accepted a request, but the response never reached your server. Idempotency guarantees that a single business submission has only one business effect, however many times you send it, so a retry never charges twice.

Which requests need an idempotency key

Send the key in the Idempotency-Key request header, 1–255 characters. If it's missing, the API returns 400 with error.field set to Idempotency-Key.

Idempotency rules

The scope is merchant + environment + method + path + idempotency key. The same key in the test and live environments doesn't interfere, and rotating an API key doesn't change the scope.

• "Core business parameters" include the amount, the currency, the merchant order ID, the merchant refund ID, the linked payment ID and so on. The fields compared for each endpoint are listed on its endpoint page (for example, Create payment). Card details aren't compared and aren't stored: replaying a key never charges newly submitted card details.
• A request rejected with 400, 401, 403 or 422 doesn't consume the idempotency key. Fix the request and submit it with a new key.
• If you create a checkout session with a new key but the same order ID, amount and currency, the platform creates a new checkout session for the same payment (for example, when the old session has expired). This isn't a conflict and doesn't create a second payment.

Generate and store idempotency keys

Use one key per business submission, and use a given key for only one endpoint. Persist the key together with the order before you send the request, so that after a process crash you can read the original key back from the database and retry.

Retention period

Idempotency records are kept online for 7 days. After that, uniqueness protection on merchant order IDs and refund IDs still applies, so the same order is never treated as new business and charged again.

Example scenarios

Expand a scenario to see its sequence of requests and responses:

POST /v1/payments  Idempotency-Key: K   → (timeout, no response)
POST /v1/payments  Idempotency-Key: K   → 200 {"id":"pay_demo_001","status":"succeeded",…}

POST /v1/payments  Idempotency-Key: K   → 500 {"error":{"code":"internal_error","retryable":true},…}
POST /v1/payments  Idempotency-Key: K   → 200 {"id":"pay_demo_001","status":"processing",…}

POST /v1/payments  Idempotency-Key: K  {"amount":10000,…} → 201
POST /v1/payments  Idempotency-Key: K  {"amount":12000,…} → 409 {"error":{"code":"idempotency_conflict",…}}

POST /v1/payments  Idempotency-Key: K1  {"merchant_order_no":"ORDER-001",…} → 201 pay_demo_001
POST /v1/payments  Idempotency-Key: K2  {"merchant_order_no":"ORDER-001",…} → 409 {"error":{"code":"order_no_conflict","related_resource_id":"pay_demo_001",…}}

Server A: POST /v1/payments  Idempotency-Key: K → 201 pay_demo_001
Server B: POST /v1/payments  Idempotency-Key: K → 200 pay_demo_001 (or 409 operation_in_progress, then retry later with K)

POST /v1/payments  Idempotency-Key: K → 201 pay_demo_001
POST /v1/payments  Idempotency-Key: K → 200 pay_demo_001 (same for requests 2–10)

POST /v1/payments  Idempotency-Key: K  (card A) → (timeout)
POST /v1/payments  Idempotency-Key: K  (card B) → 200 result of the original operation (card B isn't charged)

POST /v1/payments/pay_demo_001/confirm  Idempotency-Key: K2 → 409 {"error":{"code":"payment_in_progress","related_resource_id":"pay_demo_001",…}}

GET  /v1/payments/pay_demo_001 → 200 {"status":"failed","failure":{"code":"card_declined",…}}
POST /v1/payments/pay_demo_001/confirm  Idempotency-Key: K3 (card B) → 200 {"status":"succeeded","attempt_count":2,…}

POST /v1/payments  Idempotency-Key: K → 429  Retry-After: 2
(wait 2 seconds)
POST /v1/payments  Idempotency-Key: K → 201 pay_demo_001

POST /v1/refunds  Idempotency-Key: K  {"merchant_refund_no":"R-001",…} → (timeout)
POST /v1/refunds  Idempotency-Key: K  {"merchant_refund_no":"R-001",…} → 200 ref_demo_001 (the same refund)

POST /v1/payments/pay_demo_007/cancel  Idempotency-Key: K → 202 {"status":"requires_action",…}
(later you receive payment.canceled, or a query returns the final status)

POST /v1/payments  Idempotency-Key: K → 503 {"error":{"code":"temporarily_unavailable","retryable":true},…}
(later)
POST /v1/payments  Idempotency-Key: K → 201 pay_demo_001

Retry with a new card

• Do this only after the payment has status=failed (the previous attempt clearly failed).
• Call POST/v1/payments/{payment_id}/confirm with a new idempotency key, and have the payer enter their card details again.
• You must do it before expires_at and within the maximum number of attempts (3 by default). The new attempt keeps using the original payment and the rate in effect at that time.
• While the payment is still in progress (processing or requires_action), confirming with a new key is rejected (409 payment_in_progress) and no new charge is made.

How to check the status when the outcome is unknown

• If you have the payment ID: GET/v1/payments/{payment_id}.
• If you don't have the payment ID (for example, you crashed before saving the response): GET /v1/payments?merchant_order_no=... (exact match, case-sensitive).
• For refunds: GET /v1/refunds/{refund_id}, or GET /v1/refunds?merchant_refund_no=....

An order's validity period only limits new payment actions. It doesn't invalidate a payment that was already submitted: a processing payment keeps being checked after expires_at passes and can still succeed.

Don't charge again with a new key

Why: when a request times out or returns 5xx or 202, the money may already have been charged. If you then start the payment again with a new idempotency key or a new merchant order ID, the platform treats it as new business, and the payer can be charged twice. There are only two correct approaches: retry with the original idempotency key, or query by payment ID or merchant order ID.

// Don't do this: after a timeout, charging again with a new idempotency key or a new order ID can charge the payer twice
try {
  await createPayment(order, { idempotencyKey: order.paymentIdempotencyKey });
} catch (timeoutError) {
  await createPayment(order, { idempotencyKey: crypto.randomUUID() }); // ✗ New key = new business
  await createPayment({ ...order, orderNo: `${order.orderNo}-retry` }); // ✗ New order ID = new payment
}

Recommended polling frequency

• Leave at least 10 seconds between two queries for the same object, and don't poll in concurrent batches.
• A query only reads the state the platform currently knows. It doesn't trigger a query to the provider: the status updates only after the platform has queried the provider, so polling faster won't get you the result sooner.
• Webhooks are the primary channel and queries are the fallback. When the two disagree, the latest version wins.

429 and Retry-After

• 429 rate_limited: The request was not executed. Wait for Retry-After seconds, then retry with the original idempotency key. Using a different API key doesn't get around the merchant's overall limit.
• 503 temporarily_unavailable: The platform has paused new transactions on this channel. This request was also not accepted and created no payment. Retry later with the original idempotency key. It's the only 5xx that clearly means "not accepted". Treat every other 5xx as an unknown outcome.
• Client timeouts: at least 20 seconds for creating and confirming payments (the platform waits synchronously for the provider for about 15 seconds and returns 202 beyond that), and at least 10 seconds for queries.

Reference implementation for retries

Retry network errors, 429 and 5xx with the same idempotency key. If you still have no result, switch to querying or wait for the webhook.

const API_BASE = 'https://api.payhub.example';

// Retry network errors, 429 and 5xx (including 503 temporarily_unavailable) with the same idempotency key; return everything else to the caller
export async function postWithRetry(path, body, { idempotencyKey, maxAttempts = 5 } = {}) {
  let lastError;
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    let res = null;
    try {
      res = await fetch(`${API_BASE}${path}`, {
        method: 'POST',
        headers: {
          Authorization: `Bearer ${process.env.PAYHUB_API_KEY}`,
          'Content-Type': 'application/json',
          'Idempotency-Key': idempotencyKey // Every retry uses the same key
        },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(20_000) // The platform waits synchronously for about 15 seconds, so set a longer timeout
      });
    } catch (err) {
      lastError = err;
    }
    if (res && res.status !== 429 && res.status < 500) return res;
    if (attempt === maxAttempts) break;
    let waitMs = Math.min(30_000, 1000 * 2 ** (attempt - 1)) + Math.floor(Math.random() * 250);
    if (res?.status === 429) {
      const raw = res.headers.get('Retry-After');
      const seconds = raw === null ? NaN : Number(raw);
      if (Number.isFinite(seconds) && seconds >= 0) waitMs = seconds * 1000;
    }
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }
  // Still no result: mark the order "Confirming", then query or wait for the webhook; any later retry must use the same key
  throw Object.assign(new Error('Outcome unknown'), { code: 'RESULT_UNKNOWN', cause: lastError });
}

// If a crash left you without a saved payment ID, query by merchant order ID (exact match, case-sensitive)
export async function findPaymentByOrderNo(orderNo) {
  const qs = new URLSearchParams({ merchant_order_no: orderNo });
  const res = await fetch(`${API_BASE}/v1/payments?${qs}`, {
    headers: { Authorization: `Bearer ${process.env.PAYHUB_API_KEY}` },
    signal: AbortSignal.timeout(10_000)
  });
  if (!res.ok) throw new Error(`Query failed: HTTP ${res.status}`);
  const page = await res.json();
  return page.data[0] ?? null; // Order IDs are unique per environment, so at most one; null: no payment was ever created for this order
}

Check your implementation item by item with the self-test checklist in the Testing guide.