Prevent duplicate payments - Get started

#!/usr/bin/env node
// Persist request_id BEFORE sending, so a retry after a timeout reuses the
// SAME key and body instead of risking a duplicate charge. This is the
// pattern behind every "safe to retry" claim elsewhere in these docs: the
// idempotency key only protects you if it existed before the first network
// call, not if you mint a fresh one on every attempt.
//
// The database layer below is an in-memory STUB for this sample only --
// replace `ordersDb` / `attemptsDb` with your real table. Everything else
// (timeout handling, backoff, status branching) is the pattern to copy.
const API_BASE = process.env.RADIUMONE_API_BASE || "https://api-sandbox.radiumone.io/gateway";
const accessToken = process.env.RADIUMONE_ACCESS_TOKEN;

// --- STUB: replace with your real database ---------------------------------
const ordersDb = new Map(); // order_id -> { paid }
const attemptsDb = new Map(); // order_id -> { attempt, request_id, body, final }

function getOrder(orderId) {
  return ordersDb.get(orderId) ?? { paid: false };
}

function markOrderPaid(orderId) {
  ordersDb.set(orderId, { paid: true });
}

// Loads the in-flight attempt row for this order, or creates the next one --
// all inside a single database transaction (this Map write stands in for
// `SELECT ... FOR UPDATE` + `INSERT`). A retry of an in-flight attempt reuses
// THIS row's request_id and body; only a brand-new attempt (after the prior
// one went final) gets a new row and a new key.
function loadOrCreateAttempt(orderId, buildBody) {
  const existing = attemptsDb.get(orderId);
  if (existing && !existing.final) return existing; // in-flight: reuse it, don't touch request_id
  const attempt = (existing?.attempt ?? 0) + 1;
  // ✗ don't: uuid() inside the retry loop -- request_id must be generated
  // ONCE per attempt, here, before the row is persisted.
  const requestId = `ord-${orderId}-pay-${attempt}`;
  const row = { attempt, request_id: requestId, body: buildBody(requestId), final: false };
  attemptsDb.set(orderId, row); // persisted BEFORE the purchase call below
  return row;
}

function markAttemptFinal(orderId) {
  const row = attemptsDb.get(orderId);
  if (row) row.final = true; // DECLINED: this key is done; the next attempt gets attempt+1
}
// --- end STUB ----------------------------------------------------------------

// Exponential backoff with jitter: attempt 1 waits ~250-500ms, doubling each
// attempt, capped at 4s -- avoids hammering the gateway in a tight retry loop.
function backoffMs(attempt) {
  const base = Math.min(250 * 2 ** (attempt - 1), 4000);
  return base + Math.random() * base;
}

