Users

Users

Users are the customers operating under your GMA partner account. Each user can hold one or more account types (e.g. USD) and may have stablecoin wallets in addition to fiat accounts.

As a GMA partner you have full visibility into every user's balance, account history, and activity — but you do not create users directly through the API. Users are provisioned by FV Bank and then associated with your partner account.

---

Key concepts

• Account types — Each user can hold multiple account types. Use accountType path variables like USD when querying balances or history.
• Available balance — Always use availableBalance (not raw balance) when checking whether a user has sufficient funds for a payment.
• Pagination — All list endpoints accept pageNumber (1-based) and pageSize. Send 1 for the first page, 2 for the second, and so on.
• Stablecoin wallets — Users can have USDC or PYUSD wallets. Call the wallet creation endpoint to provision one before initiating a stablecoin payment.

---

Common workflows

Check a user's balance before a payment

1. GET /users/balances/{accountType} — list balances for all users of a given account type, or
2. POST /users/{userId}/accounts/{accountType}/balance — fetch a single user's balance for a specific account.

Pull a user's transaction history

POST /users/{userId}/accounts/{accountType}/history — returns a paginated, filterable history of all transactions on the account. Filter by Direction (credit/debit), date range, or transaction type.

Search for a specific user

POST /users/search — accepts keyword and filter criteria to locate a user by name, email, or status.