Create a Virtual Account

Create a virtual (reserved) account that a customer can transfer money into. When funds arrive, BillStack records the payment against the account’s reference and sends you a webhook.

Endpoint

POST https://api.billstack.co/v2/thirdparty/generateVirtualAccount/

string

required

Your secret key as a Bearer token: Bearer Bill_Stack-SEC-KEY-…

string

required

application/json

Body parameters

string

required

A unique reference for the reserved account.

string

required

Customer email.

string

required

Customer phone.

string

required

Customer first name.

string

required

Customer last name.

string

required

The bank to generate the account with. Supply one bank per request:

9PSB - 9PSB Bank
SAFEHAVEN - Safehaven MFB
PROVIDUS - Providus Bank
PALMPAY - PalmPay Bank

string

Required when bank is PALMPAY. Either nin or bvn.

string

Required when bank is PALMPAY. The NIN or BVN value matching idType.

You can only generate one bank per request. To offer a customer multiple banks, call the endpoint once per bank.

Request

curl -X POST https://api.billstack.co/v2/thirdparty/generateVirtualAccount/ \
  -H "Authorization: Bearer Bill_Stack-SEC-KEY-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_12345",
    "email": "customer@example.com",
    "phone": "08012345678",
    "firstName": "Ahmad",
    "lastName": "Naziru",
    "bank": "9PSB"
  }'

curl -X POST https://api.billstack.co/v2/thirdparty/generateVirtualAccount/ \
  -H "Authorization: Bearer Bill_Stack-SEC-KEY-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_12345",
    "email": "customer@example.com",
    "phone": "08012345678",
    "firstName": "Ahmad",
    "lastName": "Naziru",
    "bank": "PALMPAY",
    "idType": "nin",
    "idNumber": "12345678901"
  }'

Response

{
  "status": true,
  "message": "Account reserved",
  "data": {
    "reference": "R-XXXXXXXXXXX",
    "account": [
      {
        "account_number": "0000000000",
        "account_name": "Alias-Ahmad Naziru",
        "bank_name": "9PSB Bank",
        "bank_id": "9PSB",
        "created_at": "2024-04-02 05:47:42"
      }
    ],
    "meta": {
      "firstName": "Ahmad",
      "lastName": "Naziru",
      "email": "sna@gmail.com"
    }
  }
}

Response fields

Field	Description
`data.reference`	The reserved account reference. Payments into this account are reported against it.
`data.account`	The generated account(s). Each has `account_number`, `account_name`, `bank_name`, `bank_id`, and `created_at`.
`data.meta`	The customer details the account was created with.

Store data.reference against your order. When a payment arrives, the PAYMENT_NOTIFICATION webhook carries the same reference so you can match it back.

Getting Started

Webhooks

Reserved Accounts

Transactions

Create a Virtual Account

Endpoint

Body parameters

Request

Response

Response fields