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

# Collection accounts

> Permanent account numbers your payers pay into.

A **static** virtual account is one of your business's collection accounts: a permanent number you can print on invoices, give to a branch, or show at checkout. Each payment into it settles on to your business's account at the bank.

Needs the `VIRTUAL_ACCOUNTS` feature and `virtual-accounts:write`. In live mode the bank must also have approved your business and recorded your settlement account.

## Create one

```bash theme={null}
curl https://$MESH_HOST/v1/virtual-accounts \
  -H "X-Api-Key: $MESH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "type": "static", "label": "Lekki branch" }'
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": "9b2e4c1a-…",
    "account_number": "6037000014",
    "account_name": "Ada Stores",
    "name_status": "pending",
    "type": "static",
    "purpose": "collection",
    "label": "Lekki branch",
    "status": "active",
    "fee_bearer": "business",
    "settles_to": "core_banking",
    "settlement_account": null,
    "created_at": "2026-11-21T09:00:00Z"
  },
  "message": "…",
  "request_id": "…"
}
```

| Field | |
| - | - |
| `label` | Optional, up to 50 characters. Your own name for it |
| `fee_bearer` | `business` (the default) or `customer`: who pays the bank's charge on each payment |

* **`name_status`** starts `pending` while the bank's provider names the number, then becomes `confirmed` (or `failed`). You'll get `va.name.confirmed` or `va.name.failed`.
* **`settlement_account`** is the account at the bank the payments go on to, or `null` when it follows your business's default, which the bank records.

## Rename it, or name a number

`PATCH /v1/virtual-accounts/{accountId}` changes the name payers see, and/or the label. Send a person's name (`first_name`, `last_name`, optional `middle_name`) or free text (`account_name`), not both.

* A number from the provider's pool is renamed there first: `202`, `name_status` `pending`, and a second rename meanwhile is `409` (code `25`).
* A number from one of your [number patterns](https://docs.mesh.larkwave.org/api-reference/introduction.md) is named at once: `200`.

`PUT /v1/virtual-accounts/numbers/{accountNumber}` names a number under one of your patterns, even before its first payment. If nobody holds it yet, it creates the account (`201`).

## Payments and settlements

* `GET /v1/virtual-accounts/{accountId}/payments` lists the payments into it.
* `GET /v1/virtual-accounts/{accountId}/settlements` lists each payment passed on to your settlement account: `queued`, `settled` or `failed`.
* `GET /v1/collection-settlements` lists them across every collection account.

Each payment also arrives as a webhook: `va.payment.success` when credited, and `va.settlement.completed` when passed on to your account at the bank.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.