Retrieve supported institutions

Supported institutions are the banks and mobile money providers you can pay out to. When you add an external account for a global bank or mobile money payee, you must include the institution_id of the destination institution. Use this endpoint to look it up.

US bank accounts (ACH or wire) and SEPA accounts do not use an institution_id, so you only need this lookup for global bank and mobile money payees.

List institutions

Call Get external account institutions. Filter by country and type to narrow the list.

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

Query parameters:

country_iso_code: country to list institutions for, as an ISO 3166-1 alpha-2 code (for example, NG).
institution_type: bank or mobile_money.
page and items_per_page: pagination controls.

The response is a paginated list. Each item carries the id you pass as institution_id, along with the institution's supported currency and per-transaction amount limits:

{
  "data": {
    "items": [
      {
        "id": "c4788635-764d-43d3-9ffb-966b0fe29ff9",
        "name": "Keystone Bank PLC",
        "country_iso_code": "NG",
        "currency": "NGN",
        "account_number_type": "bank_account_number",
        "min_amount": 1,
        "max_amount": 10000
      }
    ],
    "page": 1,
    "items_per_page": 10,
    "total_pages": 6
  },
  "error": null
}

Use the institution id

Pass the id from the list as institution_id when you add an external account for a global bank (payee_type: bank_account) or mobile money (payee_type: mobile_money) payee. Match the account's currency to the one the institution supports.