Idempotency

curl -X POST "https://api.next.orenda.finance/v1/customers/{customerId}/accounts/{accountId}/payments" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f1c2e8a-7b4d-4e91-a5c2-9d0f6b18e4a7" \
  -H "Content-Type: application/json" \
  -d '{
        "beneficiaryId": "ben_4b8e1c9d",
        "amount": "150.00",
        "currency": "GBP",
        "reference": "Rent",
        "purpose": "PP001"
      }'

// Mint once, when the user commits to the action.
// crypto.randomUUID() needs a secure context (https/localhost) in the browser,
// and Node 19+. On older Node: require("crypto").randomUUID().
const idempotencyKey = crypto.randomUUID();

const backoff = (attempt) =>
  new Promise((r) => setTimeout(r, 500 * attempt));

async function sendPayment(attempt = 1) {
  let res;
  try {
    res = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${accessToken}`,
        "Idempotency-Key": idempotencyKey, // same key on every attempt
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payment) // same parameters on every attempt
    });
  } catch (networkError) {
    // The case this whole page exists for: we never saw a response, so we don't
    // know whether the payment went out. The key makes resending safe.
    if (attempt < 5) {
      await backoff(attempt);
      return sendPayment(attempt + 1);
    }
    throw networkError;
  }

  // A gateway can return HTML, so don't assume the body parses.
  const result = await res.json().catch(() => null);

  // Retry the two transient cases with the SAME key: the server hasn't given a
  // final answer (5xx), or another attempt is still mid-flight. Everything else
  // is final — IDEMPOTENCY_KEY_CONFLICT in particular is permanent, so retrying
  // it just repeats the same error.
  const transient =
    res.status >= 500 ||
    (res.status === 409 && result?.code === "IDEMPOTENT_REQUEST_IN_PROGRESS");

  if (transient && attempt < 5) {
    await backoff(attempt);
    return sendPayment(attempt + 1);
  }

  return result;
}