Accounts

What an account is, how you open one with the accounts API, and the words the account pages use.

API version: v2.

An account holds money for one of your customers. It has bank details that payers send money to, and it can send money out with a transfer. Many accounts also have a wallet address, because they hold the balance as a stablecoin.

A money example. Ada, a freelancer in London, invoices a US client 1,200.00 USD.

1. You open a USD account for Ada with POST /v2/accounts. It starts pending.
2. The bank approves it. The account becomes active and gets a US account number and routing number.
3. The client sends 1,200.00 USD by ACH to those details, and Ada's balance shows the full 1,200.00 USD. Gravv bills any deposit fee on your plan to your business separately.

How you open an account

1. Find an account option with GET /v1/accounts/capabilities. The route is under /v1, but it is the first step of a v2 account.
2. Read the requirements for that option with GET /v2/accounts/requirements.
3. Open the account with one POST /v2/accounts.
4. Track activation until the account is active, then read its bank details.

Accounts v2 walks through each step.

Before any account: the customer and KYC

Every account belongs to a customer. Create the customer first, then verify them:

1. Create the customer.
2. Verify them with KYC. For a business, KYC verifies every associated person first, then the business.
3. Call GET /v1/customers/{customer_id} and check that the kyc entry with type basic has status completed.

The API refuses to open an account until that entry is completed.

Internal accounts

Internal accounts are the accounts Gravv holds: your business's own accounts and the accounts you open for your customers. External accounts are the bank accounts and mobile wallets outside Gravv that you pay out to. External accounts covers them.

Customer accounts

A customer account is one you open for a customer after their KYC is complete. All money the customer receives or sends moves through it.

Wallet-backed and fiat-only

• Wallet-backed. The bank turns every deposit into USDC and puts it in a wallet that belongs to the account, on the network you chose. The account has bank details for payers and a wallet address.
• Fiat-only. The money stays in the account's own currency at the bank. There is no wallet.

You choose the kind by choosing the account option. An option with a non-empty token_wallets list is wallet-backed.

Account types

account_type	Use
operating	Everyday receiving and paying. Every option offers it
yield, revenue	Offered by some wallet-backed USD options

You set up your business's card account, which backs every card you issue, separately. See Set up your card account.

Main accounts

A main account is your business's own account. A customer account is one you open for one of your customers. The category field of an account says which it is, main or sub_account. Send category sub_account for a customer account.

To find your business's own account, and the customer id it belongs to, call GET /v2/accounts?category=main.

Statuses

Status	Meaning
pending	Being opened. There are no bank details yet
active	Open, with bank details. It can receive and send money
rejected, failed	The bank refused it, or opening failed. Read status_reason
frozen	Suspended
closed	Closed
deleted, manual_review	Appear only on older accounts

Next steps

Find an account option, read what it needs, open the account and track its activation.

Send one POST /v2/accounts and read the errors it can return.

List accounts with filters, and read balances and bank details.

Follow step-by-step recipes for each currency and kind of account.