API Reference

Human-readable reference for all Payments Service REST endpoints. For interactive exploration and full request/response schemas, see API Specification (Swagger UI).

Authentication

All endpoints require AWS Signature V4 (SigV4) authentication via the Authorization header.

Caller Type Authentication

Internal FloatMe services

AWS IAM + SigV4. The caller’s AWS account ID is validated by the fmsdk/authorizer middleware.

Mobile app

JWT token. The user ID is extracted from the token by the authorizer middleware and used for path parameter validation.

Payments

Method Path Summary

POST

/payments

Submit a payment. Routes to JPM ACH (subscription), Usio ACH (float/loan), Usio pinless debit/credit, or Usio RTP based on request body. Returns status of ACHSENT, COMPLETED, or FAILED.

GET

/{user_id}/payments

Get all payment records for a user from prod-payments, ordered by submit date.

GET

/payments/{confirmation_id}

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

See Payment Flow for routing logic and status transitions.

Prenotes

Method Path Summary

POST

/prenotes/jpm

Submit a zero-dollar ACH prenote to JPM for bank account validation. Fetches bank account from DynamoDB, decrypts with KMS, submits directly to JPM.

POST

/prenotes/usio

Submit a zero-dollar ACH prenote to Usio. Can target the subscription debit account (29111679) or float debit account (29063402) depending on the request body.

See Prenotes for submission flow and NACHA return code reference.

Debit Cards

Two versions of the debit card endpoints coexist, backed by different DynamoDB tables:

  • v1 endpoints use the legacy path /{user_id}/debit-card (singular). They operate on pinless-default-card — the legacy table with one record per user.

  • v2 endpoints use /{user_id}/payments/debit-cards (plural, nested under payments). They operate on the new prod-payments single table, which supports multiple debit cards per user.

New cards are written to both tables when primary_card_type = ALL. Reads on the new table fall back to the legacy table transparently — see DynamoDB Tables for the migration fallback behaviour.

v1 Endpoints (Legacy)

Method Path Summary

POST

/{user_id}/debit-card

Save a Usio pinless debit/credit token for a user. Raw card numbers are never stored.

GET

/{user_id}/debit-card

Get the user’s primary debit card record, including masked card number and validity status.

DELETE

/{user_id}/debit-card

Delete the user’s debit card record.

GET

/{user_id}/debit-card/check

Check whether the user’s debit card can currently be changed based on recent payment activity. Returns 402 Payment Required if a change is not allowed due to an outstanding float or loan.

PATCH

/{user_id}/debit-card/toggle-failure

Test environment only. Forces the user’s debit card to return a failure response. Used for QA payment failure testing.

GET

/{user_id}/debit-card/changes

Get the history of debit card changes for a user.

v2 Endpoints

Method Path Summary

POST

/{user_id}/payments/debit-cards

Save a Usio debit token (v2 path). Uses v2 card validation logic; skips outstanding-float check for admin callers.

GET

/{user_id}/payments/debit-cards

Get all debit cards for a user. Accepts optional debit_card_status query parameter (ACTIVE).

GET

/{user_id}/payments/debit-cards/{debit_card_id}

Get a specific debit card by its FloatMe debit card ID.

DELETE

/{user_id}/payments/debit-cards/{debit_card_id}

Delete a specific debit card by FloatMe debit card ID.

PATCH

/{user_id}/payments/debit-cards/{debit_card_id}

Update a specific debit card by FloatMe debit card ID.

Admin Endpoints

Method Path Summary

POST

/admin/{user_id}/payments/debit-cards/{debit_card_id}/update

Admin/support endpoint. Toggles toggle_failure (force card to fail) or toggle_valid (override validity) on a debit card.

PATCH

/admin/{user_id}/payments/debit-cards/{debit_card_id}

Admin update of a debit card using v2 logic. Skips outstanding-float verification — intended for Backoffice and internal API calls only.

PATCH

/admin/{user_id}/payments/debit-cards/{debit_card_id}/toggle-failure

Admin version of toggle-failure by debit card ID.

POST

/{user_id}/debit-card/force

Force-delete a debit card. Support/admin endpoint.

See DynamoDB Tables for the debit card table schemas and migration fallback behaviour.

Bank Accounts

Method Path Summary

GET

/{user_id}/bank-accounts/{account_id}

Returns the last 4 digits of the account number for the given user and Plaid account ID.

DELETE

/{user_id}/bank-accounts/{account_id}

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

GET

/check-bank-account

Checks whether a bank account already exists by hash. Returns the user IDs that have the same account_routing_hash. Used for fraud detection across accounts. Note: this is a GET request with a body — some HTTP clients do not support this pattern.

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

Refunds

Method Path Summary

POST

/refunds

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

GET

/{user_id}/refunds

Get all refund records for a user from usio-debit-refunds.

Blocklist

Method Path Summary

GET

/{user_id}/payments/blocklists

Returns the current blocklist status for a user (BLOCKED or NOTBLOCKED).

GET

/{user_id}/payments/blocklists/history

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

POST

/{user_id}/payments/blocklist

Manually add a user to the blocklist. Support/admin endpoint. Requires a trigger_id (reason/reference ID).

DELETE

/{user_id}/payments/blocklist

Manually remove a user from the blocklist. Also triggered automatically via SQS when a user updates their bank account.

See Blocklist for auto-blocking logic and return code reference.

Fraud

Method Path Summary

GET

/fraud-check

Performs up to four fraud checks (user ID, install ID, bank account hash, debit card hash). Returns can_float: true if all checks pass. Note: this is a GET request with a body.

POST

/fraud-check

Saves the result of a completed float (success or failure) to the fraud log. Called by the float-service after disbursement.

See Fraud Detection for check behavior and log storage details.

Usio Transactions

Method Path Summary

GET

/{user_id}/usio/transactions

Returns Usio transaction records for a user. Requires email query parameter. Optional transaction_type filter (credit or debit).

POST

/{user_id}/payments/usio/transactions/{confirmation_id}/check

Checks whether a Usio tokenization transaction passes the AVS code check. Queries the Usio master account only.

Payment Methods

Method Path Summary

GET

/{user_id}/payment-methods

Returns available payment methods for a user, including RTP eligibility. Returns rtp_eligible: false if the user has no bank account on file or if the RTP eligibility check fails.

QA

Method Path Summary

POST

/qa/payments

Test environment only. Saves a list of payment records directly to the test DynamoDB table. Used to seed test data.

Error Codes

HTTP Status Meaning

200 OK

Request succeeded. For SubmitPayment, the body contains a status field — check it for FAILED even on 200.

201 Created

Resource created successfully (prenotes, blocklist add, QA payments).

202 Accepted

Accepted for processing (debit card delete, bank account delete, force-delete).

204 No Content

Action completed; no response body.

400 Bad Request

Invalid request body (JSON decode error, missing required fields).

402 Payment Required

Returned by CheckDebitCardChange when the card cannot be changed due to an outstanding payment.

404 Not Found

Resource not found (payment, debit card, bank account, refund).

409 Conflict

Returned by SaveDebitCard / SaveDebitCardV2 when the card cannot be changed at this time.

500 Internal Server Error

Unhandled server error, provider API error, or DynamoDB write failure.
POST /payments returns 200 with status = "FAILED" when the payment provider rejects the payment. It only returns 500 on infrastructure errors (e.g. DynamoDB write failure, provider unreachable).