> ## 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.

# Get a Virtual Account

> Retrieve a reserved virtual account and its bank details.

Fetch a single reserved account — its provider account(s) and the customer it belongs to. Look it up by the `reference` you supplied when creating it, or by the customer's `email`.

## Endpoint

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

<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

Provide **one** of the following to identify the account:

<ParamField body="reference" type="string">
  The merchant reference you supplied when creating the account.
</ParamField>

<ParamField body="email" type="string">
  The customer's email address.
</ParamField>

<Note>
  Send either `reference` or `email`. Accounts are scoped to your business, so you only ever retrieve accounts you created.
</Note>

## Request

```bash theme={null}
curl -X POST https://api.billstack.co/v2/thirdparty/getVirtualAccount/ \
  -H "Authorization: Bearer Bill_Stack-SEC-KEY-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "order_12345"
  }'
```

## Response

```json theme={null}
{
  "status": true,
  "message": "Account retrieved",
  "data": {
    "reference": "R-XXXXXXXXXXX",
    "merchant_reference": "order_12345",
    "customer": "customer@example.com",
    "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": "customer@example.com"
    }
  }
}
```

### Response fields

| Field                     | Description                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `data.reference`          | The BillStack reference for the reserved account.                                                                                     |
| `data.merchant_reference` | The reference you supplied at creation.                                                                                               |
| `data.customer`           | The customer email the account belongs to.                                                                                            |
| `data.account`            | All provider accounts reserved for this customer. A customer may hold more than one (for example, both a 9PSB and a PalmPay account). |
| `data.meta`               | The customer details the account was created with.                                                                                    |

<Note>
  A single customer record can hold accounts across multiple banks. The `account` array contains every provider account reserved for that customer under your business.
</Note>