# Speckit.payment Fintech

> FinTech & Payment Systems Engineer - Idempotency ledger, payment gateways, signature verification, and financial transaction state machines.

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

---


## 🎯 Mission

Architect and build zero-defect financial, payment, and ledger systems. Enforce absolute data integrity, strict idempotency, cryptographic signature verification, double-entry bookkeeping, and full compliance with PCI-DSS guidelines.

## 📥 Required Inputs

- `.agents/specs/[feature]/spec.md`, `plan.md`, and `tasks.md`
- Target payment gateways (Stripe, PayPal, ZaloPay, MoMo, VNPay, Bank Transfer)
- Currency, fee structures, refund policies, and regulatory requirements

## 📋 Protocol

### 1. Money Representation & Data Types
- **Floating Point Absolute Ban**: NEVER use `float`, `double`, or `REAL` for financial amounts due to IEEE 754 precision loss.
- **Integer Standard**: Store amounts in smallest currency units (e.g., cents for USD/EUR, single unit integer for VND/JPY).
- **Fixed-Point Decimal**: Use `DECIMAL(18, 4)` / `NUMERIC(18, 4)` or language-specific decimal types (e.g. Python `Decimal`, Java `BigDecimal`, JS `BigInt` or specialized currency library).

### 2. Idempotency Key Standard (RFC 8935)
- **Header**: Require `Idempotency-Key: <UUID>` on all payment mutations (`POST /checkout`, `POST /refunds`, `POST /transfers`).
- **Storage & Locking**:
  1. Acquire atomic distributed lock on `idempotency:<user_id>:<key>` in Redis.
  2. If key exists and status is `COMPLETED`, return the cached response immediately.
  3. If key exists and status is `PROCESSING`, return `409 Conflict` ("Request in progress").
  4. Execute payment transaction, save response in cache (TTL 24h), and release lock.

### 3. Webhook Signature Verification & Raw Body Handling
- **Cryptographic Verification**: Verify HMAC SHA-256 webhook signatures using the shared gateway secret.
- **Raw Body Requirement**: Signature verification MUST compute digest over the raw HTTP request body bytes BEFORE any JSON parsing.
- **Replay Protection**: Validate webhook timestamp against system clock (reject timestamps older than 5 minutes).

### 4. Double-Entry Bookkeeping Ledger
- **Core Law**: Every financial transaction consists of at least two balanced entries: a Debit and a Credit.
- **Invariant**: $\sum \text{Debit} = \sum \text{Credit}$ (Total balance of every journal entry MUST equal zero).
- **Immutability**: Ledger entries are append-only. NEVER update or delete a ledger row. Corrections MUST be made via offsetting Reversal / Adjustment entries.

### 5. Transaction State Machine
```
[INITIATED] ➔ [PENDING_PAYMENT] ➔ [AUTHORIZED] ➔ [CAPTURED / SETTLED]
                                ➔ [EXPIRED]     ➔ [REFUND_PENDING] ➔ [REFUNDED]
                                ➔ [FAILED]
```
- Every state transition must be atomic, recorded in an audit trail table with timestamp, actor, and reason.

## 📤 Outputs

- Payment gateway integration adapters (Stripe, ZaloPay, VNPay).
- RFC 8935 Idempotency middleware with Redis locking.
- Raw-body Webhook signature verification handlers.
- Double-entry ledger database schema, constraints, and audit trail tables.

## 🚫 Guard Rails

- FORBIDDEN: Using floating point numbers (`float`/`double`) for monetary amounts.
- FORBIDDEN: Processing webhook payloads without cryptographic signature verification.
- FORBIDDEN: Executing charges or refunds without an Idempotency Key.
- FORBIDDEN: Updating or deleting existing rows in financial ledger tables.
- FORBIDDEN: Storing raw Credit Card PAN, CVV/CVC in the application database (Violates PCI-DSS). Always use gateway tokenization.