Glossary

The words the Gravv API and these docs use, each with a one-line meaning and the page that explains it.

These are the terms the Gravv API and these docs use. Each links to the page that explains it in full.

Example. "Open a v2 account for a verified customer, add a payee, and send a transfer with a fresh idempotency key" means all of these:

The customer's basic KYC is completed.
You create the account with POST /v2/accounts.
You save the recipient as an external account and wait until it is active.
You send POST /v1/transfer with a new Idempotency-Key header.

Your business and access

Term	Meaning
Business	You, the company that integrates with Gravv. Your API key identifies it, so no request names it. See Authentication
API key	Your secret key, sent in the `Api-Key` header. One per environment: `grvSec_sandbox_…` or `grvSec_live_…`. No endpoint uses the Dashboard's public key
Sandbox and live	The test and the real environment. They share one host, `https://api.gravv.xyz`. The key decides which one you reach, and each holds its own data. See Environments
Dashboard	Gravv's web app for your team. A few actions, such as approving a payee or a transfer, are Dashboard-only
Main account	Your business's own account, which pays fees that have no account of their own. See How fees work

Customers and verification

Term	Meaning
Customer	A person (`individual`) or a company (`business`) you serve. Accounts, cards, wallets and payees belong to a customer. See Onboard your first customer
KYC	Know your customer, the check of a person's identity. For a business it covers the company and its people, sometimes called KYB. See KYC
Hosted KYC and server-to-server KYC	Two ways to run KYC: send the customer to a hosted link, or upload their documents yourself and start the check from your server
Card KYC	KYC with a liveness check for a customer who will get a card, under `/v1/risk/`. See Card KYC and activation
Feature	A product switched on for one customer, such as `virtual_cards`. Activating it can start work that cannot be undone

Accounts and wallets

Term	Meaning
Account	Holds money for one customer, with bank details payers send to. See Accounts
Account application	The request to open an account, which the bank reviews. A v2 application can be `blocked` until you send what it asks for. See Fix a blocked application
Capabilities and requirements	Which account options a customer can open, and which fields and documents an option needs. See Find an account option
Wallet-backed account	An account whose balance is held as a stablecoin in a wallet, with bank details in front of it
Card account	The one account of type `card` that backs every card your business issues. See Set up your card account
Wallet	A blockchain address of one customer on one network, with no bank details. See Wallets
Network	The blockchain a wallet or address is on, such as `polygon` or `stellar`. Gravv does not credit coins sent on another network
Ledger balance	An account's balance in minor units with a `scale`, beside the decimal `balance`. See Formats and limits

Moving money

Term	Meaning
Transfer	A movement of money from an account or wallet, made with `POST /v1/transfer` to another account, a payee or a crypto address. See Transfers
Internal transfer	A transfer between two accounts at Gravv
Rail	The payment system a bank payment uses: `ach`, `wire`, `rtp`, `swift`, `sepa` or `fps`
Remittance	A payout to a bank account or mobile wallet abroad. See International transfers
External account, or payee	A bank account or mobile wallet outside Gravv that a customer pays. It must be `active` before a transfer to it can succeed. See External accounts
Institution	A bank or mobile-wallet operator in Gravv's list, referenced by `institution_id`
Paused transfer	A transfer that waits for something from you, such as a supporting document or sender details, before it pays out. See Paused transfers
Supporting document	A file that backs a payout, such as an invoice, uploaded with `POST /v1/transfer/documents`
Remitter	The person or business sending a remittance, when the payout must carry their details
Transfer limits	Per-sender caps in USD, per transfer, day, week, month and year. A transfer over a cap pauses. See Transfer limits
Deposit	Money arriving in an account by a bank rail, or in a wallet on chain. See Receive deposits
Collection	Taking a payment from a customer, by bank transfer or card. See Collections
Payment intent	A card payment you start, with a hosted payment link or a saved card's `card_token`
OTC order	A foreign exchange trade placed from a quote. See Foreign exchange
Quote	A price for an exchange, valid for a few minutes, which an OTC order uses
Settlement instruction	One of your business's own bank accounts or wallets, saved to receive FX proceeds. It is not a payee. See Settlement instructions
Fee	What Gravv charges for a movement or a check, priced by your plan. See How fees work

Ids, retries and events

Term	Meaning
`transaction_id` and `reference`	A transfer's two ids. You find the transfer in transactions with the first, and resume it with the second. See Formats and limits
`client_reference`	Your own reference for a payment. Keep one per payment
Idempotency key	The `Idempotency-Key` header that lets you retry a POST without doing it twice. See Idempotent requests
Webhook	An HTTPS call Gravv makes to your URL when something changes. See Webhooks
`event_id`	The id of one webhook event, in its body. Deduplicate on it
Webhook history	The record of events sent to you. Read it with `GET /v1/webhooks/history`, and resend an event from it
Simulator	A sandbox-only route that makes something happen without real money, such as a test deposit. See Test accounts in sandbox
Status labels	How these docs mark a route: Available, Not yet available or Not supported