Accepting payments with GHS Virtual Bank Account

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

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 GHS 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 would need to upgrade this limit, please send a request to [email protected].
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.
Verify payments: After you receive a webhook notification from us, verify the payment by making a request to our Transaction Query API.

Creating a GHS Virtual Bank Account

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

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

Request Parameters

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`currency`	string	✅ Yes	The currency of the virtual bank account. Set this to GHS
`account_name`	string	✅ Yes	The name of the Virtual Bank account.
`account_reference`	string	✅ Yes	Your unique reference to identify a virtual bank account.
`customer`	string	✅ Yes	This is the information of your customer to which you assign the virtual bank account.
`customer.name`	string	✅ Yes	The customer's name.
`customer.email`	string	✅ Yes	The customer's email.
permanent	string	✅ Yes	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": {
        "account_name": "John Doe",
        "account_number": "9980009558",
        "bank_name": "UNITED BANK FOR AFRICA",
        "customer": {
            "name": "John Doe",
            "email": "[email protected]"
        },
        "account_reference": "GHS0p0KTQ9",
        "unique_id": "KPY-VA-phmSmYt82You8Kg",
        "account_status": "active",
        "created_at": "2026-10-07T13:39:36.410Z",
        "currency": "GHS"
    }
}

Retrieving the details of a GHS 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": "UNITED BANK FOR AFRICA",
        "currency": "GHS",
        "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": "GHS",
   "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": "United Bank for Africa"
     },
     "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": "GHS",
        "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": "XXXXXXX",
                "bank_name": "First bank"
            }
        },
        "payer_bank_account": {
            "account_number": null,
            "account_name": "XXXXXXXX",
            "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:

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

Fetching transactions done on an GHS 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

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

PARAMETER	TYPE	REQUIRED	DESCRIPTION
`account_number`	String	True	This is the account number of the Fixed Virtual Bank Account.
`start_date`	String	False	This is the specific date from which you would like the query to start. The expected date format is YYYY-MM-DD.
`end_date`	String	False	This is the specific end date for the search query. The expected date format is YYYY-MM-DD.
`page`	Number	False	This specifies the page number to retrieve. By default it is 1.
`limit`	Number	False	This 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": "GHS",
       "transactions": [
           {
               "reference": "KPY-PAY-AeL50YU1mdozvWR",
               "status": "success",
               "amount": "10.00",
               "fee": "0.10",
               "currency": "GHS",
               "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
       }
   }
}

Deleting or Deactivating a Virtual Bank Account

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

NOTE: To delete or deactivate an account, you’ll need to reach out to [email protected] with the details of the account and the reason for deactivation.

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