Accounts (v2)

Choose the recipe for opening a v2 account for a customer: USD, EUR, GBP, NGN or Kenya-held, wallet-backed or fiat-only, and what to do until it is active.

Each recipe on this page opens a bank account in a customer's name and follows it until a payer can send money to it. Every recipe starts the same way. You find what the customer can open, then send one create request.

API version: v2. These recipes open accounts with POST /v2/accounts.

Money example. Ada, a UK freelancer, wants a US client to pay her 1,200.00 USD. Capabilities lists the USD options a GB individual can have. Requirements says the default option needs 13 fields and 2 documents. One POST /v2/accounts call returns pending. When applications.accounts.completed arrives, you read the account number and routing number, and Ada's client pays 1,200.00 USD into the account.

Two words used everywhere

• Wallet-backed. The bank turns each deposit into USDC and puts it in a wallet that belongs to the account, on the network you choose. The option has a non-empty token_wallets, and the create request must carry network (or wallet_id).
• Fiat-only. The money stays in the account's currency at the bank. The option has token_wallets: [], and the create request must not carry network or wallet_id.

You never send a "backing" flag. You choose the backing by choosing the option, and you name the option in bank_code.

Choose your recipe

The options a customer sees depend on their country. Read excluded_countries from capabilities for each customer. Never rely on a fixed list.

After you send the create request:

Rules every recipe relies on

• Send every request to https://api.gravv.xyz with your key in the Api-Key header. A key that starts with grvSec_sandbox_ reaches sandbox. Any other key is live.
• The customer's basic KYC must be completed. For a business, every associated person's KYC must be completed first, then the business's. See Customers and KYC.
• Send a new Idempotency-Key with every POST. Gravv replays a 4xx for 24 hours under its key, so use a new key after you fix a request. After a 5xx or a timeout, retry with the same key. Gravv does not duplicate the account.
• A 400 response to a create request lists every problem in details, keyed by field. Fix them all at once.
• network and wallet_id go at the top level, never in data.root. Always send customer_type. Send citizenship_country (a person) or incorporation_country (a business) in data.root.
• Use category sub_account for a customer's account.
• The create response has no application_id. Read it from GET /v2/accounts/{id}.
• v2 never sends account.activated for an account you open. Wait for applications.accounts.completed, then read the account for its bank details.
• Deduplicate webhooks on the body's event_id.
• Sandbox KYC does not complete today. Until Gravv fixes it, every sandbox create request returns CUSTOMER_KYC_INCOMPLETE. Capabilities, requirements, reads and error paths work.