async function sendWithTimeout(body, timeoutMs = 8000) {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);
  try {
    return await fetch(`${API_BASE}/v1/transactions/purchase`, {
      method: "POST",
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${accessToken}` },
      body: JSON.stringify(body), // identical bytes on every retry
      signal: controller.signal,
    });
  } finally {
    clearTimeout(timer);
  }
}

async function purchaseWithPersistedRequestId(orderId, maxAttempts = 4) {
  const order = getOrder(orderId);
  if (order.paid) return { skipped: true, reason: "order already paid" }; // fail-closed: never re-send for a paid order

  const attempt = loadOrCreateAttempt(orderId, (requestId) => ({
    request_id: requestId,
    amount: { currency: "SGD", value: "5000" },
    card: { token: "tok_from_elements" },
    channel: "ECOMMERCE",
    order_reference: `ORD-${orderId}`,
  }));

  for (let i = 1; i <= maxAttempts; i += 1) {
    let res;
    try {
      res = await sendWithTimeout(attempt.body);
    } catch (networkErrOrTimeout) {
      if (i === maxAttempts) throw networkErrOrTimeout; // fail-closed: surface it, don't guess
      await new Promise((r) => setTimeout(r, backoffMs(i)));
      continue; // timeout: retry the SAME stored body/request_id, never a new one
    }

    if (res.status >= 500) {
      if (i === maxAttempts) throw new Error(`server error ${res.status} after ${i} attempts`);
      await new Promise((r) => setTimeout(r, backoffMs(i)));
      continue; // 5xx: retry the SAME stored body/request_id
    }

    const payload = await res.json();
    if (!res.ok) {
      // A 4xx here (other than a replayed body-mismatch you triggered
      // yourself) is a bug in this code, not a retryable state.
      throw new Error(`purchase failed: ${payload.type ?? payload.code} (${res.status})`);
    }

    if (payload.data.status === "PENDING") {
      attempt.pendingTransactionId = payload.data.id; // you'll need this id even without a webhook
      return { status: "PENDING", transactionId: payload.data.id }; // defer to webhook/status inquiry, don't loop here
    }

    if (payload.data.status === "DECLINED") {
      markAttemptFinal(orderId); // this key is done; a NEW shopper attempt gets attempt+1, a new request_id
      return { status: "DECLINED", transactionId: payload.data.id };
    }

    // CAPTURED (or any other final success status).
    markOrderPaid(orderId);
    markAttemptFinal(orderId);
    return { status: payload.data.status, transactionId: payload.data.id };
  }
  throw new Error("unreachable");
}

purchaseWithPersistedRequestId("1001").then((r) => console.log(JSON.stringify(r, null, 2)));

#!/usr/bin/env python3
"""Persist request_id BEFORE sending, so a retry after a timeout reuses the
SAME key and body instead of risking a duplicate charge. This is the pattern
behind every "safe to retry" claim elsewhere in these docs: the idempotency
key only protects you if it existed before the first network call, not if
you mint a fresh one on every attempt.

The database layer below is an in-memory STUB for this sample only --
replace ``ORDERS_DB`` / ``ATTEMPTS_DB`` with your real table. Everything
else (timeout handling, backoff, status branching) is the pattern to copy.
"""
import os
import random
import time
from dataclasses import dataclass

import requests

API_BASE = os.environ.get("RADIUMONE_API_BASE", "https://api-sandbox.radiumone.io/gateway")
ACCESS_TOKEN = os.environ.get("RADIUMONE_ACCESS_TOKEN", "")


# --- STUB: replace with your real database ----------------------------------
@dataclass
class Attempt:
    attempt: int
    request_id: str
    body: dict
    final: bool = False
    pending_transaction_id: str | None = None


ORDERS_DB: dict[str, bool] = {}  # order_id -> paid
ATTEMPTS_DB: dict[str, Attempt] = {}  # order_id -> current attempt row


def get_order_paid(order_id: str) -> bool:
    return ORDERS_DB.get(order_id, False)


def mark_order_paid(order_id: str) -> None:
    ORDERS_DB[order_id] = True


def load_or_create_attempt(order_id: str) -> Attempt:
    """Loads the in-flight attempt row for this order, or creates the next
    one -- all inside a single database transaction (this dict write stands
    in for ``SELECT ... FOR UPDATE`` + ``INSERT``). A retry of an in-flight
    attempt reuses THIS row's request_id and body; only a brand-new attempt
    (after the prior one went final) gets a new row and a new key."""
    existing = ATTEMPTS_DB.get(order_id)
    if existing is not None and not existing.final:
        return existing  # in-flight: reuse it, don't touch request_id

    attempt_number = (existing.attempt if existing else 0) + 1
    # ✗ don't: uuid4() inside the retry loop -- request_id must be generated
    # ONCE per attempt, here, before the row is persisted.
    request_id = f"ord-{order_id}-pay-{attempt_number}"
    body = {
        "request_id": request_id,
        "amount": {"currency": "SGD", "value": "5000"},
        "card": {"token": "tok_from_elements"},
        "channel": "ECOMMERCE",
        "order_reference": f"ORD-{order_id}",
    }
    row = Attempt(attempt=attempt_number, request_id=request_id, body=body)
    ATTEMPTS_DB[order_id] = row  # persisted BEFORE the purchase call below
    return row


def mark_attempt_final(order_id: str) -> None:
    row = ATTEMPTS_DB.get(order_id)
    if row:
        row.final = True  # DECLINED: this key is done; the next attempt gets attempt+1
# --- end STUB -----------------------------------------------------------------


def backoff_seconds(attempt: int) -> float:
    """Exponential backoff with jitter: attempt 1 waits ~0.25-0.5s, doubling
    each attempt, capped at 4s -- avoids hammering the gateway in a loop."""
    base = min(0.25 * 2 ** (attempt - 1), 4.0)
    return base + random.random() * base


def purchase_with_persisted_request_id(order_id: str, max_attempts: int = 4) -> dict:
    if get_order_paid(order_id):
        return {"skipped": True, "reason": "order already paid"}  # fail-closed: never re-send for a paid order

    attempt = load_or_create_attempt(order_id)
    headers = {"Authorization": f"Bearer {ACCESS_TOKEN}"}

    for i in range(1, max_attempts + 1):
        try:
            resp = requests.post(
                f"{API_BASE}/v1/transactions/purchase",
                json=attempt.body,  # identical bytes on every retry
                headers=headers,
                timeout=8,
            )
        except requests.exceptions.Timeout:
            if i == max_attempts:
                raise  # fail-closed: surface it, don't guess
            time.sleep(backoff_seconds(i))
            continue  # timeout: retry the SAME stored body/request_id, never a new one

        if resp.status_code >= 500:
            if i == max_attempts:
                raise RuntimeError(f"server error {resp.status_code} after {i} attempts")
            time.sleep(backoff_seconds(i))
            continue  # 5xx: retry the SAME stored body/request_id

        payload = resp.json()
        if not resp.ok:
            # A 4xx here (other than a replayed body-mismatch you triggered
            # yourself) is a bug in this code, not a retryable state.
            code = payload.get("type") or payload.get("code")
            raise RuntimeError(f"purchase failed: {code} ({resp.status_code})")

        status = payload["data"]["status"]
        if status == "PENDING":
            attempt.pending_transaction_id = payload["data"]["id"]  # you'll need this id even without a webhook
            return {"status": "PENDING", "transaction_id": payload["data"]["id"]}  # defer to webhook/status inquiry

        if status == "DECLINED":
            mark_attempt_final(order_id)  # this key is done; a NEW shopper attempt gets attempt+1, a new request_id
            return {"status": "DECLINED", "transaction_id": payload["data"]["id"]}

        # CAPTURED (or any other final success status).
        mark_order_paid(order_id)
        mark_attempt_final(order_id)
        return {"status": status, "transaction_id": payload["data"]["id"]}

    raise RuntimeError("unreachable")


if __name__ == "__main__":
    import json

    print(json.dumps(purchase_with_persisted_request_id("1001"), indent=2))