Virtual Bank Accounts (or Virtual Accounts) are a special type of bank account that you can use to receive payments from your customers. Customers only need to make transfers from their preferred bank app into the virtual account assigned to them. Because this account is dedicated to a single customer, every payment made to that account will be associated with the customer.

📘

It is important to note that Virtual Bank Accounts do not store monetary value like regular bank accounts; they only provide a means for your customers to pay you.

The Virtual Bank Account can be used to accept payments from customers at any time. You won't need to generate a new bank account for the customer every time they need to pay you. Making payments with Virtual Bank Accounts is flexible and absolutely stress-free for customers since they can choose to pay from their preferred banking channels.

Prerequisite

Create an account on Korapay here and submit all necessary compliance details.

Accepting payments with Virtual Bank Account

There are three main steps to note when it comes to accepting payments from your customers with Virtual Bank Accounts:

1. Create Virtual Accounts for customers
To create Virtual Bank Accounts for your customers make a request to the Create Virtual Bank Account API. These accounts can be used to accept payments immediately after they are created. To retrieve details of a virtual account, make a request to the Virtual Bank Account Query API.

🚧

By default, you can only create a total of fifty (50) virtual bank accounts. If you would need to upgrade this limit, please send a request to [email protected].

2. Set up webhooks
Since payments to virtual accounts are initiated outside your application, you can only be notified when the payment is complete. This makes it important to set up webhooks so that Korapay can notify you when your customers make payments.

3. Verify payments
After you receive a webhook notification from us, verify the payment by making a request to our Transaction Query API.

Creating a Virtual Bank Account

To create a Virtual Bank Account, you’ll need to make a request to the Create Virtual Bank Account API endpoint.

🚧

Currently, all generated Virtual Bank Accounts are Wema bank accounts and only Wema bank code 035 should be passed in the bank_code field.

Endpoint - https://api.korapay.com/merchant/api/v1/virtual-bank-account

Here are the request parameters for the endpoint:

Here's what a response would look like:

{
  "status": true,
  "message": "Virtual bank account created successfully",
  "data" {
    "account_name": "Afro Jon",
    "account_number": "7657789765",
    "bank_code": "035",
    "bank_name": "Wema Bank",
    "account_reference": "{{your_account_reference}}",
    "unique_id": "{{ korapay_account_reference}}",
    "account_status": "active",
    "created_at": "2021-08-10TI7:38:42.521Z",
    "currency": "NGN",
    "customer": {
       "name": "Test Customer"
    }
  }
}

Updating the KYC details of a Virtual Bank Account

The KYC details of a Virtual Bank Account can be updated once. To do this, you’ll need to initiate a PATCH request to the VBA Query API endpoint:

https://api.korapay.com/merchant/api/v1/virtual-bank-account/:accountReference

These are the parameters to use:

Here's what the sample response to the request to update KYC details would look like:

{
  "status": true,
  "message": "Virtual bank account kyc updated successfully"
}

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’ll need to initiate a GET request to the Virtual Bank Account Query API endpoint.

Endpoint - https://api.korapay.com/merchant/api/v1/virtual-bank-account/:accountReference

Here's what the response of a successful request would look like:

{
  "status": true,
  "message": "Virtual bank account retrieved successfully",
  "data": {
    "account_name": "Afro Jon",
    "account_number": "7657789765",
    "bank_code": "035",
    "bank_name": "Wema Bank",
    "account_reference": "{{your_account_reference}}",
    "unique_id": "{{ korapay_account_reference }}",
    "account_status": "active",
    "created_at": "2021-08-10TI7:38:42.521Z",
    "currency": "NGN",
    "customer": {
       "name": "Test Customer"
    }
  }
}

The details of a Virtual Bank Account can also be viewed on your Merchant dashboard. Simply click on an account on the list of Virtual Bank Accounts to view its details.

On the details page, you would see an account summary showing the account name, account number, details of the customer to which the virtual account has been assigned, as well as other important information on the account. You would also see a list of all the transactions made through the virtual account in the Transaction History section.

Getting notified of payments

After payment has been made into a VBA, we send a webhook notification to your webhook notification URL. The reference in the notification payload will be used to get the details of the payment.

