From fe0d1a4e42d465305d804dafeb4dfd9fd7dc73ea Mon Sep 17 00:00:00 2001 From: Amandeep Singh Date: Sun, 28 Jun 2026 15:44:15 +0530 Subject: [PATCH] docs: add payment idempotency keys gotcha to sample repo --- .../.almanac/pages/payment-idempotency-keys.md | 13 +++++++++++++ examples/sample-repo/src/payments.ts | 4 ++-- 2 files changed, 15 insertions(+), 2 deletions(-) create mode 100644 examples/sample-repo/.almanac/pages/payment-idempotency-keys.md diff --git a/examples/sample-repo/.almanac/pages/payment-idempotency-keys.md b/examples/sample-repo/.almanac/pages/payment-idempotency-keys.md new file mode 100644 index 00000000..57084239 --- /dev/null +++ b/examples/sample-repo/.almanac/pages/payment-idempotency-keys.md @@ -0,0 +1,13 @@ +--- +title: Payment Idempotency Keys +summary: "Always pass an idempotency key when calling the payment provider to safely retry authorizations." +topics: [gotchas, payments] +files: + - src/payments.ts +--- + +# Payment Idempotency Keys + +When retrying an authorization request with the payment provider, it is critical to use an idempotency key. This ensures that the payment provider will not charge the customer twice if the first request succeeded but we timed out while waiting for the response. + +Agents editing [[src/payments.ts]] should ensure that any calls to the provider include an idempotency key generated at the beginning of the checkout session. diff --git a/examples/sample-repo/src/payments.ts b/examples/sample-repo/src/payments.ts index 60b4399b..ad8d1091 100644 --- a/examples/sample-repo/src/payments.ts +++ b/examples/sample-repo/src/payments.ts @@ -1,7 +1,7 @@ -export async function authorizePayment(amountCents: number): Promise { +export async function authorizePayment(amountCents: number, idempotencyKey?: string): Promise { if (amountCents <= 0) { throw new Error("amountCents must be positive"); } - return "receipt_sample"; + return "receipt_sample_" + (idempotencyKey || "none"); }