Usio Integration

Usio API documentation

Usio handles float disbursements (pinless credit) and float/subscription collections (pinless debit and ACH). Unlike JPM, Usio supports both instant pinless card payments and ACH bank transfers, and operates across four separate merchant accounts.

Authentication

Each request to the Usio API requires three credentials: the merchant account ID, a login, and a password. These are stored in AWS Secrets Manager and loaded once per Lambda cold start.

Pinless Payments

Pinless debit/credit uses tokenized card references to charge or credit a user’s debit card without requiring the raw card number or CVV. Tokens are created once in the mobile app (using the Usio master account), then stored in DynamoDB and reused for all subsequent payments.

Debit card tokens are stored in two tables as part of an ongoing migration: the new prod-payments single table (supports multiple cards per user) and the legacy pinless-default-card table (one record per user, used as a fallback for older cards). See DynamoDB Tables for the full schema and migration fallback behaviour.

Settlement: Instant. Pinless payments return success or failure immediately — no polling required.
What we store: Usio credit token (transaction_reference_id) and debit token (debit_transaction_reference_id). Raw card numbers are never stored (PCI compliant).
Failure codes: See the Usio gateway response codes for the full list of pinless failure codes.

Error 5030: Unable to locate record means Usio cannot find the original token. This typically occurs for tokens created before the master account migration — they were not transferred correctly.

ACH Payments

Usio ACH payments are submitted with the user’s account number, routing number, name, address, and email. Settlement takes several business days.

No webhooks: Usio does not send status callbacks. ACH payment status must be polled manually.
Polling: The check-ach-worker Lambda polls Usio daily for outstanding ACHSENT payments.
Return codes: Returned payments carry a standard NACHA return code. See Usio ACH return codes.

ACH Return Rate Limits

Usio enforces return rate thresholds per merchant account. Exceeding these limits can result in account restrictions.

Category	Threshold	Return Codes
Overall ACH return rate	< 15%	All return codes
Administrative returns	< 3%	R02, R03, R04
Unauthorized returns	< 0.5%	R05, R07, R10, R11, R29, R51

Merchant Accounts

We maintain four merchant accounts with Usio, each with a distinct role:

Account ID Name Purpose

Account ID	Name	Purpose
`10790868`	Master	Creates debit and credit tokens via the mobile app frontend. Tokens created here work across all other accounts. This account is not used for payment submission directly.
`29063402`	Float Debit	Receives ACH and pinless debits for float collections. All floats credited from account `29063403` are collected back to this account.
`29063403`	Float Credit	Sends ACH and pinless credits for float disbursements. NSF refunds and JPM-returned float payments are also sent from this account.
`29111679`	Subscription Debit	Collects subscription fees via Usio (webhook-triggered and batch collections). Scheduled subscription collections use JPM instead.

10790868

Master

Creates debit and credit tokens via the mobile app frontend. Tokens created here work across all other accounts. This account is not used for payment submission directly.

29063402

Float Debit

Receives ACH and pinless debits for float collections. All floats credited from account 29063403 are collected back to this account.

29063403

Float Credit

Sends ACH and pinless credits for float disbursements. NSF refunds and JPM-returned float payments are also sent from this account.

29111679

Subscription Debit

Collects subscription fees via Usio (webhook-triggered and batch collections). Scheduled subscription collections use JPM instead.

Usio Sync

The Usio sync system periodically pulls transaction data from the Usio API to keep DynamoDB payment records accurate. It is necessary because Usio has no webhook mechanism. The usio-scheduler Lambda runs every 30 minutes and enqueues jobs by date range and merchant account; the usio-syncer Lambda processes each job and writes payment records to DynamoDB.

See Payment Syncing for the detailed flow diagram and how the Usio sync fits into the broader ACH reconciliation picture.

Debit Card Token Refresh

Usio tokens can expire. A daily refresh cycle (usio-refresh-scheduler → SQS → usio-refresh-worker) queries both the new prod-payments single table and the legacy pinless-default-card table for expiring cards, de-duplicates by token reference ID, and refreshes tokens via the Usio API. Both tables are updated with the new token.

See Payment Syncing for the detailed refresh flow diagram.

Payment Syncing — ACH status polling and Usio transaction sync flows
Blocklist — Which Usio return codes trigger user blocklisting
Prenotes — Usio prenote submission for bank account verification
DynamoDB Tables — Debit card table schemas and migration fallback behaviour