External accounts

Save and use payees, the bank accounts and mobile wallets outside Gravv that your customers pay.

An external account, or payee, is a bank account or mobile wallet outside Gravv that one of your customers pays. You save it once, wait until it is active, then use its id as the destination of a transfer. Every payee belongs to one customer (customer_id). This page explains the steps to set up a payee, the payee types and the events Gravv sends.

Example. A remittance app's user in Houston pays her brother's bank account in Lagos. The app looks the bank up in the institutions list, checks the account name with the bank (CHINEDU OKECHUKWU EZE), saves the payee (HTTP 200, active at once) and sends 250.00 USD to it. Next month it pays the same payee id again, with no new setup.

How it works

1. Find the institution. For local bank accounts and mobile wallets, and to look up a SWIFT bank, retrieve supported institutions and keep the id as institution_id.
2. Check the account (optional). Verify an external account to see the bank's name for the holder. It covers bank account numbers only.
3. Look for an existing payee. Retrieve external accounts with search set to the account number, so you do not save a duplicate.
4. Save the payee. Add an external account. For local bank and mobile wallet payees, the API returns HTTP 200 active. For US, SWIFT, SEPA and UK payees, it returns HTTP 202 pending, and the payee becomes active later.
5. Fix it if setup failed. Update an external account corrects a setup_failed payee without creating a new one.

Payee types at a glance

Saving a payee does not mean that Gravv can pay that country. Gravv decides whether a route is open when you send the transfer. See Payments and supported countries.

Events

Gravv sends external_account.created when you save the payee, then external_account.active or external_account.setup_failed. event_data is the full payee, as Get an external account returns it. See Webhooks for signing and delivery.

Next steps