Guides
API ReferenceCreate Account

Accepting payments with KES 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 VBAs for your customers: To create Virtual Bank Accounts for your customers, make a request to the Create Virtual Bank Account API. The creation of KES accounts occurs asynchronously. Initially, the account will be in a pending status and will only be available to receive funds once you are notified via the account_number.creation webhook that the account is active. 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 need to upgrade this limit, please send a request to [email protected].
  2. Set up Webhook: 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 KES Virtual Bank Account


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

Endpoint: 

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

Request Parameters

PARAMETERTYPEREQUIREDDESCRIPTION
currencystringYes ✅The currency of the virtual bank account. Set this to KES
account_namestringYes ✅The name of the Virtual Bank account.
account_referencestringYes ✅Your unique reference to identify a virtual bank account.
customerstringYes ✅This is the information of your customer to which you assign the virtual bank account.
customer.namestringYes ✅The customer's name.
customer.emailstringYes ✅The customer's email.
permanentstringYes ✅This shows if the account is permanent or temporary. This can only be set to true for now.

Sample Response:

{
    "status": true,
    "message": "Virtual bank account created successfully",
    "data": {
        "bank_name": "Choice Bank",
        "account_reference": "your-account-reference-906",
        "unique_id": "KPY-VA-n9vAKSZUwB0HtWe",
        "account_status": "pending",
        "created_at": "2026-06-16T06:40:06.158Z",
        "currency": "KES"
    }
}

Getting notified when the Virtual Bank Account is ready


Because the account is created asynchronously, we notify you with an account_number.creation webhook once account number is . This webhook is sent before any payment can be made into the account, it tells you the account is now active and ready to receive payments.

  • If the account was created successfully, the webhook status is active and the payload contains the assigned account number under bank_details.
  • If account creation failed, the webhook status is failed and no bank_details are included.

Only after receiving an active account_number.creation webhook should you share the account details with your customer.

Sample Webhook:

{
  "event": "account_number.creation",
  "status": "active",
  "data": {
    "reference": "KPY-WBK-xxxxxxxxxx",
    "account_reference": "kes-vba-ref-001",
    "status": "active",
    "bank_details": {
      "account_number": "1003346789",
      "account_name": "Jane Doe",
      "status": "active",
      "currency": "KES"
    },
    "date": "2026-06-16T10:26:42.000Z"
  }
}

Retrieving the details of an KES 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

Sample Response:

{
    "status": true,
    "message": "Virtual bank account retrieved successfully",
    "data": {
        "account_name": "Steph James testing company",
        "account_number": "46013001312270",
        "account_status": "active",
   "account_reference": "{{your_account_reference}}",
   "unique_id": "{{ korapay_account_reference }}",
        "bank_name": "Choice Bank",
        "currency": "KES",
        "created_at": "2026-06-16T10:13:44.000Z",
        "customer": {
            "name": "John Doe",
            "email": "[email protected]"
        }
    }
}

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.

In 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 a 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.

Sample Webhook Notification

{
 "event": "charge.success",
 "data": {
   "reference": "KPY-PAY-xxxxxxxxxx",
   "currency": "KES",
   "amount": "5000.00",
   "fee": "50.00",
   "status": "success",
   "amount_paid": "5000.00",
   "payment_reference": "kes-vba-ref-001",
   "transaction_date": "2026-06-16T11:02:54.000Z",
   "virtual_bank_account_details": {
     "payer_bank_account": {
       "account_name": "John Buyer",
       "account_number": "9012345678",
       "bank_name": "Choice Bank"
     },
     "virtual_bank_account": {
       "account_number": "1003346789",
       "account_name": "Jane Doe",
       "account_reference": "kes-vba-ref-001"
     }
   },
   "customer": {
     "name": "Jane Doe",
     "email": "[email protected]"
   }
 }
}

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

Sample Response:

{
    "status": true,
    "message": "Charge retrieved successfully",
    "data": {
        "reference": "KPY-PAY-mglV8cWzkke4CSg",
        "status": "success",
        "amount": "10.00",
        "amount_paid": "10.00",
        "fee": 0.1,
        "currency": "KES",
        "description": "Payment to Demo Merchant by Don James",
        "customer": {
            "name": "Don James",
            "email": "[email protected]"
        },
        "virtual_bank_account": {
            "account_number": "46013001311785",
            "account_name": "Test Account 1",
            "account_reference": "0U00p0kpw4",
            "transaction_narration": null,
            "payer_bank_account": {
                "account_number": null,
                "account_name": "NCBA  Bank M-pesa",
                "bank_name": "M-PESA"
            }
        },
        "payer_bank_account": {
            "account_number": null,
            "account_name": "NCBA  Bank M-pesa",
            "bank_name": "M-PESA"
        }
    }
}

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 transactions done on KES Fixed 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

Request Parameters

🚧

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

PARAMETERTYPEREQUIREDDESCRIPTION
account_numberStringTrue ✅This is the account number of the Fixed Virtual Bank Account.
start_dateStringTrue ✅This is the specific date from which you would like the query to start. The expected date format is YYYY-MM-DD.
end_dateStringTrue ✅This is the specific end date for the search query. The expected date format is YYYY-MM-DD.
pageNumberFalseThis specifies the page number to retrieve. By default it is 1.
limitNumberFalseThis is the maximum number of transactions that can be retrieved at once. By default, this is set to 100 and is configurable.

Sample Response

{
   "status": true,
   "message": "Virtual bank account transactions retrieved successfully",
   "data": {
       "total_amount_received": 10,
       "account_number": "46013001311785",
       "currency": "KES",
       "transactions": [
           {
               "reference": "KPY-PAY-AeL50YU1mdozvWR",
               "status": "success",
               "amount": "10.00",
               "fee": "0.10",
               "currency": "KES",
               "description": "Payment to Demo Merchant by Don James",
               "transaction_date": "2026-06-16 09:56:53",
               "payer_bank_account": {
                   "account_number": "254721760513",
                   "account_name": "John Doe",
                   "bank_name": "07"
               }
           }
       ],
       "pagination": {
           "page": 1,
           "total": 1,
           "pageCount": 2,
           "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.

🚧

NOTE: 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 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 this endpoint, Credit Sandbox VBA

Updated 7 days ago

Did this page help you?