Idempotency & Safety Rails — Guide

In distributed payment systems, the same operation can be triggered multiple times — a Lambda function retried by SQS, a user double-clicking a payment button, a webhook replayed after a timeout. Without idempotency controls, each trigger executes independently and you end up with duplicate charges, double refunds, or duplicate payouts.

This tool addresses Agent Safety Layer 3 — the idempotency and retry safety layer. It generates a configuration file specifying how each payment action constructs its idempotency key, how long to retain deduplication records, and how the circuit breaker should behave when downstream payment services degrade.

The output is a YAML or JSON configuration file your agent reads at startup. It tells the agent exactly how to construct idempotency keys and when to stop retrying.

1. The left panel shows 13 action cards across 5 categories. Use the category chips to filter by Payments, Billing, Payouts, Operations, or Fraud.
2. Click any action card to open its detail panel on the right. Each action has its own idempotency strategy, key format, TTL, and circuit breaker settings.
3. The output updates in real time — there is no generate button. Every change you make is immediately reflected in the YAML/JSON output panel.

1. Strategy: how the idempotency key is generated. See the three strategy patterns below for details on when to use each.
2. Key Format: the exact string template used to construct the key. For example: {userId}-{orderId}-{action}. This is what gets stored in DynamoDB and checked on each subsequent invocation.
3. TTL: how long the idempotency record is retained. After expiry, the same key can trigger a new execution. Set this longer than your retry window.
4. PCI tag: indicates whether this action is in-scope for PCI DSS. If tagged in-scope, your DynamoDB idempotency table must satisfy PCI Req 3.5 (encryption at rest) and Req 10.2 (audit logging of access).

1. The circuit breaker panel is below the action list. It has one global configuration that applies across all actions (you can override per-action in the generated config).
2. Failures to open: how many consecutive failures trigger the circuit to open. Lower values are more sensitive (faster protection, more false positives). Start with 5.
3. Successes to close: how many consecutive successful probes in half-open state are needed before the circuit fully closes. Higher values are more conservative. Start with 2.
4. Open timeout: how long (in seconds) the circuit stays open before allowing probe requests through (entering half-open). Set this to your downstream service's typical recovery time — 30–60 seconds is common.
5. Retry settings: max retries, initial delay (ms), backoff multiplier, and max delay cap. With multiplier 2 and initial delay 500ms: retries occur at 500ms, 1s, 2s, 4s, then cap at max delay.

1. Toggle between YAML and JSON using the format chips. Click the export button to download agent-idempotency-config.yml or .json.
2. Load the file in your agent at startup. Reference each action's configuration block by its action key (e.g. payments.authorise, refunds.process) before executing the corresponding operation.
3. Store the idempotency keys in a DynamoDB table with TTL enabled. The table should be encrypted at rest (AWS managed key or KMS CMK) to satisfy PCI Req 3.5 if any in-scope actions are included.