Payments Service

The Payments Service executes every money movement on the FloatMe platform: pinless debit and credit, RTP, and ACH through Usio and JPM. It stores the debit card tokens and bank accounts those payments use, resolves ACH settlement after submission, and publishes payment lifecycle events to Kinesis.

What This Service Owns

Domain Responsibility

Domain	Responsibility
Payments	Routing each submission to JPM or Usio, persisting the record, and tracking it to `COMPLETED`, `FAILED`, `CHARGED_BACK`, or `REFUNDED`
Payment Syncing	Resolving `ACHSENT` payments through JPM webhooks, daily settlement checks, and Usio transaction, return, and chargeback syncs
Debit Cards	Tokenized Usio card storage, card-change rules, suspension, token refresh, and change history
Bank Accounts	KMS-encrypted account and routing numbers with account masks, and zero-dollar prenotes
Return Codes	The per-code engine that invalidates bank accounts and cards, blocklists users, and sends Iterable comms on ACH returns and card declines
Blocklist	`BLOCKED` / `NOTBLOCKED` records that stop ACH collection until a user links a new bank account
Fraud	24-hour float fraud signals on user, install, bank account hash, and card hash
Refunds	Usio refunds tied to a payment or submitted as an arbitrary amount
Events	Payment lifecycle events on the `site-payments` Kinesis stream

Payments

Routing each submission to JPM or Usio, persisting the record, and tracking it to COMPLETED, FAILED, CHARGED_BACK, or REFUNDED

Payment Syncing

Resolving ACHSENT payments through JPM webhooks, daily settlement checks, and Usio transaction, return, and chargeback syncs

Debit Cards

Tokenized Usio card storage, card-change rules, suspension, token refresh, and change history

Bank Accounts

KMS-encrypted account and routing numbers with account masks, and zero-dollar prenotes

Return Codes

The per-code engine that invalidates bank accounts and cards, blocklists users, and sends Iterable comms on ACH returns and card declines

Blocklist

BLOCKED / NOTBLOCKED records that stop ACH collection until a user links a new bank account

Fraud

24-hour float fraud signals on user, install, bank account hash, and card hash

Refunds

Usio refunds tied to a payment or submitted as an arbitrary amount

Events

Payment lifecycle events on the site-payments Kinesis stream

Documentation

Architecture — system context, component inventory, external dependencies
Infrastructure — Lambda config, API gateways, queues, streams, schedules, secrets
API Specification — OpenAPI specs (Swagger UI)
DynamoDB Tables — every table and single-table item type, keys, enums
Payment Flow — routing, merchant accounts, pinless gates, statuses, RTP, refunds
Payment Syncing — JPM webhooks, check-ach, Usio sync, JPM transaction sync
Debit Cards — card add and change rules, suspension, first-debit event, token refresh
Bank Accounts & Prenotes — account cache, masks, removal, prenotes
Return Codes — engine, dispatch paths, and the generated per-code tables
Blocklist — block and unblock flows, record semantics
Fraud Detection — check sequence, signals, environment toggles
Events — published event types and consumers, consumed queues
Feature Flags — GrowthBook flag index