neishap/payments-core

1. What is built (working code, 25/25 tests passing)

Module	File	What it does
Double-entry ledger	app/ledger.py	Integer-cent journal, balanced postings, holds, idempotency keys, trial balance always 0
Virtual cards	app/cards.py	Luhn-valid PANs, open loop (sponsor BIN) or closed loop (private prefix), AES-256-GCM PAN vault, HMAC-SHA256 fingerprints, CVV derived never stored, freeze/close
Authorization engine	app/cards.py	ISO 8583-style decisioning with real response codes: 00, 14, 51, 54, 57, 61, 62, N7; MCC and merchant locks; per-transaction and daily limits; hold, capture, reversal
Gift cards	app/stored_value.py	80-bit Crockford codes, hashed at rest, partial redemption, merchant scope (closed loop), CARD Act 5-year minimum enforced
Vouchers	app/stored_value.py	Fixed or percent off, max redemptions, expiry, merchant scope, booked as promo expense
Payroll	app/payroll.py	IRS Pub 15-T (2026) Worksheet 1A + annual percentage tables (standard and Step 2 checkbox, single, MFJ, HoH), W-4 Steps 3 and 4, Social Security 6.2% to the $184,500 wage base, Medicare 1.45% plus 0.9% over $200,000, FUTA 0.6% on first $7,000, FLSA overtime
Direct deposit	app/nacha.py	NACHA PPD files: 94-character records, blocking factor 10, entry hash, ABA check digit validation, credits 22/32, prenotes 23/33, debits 27/37
FedNow / Fedwire	app/iso20022.py	ISO 20022 pacs.008.001.08 with Business Application Header head.001, UETR, USABA clearing IDs
Bank bridge	app/bank_bridge.py	Single outbound gateway: file, SFTP, or HTTPS; every file SHA-256 hashed into the audit chain
Security	app/security.py	SHA-256, HMAC-SHA256, AES-256-GCM, hashed API keys, signed webhooks with replay window, tamper-evident hash-chained audit log
API	app/main.py	FastAPI, bearer keys, idempotency headers, all modules exposed under /v1
KYC + OFAC	app/compliance.py	CIP onboarding, SSN range validation (stored as HMAC + last 4), live Treasury SDN + alias list (39,688 entries loaded Oct 28, 2026), fuzzy name screening, CTR and structuring alerts
Fraud scoring	app/fraud.py	0-100 risk score on every authorization (amount z-score, velocity, decline bursts, new merchant, high-risk MCC, overnight); 70+ declines with code 59
Disputes	app/disputes.py	Network reason codes, Reg E provisional credit, representment reversal
ACH returns	app/ach_returns.py	R-code returns reverse the ledger; NOC C-codes surface account corrections
Reconciliation	app/reconciliation.py	Ledger vs bank statement matching; flags breaks on both sides
Tax filings	app/tax_filings.py	Form 941, 940, EFTPS monthly/semiweekly schedule, Nevada MBT 1.17% over $50,000 a quarter, Nevada UI on the $43,700 wage base at your DETR-assigned rate
Earned wage access	app/ewa.py	Free advances up to 50% of earned net pay, auto-recovered at payroll; pay-to-card puts net pay in a wallet instantly
Key management	app/kms.py	Versioned AES-256-GCM keyring, zero-downtime rotation of every stored secret
Access control	app/security.py, app/main.py	Scoped API keys (payroll, cards, chain, compliance, admin), TOTP (RFC 6238) on admin actions, per-key rate limiting
Observability	app/main.py	JSON request logs, Prometheus /metrics including live ledger imbalance
ISO 8583 gateway	app/iso8583.py	Bitmap codec, 0100/0110 handling, TCP server with 2-byte length framing for processor links
Webhooks	app/main.py	HMAC-SHA256 signed events with timestamp
Feeless tangle	app/chain.py	IOTA-style DAG, Ed25519, PoW anti-spam instead of gas, coordinator-signed minting, coins, sub-coins, NFTs (gaming, audio), airdrops, mining rewards, P2P gossip and sync, supply cap
DEX + bot	app/dex.py	Escrow-locked orders, single-block atomic swaps, cancel, market-making bot with inventory cap
Coin bridge	app/bridge_onchain.py	No-fee peg between coin and payment wallets
Deploy	Dockerfile, docker-compose.yml, .env.example	Container image and a two-node network
Front end	static/index.html	Dashboard: wallets, cards, gift cards, vouchers, payroll, instant payments, tangle, compliance and ops

Payroll was checked against the IRS 2026 monthly wage-bracket table (row $2,245 to $2,275: Single $92, Single checkbox $180, MFJ checkbox $92). The engine matches within $1.

2. Money flow, front end to back end

1. Front end calls the API with a bearer key and an Idempotency-Key header.
2. API validates the request and calls the domain module (cards, stored value, payroll).
3. Domain module writes balanced journal entries to the ledger. Each write is appended to the SHA-256 audit chain.
4. Anything leaving the platform (ACH, FedNow, Fedwire) becomes a file or message in the bank bridge.
5. The sponsor bank submits it to the Fed (FedACH, FedNow, Fedwire). Card traffic goes through the card network via your processor.
6. Returns, settlements and statements come back (NACHA returns, camt.054/camt.053, network clearing files) and are reconciled against the ledger.

3. The Federal Reserve link: how it works in the real world

• Only depository institutions (banks, credit unions) with a Fed master account connect directly to FedACH, FedNow and Fedwire. A fintech reaches them through a sponsor bank that holds your customers' money in an FBO (for benefit of) account.
• Fedwire Funds moved to ISO 20022 on July 14, 2025. FedNow has used ISO 20022 since it launched in July 2023. The pacs.008 builder here follows that format. Your bank's certification with the Fed is the final check.
• Reserve requirements have been 0% since March 26, 2020, so you don't hold reserves. The bank does the Fed side.
• What you need from the bank: ODFI routing number, Company ID, SFTP or API credentials, the Fed service ID for instant payments, and your FedNow transaction limit. These all map to PAY_* environment variables in app/config.py.

