Architecture

System Context

The Payments Service is 16 AWS Lambda functions. The API Lambda sits behind two AWS IAM API Gateways and is called by other FloatMe services, and by the mobile app for card management through the shared mobile API host; JPM reaches the webhook handler through the shared jpm.webhooks.floatme.io gateway. Scheduled and queue-driven Lambdas reconcile ACH settlement with JPM and Usio, and a DynamoDB stream feeds payment records carrying an event type onto the site-payments Kinesis stream.

system context payment service

Components

Runtime configuration is in Infrastructure. Names carry the site-payments- prefix (test, staging, or prod).

Component Trigger Purpose

site-payments-api

API Gateway site-payments and site-payments-rest (AWS IAM)

REST API — payment submission, debit cards, bank accounts, prenotes, refunds, fraud checks, blocklist, admin

site-payments-jpm-webhook-handler

API Gateway jpm.webhooks.floatme.io

Validates JPM status callbacks and enqueues REJECTED / RETURNED transactions — JPM Webhooks

site-payments-jpm-webhook-processor

SQS site-payments-jpm-webhooks

Marks the payment FAILED with the JPM return code and info

site-payments-check-ach-scheduler

EventBridge check-ach (daily 17:00 UTC)

Enqueues every ACHSENT debit for a settlement check — Check ACH

site-payments-check-ach-worker

SQS site-payments-check-ach

Completes ACH debits via a Plaid transaction match, a JPM status poll, or the 3-business-day rule

site-payments-usio-scheduler

EventBridge (three rules, prod only)

Fans out one Usio sync job per merchant account and job type — Usio Sync

site-payments-usio-syncer

SQS site-payments-usio-sync

Pulls Usio transactions, ACH returns, chargebacks, and the daily ACH risk report

site-payments-usio-refresh-scheduler

EventBridge site-usio-token-refresh-event (daily 15:00 UTC)

Enqueues debit cards expiring this month — Token Refresh

site-payments-usio-refresh-worker

SQS site-payments-usio-refresh

Refreshes Usio card tokens and stores the new expiration

site-payments-prenoter

SQS site-payments-prenotes

Calls the prenote endpoints for queued requests — Prenotes

site-payments-kinesis-feeder

DynamoDB Stream on payments (dynamo_legacy_region)

Publishes payment records with a non-empty event_type to Kinesis — Events

site-payments-blocklist-handler

Kinesis site-payments (SUBSCRIPTION_RETURNED, FLOAT_DEBIT_RETURNED)

Runs the return-code engine’s bank action on returned debits — ACH dispatch

site-payments-blocklist-remover

SQS site-payments-blocklist-remove

Writes a NOTBLOCKED record — Unblock flow

site-payments-balance-reporter

EventBridge balance-reporter (daily 13:00 UTC) + balance-reporter-hourly (prod only)

Posts Usio float-credit and loan-credit prefunding balances to Slack

site-payments-jpm-syncer

EventBridge jpm-syncer (daily 13:00 UTC)

Copies the last three days of JPM transaction details into jpm-transaction-details — JPM Transaction Sync

site-payments-debit-card-fixer

SQS site-payments-debit-fixer

Repairs debit card records for user IDs enqueued by scripts/debit-fixer — Debit Fixer

Storage is in DynamoDB Tables: payment records in the payments table (dynamo_legacy_region), everything else in the site-payments single table and a set of named tables.

External Dependencies

Service Role

JPM

Subscription ACH debits and JPM prenotes (mTLS + JWS); status webhooks; status polling and transaction detail sync

Usio

Pinless debit and credit, RTP credit, float and loan ACH, Usio prenotes and refunds, token refresh, transaction and return sync, ACH risk report, prefunding balances

Transactions Service

Account and routing numbers with the official account mask; Plaid transactions for Plaid clearing

Float Service

Active floats for card-change rules; float list and collection history for Plaid clearing

LOC Service

Open installment loans for card-change rules

User Service

Activates the user after a card save; user lookup for the first-debit event and comms email; bans on the debit-card fraud window

Underwriting Service

Recalculation after a debit card save

Admin API

Admin note on a suspended-card rejection

GrowthBook

Feature flags — GrowthBook Flags

Iterable

Per-code comms events from the return-code engine

Segment

first_debit_card_connected and debit_card_updated events

AppsFlyer

first_debit_card_connected server-to-server event

Slack

Balance reports

AWS KMS

alias/site-payments-bank-account key for account and routing numbers

Kinesis site-payments

Outbound payment event stream — Events