# Idempotent Financial Workflows

> Designs retry-safe financial workflows across APIs, workers, webhooks, queues, payment providers. Use for payments, payouts, transfers, imports, webhooks, scheduled jobs, retries, or outbox/inbox flows risking duplicate money moves.

- Skill: `rockclaver/idempotent-financial-workflows` (Agent Skill)
- Install (CLI): `npx skillmds@latest add rockclaver/idempotent-financial-workflows`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rockclaver/idempotent-financial-workflows/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: rockclaver (https://skillmd.com/u/rockclaver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/rockclaver/idempotent-financial-workflows

---


# Idempotent Financial Workflows

## Workflow

1. **Classify**: API command (client retries), webhook (duplicate/out-of-order), worker job (queue redelivers), batch import (file/row reprocessed), external call (provider succeeds while local times out).
2. **Define idempotency**: key source (client key, event id, transfer id, row/business key); scope (tenant/account/provider/endpoint); stored result (pending/succeeded/failed/payload/ref); conflict: same key+payload returns prior result, different payload rejected; prefer durable DB constraints over in-memory dedupe.
3. **Order side effects**: validate first; persist intent before external calls; wrap co-committing state in a transaction; use an outbox for post-commit effects; store provider ids; expose completion only once records exist.
4. **Test**: duplicate same key/payload; duplicate same key/diff payload; retry after timeout/exception; webhook delivered twice; worker crash after partial writes; out-of-order events.
5. **Implement**: reuse existing transaction helpers, repositories, job frameworks, provider adapters; keep handlers thin, idempotency decisions in a service layer.

## Guardrails

- Do not rely on frontend disabling, memory, or queue visibility timeouts alone.
- Do not call a money-moving provider before recording local intent to recover.
- Do not mark an operation permanently failed if the side effect may have succeeded.
- Do not hide duplicate/conflict behavior; log it in metrics or stored state.