Create a wallet
Provision a customer-owned wallet. Returns a wallet handle and a real, fundable account number. KYC identity is required at creation.
Create a wallet
Provisions a customer-owned wallet with the provider and returns its handle and a real, fundable account number.
Wallet creation carries the holder's KYC identity — the provider name-matches and, for a real bank-backed wallet, is the custodian of record. These fields are required.
Request
POST /wallets
| Field | Type | Required | Description |
|---|---|---|---|
reference | string | yes | Your idempotent reference for this provisioning request. Re-sending the same reference returns the same wallet. |
bvn | string | yes | The holder's Bank Verification Number. Individual KYC — the provider name-matches against it. |
firstName | string | yes | The holder's first name (name-match). |
lastName | string | yes | The holder's last name (name-match). |
phone | string | no | The holder's phone. |
email | string | no | The holder's email. |
metadata | object | no | Opaque provider-specific fields the neutral layer does not model. Keep narrow. |
Response
| Field | Type | Description |
|---|---|---|
walletId | string | The provider's stable handle for this wallet — the id every later credit / debit / balance addresses. |
accountNumber | string | The provider-held account number — a real bank account the customer funds by direct transfer at zero collection cost. (Optional: not every provider exposes a fundable number.) |
bankCode | string | The bank of the account number. |
provider | string | The provider holding this wallet (data, for forensics). |
reference | string | Your reference, echoed back. |
success | boolean | Whether provisioning succeeded. |
Through the One API
When you provision Wallet through the One API
(POST /products/wallet/provision), pass these identity fields in the request
metadata — the One API threads them to the wallet product untouched. The wallet
is minted one-per-customer, keyed on your customer_ref.
Amounts elsewhere in the wallet API are always kobo (integer minor units).