Add an external account

Adds a new external account for transfers to accounts that are not created with Gravv.

POST/v1/external-accounts

Async setup contract

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

200 OK: The external account is fully registered with at least one partner. The status field is active. You can initiate transfers immediately.
202 Accepted: the external account record is created and a background worker calls our partners. The status field is pending. To learn when it changes to active, either check the status by calling GET /v1/external-accounts/{external_account_id} until it is active, or subscribe to the payee.setup.* webhook events.
400 Bad Request: Input validation failed. Fix the input and retry.

A duplicate POST with the same account_number (or iban), currency, and payee_type for the same customer is idempotent and returns the existing record.

Headers

A unique key to prevent duplicate requests.

Request Body

Name of the account holder.

ID of the customer who owns the external account.

Optional. US payment rail to use when payee_type is ach_wire. Accepted values: ach (ACH transfer) or wire (domestic wire). Defaults to wire when omitted.

Possible values: ach, wire

Request Examples

{
"payee_type": "ach_wire",
"account_number": "4401682860",
"account_name": "Amina Bello",
"bank_name": "Example Community Bank",
"currency": "USD",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"routing_number": "101019644",
"account_owner_type": "individual",
"account_type": "savings",
"address": {
"address_line1": "1800 N Pole St, Orlando, FL 32801",
"state": "US-FL",
"country": "US",
"postal_code": "32801",
"city": "Orlando"
}
}

{
"payee_type": "bank_account",
"account_number": "1776218486",
"account_name": "Amina Bello",
"bank_name": "Access Bank",
"currency": "NGN",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"institution_id": "c0cb83fa-8116-4744-8bc8-0c1cba405400"
}

{
"payee_type": "mobile_money",
"phone_number": "+233241234567",
"account_name": "Kwame Mensah",
"bank_name": "MTN Mobile Money",
"currency": "GHS",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"institution_id": "5c8d94fb-a927-5fed-b19d-1454c8f142a9"
}

{
"payee_type": "sepa",
"account_owner_type": "individual",
"iban": "DE89370400440532013000",
"account_name": "Anna Schmidt",
"bank_name": "Deutsche Bank",
"currency": "EUR",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"address": {
"address_line1": "Unter den Linden 13",
"city": "Berlin",
"state": "Berlin",
"postal_code": "10117",
"country": "DE"
}
}

{
"payee_type": "swift",
"account_owner_type": "individual",
"account_number": "1245909283",
"account_name": "Amina Bello",
"bank_name": "Guaranty Trust Bank (GTBank)",
"bic": "NG2893A",
"currency": "USD",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"address": {
"address_line1": "15 Admiralty Way, Lekki Phase 1",
"house_building_number": "1 B",
"address_line2": "Suite 202",
"city": "Lekki",
"postal_code": "105102",
"state": "Lagos",
"country": "NG"
}
}

{
"payee_type": "swift",
"account_owner_type": "individual",
"iban": "GB33BUKB20201555555555",
"account_name": "Amina Bello",
"bank_name": "Guaranty Trust Bank (GTBank)",
"bic": "NG2893A",
"currency": "USD",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"address": {
"address_line1": "15 Admiralty Way, Lekki Phase 1",
"house_building_number": "1 B",
"address_line2": "Suite 202",
"city": "Lekki",
"postal_code": "105102",
"state": "Lagos",
"country": "NG"
}
}

Responses

Status	Description
`200`	The external account is fully registered with our payment partners. The `status` field is `active`.
`202`	The external account record is created and registration with our payment partners is still in progress. The `status` field is `pending`. To learn when it changes to `active`, either check the status by calling `GET /v1/external-accounts/{external_account_id}` until it is `active`, or subscribe to the `payee.setup.*` webhook events.
`400`	Validation failed.

200 response

External account identifier; use this to fetch or initiate transfers.

Possible values: ach_wire, sepa, swift, bank_account, mobile_money, fps

Category of financial institution linked to this account.

Possible values: bank, mobile_money

ISO 3166-1 alpha-2 country code of the linked institution.

active: The external account is fully registered with our payment partners and is ready to use. pending: Registration is still in progress. To learn when it changes to active, either check the status by calling GET /v1/external-accounts/{external_account_id} until it is active, or subscribe to the external account webhook events.

Possible values: active, pending

202 response

External account identifier; use this to fetch or initiate transfers.

Possible values: ach_wire, sepa, swift, bank_account, mobile_money, fps

Category of financial institution linked to this account.

Possible values: bank, mobile_money

ISO 3166-1 alpha-2 country code of the linked institution.

Possible values: active, pending

400 response

Authorization

ApiKeyAuth

Was this page helpful?