External Accounts overview

Use the External Accounts API to add and verify transfer recipients, retrieve external accounts, and discover supported institutions.

How it works

External accounts are recipient bank accounts, mobile-money accounts, or other destinations outside Gravv that your customers send money to. The recommended flow is:

1. Verify first — call POST /v1/external-accounts/verify with at least one identifier (account_number, iban, phone, or clabe) to resolve the account holder's name with the destination institution before saving the recipient. This lets you show the resolved name to your user and avoid failed transfers.
2. Add the recipient — call POST /v1/external-accounts to register the account with Gravv's payment partners.
3. Transfer — once the external account is active, use it as the destination in the Transfers API.

Async registration contract

Registering an external account with payment partners runs asynchronously. The response status code tells you the outcome:

You can also subscribe to external account webhook events instead of polling.

Endpoints

Authentication

All requests use https://api.gravv.xyz/v1/ and authenticate with the Api-Key header. Write requests require an Idempotency-Key header — the playground generates one automatically and lets you replace it.