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

# Virtual Accounts

> List, Fetch, and Provision Collection Account Numbers

A virtual account is a **collection account number** you give payers. Incoming M-Pesa, PesaLink, and RTGS credits settle against that number.

## Primary Account

Provisioned when your merchant is activated. One permanent number for the merchant.

```http theme={null}
GET https://vas.finpaytech.co/business-api/api/v1/merchants/me/virtual-account
Authorization: Bearer <access-token>
```

## List All Accounts

```http theme={null}
GET https://vas.finpaytech.co/business-api/api/v1/merchants/me/virtual-accounts
Authorization: Bearer <access-token>
```

## Get One Account

```http theme={null}
GET https://vas.finpaytech.co/business-api/api/v1/merchants/me/virtual-accounts/{virtualAccountId}
Authorization: Bearer <access-token>
```

## Sample Response

```json theme={null}
{
  "id": "9d6be39e-9465-4d67-a05a-4b366352bd64",
  "merchantId": "301f0991-8f7c-4501-a1d4-c317fe7b7f23",
  "ownerType": "MERCHANT",
  "ownerId": "301f0991-8f7c-4501-a1d4-c317fe7b7f23",
  "purpose": "LEGACY",
  "purposeLabel": "Legacy merchant VA",
  "accountNumber": "7600000035",
  "accountName": "Emaal - WithLotus",
  "accountType": "STATIC",
  "status": "ACTIVE",
  "balance": 130.00,
  "currency": "KES",
  "singleDepositLimit": null,
  "expireAt": null,
  "createdAt": "2026-08-31T12:47:01.898Z"
}
```

Show payers `accountNumber` (and `accountName` where the channel displays a name). `status` must be `ACTIVE` before you publish the number.

Invoice accounts also return `singleDepositLimit` and `expireAt`. Do not reuse an invoice number after it is paid or expired.

## Provision Brand, Subscriber, or Currency

Invoice VAs are not created on this route. Use [Invoice VA](#invoice-va) (`POST https://vas.finpaytech.co/business-api/api/v1/merchants/me/expected-payments`).

```http theme={null}
POST https://vas.finpaytech.co/business-api/api/v1/merchants/me/virtual-accounts
Authorization: Bearer <access-token>
Content-Type: application/json
```

**Brand** (one permanent number for a shop):

```json theme={null}
{
  "purpose": "BRAND",
  "subMerchantId": "<sub-merchant-id>"
}
```

**Subscriber** (one permanent number for a customer). You can also call [Customers and Subscribers](/guides/customers-and-subscribers):

```json theme={null}
{
  "purpose": "SUBSCRIBER",
  "customerId": "<customer-id>"
}
```

**Currency** (dedicated `KES` or `USD` number):

```json theme={null}
{
  "purpose": "CURRENCY",
  "currency": "USD"
}
```

Returns `201` and the same virtual-account object, including the new `accountNumber`.

## Invoice VA

A one-time number for a single bill. Amount and expiry are enforced. Do not reuse the number after it is paid, expired, or cancelled.

```http theme={null}
POST https://vas.finpaytech.co/business-api/api/v1/merchants/me/expected-payments
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "paymentReference": "INV-2026-1044",
  "amount": 2500.00,
  "currency": "KES",
  "expiresAt": "2026-09-12T21:00:00Z",
  "provisionInvoiceVa": true
}
```

`provisionInvoiceVa` defaults to `true`. The response includes `virtualAccountNumber`. Full request and cancel flow: [Invoice VA](/guides/invoices).

## Balance History

```http theme={null}
GET https://vas.finpaytech.co/business-api/api/v1/merchants/me/virtual-account/balance-history
Authorization: Bearer <access-token>
```

Each row is one successful credit with previous and new running balance.