Financial Accounts Advanced

Retrieve all bank account linked to a BVN

This API offers merchants the capability to access an extensive list of bank accounts linked to a specific Bank Verification Number (BVN). This feature is particularly valuable for financial institutions and businesses that require bank account authentication for various purposes.

The process of retrieving these financial accounts involves three distinct stages:

  1. Initialize: In this initial step, the process begins by initiating a consent request. The merchant's system sends a request to the API, expressing the intention to retrieve financial information. This request typically involves providing the user's BVN as input.
  2. Get Consent: During this stage, the merchant is required to provide the contact details necessary to receive a One-Time Password (OTP). This OTP serves as a means of authentication and verification.
  3. Retrieve Financial Accounts: In the final stage, the OTP obtained from the previous step is inputted. This step completes the process and allows the API to fetch all the bank accounts associated with the provided BVN.

👍

TEST DATA

number: 54651333604

verify_with: 0701***2345

otp: 123456

📘

POST

{{URL}}/identitypass/verification/list/financial_accounts/advance

Parameters

Header

KeyDescription
app-idYour App ID
x-api-keyYour Secret Key

Body

KeyDescription
numberBank Verification Number
verify_withContact details to receive OTP with
otpOtp sent to preferred contact

"INITIALIZE" Response

{
    "status": true,
    "detail": "Verification Successful",
    "response_code": "00",
    "data": {
        "code": "select_contact",
        "detail": "These are the contact details tied to your BVN. Choose where you want the OTP delivered.",
        "contacts": [
            "0701***2345"
        ]
    }
}

"GET CONSENT" Response

{
    "status": true,
    "detail": "Verification Successful",
    "response_code": "00",
    "data": {
        "code": "otp_generated",
        "detail": "Please provide the OTP sent to 0701***2345"
    }
}

"RETRIEVE FINANCIAL ACCOUNTS" Response

{
    "status": true,
    "detail": "Verification Successful",
    "response_code": "00",
    "data": [
        {
            "accountname": "John Doe",
            "accountnumber": "1020304050",
            "accountDesignation": 2,
            "accountstatus": 4,
            "accounttype": 1,
            "institution": 26,
            "branch": "4650417",
            "AccountDesignationName": "INDIVIDUAL",
            "AccountStatusName": "PND",
            "AccountTypeName": "CURRENT",
            "bankName": "Polaris Bank Plc",
            "bankType": "Commercial Bank"
        },
        {
            "accountname": "John Doe",
            "accountnumber": "1122334455",
            "accountDesignation": 4,
            "accountstatus": 1,
            "accounttype": 2,
            "institution": 14,
            "branch": "4659944",
            "accounttier": 3,
            "AccountDesignationName": "OTHERS",
            "AccountStatusName": "ACTIVE",
            "AccountTypeName": "SAVINGS",
            "bankName": "First Bank of Nigeria",
            "bankType": "Commercial Bank"
        }
    ]
}

Response Description (INITIALIZE)

ResponseDescription
statusIndicates that the request was successful.
detailThis field indicates the detail of the response.
response_codeRepresents the response code.
dataAn object containing additional data related to the verification.
codeA code indicating that the user needs to select a contact for OTP delivery.
detailA detailed message instructing the user to choose where they want the OTP delivered.
contactsAn array containing the contact details tied to the account.

Response Description (GET CONSENT)

ResponseDescription
statusIndicates that the request was successful.
detailThis field indicates the detail of the response.
response_codeRepresents the response code.
dataAn object containing additional data related to the verification.
codeThe OTP code generated.
detailA detailed message instructing the user to provide the OTP sent to contact.

Response Description (RETRIEVE FINANCIAL ACCOUNTS)

ResponseDescription
statusIndicates that the request was successful.
detailThis field indicates the detail of the response.
response_codeRepresents the response code.
dataAn object containing additional data related to the verification.
accountnameThe name associated with the financial account.
accountnumberThe account number of the financial account.
accountDesignationA numerical value representing the account designation type.
accountstatusA numerical value indicating the status of the account.
accounttypeA numerical value representing the type of financial account.
institutionA numerical value identifying the financial institution associated with the account.
branchThe branch code or identifier associated with the account.
AccountDesignationNameThe human-readable name corresponding to the account designation.
AccountStatusNameThe human-readable name corresponding to the account status.
AccountTypeNameThe human-readable name corresponding to the account type.
bankNameThe name of the bank or financial institution.
bankTypeThe type of bank, which might indicate whether it is a commercial bank, investment bank, etc.