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
Response · 200
string
The wallet balance, in minor units.
string
What you can spend now, in minor units. Check this before a payout.
string
Money on hold for payouts in progress, such as their fees. Already taken out of balance.
string
Money that has left the wallet for payouts that have not finished yet.
string
The wallet’s state.
boolean
Whether this currency can have a permanent virtual account.
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.
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.
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.
  • A conversion from another wallet. See Conversions.

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
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.
Response
boolean
true for your reusable account. false for a one-off account issued for a single pay-in.
integer | null
The pay-in a one-off account was issued for. null on a permanent account.
string | null
When a one-off account stops working. null on a permanent account.
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

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 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. A payout that the wallet cannot cover returns 422 wallet_insufficient_funds, with available and required in details.
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