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

# One-off payment accounts

> A dynamic account for one invoice or order, for a set amount.

A **dynamic** virtual account is lent to you for one payment of a set amount: one per invoice, order or checkout. When the right amount arrives it's `paid`; if nothing arrives before it expires, it's `expired`.

Needs `VIRTUAL_ACCOUNTS` and `DYNAMIC_VIRTUAL_ACCOUNTS`, and `virtual-accounts:write`.

## 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": "dynamic",
    "reference": "INV-2026-0042",
    "amount_minor": 2500000,
    "expiry_minutes": 60,
    "fee_bearer": "customer",
    "payer_name": "Chidi Eze"
  }'
```

| Field | |
| - | - |
| `reference` | Required. Your own invoice or order number: 1 to 40 letters, digits, `-` or `_`, unique to your business |
| `amount_minor` | Required. The amount, in kobo |
| `expiry_minutes` | Optional. How long the number waits for the payment |
| `fee_bearer` | `business` (the default) or `customer`. With `customer`, the payer sends the amount plus the charge |
| `payer_name` | Optional, 2 to 150 characters. Who you expect to pay |
| `collection_account_id` | Optional. One of your collection accounts for the payment to settle into |

The answer's `payment_terms` tell you what to show the payer:

| Field | |
| - | - |
| `total_payable_minor` | **What the payer must send.** Includes the charge when the payer bears it |
| `fee_minor`, `vat_minor`, `charge_minor` | The bank's charge and its VAT |
| `settlement_minor` | What reaches you |
| `expires_at` | When the number stops waiting |
| `received_minor`, `paid_at`, `transaction_id` | Filled once paid |

## Find it by your reference

You don't have to store Mesh's id: `GET /v1/virtual-accounts?reference=INV-2026-0042` returns the list with at most one account, and an empty list when there's none.

## Outcomes

| Event | When |
| - | - |
| `dva.payment.success` | The right amount arrived. The account is `paid` |
| `dva.payment.held` | Something else arrived: another amount, a late payment or a second one. See [held payments](https://docs.mesh.larkwave.org/guides/held-payments.md) |
| `dva.expired` | Nothing arrived in time |
| `dva.cancelled` | You cancelled it |

To withdraw an account before it's paid, `POST /v1/virtual-accounts/{accountId}/cancel`. Only one still waiting for its payment can be cancelled; anything else is `409` (code `65`).


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