Create a wallet
BVNK offers capabilities to create and manage crypto wallets directly from within the BVNK portal.
When you create a fiat wallet, it is not available right away. Before you can use it, request your Account Manager for the wallet verification.
Create a wallet
To create a wallet, do the following:
- API
- Portal
To create a fiat or crypto wallet with an assigned wallet profile, send the POST /ledger/v1/wallets request using the following parameters:
- ACH/FedWire Wallet Creation
- SWIFT Wallet Creation
- Crypto Wallet Creation
{
"currencyCode": "USD",
"name": "ACH/FEDWIRE test",
"customerReference": "09c04f1b-77b2-42cc-a0c0-da9748a3be11",
"instruction": {
"walletProfile": "2a3fe604-2b14-4009-90b3-1e48f1a38b11",
"type": "FIAT",
"virtualAccountRequired": true
}
}
| Parameter | Description |
|---|---|
currencyCode | Currency code for the wallet. |
name | Name of the wallet. |
customerReference | Unique reference to the customer who owns the wallet. |
instruction | Information on the wallet type. |
instruction.type | Type of the wallet: fiat or crypto. |
instruction.walletProfile | Profile to assign to the virtual account. |
instruction.virtualAccountRequired | Indication whether a virtual account is required. Currently supports true only. |
In the successful response, you get the details of the new wallet:
- Fiat Wallet
- Crypto Wallet
{
"id": "a:25032877416178:1PL2yxP:1",
"accountReference": "5bc49988-fe25-408f-bccc-3e0fe96cf322",
"customerReference": "fb8c0b12-6552-429e-955e-70af0873331",
"name": "USD ",
"status": "ACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": []
}
The id of the created wallet is returned in a link via response header: Location: https://api.sandbox.bvnk.com/ledger/v1/wallets/{id}.
By default the wallet has an INACTIVE status and should not be made available to the customer until it has been activated (ACTIVE status). The endpoint provided in the response header should be called periodically, to determine if the wallet has been activated as well as if a virtual account has been created and made available. See the Wallet Read API endpoint.
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. In case of a fiat wallet, the associated virtual account will be permanently closed with the banking partner.
Assign a wallet profile
To list the existing Wallet Profiles, send the GET /ledger/v1/wallets/profiles request using the following query parameters.
| Query Parameters | Values |
|---|---|
currencyCodes | Code for fiat and cryptocurrency. See the detailed list of supported currencies. |
paymentMethods | Payment methods available for the wallet. See the detailed list of payment methods. |
In the response, you get the Profile reference that you can assign to your customer's wallet based on the currency and payment method.
- Fiat Wallets
- Crypto Wallet (EU Entity)
- Crypto Wallet (US Entity)
{
"profiles": [
{
"reference": "bd72bff2-6842-4212-9aa3-9298597d7d6e",
"currencyCodes": [
"GBP"
],
"paymentMethods": [
"FASTER_PAYMENT"
]
},
{
"reference": "c143fce7-a0e4-4475-86cd-ed37bc30efa5",
"currencyCodes": [
"EUR"
],
"paymentMethods": [
"SWIFT"
]
},
{
"reference": "18f9a1bf-0d77-45f5-b5ff-1e90411d88ce",
"currencyCodes": [
"USD"
],
"paymentMethods": [
"SWIFT"
]
},
{
"reference": "2a3fe604-2b14-4009-90b3-1e48f1a38b11",
"currencyCodes": [
"USD"
],
"paymentMethods": [
"ACH",
"FEDWIRE"
]
},
{
"reference": "fe55d078-eaad-4c8b-a917-15170548df67",
"currencyCodes": [
"EUR"
],
"paymentMethods": [
"SEPA_CT",
"SEPA_INST"
]
}
]
}
Fetch wallets
The endpoint provides comprehensive information for each wallet, including status, balance, and other relevant details. This enables efficient monitoring and management of all payment channels linked to the customer, ensuring full operational visibility. You can list all wallets assigned to a customer and retrieve information for a specific wallet by providing its reference.
All wallets
To list all the wallets associated with a specific customer, send the GET /ledger/v1/wallets request.
In the response, you receive the detailed information on each wallet:
Response
{
"content": [
{
"id": "a:25061762277338:4nJVWl1:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
"name": "Jonsal",
"status": "ACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "Embedded customer A",
"accountNumber": "900768107004",
"code": "101019644",
"accountNumberFormat": "ABA",
"paymentReference": null
}
]
},
{
"id": "a:25061762217894:7kqBQY6:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "9ba4c65c-8c81-4e39-80b6-a803d9e66efd",
"name": "John Legend",
"status": "INACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": []
},
{
"id": "a:25061762124495:Sichkow:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "9ba4c65c-8c81-4e39-80b6-a803d9e66efd",
"name": "USD",
"status": "INACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": []
},
{
"id": "a:25060450775603:v28lmzW:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "Dave's Wallet",
"status": "ACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "EUR"
},
"ledgers": []
},
{
"id": "a:25052770895915:fQcLGMh:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
"name": "JL Wallet",
"status": "ACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "Embedded customer A",
"accountNumber": "900679904231",
"code": "101019644",
"accountNumberFormat": "ABA",
"paymentReference": null
}
]
},
{
"id": "a:25052256822125:xAWTzSB:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "USDC Wallet",
"status": "ACTIVE",
"balance": {
"value": 1106.71,
"currencyCode": "USDC"
},
"ledgers": []
},
{
"id": "a:25052233445967:xnrik2v:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "USDT Wallet",
"status": "ACTIVE",
"balance": {
"value": 120.50,
"currencyCode": "USDT"
},
"ledgers": []
},
{
"id": "a:25052137356562:qjOSsJf:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
"name": "USD Wallet NEW",
"status": "TERMINATED",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "Embedded customer A",
"accountNumber": "900072464417",
"code": "101019644",
"accountNumberFormat": "ABA",
"paymentReference": null
}
]
},
{
"id": "a:25051268495394:hNyZppE:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "Bitcoin Wallet Test account # 1",
"status": "INACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "BTC"
},
"ledgers": []
},
{
"id": "a:25042472328513:DjpwMfa:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
"name": "USD Wallet Test",
"status": "ACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "Embedded customer A",
"accountNumber": "900222018455",
"code": "101019644",
"accountNumberFormat": "ABA",
"paymentReference": null
}
]
},
{
"id": "a:25042460023997:xgImmdY:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "ETH Wallet",
"status": "INACTIVE",
"balance": {
"value": 0.23,
"currencyCode": "ETH"
},
"ledgers": []
},
{
"id": "a:25041166078335:oYJeFUK:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
"name": "USDT Wallet",
"status": "ACTIVE",
"balance": {
"value": 71.63,
"currencyCode": "USDT"
},
"ledgers": []
},
{
"id": "a:25040249187073:wR42W6d:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "USDC Wallet",
"status": "INACTIVE",
"balance": {
"value": 200.00,
"currencyCode": "USDC"
},
"ledgers": []
},
{
"id": "a:25040150970798:mGX7Twm:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "Wallet EUR",
"status": "INACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "EUR"
},
"ledgers": []
},
{
"id": "a:25031066969227:zFSl3Ea:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
"name": "USD Wallet 3",
"status": "ACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "Embedded Customer A",
"accountNumber": "900554317794",
"code": "101019644",
"accountNumberFormat": "ABA",
"paymentReference": null
}
]
},
{
"id": "a:25031066539770:Ia9mdf9:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "9ba4c65c-8c81-4e39-80b6-a803d9e66efd",
"name": "USD Wallet Customer B",
"status": "INACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": []
},
{
"id": "a:25030652262360:ewsQxR8:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
"name": "USD Wallet 2",
"status": "ACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "Embedded customer A",
"accountNumber": "900914731533",
"code": "101019644",
"accountNumberFormat": "ABA",
"paymentReference": null
}
]
},
{
"id": "a:25030559783181:81aaB4K:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "USD Swift",
"status": "ACTIVE",
"balance": {
"value": 137.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "System Pay Services Solutions Spain S.L.",
"accountNumber": "ES250182851098200007418",
"code": "BBVAESMMXXX",
"accountNumberFormat": "SWIFT",
"paymentReference": "REF-CL1CDC7"
}
]
},
{
"id": "a:25030558827793:LO8IHmy:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
"name": "USD Embedded Wallet",
"status": "ACTIVE",
"balance": {
"value": 872.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "Embedded customer A",
"accountNumber": "900012647634",
"code": "101019644",
"accountNumberFormat": "ABA",
"paymentReference": null
}
]
},
{
"id": "a:25030548796673:JtdGolN:1",
"accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
"customerReference": null,
"name": "USD Main Wallet",
"status": "INACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": [
{
"type": "FIAT",
"accountHolderName": "Commercial US",
"accountNumber": "900364186010",
"code": "101019644",
"accountNumberFormat": "ABA",
"paymentReference": null
}
]
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 20,
"sort": [],
"offset": 0,
"paged": true,
"unpaged": false
},
"last": false,
"totalElements": 23,
"totalPages": 2,
"first": true,
"size": 20,
"number": 0,
"sort": [],
"numberOfElements": 20,
"empty": false
}
Wallet by customer reference
To retrieve wallet details by customer reference, send the GET ledger/v1/wallets?customerReference={customerReference} request with the {customerReference} specified in the path.
In the response, you receive the list with detailed information on each customer wallet:
Response
{
"content": [
{
"id": "a:24101151618956:Xlfn0oR:1",
"accountReference": "ceb9400d-eee2-4cc0-89dc-1b3548f7291d",
"customerReference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
"name": "My USD Wallet",
"status": "INACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": []
},
{
"id": "a:24101151422432:gCl7SeI:1",
"accountReference": "ceb9400d-eee2-4cc0-89dc-1b3548f7291d",
"customerReference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
"name": "My USD Wallet 2",
"status": "INACTIVE",
"balance": {
"value": 0.00,
"currencyCode": "USD"
},
"ledgers": []
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 20,
"sort": [],
"offset": 0,
"paged": true,
"unpaged": false
},
"last": true,
"totalElements": 2,
"totalPages": 1,
"first": true,
"size": 20,
"number": 0,
"sort": [],
"numberOfElements": 2,
"empty": false
}
Wallet by Wallet ID
To retrieve wallet details by its unique identifier, send the GET ledger/v1/wallets/{id} request with the {id} specified in the path.
In the response, you receive the detailed information on the wallet:
Response
{
"id": "a:24101151422432:gCl7SeI:1",
"accountReference": "ceb9400d-eee2-4cc0-89dc-1b3548f7291d",
"customerReference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
"name": "My USD Wallet 2",
"status": "INACTIVE",
"balance": {
"value": 1000.00,
"currencyCode": "USD"
},
"ledgers": []
}
Wallet webhook
To get notified when the a new wallet is created, listen to the Ledger wallet creation notification.
What's next?
Now, when you have 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.