Add a bank account to a counterparty

POST

/counterparty-instruments

Attaches a Nigerian bank account instrument to an existing counterparty under the authenticated entity. The account holder name (account_name) is never supplied by the caller — it is resolved server-side by looking up account_number and bank_code against the issuing bank via Flutterwave's account resolution service, so the request will fail if the account cannot be verified.

The combination of account_number and the resolved instrument type must be unique per entity: you cannot save the same bank account twice for the same entity, even under different counterparties.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

Responses

🟢201

application/json

The bank account was verified and saved to the counterparty successfully.

Bodyapplication/json

🟠400

🟠401

🟠404

🟠409

Request Example

Shell

JavaScript

Java

Swift

cURL

Minimal — required fields onlyAll fields

curl --location '/counterparty-instruments' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "counterparty_id": "01HZ9KPQR3VTXMN84JWYB65CD0",
    "account_number": "0690000031",
    "bank_code": "044"
}'

Response Example

201 - Success

{
    "message": "Counterparty instrument added successfully",
    "status": "success",
    "data": {
        "id": "01J5RZ8N3F7Q2VYTHB6WCXK4M9",
        "entity_id": "01HZ9ABCD1234EFGH5678IJKL90",
        "counterparty_id": "01HZ9KPQR3VTXMN84JWYB65CD0",
        "account_number": "0690000031",
        "account_name": "JOHN ADEBAYO DOE",
        "bank_code": "044",
        "bank_name": "Access Bank",
        "display_name": "Primary Salary Account",
        "status": "active",
        "country": "NG",
        "created": 1722870000000,
        "updated": 1722870000000
    }
}

Modified at 2026-09-30 00:29:30

List all ACL roles

List counterparty instruments