NGN Virtual Account

In this section, we will go over the steps required to set up and maintain an NGN permanent virtual account. We would like to start by explaining how permanent virtual accounts can be created on Fincra.

πŸ“˜

Important

  • BVN is required when requesting a permanent virtual account.
  • Only requests for Individual and corporate NGN virtual accounts will be instantly approved.
  • Funds received by a virtual account created settles in the balances of the merchant.

Supported Banks

Listed below are the banks that are supported in the creation of NGN virtual accounts. This value is what you pass in under the "channel" field when making a virtual account request.

S/NBankValue
1Globus Bankglobus
2Providus Bankprovidus

API Guide

1 - Get customer details

To create a virtual account, you'll need to pass information such as currency, accountType, channel, KYCInformation, etc.

Please find below the request parameters for the endpoint.

FieldMandatorytypeDescription
currencyYesstringThe virtual account currency.e.g NGN
accountTypeYesstringThe virtual account type. This can be "individual" or "corporate"
channelNostringThe value should be globus for globus bank accounts .
dateOfBirthNostringThe date of birth of the customer.
KYCInformation.firstNameYesstringThe customer's first name . This is required to create an individual account
KYCInformation.lastNameYesstringThe customer's last name . This is required to create an individual account
KYCInformation.emailNostringThe customer's email.
KYCInformation.bvnYesstringBank verification number.
merchantReferenceNostringA unique ID/reference of the virtual account on your system.

2 - Request a virtual account

Make an API request to the create virtual account endpoint

Endpoint:

{{base_url}}/profile/virtual-accounts/requests
curl --location 'https://api.fincra.com/profile/virtual-accounts/requests' \
--header 'api-key: <Your API secret key>' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \

Payload:

{
    "currency": "NGN",
    "accountType": "individual",
    "KYCInformation": {
        "firstName": "John",
        "lastName": "Doe",
        "email": "[email protected]",
        "bvn": "12345678901"
    },
    "channel": "globus"
}
{
    "currency": "NGN",
    "accountType": "corporate",
    "KYCInformation": {
        "email": "[email protected]",
        "bvn": "12345678901",
        "businessName": "Customer Business Name"
    },
    "channel": "globus"
}

If successful, you will receive a JSON snippet with the details of the newly created virtual account:

{
    "success": true,
    "message": "We use this to communicate information to you.",
    "data": {
        "status": "approved",
        "isActive": true,
        "accountNumber": "3992219528",
        "merchantReference": null,
        "KYCInformation": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]"
        },
        "accountInformation": {
            "accountNumber": "3992219528",
            "accountName": "Customer's full name",
            "bankName": "GLOBUS BANK",
            "bankCode": "103"
        },
        "verifiedKYCData": null,
        "note": null,
        "accountOpeningFee": 0,
        "pendingAdditionalInfoCount": 0,
        "isPermanent": true,
        "expiresAt": null,
        "isCheckoutVa": false,
        "isBankTransferVa": false,
        "isSuspended": false,
        "reason": null,
        "monthlyVolume": null,
        "entityName": null,
        "paymentFlowDescription": null,
        "attachments": [],
        "meansOfId": [],
        "bankStatement": [],
        "utilityBill": [],
        "virtualAccountType": "additional",
        "riskRating": null,
        "checklist": null,
        "riskScreening": null,
        "channelKycUpdateStatus": null,
        "channelKycUpdateResponse": null,
        "_id": "************************",
        "business": "*******************",
        "currency": "NGN",
        "accountType": "individual",
        "entityType": "main_account",
        "currencyType": "fiat",
        "createdAt": "@timestamp",
        "updatedAt": "@timestamp"
    }
}

Important Notes:

  • _id : This is the unique Identifier for the virtual account that was just created.
  • business : This is your business ID.
  • entityType : This states that the virtual account belongs to you

3 - Receive and validate webhook notification

Listen for webhook events. We will send a notification to your webhook URL that indicates the status of the virtual account creation. Read our guide on securing and validating the webhook notification on your end.

Webhook Response:

{
  "event": "virtualaccount.approved",
  "data": {
    "id": "************************",
    "business": "******************",
    "isSubAccount": false,
    "currency": "NGN",
    "currencyType": "fiat",
    "status": "approved",
    "email": "[email protected]",
    "accountType": "individual",
    "accountInformation": {
      "accountNumber": "3992219528",
      "accountName": "Customer's full name",
      "bankName": "GLOBUS BANK",
      "bankCode": "103"
    },
    "accountOpeningFee": 0,
    "isPermanent": true,
    "virtualAccountType": "additional",
    "createdAt": "@timestamp",
    "updatedAt": "@timestamp"
  }
}

Important Notes:

  • id : This is the unique Identifier for the virtual account that was just created.

4 - Retrieving the details of a virtual bank account

The details of a Virtual Bank Account can be retrieved at any time after creating the account. To do this, you will need to make an API request to the Virtual Bank Account Query API.

Endpoint:

{{base_url}}/profile/virtual-accounts/<virtual account id>
curl --location 'https://api.fincra.com/profile/virtual-accounts/{{virtual_account_id}}' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>'

If successful, you will receive a JSON snippet with the details of the virtual account.

