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.