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": "bank_account_us",
  "account_number": "4401682860",
  "account_name": "Joshua Edicha",
  "bank_name": "Lead 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": "Joshua Edicha",
    "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", // external account id
    "institution_country_iso_code": null,
    "institution_id": null,
    "institution_name": "Lead Bank",
    "institution_type": null,
    "payee_type": "bank_account_us",
    "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",  // institution id
        "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", // institution id
        "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": "Joshua Edicha",
  "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": "Joshua Edicha",
    "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", // external account id
    "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", // external account id
    "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.