Feature Summary

A categorized reference of capabilities exposed by the Payments Service. For flow details and data models, follow the cross-references on each section.

Payments

Feature Description

Feature	Description
Submit payment	Accepts a payment request and routes it to the appropriate processor and method. Supports ACH subscription via JPM, ACH subscription/float credit/debit via Usio, and pinless subscription/float credit/debit via Usio.
Get payments by user	Returns all payment records for a given user from the `prod-payments` table, ordered by submit date.
Get payment by confirmation ID	Returns a single payment record by its processor-assigned confirmation ID.

Submit payment

Accepts a payment request and routes it to the appropriate processor and method. Supports ACH subscription via JPM, ACH subscription/float credit/debit via Usio, and pinless subscription/float credit/debit via Usio.

Get payments by user

Returns all payment records for a given user from the prod-payments table, ordered by submit date.

Get payment by confirmation ID

Returns a single payment record by its processor-assigned confirmation ID.

See Payment Flow for the full submission lifecycle and status transition reference.

Prenotes

Feature Description

Feature	Description
Submit JPM prenote	Submits a zero-dollar ACH transaction to JPM for the user’s bank account. Validates the account before the first real ACH payment.
Submit Usio prenote (subscription account)	Submits a zero-dollar ACH transaction to the Usio subscription debit account (`29111679`).
Submit Usio prenote (float debit account)	Submits a zero-dollar ACH transaction to the Usio float debit account (`29063402`).

Submit JPM prenote

Submits a zero-dollar ACH transaction to JPM for the user’s bank account. Validates the account before the first real ACH payment.

Submit Usio prenote (subscription account)

Submits a zero-dollar ACH transaction to the Usio subscription debit account (29111679).

Submit Usio prenote (float debit account)

Submits a zero-dollar ACH transaction to the Usio float debit account (29063402).

See Prenotes for the submission flow, batch processing, and NACHA return code reference.

Debit Cards

Feature	Description
Save debit card	Stores Usio pinless debit and credit tokens for a user. Raw card numbers are never stored (PCI compliant).
Get debit card	Returns the current debit card record for a user, including masked card number and validity status.
Delete debit card	Removes a user’s debit card record. Subsequent pinless payments will fail until a new card is added.
Check debit card changeable	Determines whether a user’s debit card can currently be changed based on recent payment activity.
Get debit card changes	Returns the history of debit card changes for a user.
Admin update debit card	Support/admin-only endpoint to update debit card details, including overriding validity status.
Toggle debit card failure	Test-environment-only endpoint. Forces a debit card to return a failure response for testing purposes.

Feature

Description

Save debit card

Stores Usio pinless debit and credit tokens for a user. Raw card numbers are never stored (PCI compliant).

Get debit card

Returns the current debit card record for a user, including masked card number and validity status.

Delete debit card

Removes a user’s debit card record. Subsequent pinless payments will fail until a new card is added.

Check debit card changeable

Determines whether a user’s debit card can currently be changed based on recent payment activity.

Get debit card changes

Returns the history of debit card changes for a user.

Admin update debit card

Support/admin-only endpoint to update debit card details, including overriding validity status.

Toggle debit card failure

Test-environment-only endpoint. Forces a debit card to return a failure response for testing purposes.

See DynamoDB Tables for the pinless-default-card schema and token lifecycle.

Fraud

Feature	Description
Perform fraud checks	Evaluates up to four fraud signals for a user: user ID history, install ID history, bank account hash (detects shared bank accounts across users), and debit card hash (detects shared cards across users).
Save fraud check results	Persists the results of an external fraud evaluation for audit and downstream use.

Feature

Description

Perform fraud checks

Evaluates up to four fraud signals for a user: user ID history, install ID history, bank account hash (detects shared bank accounts across users), and debit card hash (detects shared cards across users).

Save fraud check results

Persists the results of an external fraud evaluation for audit and downstream use.

See Fraud Detection for how checks are evaluated and stored.

Refunds

Feature Description

Feature	Description
Submit refund	Creates a Usio refund transaction. Can be tied to a specific payment record or submitted as an arbitrary amount not linked to any existing payment.
Get refunds by user	Returns all refund records for a given user from the `usio-debit-refunds` table.

Submit refund

Creates a Usio refund transaction. Can be tied to a specific payment record or submitted as an arbitrary amount not linked to any existing payment.

Get refunds by user

