> ## Documentation Index
> Fetch the complete documentation index at: https://docs.billstack.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Virtual Account

> Generate a dedicated virtual bank account a customer can pay into.

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](/webhooks/overview).

## Endpoint

```http theme={null}
POST https://api.billstack.co/v2/thirdparty/generateVirtualAccount/
```

<ParamField header="Authorization" type="string" required>
  Your secret key as a Bearer token: `Bearer Bill_Stack-SEC-KEY-…`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  `application/json`
</ParamField>

## Body parameters

<ParamField body="reference" type="string" required>
  A unique reference for the reserved account.
</ParamField>

<ParamField body="email" type="string" required>
  Customer email.
</ParamField>

<ParamField body="phone" type="string" required>
  Customer phone.
</ParamField>

<ParamField body="firstName" type="string" required>
  Customer first name.
</ParamField>

<ParamField body="lastName" type="string" required>
  Customer last name.
</ParamField>

<ParamField body="bank" type="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
</ParamField>

<ParamField body="idType" type="string">
  **Required when `bank` is `PALMPAY`.** Either `nin` or `bvn`.
</ParamField>

<ParamField body="idNumber" type="string">
  **Required when `bank` is `PALMPAY`.** The NIN or BVN value matching `idType`.
</ParamField>

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

## Request

<CodeGroup>
  ```bash 9PSB theme={null}
  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"
    }'
  ```

  ```bash PalmPay theme={null}
  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"
    }'
  ```
</CodeGroup>

## Response

```json theme={null}
{
  "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.                                                             |

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