Virtual Accounts

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.

GET https://vas.finpaytech.co/business-api/api/v1/merchants/me/virtual-account
Authorization: Bearer <access-token>

List All Accounts

GET https://vas.finpaytech.co/business-api/api/v1/merchants/me/virtual-accounts
Authorization: Bearer <access-token>

Get One Account

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

Sample Response

{
  "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 (POST https://vas.finpaytech.co/business-api/api/v1/merchants/me/expected-payments).

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):

{
  "purpose": "BRAND",
  "subMerchantId": "<sub-merchant-id>"
}

Subscriber (one permanent number for a customer). You can also call Customers and Subscribers:

{
  "purpose": "SUBSCRIBER",
  "customerId": "<customer-id>"
}

Currency (dedicated KES or USD number):

{
  "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.

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.

Balance History

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.

Getting Started

Guides

Primary Account

List All Accounts

Get One Account

Sample Response

Provision Brand, Subscriber, or Currency

Invoice VA

Balance History

​Primary Account

​List All Accounts

​Get One Account

​Sample Response

​Provision Brand, Subscriber, or Currency

​Invoice VA

​Balance History

Primary Account

List All Accounts

Get One Account

Sample Response

Provision Brand, Subscriber, or Currency

Invoice VA

Balance History