Developer Platform
View as Markdown Open in ChatGPT Open in Claude

Add an external account

You must add any account not created with Gravv as an external account. To transfer funds to an external account, first use the recipient’s details to create a customer. Then use the Add an external account endpoint with the recipient's customer id to link the recipient to their bank account.

You can add an external account for either external transfers or international transfers.

Add an external account for external transfers

Use the recipient's bank account details and customer id to add an external account for external transfers:

curl --request POST \
     --url https://api.gravv.xyz/v1/external-accounts \
     --header 'Api-Key: <API_KEY>' \
     --header 'Idempotency-Key: 979879887678789_attempt_1' \
     --header 'content-type: application/json' \
     --data '
{
  "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"
  }
}
'

You will get a response showing the recipient's bank account details and an external account id. Use the external account id for your external transfers:

{
  "data": {
    "account_name": "Amina Bello",
    "account_number": "4401682860",
    "account_owner_type": "individual",
    "address": {
      "address_line1": "1800 N Pole St, Orlando, FL 32801",
      "address_line2": null,
      "city": "Orlando",
      "country": "US",
      "postal_code": "32801",
      "state": "US-FL"
    },
    "currency": "USD",
    "customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
    "date_created": "2025-08-29T12:16:15.019149Z",
    "iban": null,
    "id": "e0c0d076-fd86-4739-b26d-527ab83ab033",
    "institution_country_iso_code": null,
    "institution_id": null,
    "institution_name": "Example Community Bank",
    "institution_type": null,
    "payee_type": "ach_wire",
    "routing_number": "101019644"
  },
  "error": null
}

Add an external account for international transfers

For international transfers, you can add two types of global recipients:

  • Global bank account recipient: For sending funds to traditional bank accounts
  • Global mobile money recipient: For sending funds to mobile money accounts

Both types follow the same setup process but use different account identifiers.

Get the institution ID

First, check Supported countries to confirm that Gravv supports international transfers in the recipient's country. If Gravv supports the country, call the Get external account institutions endpoint to fetch the institution id. Include the country’s ISO code in the query parameters:

curl --request GET \
     --url 'https://api.gravv.xyz/v1/external-accounts/institutions?country_iso_code=<ISO code>' \
 --header 'Api-Key: <API_KEY>' \
 --header 'accept: application/json'

The response returns both bank and Mobile Money institutions. Note the account_number_type field to identify the institution type. Copy the institution id from the response:

{
"data": {
"items": [
  {
    "account_number_type": "bank_account_number",
    "country_iso_code": "NG",
    "currency": "NGN",
    "id": "279f86b7-2d03-48f4-aa27-3766de250099",
    "max_amount": 10000,
    "min_amount": 1,
    "name": "Stanbic IBTC Bank PLC"
  },
  {
    "account_number_type": "bank_account_number",
    "country_iso_code": "NG",
    "currency": "NGN",
    "id": "c0cb83fa-8116-4744-8bc8-0c1cba405400",
    "max_amount": 10000,
    "min_amount": 1,
    "name": "Access Bank PLC"
  }
],
"items_per_page": 10,
"page": 1,
"total_pages": 3
},
"error": null
}

Add a global bank account recipient

Use the recipient's bank account details, customer id, and the institution id to create a global bank account recipient:

curl --request POST \
 --url https://api.gravv.xyz/v1/external-accounts \
 --header 'Api-Key: <API_KEY>' \
 --header 'Idempotency-Key: 979879887678789_attempt_1' \
 --header 'content-type: application/json' \
 --data '
{
"payee_type": "bank_account",
"currency": "NGN",
"account_number": "4401682860",
"account_name": "Amina Bello",
"bank_name": "Access Bank",
"institution_id": "c0cb83fa-8116-4744-8bc8-0c1cba405400",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db"
}
'

You will get a response showing the recipient's bank account details and an external account id:

{
"data": {
"account_name": "Amina Bello",
"account_number": "4401682860",
"address": null,
"currency": "NGN",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"date_created": "2025-10-10T11:14:37.921052Z",
"iban": null,
"id": "74943275-6874-41b4-bd71-13d6cf5ed802",
"institution_country_iso_code": "NG",
"institution_id": "c0cb83fa-8116-4744-8bc8-0c1cba405400",
"institution_name": "Access Bank PLC",
"institution_type": "bank",
"payee_type": "bank_account",
"routing_number": null
},
"error": null
}

Add a global Mobile Money recipient

Use the recipient's Mobile Money account details, customer id, and the institution id for the Mobile Money provider to create a global Mobile Money recipient. For mobile money, the account_number field should contain the phone number:

curl --request POST \
 --url https://api.gravv.xyz/v1/external-accounts \
 --header 'Api-Key: <API_KEY>' \
 --header 'Idempotency-Key: 979879887678789_attempt_1' \
 --header 'content-type: application/json' \
 --data '
{
"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"
}
'

You will get a response showing the recipient's mobile money account details and an external account id:

{
"data": {
"account_name": "Kwame Mensah",
"phone_number": "+233241234567",
"account_owner_type": null,
"address": null,
"currency": "GHS",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"date_created": "2025-10-10T11:14:37.921052Z",
"iban": null,
"id": "8f2a9c65-3d4e-4b2f-a891-6e5d7c8f9a01",
"institution_country_iso_code": "GH",
"institution_id": "5c8d94fb-a927-5fed-b19d-1454c8f142a9",
"institution_name": "MTN Mobile Money",
"institution_type": "mobile_money",
"payee_type": "mobile_money",
"routing_number": null
},
"error": null
}

Add a SEPA recipient

For SEPA transfers, use the recipient's IBAN, address, customer id, and account owner type. SEPA recipients don't require an institution ID:

curl --request POST \
 --url https://api.gravv.xyz/v1/external-accounts \
 --header 'Api-Key: <API_KEY>' \
 --header 'Idempotency-Key: 979879887678789_attempt_1' \
 --header 'content-type: application/json' \
 --data '
{
"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",
"postal_code": "10117",
"country": "DE"
}
}
'

You will get a response showing the recipient's SEPA account details and an external account id:

{
"data": {
"account_name": "Anna Schmidt",
"account_number": null,
"account_owner_type": "individual",
"address": {
  "address_line1": "Unter den Linden 13",
  "address_line2": null,
  "city": "Berlin",
  "country": "DE",
  "postal_code": "10117",
  "state": null
},
"currency": "EUR",
"customer_id": "373556ec-74e5-4cde-909c-b94d864915db",
"date_created": "2025-11-26T10:15:30.921052Z",
"iban": "DE89370400440532013000",
"id": "9d3f1b2e-5c4a-4e8f-b9a2-7c6e8d9f0b12",
"institution_country_iso_code": null,
"institution_id": null,
"institution_name": "Deutsche Bank",
"institution_type": null,
"payee_type": "sepa",
"routing_number": null
},
"error": null
}

Use the external account id from any of these responses for your international transfers.

Add a SWIFT recipient

Use SWIFT transfers for international USD transfers outside the US and SEPA zone. SWIFT recipients require the recipient's bank account details, Bank Identifier Code (BIC), address, customer id, and account owner type:

curl --request POST \
 --url https://api.gravv.xyz/v1/external-accounts \
 --header 'Api-Key: <API_KEY>' \
 --header 'Idempotency-Key: 979879887678789_attempt_1' \
 --header 'content-type: application/json' \
 --data '
{
"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",
"city": "Lekki",
"state": "Lagos",
"postal_code": "105102",
"country": "NG"
}
}
'
Was this page helpful?