Retrieve supported institutions

Find the bank or mobile wallet operator to pay, and the institution_id that a local payee needs.

This page shows how to find the bank or mobile wallet operator to pay, and its institution_id. The institutions list holds the banks and mobile wallet operators that the API knows, with an id for each.

A local bank or mobile wallet payee must carry an institution_id from this list. The API accepts a payee saved without one, but the transfer returns this payee is not yet set up for transfers — please contact support to complete its setup.

You also use the list to look up a SWIFT bank and its address.

Example. To pay a mobile wallet in Ghana, you list country_iso_code=GH&institution_type=mobile_money. Three operators come back, each with account_number_type phone_number. You show them to your user, keep the id of the one they choose, and save the payee with it and the wallet's phone number.

List institutions

Send GET /v1/external-accounts/institutions:

curl --request GET \
     --url 'https://api.gravv.xyz/v1/external-accounts/institutions?country_iso_code=NG&institution_type=bank&items_per_page=100' \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "items": [
      {
        "account_number_type": "bank_account_number",
        "country_iso_code": "NG",
        "currency": "NGN",
        "id": "2ce313c8-de20-48dd-bfc6-949b8fd5ad84",
        "max_amount": 10000,
        "min_amount": 1,
        "name": "GT Bank"
      }
    ],
    "items_per_page": 100,
    "page": 1,
    "total_items": 85,
    "total_pages": 1
  },
  "error": null
}

Filter	Use
country_iso_code	Exact match, in upper case: NG, not ng
institution_type	bank, mobile_money, swift or swift_intermediary. Without it, the list returns every type except swift_intermediary
account_number_type	bank_account_number, iban, phone_number or clabe
currency	A currency, such as XOF
swift_code	A BIC, for SWIFT banks
search	Finds SWIFT banks by name or BIC. Send at least 3 characters
page, items_per_page	Paging. The default page size is 10

Read each item as follows:

• id is the institution_id to save on the payee. Take it from the list in the same environment, because ids can differ between sandbox and live.
• account_number_type says which payee field holds the number. bank_account_number means the number goes in account_number, and phone_number means it goes in phone_number.
• currency is the currency you save the payee in.
• min_amount and max_amount are reference values. Gravv does not enforce them on transfers.
• Some countries list the same operator under two names. Each recipe names the row its route pays.

Look up a SWIFT bank

SWIFT banks appear only when you pass swift_code, search or institution_type=swift:

curl --request GET \
     --url 'https://api.gravv.xyz/v1/external-accounts/institutions?swift_code=ZEIBNGLA' \
     --header 'Api-Key: <API_KEY>'

{
  "data": {
    "items": [
      {
        "account_number_type": "bank_account_number",
        "address": "ZENITH HEIGHTS, PLOT 84 AJOSE ADEOGUN STREET, VICTORIA ISLAND, LAGOS",
        "country_iso_code": "NG",
        "currency": "USD",
        "id": "fc7b9fc8-d85c-5473-9b62-f88b9eb5815b",
        "max_amount": 0,
        "min_amount": 0,
        "name": "ZENITH BANK PLC",
        "prefill": {
          "bank_address_line_1": "87 AJOSE ADEOGUN STREET, ZENITH HEIGHTS",
          "bank_city": "VICTORIA ISLAND",
          "bank_country": "NG",
          "bank_name": "ZENITH BANK PLC",
          "bank_postal_code": "101241",
          "bank_state": "LAGOS",
          "bic": "ZEIBNGLA",
          "institution_id": "fc7b9fc8-d85c-5473-9b62-f88b9eb5815b"
        },
        "swift_code": "ZEIBNGLA"
      }
    ],
    "items_per_page": 10,
    "page": 1,
    "total_items": 1,
    "total_pages": 1
  },
  "error": null
}

prefill holds the SWIFT payee's bank fields, ready to copy into Add an external account. address is one display string. An unknown BIC returns 200 with an empty items list.

US (ach_wire), SEPA and Faster Payments payees do not need an institution_id.

A bank or operator in this list is one that the API knows. Being listed does not mean that a payout route to it is open. See Payments and supported countries.