Returns all refund records for a given user from the usio-debit-refunds table.

Bank Accounts

Feature	Description
Get bank account (last 4)	Returns the last 4 digits of the account number for a user’s bank account, identified by Plaid account ID.
Delete bank account	Removes a bank account record from DynamoDB. Also triggers blocklist removal for the user.
Check bank account exists	Looks up whether a bank account (by hash) already exists in the system, and returns the user IDs that have it saved. Used for fraud detection across accounts.

Feature

Description

Get bank account (last 4)

Returns the last 4 digits of the account number for a user’s bank account, identified by Plaid account ID.

Delete bank account

Removes a bank account record from DynamoDB. Also triggers blocklist removal for the user.

Check bank account exists

Looks up whether a bank account (by hash) already exists in the system, and returns the user IDs that have it saved. Used for fraud detection across accounts.

See DynamoDB Tables for the bank-accounts schema and encryption details.

Payment Syncing

Feature Description

Feature	Description
JPM webhook processing	Receives payment status callbacks from JPM and updates the corresponding payment record in DynamoDB. Decoupled via SQS — handler enqueues, processor updates.
ACH status polling (check-ach)	Daily CloudWatch-triggered job that polls both JPM and Usio for the current status of all outstanding `ACHSENT` payments. Marks cleared or returned payments accordingly.
Usio transaction sync	Periodic job (every 30 min in prod) that fetches raw transaction data from the Usio API and stores it in DynamoDB. Necessary because Usio has no webhook mechanism.
Usio token refresh	Daily job that refreshes Usio pinless debit/credit tokens before they expire, keeping debit cards valid for payment.
JPM transaction sync	Daily job that syncs JPM transaction data to DynamoDB.

JPM webhook processing

Receives payment status callbacks from JPM and updates the corresponding payment record in DynamoDB. Decoupled via SQS — handler enqueues, processor updates.

ACH status polling (check-ach)

Daily CloudWatch-triggered job that polls both JPM and Usio for the current status of all outstanding ACHSENT payments. Marks cleared or returned payments accordingly.

Usio transaction sync

Periodic job (every 30 min in prod) that fetches raw transaction data from the Usio API and stores it in DynamoDB. Necessary because Usio has no webhook mechanism.

Usio token refresh

Daily job that refreshes Usio pinless debit/credit tokens before they expire, keeping debit cards valid for payment.

JPM transaction sync

Daily job that syncs JPM transaction data to DynamoDB.

See Payment Syncing for detailed flow diagrams.

Blocklist

Feature Description

Feature	Description
Auto-blocklist on ACH return	When a `SUBSCRIPTION_RETURNED` or `FLOAT_DEBIT_RETURNED` Kinesis event carries a blocking return code (R02, R03, R04, R16, or JPM equivalents), the user is automatically blocked from future ACH payments.
Get blocklist status	Returns the current blocklist status for a user.
Get blocklist history	Returns the full history of blocklist status changes for a user.
Add to blocklist (manual)	Support/admin endpoint to manually block a user.
Remove from blocklist	Automatically triggered when a user updates their bank account (via SQS event). Also available as a manual admin endpoint.

Auto-blocklist on ACH return

When a SUBSCRIPTION_RETURNED or FLOAT_DEBIT_RETURNED Kinesis event carries a blocking return code (R02, R03, R04, R16, or JPM equivalents), the user is automatically blocked from future ACH payments.

Get blocklist status

Returns the current blocklist status for a user.

Get blocklist history

Returns the full history of blocklist status changes for a user.

Add to blocklist (manual)

Support/admin endpoint to manually block a user.

Remove from blocklist

Automatically triggered when a user updates their bank account (via SQS event). Also available as a manual admin endpoint.

See Blocklist for flow diagrams and the complete return code reference.

Balance Reporting

Feature Description

Feature	Description
Daily merchant account balance report	Once per day (13:00 UTC, prod only), the `balance-reporter` Lambda queries Usio for the current balance of each merchant account and posts a summary to Slack.
Hourly balance report	Runs every hour in prod. Posts a condensed balance update to Slack for real-time monitoring.

Daily merchant account balance report

Once per day (13:00 UTC, prod only), the balance-reporter Lambda queries Usio for the current balance of each merchant account and posts a summary to Slack.

Hourly balance report

Runs every hour in prod. Posts a condensed balance update to Slack for real-time monitoring.