Bank Account Management API

This section documents endpoints fintechs use to manage Nigerian bank accounts for offramp (fiat payout and settlement) operations.

Endpoints Overview

Section	Endpoint	Method	Description
Bank Codes	`/getbankscode`	POST	Retrieve supported Nigerian banks.
Add Bank Account	`/addbankaccount`	POST	Add and verify a new bank account for your fintech account.
Update Bank Account	`/updatebankaccount`	PUT	Update details of an existing bank account.
Delete Bank Account	`/deletebankaccount`	DELETE	Remove a bank account from your fintech configuration.
Get Single Bank Account	`/getbankaccounts`	GET	Retrieve a single bank account configured for your fintech account.
Get Bank Accounts	`/listbankaccounts`	GET	Retrieve all bank accounts currently configured for your fintech account.

Retrieve Supported Banks (Nigeria)

Request (All Banks)
Response (All Banks)

POST {{BASE_URL}}/getbankscode

{
  "status": "Success",
  "response_code": "00",
  "message": "Banks retrieved successfully",
  "data": {
    "countryCode": "NG",
    "banks": [
      { "bank_name": "AB MICROFINANCE BANK", "bank_code": "090270" },
      { "bank_name": "HACKMAN MICROFINANCE BANK", "bank_code": "090147" }
    ]
  }
}

Add a New Nigerian Bank Account for Fintech Payout

Accounts are automatically verified against bank records before activation.

Request (Add Bank)
Body (Add Bank)
Response (Add Bank)
Error (Add Bank)

POST {{BASE_URL}}/addbankaccount

{
  "accountNumber": "1234567890",
  "bankCode": "044",
  "isDefault": false
}

Parameters

Parameter	Type	Required	Description
`accountNumber`	string	Yes	Bank account number
`bankCode`	string	Yes	Bank identifier code (e.g. NIBSS bank code like `044`)
`isDefault`	boolean	No	Marks this bank account as the default payout account

{
  "status": "Success",
  "response_code": "00",
  "message": "Bank account added and verified successfully",
  "data": {
    "accountId": "uuid-account-id",
    "verifiedAccountName": "JOHN DOE",
    "accountNumber": "0123456789",
    "bankName": "NoAccess Bank",
    "bankCode": "044",
    "isValidated": true,
    "message": "Bank account added successfully"
  }
}

{
  "status": "Error",
  "response_code": "01",
  "message": "Validation error",
  "error": "Account number must be 10 digits"
}

{
  "status": "Error",
  "response_code": "01",
  "message": "Bank account verification failed",
  "error": "Account name does not match or account is invalid"
}

Update Bank Account

Request (Update Bank)
Body (Update Bank)
Response (Update Bank)
Error (Update Bank)

PUT {{BASE_URL}}/updatebankaccount

{
  "accountId": "uuid-account-id",
  "isDefault": true
}

Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Unique identifier (UUID) of the bank account to update
`isDefault`	boolean	No	Sets this bank account as the default payout account

{
  "status": "Success",
  "response_code": "00",
  "message": "Bank account updated successfully"
}

{
  "status": "Error",
  "response_code": "02",
  "message": "Bank account not found",
  "error": "No bank account found with the provided accountId"
}

Delete Bank Account

Accounts with pending offramp transactions cannot be deleted.

Request (Delete Bank)
Response (Delete Bank)
Error (Delete Bank)

DELETE {{BASE_URL}}/deletebankaccount?accountId=uuid-account-id

{
   "status": "Success",
  "response_code": "00",
  "message": "Bank account deleted successfully"
}

{
  "status": "Error",
  "response_code": "01",
  "message": "Cannot delete account with pending offramp transactions",
  "error": "PENDING_TRANSACTIONS"
}

Retrieve Single Bank Account

Request (Account)
Response (Account)

GET {{BASE_URL}}/getbankaccount?accountId=uuid-account-id

Query Parameters

Parameter	Type	Required	Description
`accountId`	string	Yes	Unique identifier (UUID) of the added bank account

{
  "status": "00",
  "message": "Bank accounts retrieved successfully",
  "data": {
    "accounts": [
      {
        "accountId": "account-uuid",
        "fintechId": "fintech-uuid-here",
        "accountName": "JOHN DOE",
        "accountNumber": "0123456789",
        "bankName": "Access Bank",
        "bankCode": "044",
        "isDefault": true,
        "isValidated": true,
        "validationDetails": {
          "validatedAt": "2026-02-04T10:30:00.000Z",
          "accountNameMatch": true
        },
        "createdAt": "2026-02-04T10:30:00.000Z",
        "updatedAt": "2026-02-04T10:30:00.000Z"
      }
    ]
  }
}

Retrieve All Bank Accounts

Request (Accounts)
Response (Accounts)

GET {{BASE_URL}}/listbankaccounts

{
  "status": "00",
  "message": "Bank accounts retrieved successfully",
  "data": {
    {
  "accounts": [
    {
      "accountId": "a1b2c3d4-...",
      "fintechId": "fintech-uuid",
      "accountName": "JOHN DOE",
      "accountNumber": "0123456789",
      "bankName": "Access Bank",
      "bankCode": "044",
      "isDefault": true,
      "isValidated": true,
      "validationDetails": {
                    "validatedAt": "2026-04-27T08:32:24.917Z",
                    "accountNameMatch": true
                },
      "createdAt": "2026-02-04T10:30:00.000Z",
      "updatedAt": "2026-02-04T10:30:00.000Z"
    },
    {
      "accountId": "b2c3d4e5-...",
      "fintechId": "fintech-uuid",
      "accountName": "JOHN DOE ENTERPRISES",
      "accountNumber": "9876543210",
      "bankName": "GTBank",
      "bankCode": "058",
      "isDefault": false,
      "isValidated": true,
      "validationDetails": {
                    "validatedAt": "2026-04-27T08:32:24.917Z",
                    "accountNameMatch": true
                },
      "createdAt": "2026-02-03T08:00:00.000Z",
      "updatedAt": "2026-02-03T08:00:00.000Z"
    }
  ],
  "total": 2,
  "defaultAccount": {
    "accountId": "a1b2c3d4-...",
    "accountName": "JOHN DOE",
    ...
  }
}
  }
}

​Bank Account Management API

​Endpoints Overview

​Retrieve Supported Banks (Nigeria)

​Add a New Nigerian Bank Account for Fintech Payout

​Parameters

​Update Bank Account

​Parameters

​Delete Bank Account

​Retrieve Single Bank Account

​Query Parameters

​Retrieve All Bank Accounts

Bank Account Management API

Endpoints Overview

Retrieve Supported Banks (Nigeria)

Add a New Nigerian Bank Account for Fintech Payout

Parameters

Update Bank Account

Parameters

Delete Bank Account

Retrieve Single Bank Account

Query Parameters

Retrieve All Bank Accounts