4. Official structures required to go live

Area	Requirement	Who issues it
Federal registration	Money Services Business registration (FinCEN Form 107), renewed every 2 years	FinCEN
State licensing	Money transmitter license in each state you serve. In Nevada: NRS Chapter 671, through NMLS	Nevada Financial Institutions Division and other states
Banking	Sponsor bank / BaaS agreement, FBO account, ODFI agreement for ACH	Your sponsor bank
Cards (open loop)	BIN sponsorship, network program approval, processor certification	Visa or Mastercard through the sponsor bank
Card data	PCI DSS v4.0.1 compliance (v4.0 future-dated requirements mandatory since March 31, 2025)	PCI SSC, verified by a QSA
ACH	Nacha Operating Rules, Third-Party Sender registration if you originate for others, fraud monitoring rules (2026 phases)	Nacha through the ODFI
Consumer protection	Reg E (EFTA) including the Prepaid Accounts Rule; gift card rules 12 CFR 1005.20	CFPB
AML	BSA/AML program, CIP/KYC, OFAC SDN screening, SAR and CTR filing, FinCEN prepaid access rule	FinCEN, OFAC, the sponsor bank's oversight
Payroll tax	EIN, EFTPS federal deposits, Form 941 quarterly, Form 940 annually, W-2s	IRS
Nevada payroll	Unemployment insurance account; Modified Business Tax	Nevada DETR; Nevada Department of Taxation
Unclaimed property	Gift card and dormant balance escheat (NRS 120A)	Nevada State Treasurer
Security assurance	SOC 2 Type II (banks and partners will ask)	Independent CPA firm

5. What only you and your partners can supply

Everything buildable in code is now in the codebase. These steps happen outside it:

1. Sponsor bank agreement: FBO account, ODFI credentials, Fed service ID, FedNow limit.
2. Licensing: FinCEN MSB registration and state money transmitter licenses (Nevada FID through NMLS).
3. Card program: BIN sponsorship and processor certification of the ISO 8583 link against their spec.
4. Audits: PCI DSS v4.0.1 assessment by a QSA and a SOC 2 Type II report.
5. Hardware keys: load the keyring from an HSM or cloud KMS instead of environment variables.
6. Scale-out database: the schema is portable; move from SQLite to managed PostgreSQL before multiple API workers.
7. Tokens sold to the public: get a securities and money-transmission legal review before any sale or fiat peg goes public.

6. Run it

pip install -r requirements.txt
python -m pytest -q tests
uvicorn app.main:app --port 8000
# open http://localhost:8000, click "Create first key"
docker compose up    # two-node network (set PAY_COORDINATOR_PUB for node B)

Production settings live in environment variables (PAY_ENV, PAY_ODFI_ROUTING, PAY_COMPANY_ID, PAY_CARD_BIN, PAY_FED_RECEIVER_ID, PAY_BRIDGE_MODE, SFTP and key settings). Nothing goes live until the sponsor bank supplies those values.

7. Crypto checkout: the main funding pipeline (v4)

app/crypto_pay.py makes crypto the front door of the processor:

1. The merchant creates a payment intent in USD: POST /v1/crypto/intents {amount_cents, asset}.
2. The customer pays on the hosted checkout page /pay/{id}, which shows a QR code and an exact amount.
3. Watchers detect and confirm the payment:
   • IOT on the feeless tangle: one fresh deposit address per intent, confirmed by coordinator milestones, swept to treasury with no fee.
   • ETH-SEP on Sepolia: a unique wei tag per intent, matched in blocks through a free public RPC, settled after 3 confirmations and a receipt status check.
4. Settlement credits USD to the platform funding wallet in the double-entry ledger, and payment_intent.succeeded fires as a signed webhook.
5. That funding wallet backs cards, payroll, and payouts.

Pricing: live ETH/USD from Coinbase, failing over to Kraken, then CoinGecko, with a 60-second cache and a 30-minute quote lock.

Real-money rails: ETH mainnet and Base are watch-only, paid straight to the owner's own wallet (PAY_MAINNET_ENABLED=1, PAY_EVM_MAINNET_ADDRESS). The server never holds a key that receives real money.

Legal: taking crypto for your own goods is ordinary merchant activity. Processing crypto payments for other businesses, or converting crypto to dollars for them, is money transmission. That needs FinCEN MSB registration and state licenses (Nevada through NMLS). Tax: every crypto received is income at its fair-market value on the day received.

v5 (2026-10-31)

• 43 tests pass on SQLite and on PostgreSQL 17 (full suite run with PAY_DATABASE_URL); live Sepolia watcher test passes.
• PostgreSQL adapter (row locks, upsert translation, tangle snapshot mirrored into Postgres for ephemeral hosts).
• KMS providers + rotation, card vault service, config validator, two-pass redaction, hash-chained forensic reports.
• Reg E timers, ACH returns/NOC/prenote, BSA (CIP/CTR/SAR), NRS 120A escheatment.
• Real-money wallet: POST /v1/admin/mainnet sets YOUR self-custody address (watch-only; one address serves Ethereum + Base). GET /v1/admin/wallets lists every receiving address.
• Standalone admin console: static/admin.html (also served at /admin). Generates a wallet in your browser; the key never leaves it.
• Public deploys: set PAY_BOOTSTRAP_TOKEN so only you can mint the owner API key.
• Nothing has been filed or submitted to any agency or bank.