Gravv docs
Docs Agent Sign in Get API keys
API Reference

External accounts overview

Use the External Accounts API to save the payees your customers send money to, check a bank account's holder, correct a payee that failed setup, and list the banks and wallet operators a payee can point at.

Add an external account or browse the operations in this category.

Review payee setup and verification flows.

How it works

An external account (payee) is a bank account, mobile wallet or other destination outside Gravv. The usual flow has four steps:

  1. Find the institution. For a local bank or mobile wallet payee, call GET /v1/external-accounts/institutions. These payees require an institution_id. For a SWIFT bank, find the institution by swift_code instead.
  2. Check the holder (optional). Call POST /v1/external-accounts/verify. It covers bank accounts only. Trust the returned name when verification_source is provider. A value of local means only that the format looks right.
  3. Look for an existing payee, then save it. Call GET /v1/external-accounts with search, then POST /v1/external-accounts.
  4. Pay it. Once the payee is active, pay it with the Transfers API.

Setup and status

Response Payee types Meaning
HTTP 200 bank_account, mobile_money status is active at once
HTTP 202 ach_wire, sepa, swift, fps status is pending while setup runs. Wait for external_account.active or external_account.setup_failed, or poll GET /v1/external-accounts/{external_account_id}

A payee that ends in setup_failed still counts as a duplicate, so you can't save it again. Correct it in place with PATCH /v1/external-accounts/{external_account_id} instead. See Update an external account. A duplicate returns HTTP 400 with the existing id in data.payee_id. Payee errors carry no code, so match on the message.

A listed institution or country is not an open route. Gravv decides whether a payee can be paid when you send the transfer. See Payments and supported countries.

Endpoints

Endpoint Description
POST /v1/external-accounts Add an external account
GET /v1/external-accounts List external accounts, with search
POST /v1/external-accounts/verify Check a bank account's format, and its holder's name where the bank supports it
GET /v1/external-accounts/{external_account_id} Retrieve an external account, its status and any error_message
PATCH /v1/external-accounts/{external_account_id} Correct a payee that failed setup, retry its setup, or add details a route needs
GET /v1/external-accounts/institutions List banks and wallet operators. min_amount and max_amount are reference values, not limits

Authentication

All requests use https://api.gravv.xyz and authenticate with the Api-Key header. POST /v1/external-accounts requires an Idempotency-Key header. The verify and PATCH calls do not.

Was this page helpful?
ESC