You can read more about how to handle webhook notifications here.

Here's a sample webhook notification:

{
  "event": "charge.success",
  "data": {
    "reference": "KPY-PAY-4l5O8mxmgX2kijp",
    "currency": "NGN",
    "amount": 1000,
    "fee": 15,
    "status": "success",
    "virtual_bank_account_details": {
      "payer_bank_account": {
        "account_name": "Ope Praise",
        "account_number": "******1001",
        "bank_name": "First Bank Nigeria"
      },
      "virtual_bank_account": {
        "account_name": "Afro Jon",
        "account_number": "7657789765",
        "account_reference": "{{your_account_reference}}",
        "bank_name": "Wema Bank"
      }
    },
    "transaction_date": "2021-09-08T12:06:28.309Z"
  }
}

Getting the details of payment made to Virtual Bank Account

You can get the details of payment to a Virtual Bank Account by making a GET request to the Charge Query API endpoint using the reference returned in the webhook notification request payload.

Endpoint - https://api.korapay.com/merchant/api/v1/charges/:reference

And here's what the response looks like:

{
  "status": true,
  "message": "Charge retrieved successfully",
  "data": {
    "reference": "kpy-pay-123456",
    "status": "success",
    "amount": "100.00",
    "amount_paid": "100.00",
    "fee": 1.5,
    "currency": "NGN",
    "description": "Payment to merchant",
    "customer": {
      "name": "John Doe",
      "email": "[email protected]"
    },
    "virtual_bank_account": {
      "account_number": "7650000001",
      "account_name": "John Doe",
      "account_reference": "test-ref",
      "transaction_narration": "NIP: John Doe-7650000001/John Doe",
      "payer_bank_account": {
        "account_number": "3110920293",
        "account_name": "John Doe",   
        "bank_name": "First Bank"
      }
    }
  }
}

More details on the payments made to Virtual Bank Account can be viewed from the Pay-ins page of your dashboard. Simply:

1. Log in to your dashboard. Create an account if you don’t already have one.
2. Navigate to the Pay-ins page.
3. Search for the transaction using the transaction reference.
4. Click on the transaction to view further details.

Fetching the Transactions on a Virtual Bank Account

All the payments that have been made to a Fixed Virtual Bank Account can be retrieved. To do this, you need to make a GET request to the VBA Transactions Query API endpoint.

Endpoint - https://api.korapay.com/merchant/api/v1/virtual-bank-account/transactions

See the request parameters for this endpoint below:

📘

Note

You are to pass the request parameters as a query because it is a GET request. e.g https://api.korapay.com/merchant/api/v1/virtual-bank-account/transactions?account_number=1003346789

Here's a sample response:

{
  "status": true,
  "message": "Virtual bank account transactions retrieved successfully",
  "data": {
    "total_amount_recieved": 3000,
    "account_number": "1003346789",
    "currency": "NGN",
    "transactions": [
        {
           "reference": "kpy-ex-ref-1",
           "status": "success",
           "amount": "3000.00",
           "fee": "0.00",
           "currency": "NGN",
           "description": "Test Payment",
           "payer_bank_account": {
             "account_number": "6376372682",
             "account_name": "Test Payment",
             "bank_name": "Test Bank"
           }
        }
     ],
    "pagination": {
       "page": 1,
       "total": 1,
       "pageCount": 1,
       "totalPages": 1
    },
  }
}

Suspending and Deleting a Virtual Bank Account

Virtual Bank Accounts can be suspended and deleted. When an account is suspended or deleted, no payment can be made to such an account.

📘

To suspend or delete an account, you’ll need to reach out to [email protected] with the details of the account and the reason for suspension or deletion.

Crediting a Virtual Bank Account on the Sandbox Environment

Fixed Virtual Accounts on the sandbox environment can be credited with test payments. To do this, you need to make a POST request to the Credit Sandbox VBA endpoint.

Endpoint - https://api.korapay.com/merchant/api/v1/virtual-bank-account/sandbox/credit

See the request parameters below:

See an example of a sample response below:

{
  "status": true,
  "message": "Virtual bank account credited successfully",
  "data”: null
}