Idempotency

How to make a retry safe, and why a blank key is rejected.

The dangerous moment in any payment integration is a request you sent but never got an answer to. The charge may have committed. Retrying blindly charges the customer twice; giving up may hand over goods that were never paid for.

An idempotency key removes the guess.

Idempotency-Key: order-84271-attempt-1

Send the same key on every retry of the same sale, and Vibepay collapses them into exactly one payment. The first request charges; every repeat gets the original transaction back.

The rule that matters

One key per sale attempt — reused across every retry of that attempt. A key generated fresh on each HTTP call protects nothing: the retry carries a different key and becomes a second, separate charge.

Generate the key when the cashier confirms the amount, hold it for the whole attempt, and throw it away only when you get a final answer.

// Right — generated once, per sale attempt.
const idempotencyKey = `sale-${saleId}-${Date.now()}`;

for (let attempt = 0; attempt < 3; attempt++) {
  try {
    return await charge(qrToken, amountMNT, idempotencyKey);  // same key each time
  } catch (e) {
    if (!isRetryable(e)) throw e;
    await backoff(attempt);
  }
}

// Wrong — a new key per call turns three retries into three charges.
for (let attempt = 0; attempt < 3; attempt++) {
  await charge(qrToken, amountMNT, crypto.randomUUID());
}

What a repeat returns

201 — same transaction

The repeat matched the original in every respect. You get the original transaction back, with the same id. The customer was charged once.

409 — conflict

The key was reused for a different charge, or the original has since been reversed. Nothing was charged. Use a fresh key for a genuinely new sale.

Because a matched replay returns 201, your success path needs no special handling at all — the retry simply succeeds. That is the point.

Choosing keys

Rule	Detail
Length	1–255 characters
Uniqueness	Per merchant, not per terminal. Two tills in one shop share a namespace, so include something till-specific or random.
Format	Anything. A UUID, or sale-{id}-{timestamp}, or your own order number plus an attempt nonce.
Reuse	Never across different sales. A repeated key on a different amount is a 409, not a charge.

Since keys are scoped to your merchant rather than to a terminal, a bare sequential counter per till will eventually collide with the till next to it. Prefix it, or use a UUID.

Never send a blank key

400 Bad Request

Idempotency-Key must not be blank (omit the header entirely to opt out of retry collapsing)

An empty header is rejected on purpose. It reads, in code and in logs, as though idempotency is implemented — while doing nothing at all. That is precisely the failure that double-charges a customer on a timeout, so the API refuses it at the boundary instead of letting it through.

If you genuinely do not want retry collapsing, omit the header. That is allowed, and it is explicit.

What is protecting the customer

Three independent mechanisms, so a gap in one is covered by another:

1. The idempotency key

   Collapses your retries into one transaction.

2. The single-use QR code

   Even with no key at all, a scanned code cannot be charged twice — the second attempt is a 409.

3. Replay resolution

   A retry that arrives after the original committed is recognised as a repeat rather than reported as a spurious decline, even though the balance and the code have both moved on.

You should still send a key. The QR code protects against charging the same scan twice; only the key protects against a retry of a request whose outcome you never learned.