{
    "success": true,
    "message": "Virtual account fetched successfully",
    "data": {
        "status": "approved",
        "isActive": true,
        "accountNumber": "3992219528",
        "merchantReference": null,
        "KYCInformation": {
            "firstName": "John",
            "lastName": "Doe",
            "email": "[email protected]"
        },
        "accountInformation": {
            "accountNumber": "3992219528",
            "accountName": "Customer full name",
            "bankName": "GLOBUS BANK",
            "bankCode": "103"
        },
        "verifiedKYCData": null,
        "note": null,
        "accountOpeningFee": 0,
        "pendingAdditionalInfoCount": 0,
        "isPermanent": true,
        "expiresAt": null,
        "isCheckoutVa": false,
        "isBankTransferVa": false,
        "isSuspended": false,
        "reason": null,
        "monthlyVolume": null,
        "entityName": null,
        "paymentFlowDescription": null,
        "attachments": [],
        "meansOfId": [],
        "bankStatement": [],
        "utilityBill": [],
        "virtualAccountType": "additional",
        "riskRating": null,
        "checklist": null,
        "riskScreening": null,
        "channelKycUpdateStatus": null,
        "channelKycUpdateResponse": null,
        "_id": "***********************",
        "business": {
            "name": "Fincra DevRel",
            "email": "[email protected]"
        },
        "currency": "NGN",
        "accountType": "individual",
        "entityType": "main_account",
        "currencyType": "fiat",
        "createdAt": "@timestamp",
        "updatedAt": "@timestamp"
    }
}

5 - Retrieving list of virtual accounts created

A list of all virtual accounts created can be returned via an API call to the list virtual accounts endpoint.

{{base_url}}/profile/virtual-accounts/?currency=ngn
curl --location 'https://api.fincra.com/profile/virtual-accounts/?currency=ngn' \
--header 'accept: application/json' \
--header 'api-key: <Your API secret key>'

If successful, you will receive a JSON snippet with the details of all virtual account requests made.

{
    "success": true,
    "message": "[Notice: Virtual Account endpoint changing soon. Date to be communicated soon] Merchant virtual accounts fetched successfully",
    "data": {
        "results": [
            {
                "status": "approved",
                "isActive": true,
                "accountNumber": "1234567890",
                "merchantReference": null,
                "KYCInformation": {
                    "firstName": "John",
                    "lastName": "Doe",
                    "email": "[email protected]",
                    "bvn": "TJ44iG9KQv6LOQNfjnidaniidCis6JbruEIJaHLzpIG7sdhjjsdBNRn7BoWCU3MGYYCWYt7u/sdn10D6DUhinudtcxI+Hiwuuu2oPnEA="
                },
                "accountInformation": {
                    "accountNumber": "1234567890",
                    "accountName": "Customer full name",
                    "bankName": "GLOBUS BANK",
                    "bankCode": "103"
                },
                "verifiedKYCData": null,
                "note": null,
                "accountOpeningFee": 0,
                "pendingAdditionalInfoCount": 0,
                "isPermanent": true,
                "expiresAt": null,
                "isCheckoutVa": false,
                "isBankTransferVa": false,
                "isSuspended": false,
                "reason": null,
                "monthlyVolume": null,
                "entityName": null,
                "paymentFlowDescription": null,
                "attachments": [],
                "meansOfId": [],
                "bankStatement": [],
                "utilityBill": [],
                "virtualAccountType": "additional",
                "riskRating": null,
                "checklist": null,
                "riskScreening": null,
                "channelKycUpdateStatus": null,
                "channelKycUpdateResponse": null,
                "_id": "659wdwf72nhsdjd581480",
                "business": {
                    "name": "Customer full name",
                    "email": "[email protected]"
                },
                "currency": "NGN",
                "accountType": "individual",
                "entityType": "main_account",
                "currencyType": "fiat",
                "createdAt": "2024-01-05T10:52:34.787Z",
                "updatedAt": "2024-01-05T10:52:34.787Z"
            },
            {
                "status": "approved",
                "isActive": true,
                "accountNumber": "1234567890",
                "merchantReference": null,
                "KYCInformation": {
                    "firstName": "John",
                    "lastName": "Doe",
                    "email": "[email protected]",
                    "bvn": "TJ44ijnijwui82zpIG7CcRApq7TdxBLAda0E77oOVNBNRn7Bo342hjndwxzace1vwdl3fnxU5tE/CTv10ninsi72I+K2JkPx1eeq4kdgEEF6kQynPRa9K2QoPnEA="
                },
                "accountInformation": {
                    "accountNumber": "1234567890",
                    "accountName": "Customer full name",
                    "bankName": "GLOBUS BANK",
                    "bankCode": "103"
                },
                "verifiedKYCData": null,
                "note": null,
                "accountOpeningFee": 0,
                "pendingAdditionalInfoCount": 0,
                "isPermanent": true,
                "expiresAt": null,
                "isCheckoutVa": false,
                "isBankTransferVa": false,
                "isSuspended": false,
                "reason": null,
                "monthlyVolume": null,
                "entityName": null,
                "paymentFlowDescription": null,
                "attachments": [],
                "meansOfId": [],
                "bankStatement": [],
                "utilityBill": [],
                "virtualAccountType": "additional",
                "riskRating": null,
                "checklist": null,
                "riskScreening": null,
                "channelKycUpdateStatus": null,
                "channelKycUpdateResponse": null,
                "_id": "6564kjnaskj883be479",
                "business": {
                    "name": "Customer full name",
                    "email": "[email protected]"
                },
                "currency": "NGN",
                "accountType": "individual",
                "entityType": "main_account",
                "currencyType": "fiat",
                "createdAt": "2023-11-27T15:45:02.952Z",
                "updatedAt": "2023-11-27T15:45:02.952Z"
            }
        ],
        "total": 2
    }
}