Set up wallets
This is a new wallets flow, which is recommended for all new integrations.
If you already have an existing integration with Wallets API v.1, you can continue using it. For the Wallets v.1 guide see Create a wallet.
On BVNK, you can create and manage both crypto and fiat wallets through the Portal or API. Specify a customer's ID and reference to create wallets for them; otherwise, the wallet is created for your own account.
When created, a wallet passes the following stages:
* For fiat wallets only. For crypto wallets, start with step 2: Create a wallet.
Retrieve wallet profiles
When creating crypto wallets, start with the Create a wallet step.
Before adding a wallet to your account, you must assign a wallet profile to it. The wallet profile is a template that defines the currency codes and payment methods available for a wallet.
To list the existing wallet profiles, send the GET /ledger/v2/wallets/profiles request. Send the GET /ledger/v2/wallets/profiles request to list wallet profiles. Use the optional q parameter to filter results with Lucene query syntax, such as currency:USD, method:SWIFT, or customerId:550e8400-e29b-41d4-a716-446655440000 AND currency:USD.
| Query parameter | Description |
|---|---|
q | Optional search and filter expression. You can filter by:
|
Each profile in the response has an id to use as profileId when creating a wallet. Available currencies and methods vary based on your account and jurisdiction.
{
"totalElements": 6,
"totalPages": 1,
"content": [
{
"id": "fiat:gbp:16f367db",
"currencies": ["GBP"],
"methods": ["FASTER_PAYMENT", "CHAPS"]
},
{
"id": "fiat:eur:3392c62e",
"currencies": ["EUR"],
"methods": ["SEPA_CT", "SEPA_INST"]
},
{
"id": "fiat:usd:141d6bae",
"currencies": ["USD"],
"methods": ["SWIFT"]
},
{
"id": "fiat:usd:520e259f",
"currencies": ["USD"],
"methods": ["FEDWIRE", "ACH_SAME_DAY", "ACH", "RTP", "FEDNOW"]
},
{
"id": "fiat:usd:2d4901e0",
"currencies": ["USD"],
"methods": ["BOOK"]
},
{
"id": "crypto:custodial:a0b8a34c",
"currencies": [
"BTC",
"SOL",
"EURC",
"BNB",
"XRP",
"ETH",
"USDT",
"DOGE",
"USDC",
"TRX",
"POL"
],
"methods": []
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 50
},
"hasNext": false
}
Create a wallet
To create a wallet, do the following:
- API
- Portal
- Fiat Wallet
- Crypto Wallet
To create a fiat wallet with an assigned wallet profile, send the POST /ledger/v2/wallets request with a JSON body like the following. Use the id from GET /ledger/v2/wallets/profiles as profileId.
| Parameter | Required | Description |
|---|---|---|
customerId | Unique identifier for the customer. Required if you create a wallet for your customer. | |
currency | ✅ | Currency code for the wallet. |
name | ✅ | Display name for the wallet. |
profileId | ✅ | Wallet profile id from GET /ledger/v2/wallets/profiles. |
- Create a direct fiat wallet
- Create a fiat wallet for your customer
{
"currency": "USD",
"name": "USD SWIFT",
"profileId": "fiat:usd:141d6bae"
}
In the successful response, you get the details of the new fiat wallet:
{
"id": "a:25060945127830:rTgK3wN:1",
"name": "USD SWIFT",
"status": "INACTIVE",
"balance": {
"amount": 0.00,
"currency": "USD"
},
"paymentInstruments": [],
"createdAt": "2025-06-09T14:05:12.830Z",
"updatedAt": "2025-06-09T14:05:12.830Z"
}
The id of the created wallet is returned in a Location response header, for example https://api.sandbox.bvnk.com/ledger/v2/wallets/{id}.
Wallets are not created immediately: a new wallet often appears as INACTIVE first, and then automatically transitions to an ACTIVE state. The activation process can take several minutes. Poll GET /ledger/v2/wallets/{id} or use the webhooks rather than creating duplicate wallets if activation is slow.
When the wallet is created, the paymentInstruments array is empty and the balance is 0. The paymentInstruments array will be populated with the payment details after the wallet is activated and the webhook is received.
The wallet can also have the TERMINATED status. This means the wallet can no longer be used, and that state is final; BVNK can never reactivate it. All operations, including receiving pay-ins, sending payouts, and currency conversions, are blocked for the terminated wallets. You can only access its transaction history. To learn how to terminate a wallet, see the Manage wallets guide.
Manage wallets
To manage the wallet lifecycle, use POST /ledger/v2/wallets/{walletId}/actions.
You can perform the following actions:
TERMINATE: Permanently terminates the wallet. This action is irreversible. The wallet balance must be zero (0) before termination. For fiat wallets, the associated Virtual Account is closed. Crypto wallets do not use this mechanism.BLOCK: Temporarily blocks the wallet and prevents activity.UNBLOCK: Removes a previously applied block from the wallet.
In the payload, specify the action value and provide a non-empty comment explaining the reason for the action. You can add the following comments from the list:
COMPLIANCEOPERATIONOFFBOARDINGCLIENT_REQUESTOTHER
- BLOCK
- UNBLOCK
- TERMINATE
{
"action": "BLOCK",
"comment": "COMPLIANCE"
}
If the request is successful, the endpoint returns 204 No Content.
Possible error scenarios include:
400 Bad Request: For example, this occurs if you attempt to runTERMINATEwhen the wallet has a non-zero balance.409 Conflict: For example, this occurs if you attempt to runBLOCKorUNBLOCKon a wallet that is already terminated.
Retrieve wallets
Use the wallet endpoints to monitor status and balances. GET /ledger/v2/wallets returns summaries only and does not include paymentInstruments. Full payment instrument and account details are returned by GET /ledger/v2/wallets/{id} for a single wallet.
Fiat wallet balances use 2 decimal places (e.g. 48250.75), while crypto wallet balances use 6 decimal places (e.g. 14727.556775).
All wallets
To list all wallets, send the GET /ledger/v2/wallets request.
The list response returns wallet summaries without paymentInstruments. For payment instruments and full account details, call GET /ledger/v2/wallets/{id} with that wallet's {id}.
Response
{
"content": [
{
"id": "a:25031472839104:kR7mHxQ:1",
"name": "EUR Operations",
"status": "ACTIVE",
"balance": {
"amount": 48250.75,
"currency": "EUR"
},
"createdAt": "2025-03-14T09:12:33.104Z",
"updatedAt": "2025-06-02T11:45:07.346Z"
},
{
"id": "a:25041855293741:pWnL4vB:1",
"name": "USD Payroll",
"customer": {
"id": "c7a91d3e-48f2-4b76-a835-2e6d09f1c4b8",
"name": "Greenfield Logistics"
},
"status": "ACTIVE",
"balance": {
"amount": 125400.00,
"currency": "USD"
},
"createdAt": "2025-04-18T08:30:30.565Z",
"updatedAt": "2025-06-10T14:22:19.873Z"
},
{
"id": "a:25052061784520:mVeJ2rA:1",
"name": "USD Disbursements",
"customer": {
"id": "a1f84b6c-9e23-4d17-b590-7c4a83de2f10",
"name": "Meridian Healthcare"
},
"status": "ACTIVE",
"balance": {
"amount": 52080.00,
"currency": "USD"
},
"createdAt": "2025-05-20T12:16:24.520Z",
"updatedAt": "2025-06-11T09:40:51.684Z"
},
{
"id": "a:25052061801337:hQwP5nF:1",
"name": "EUR Supplier Payments",
"customer": {
"id": "a1f84b6c-9e23-4d17-b590-7c4a83de2f10",
"name": "Meridian Healthcare"
},
"status": "INACTIVE",
"balance": {
"amount": 0.00,
"currency": "EUR"
},
"createdAt": "2025-05-20T12:16:41.337Z",
"updatedAt": "2025-05-28T10:02:15.904Z"
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 50
},
"hasNext": true
}
Specific wallet
To retrieve wallet details by its unique identifier, send the GET /ledger/v2/wallets/{id} request with the {id} specified in the path.
In the response, you receive full wallet details, including payment instruments:
- Fiat Wallet
- Crypto Wallet
{
"id": "a:25052061784520:mVeJ2rA:1",
"name": "USD SWIFT",
"customer": {
"id": "a1f84b6c-9e23-4d17-b590-7c4a83de2f10",
"name": "Meridian Healthcare"
},
"status": "ACTIVE",
"balance": {
"amount": 52080.00,
"currency": "USD"
},
"paymentInstruments": [
{
"type": "FIAT",
"accountHolderName": "MERIDIAN HEALTHCARE SERVICES LTD",
"accountNumber": "GB29MDTR60000131926819",
"remittanceInformationPrefix": "REF HK4F291",
"bankDetails": {
"name": "Meridian Trust Bank PLC",
"address": {
"addressLine1": "250 Bishopsgate",
"city": "London",
"country": "GB",
"postCode": "EC2M 4AA"
},
"bic": "MDTRGB2LXXX",
"nid": {
"value": "600001",
"type": "SORT_CODE"
}
}
}
],
"createdAt": "2025-05-20T12:16:24.520Z",
"updatedAt": "2025-06-11T09:40:51.060Z"
}
Customer's wallets
To retrieve wallets for a specific customer, send the GET /ledger/v2/wallets request and filter by customer ID using q and the Lucene syntax, for example:
GET /ledger/v2/wallets?q=customerId:550e8400-e29b-41d4-a716-446655440000 AND status:ACTIVE
The above request returns all active wallets for your customer with ID 550e8400-e29b-41d4-a716-446655440000.
In the response, you receive the list with detailed information on each customer's wallet:
Response
{
"content": [
{
"id": "a:25041855293741:pWnL4vB:1",
"name": "USD Payroll",
"customer": {
"id": "c7a91d3e-48f2-4b76-a835-2e6d09f1c4b8",
"name": "Greenfield Logistics"
},
"status": "ACTIVE",
"balance": {
"amount": 125400.00,
"currency": "USD"
},
"createdAt": "2025-04-18T08:30:30.565Z",
"updatedAt": "2025-06-10T14:22:19.873Z"
},
{
"id": "a:25041855367892:xNcD8kT:1",
"name": "GBP Collections",
"customer": {
"id": "c7a91d3e-48f2-4b76-a835-2e6d09f1c4b8",
"name": "Greenfield Logistics"
},
"status": "ACTIVE",
"balance": {
"amount": 8730.50,
"currency": "GBP"
},
"createdAt": "2025-04-18T08:31:07.892Z",
"updatedAt": "2025-06-08T16:05:43.291Z"
},
{
"id": "a:25050742918604:tGn3KqW:1",
"name": "USDC Settlements",
"customer": {
"id": "c7a91d3e-48f2-4b76-a835-2e6d09f1c4b8",
"name": "Greenfield Logistics"
},
"status": "ACTIVE",
"balance": {
"amount": 2450.75,
"currency": "USDC"
},
"createdAt": "2025-05-07T11:21:58.604Z",
"updatedAt": "2025-06-09T19:14:32.117Z"
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 50
},
"hasNext": false
}
Receive status webhook
To get notified each time a wallet's status changes, listen to the wallet notification.
What's next?
Now that you have created a wallet, you can start sending and receiving payments.
- See the available use cases to select the one that best suits your needs.
- Configure a designated wallet for customer fees.