Financial Institutions

Discover and select specific banks and payment providers required for certain recipient schemas. Some payment methods require choosing from available financial institutions before creating recipients.

Overview

Certain recipient schemas require selecting a specific financial institution (bank, mobile money provider, or payment processor) before creating the recipient. This ensures accurate routing and processing of payments through the correct provider networks.

API Endpoints

Method	Endpoint	Purpose
GET	`/financial_institutions/{country}/{schema}`	List institutions for country and schema
GET	`/financial_institutions/{id}`	Get specific institution details

Discover Required Institutions

Get the list of available financial institutions for a specific country and payment schema.

GET /financial_institutions/{country}/{schema}

Request Parameters

Parameter	Type	Description
`country`	string	ISO 3166-1 alpha-2 country code (NG, CO, KE)
`schema`	string	Payment schema requiring institution selection

Examples

Nigerian Banks:

curl -H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
https://api.due.network/v1/financial_institutions/NG/bank_africa

Nigerian Mobile Money Providers:

curl -H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
https://api.due.network/v1/financial_institutions/NG/momo_africa

Colombian Banks:

curl -H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
https://api.due.network/v1/financial_institutions/CO/bank_colombia

Response

[
  {
    "id": "fininst_qGGYZKST47dI8bRm",
    "name": "Enterprise Bank",
    "country": "NG",
    "schemas": ["bank_africa"]
  },
  {
    "id": "fininst_xyz123abc456def789",
    "name": "Access Bank Nigeria",
    "country": "NG", 
    "schemas": ["bank_africa"]
  },
  {
    "id": "fininst_mtn456def789ghi012",
    "name": "MTN Mobile Money",
    "country": "NG",
    "schemas": ["momo_africa"]
  }
]

Response Fields:

id - Unique financial institution identifier to use in recipient creation
name - Display name of the bank or provider
country - ISO country code
schemas - Supported payment schemas for this institution

Creating Recipients with Financial Institutions

Once you've selected a financial institution, include the financialInstitutionId when creating recipients.

Nigerian Bank Account

curl -X POST https://api.due.network/v1/recipients \
-H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
-H "Content-Type: application/json" \
-d '{
  "name": "Adebayo Okafor",
  "details": {
    "schema": "bank_africa",
    "financialInstitutionId": "fininst_qGGYZKST47dI8bRm",
    "accountNumber": "0123456789",
    "accountName": "Adebayo Okafor"
  },
  "isExternal": true
}'

Colombian Bank Account

curl -X POST https://api.due.network/v1/recipients \
-H "Authorization: Bearer your_api_key" \
-H "Due-Account-Id: your_account_id" \
-H "Content-Type: application/json" \
-d '{
  "name": "Carlos Rodriguez",
  "details": {
    "schema": "bank_colombia",
    "accountType": "individual",
    "firstName": "Carlos",
    "lastName": "Rodriguez",
    "financialInstitutionId": "fininst_bancolombia_001",
    "bankAccountType": "cc",
    "accountNumber": "1234567890",
    "idType": "cc",
    "idNumber": "12345678"
  },
  "isExternal": true
}'

Integration Workflow

1. Check Schema Requirements

Determine if a payment schema requires financial institution selection by checking in the schema list

2. Get the institutions

Fetch the list of institutions by schema and country

3. Create Recipient with Selection

Include the selected financialInstitutionId in the recipient creation request.

Error Handling

Missing Financial Institution

Error (422):

{
  "statusCode": 422,
  "message": "Validation error",
  "code": "err_validation",
  "details": {
    "financialInstitutionId": "required"
  }
}