Idempotency and Retries

A request can time out after Payment Labs has done the work. Before you retry, you need to know whether repeating the request is harmless or creates a second object. This page answers that for every operation that changes data.

Before you start

Read Errors for which status codes to retry and how to back off.

The short version

• Payment Labs has no idempotency-key header. Sending the same request twice is safe only where this page says so.
• Creating batches, payments, checkouts, refunds, plans and offers is not idempotent. A retry can create a duplicate. Check first, using your referenceId.
• Moving money on an existing object (submitting a payment, charging a checkout, approving and paying a payment request) is protected: a repeat never pays twice.
• Wallet credits and charges are idempotent when you send a referenceId. Wallet load refunds are always idempotent on their required externalId.

Operations that are not idempotent

Each call creates a new object, even with the same body. Payment Labs does not check referenceId for uniqueness on these.

Pattern for a safe create:

async function createPaymentOnce(token: string, batchId: string, body: { referenceId: string } & Record<string, unknown>) {
  const headers = { Authorization: `Bearer ${token}`, "Content-Type": "application/json" };
  const base = "https://api-sandbox.paymentlabs.io";
  try {
    const created = await fetch(`${base}/batches/${batchId}/payments`, { method: "POST", headers, body: JSON.stringify(body) });
    if (created.ok) return created.json();
    if (created.status < 500) throw new Error(`Create failed with ${created.status}: ${await created.text()}`);
  } catch (error) {
    if (!(error instanceof TypeError)) throw error; // network failure: fall through and check
  }
  await new Promise((resolve) => setTimeout(resolve, 5000));
  const search = await fetch(`${base}/payments/search`, {
    method: "POST",
    headers,
    body: JSON.stringify({
      filter: {
        all: [
          { fact: "batchId", operator: "equals", value: batchId },
          { fact: "referenceId", operator: "equals", value: body.referenceId },
        ],
      },
      pageSize: 10,
    }),
  }).then((r) => r.json() as Promise<{ data: unknown[] }>);
  if (search.data.length > 0) return search.data[0];
  throw new Error("Payment was not created; it is safe to send the create request again");
}

This works only if each referenceId you send is unique in your system. Use your own invoice, order or transfer ID.

Operations that are safe to repeat

Resend Webhook is the exception by design: each call delivers the event to your endpoint again.

Retrying a payout safely

1. Create the payment with a unique referenceId. On a timeout, search for it before creating again.
2. Submit it. On a timeout, read the payment with Get Payment:
   • status is still DRAFT and isSubmittable is true: submit again.
   • Any status past DRAFT (SUBMITTED, PROCESSING and so on): the first submit worked. Do nothing.
3. A FAILED or RETURNED payment can be submitted again after you fix the cause (for example after the payee updates their bank account). That is a new payout attempt for the same payment, not a duplicate payment.

Handling duplicate webhooks

Webhooks are delivered at least once, and a resend delivers the same event again. Make your handler idempotent: key your processing on the object ID and its status, and ignore an event that does not change what you already recorded. See Webhooks.

Next steps

• Webhooks
• Errors