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

# Wallets and balances

> Read your balances, create a wallet in a new currency, and get a virtual account to fund it.

A wallet holds your balance in one currency. Payouts and conversions debit a wallet. Pay-ins and conversions credit one. You have at most one wallet per currency.

## List balances

`GET /v1/wallets`

```bash cURL
curl "$PAYVE_API_URL/v1/wallets" \
  -H "x-api-key: $PAYVE_API_KEY"
```

```javascript Node
const res = await fetch(`${process.env.PAYVE_API_URL}/v1/wallets`, {
  headers: { 'x-api-key': process.env.PAYVE_API_KEY },
});
const { data: wallets } = await res.json();
const ngn = wallets.find((w) => w.currency === 'NGN');
const available = BigInt(ngn.availableBalance); // minor units
```

```python Python
import os, requests

res = requests.get(
    f"{os.environ['PAYVE_API_URL']}/v1/wallets",
    headers={"x-api-key": os.environ["PAYVE_API_KEY"]},
)
wallets = res.json()["data"]
ngn = next(w for w in wallets if w["currency"] == "NGN")
available = int(ngn["availableBalance"])  # minor units
```

```json Response · 200
{
  "data": [
    {
      "currency": "NGN",
      "balance": "125000000",
      "availableBalance": "125000000",
      "lienBalance": "5000",
      "inflightBalance": "5000000",
      "status": "active",
      "supportsVA": true,
      "hasVirtualAccount": true,
      "virtualAccountNumber": "9912345678",
      "virtualAccountBank": "Example Bank",
      "virtualAccountName": "Example Stores Ltd"
    },
    {
      "currency": "GHS",
      "balance": "46500",
      "availableBalance": "46500",
      "lienBalance": "0",
      "inflightBalance": "0",
      "status": "active",
      "supportsVA": false,
      "hasVirtualAccount": false,
      "virtualAccountNumber": null,
      "virtualAccountBank": null,
      "virtualAccountName": null
    }
  ]
}
```

**balance** `string`

The wallet balance, in minor units.

**availableBalance** `string`

What you can spend now, in minor units. Check this before a payout.

**lienBalance** `string`

Money on hold for payouts in progress, such as their fees. Already taken out of `balance`.

**inflightBalance** `string`

Money that has left the wallet for payouts that have not finished yet.

**status** `string`

The wallet's state.

**supportsVA** `boolean`

Whether this currency can have a permanent virtual account.

**hasVirtualAccount** `boolean`

Whether one exists. Its details are in the three `virtualAccount...` fields.

`GET /v1/wallets/{currency}` returns one wallet in the same shape, for example `GET /v1/wallets/NGN`. It returns `404 resource_not_found` if you have no wallet in that currency.

> [!NOTE]
>
> Balances are strings of digits in minor units. Parse them as integers. `"125000000"` in `NGN` is
> ₦1,250,000.00.

## Create a wallet

`POST /v1/wallets` creates a wallet in a currency. If you already have one, it returns it. It is safe to call more than once.

```bash
curl -X POST "$PAYVE_API_URL/v1/wallets" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "GHS" }'
```

Payve also creates a wallet for you when you first send a payout, pay-in or conversion in a new currency.

## Fund a wallet

Money reaches a wallet in three ways:

* **A transfer to your virtual account.** For `NGN`, see below.
* **A pay-in.** See [Pay-ins](/guides/payins.md).
* **A conversion** from another wallet. See [Conversions](/guides/conversions.md).

## Virtual accounts

A permanent virtual account is a bank account number that belongs to your wallet. Any transfer to it is credited to that wallet. Payve issues permanent virtual accounts for `NGN`.

### Request one

`POST /v1/wallets/NGN/request-va`

```bash
curl -X POST "$PAYVE_API_URL/v1/wallets/NGN/request-va" \
  -H "x-api-key: $PAYVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

The body is optional. Payve uses the verified details it already holds for your business. You can pass `bvn`, `phone` or `rcNumber` to supply or override them.

```json Response
{
  "data": {
    "id": 31,
    "currency": "NGN",
    "accountNumber": "9912345678",
    "accountName": "Example Stores Ltd",
    "bankName": "Example Bank",
    "status": "active",
    "isPermanent": true,
    "transactionId": null,
    "expiresAt": null,
    "createdAt": "2026-11-18T08:30:00.000Z"
  }
}
```

**isPermanent** `boolean`

`true` for your reusable account. `false` for a one-off account issued for a single pay-in.

**transactionId** `integer | null`

The pay-in a one-off account was issued for. `null` on a permanent account.

**expiresAt** `string | null`

When a one-off account stops working. `null` on a permanent account.

> [!NOTE]
>
> A Naira virtual account needs a verified BVN on your business. Without one the request fails with
> `400` and `details.code` of `bvn_required`.

### Read your virtual accounts

| Request | Returns |
| - | - |
| `GET /v1/wallets/{currency}/va` | The active permanent account for that wallet, or `null`. |
| `GET /v1/wallets/virtual-accounts` | Every permanent virtual account you have. |
| `GET /v1/wallets/virtual-accounts/{id}` | One account, with the payment it expects if it is a one-off. |

> [!WARNING]
>
> Give your permanent account number only to people who should be funding your wallet. Anything sent
> to it is credited to you. For a customer payment of a fixed amount, create a `virtual_account`
> [pay-in](/guides/payins.md#virtual-account-pay-ins) so each payment has its own account.

## Check before you send

A payout needs the amount **plus the fee**. Compare `availableBalance` with `sourceAmount + fee.amount` from the [quote](/guides/quotes.md). A payout that the wallet cannot cover returns `422 wallet_insufficient_funds`, with `available` and `required` in `details`.

> [!TIP]
>
> Do not cache balances. Read them when you need them: a pay-in or a finished payout changes them at
> any moment.

## When it fails

| Status and code | Cause | Fix |
| - | - | - |
| `404 resource_not_found` | No wallet in that currency. | Create it with `POST /v1/wallets`. |
| `422 validation_missing_field` | `currency` is not three letters. | Send an ISO currency code. |
| `400 validation_missing_field` | A Naira virtual account was requested without a verified BVN. | Finish verification. |
| `422 wallet_frozen` | The wallet is frozen. | Contact [support](/support.md). |
