Step 2: Creating a Customer Wallet and Virtual Account
This endpoint allows you to create a wallet for a specific customer, generating a unique virtual account tied to the specific wallet. This virtual account serves as a tool for managing funds, and streamlining payment flows between your business, your customer, and their end-customers.
BETA endpoint
Please note that this endpoint is currently in beta, and it may undergo changes as we continue to improve and refine the functionality.
Idempotency supported endpoint
This means you can retry a request without worrying about it being processed multiple times.
To use this feature, add the
X-Idempotency-Key
header with a unique value (a UUID). This ensures the request is only processed once, even if it's sent multiple times.
Request:
Environment | Endpoint |
---|---|
Production | POST https://api.bvnk.com/ledger/v1/wallets |
Sandbox | POST https://api.sandbox.bvnk.com/ledger/v1/wallets |
curl --location 'https://api.sandbox.bvnk.com/ledger/v1/wallets' \
--header 'X-Idempotency-Key: cb26a411-0bf9-4920-a696-25eae38e1e33' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="vbfc61D890wg6LAAVbkR11qP9O6cXeMNmKWgcUNZaOHPiQeebp9cl6h02tWv84R8", ts="1728655672", nonce="ueLnt4", mac="rehhjPX0HgxvNgGNdwGS8EcIZRH8Y1pj4fClisKmWHE="' \
--data '{
"currencyCode": "GBP",
"name": "My GBP Wallet",
"customerReference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
"instruction": {
"type": "FIAT",
"virtualAccountRequired": true
}
}'
The details supplied to the wallet creation request.
Parameter | Type | Required | Description |
---|---|---|---|
currencyCode | String | Yes | The currency code for the wallet. |
name | String | Yes | The name of the wallet. |
customerReference | String | Yes | The unique reference to the customer who owns the wallet. |
instruction | Object | Yes | Contains the information on the wallet type. |
instruction. type | String | Yes | Type of the wallet. Currently supports FIAT only. |
instruction. virtualAccountRequired | Boolean | Yes | Indicates whether a virtual account is required. Currently supports true only. |
Response
Response code | Description |
---|---|
201 | Wallet created successfully. |
400 | Bad request. |
403 | Forbidden. |
{
"id": "a:24101151422432:gCl7SeI:1",
"accountReference": "ceb9400d-eee2-4cc0-89dc-1b3548f7291d",
"customerReference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
"name": "My GBP Wallet",
"status": "INACTIVE",
"balance": {
"value": 0,
"currencyCode": "GBP"
},
"ledgers": []
}
Response header: Location: https://api.sandbox.bvnk.com/ledger/v1/wallets/{id}
The id
of the created wallet will also be returned in a link via the response header
. By default the wallet will have 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 here.
Parameter | Type | Description |
---|---|---|
id | String | The unique wallet ID. |
accountReference | String | The account reference for this wallet. |
customerReference | String | The customer reference for this wallet. |
name | String | The wallet name. |
status | String | The status of the wallet. Possible values: - INACTIVE - ACTIVE |
balance | Object | Information about the available balance within the wallet. |
balance. value | Number | The available amount. |
balance. currencyCode | String | The currency of the wallet. |
ledgers | Object | Contains information about the ledger. |
ledgers. type | String | The type of ledger. Possible values: - FIAT - CRYPTO . |
ledgers. accountNumber | String | The account number. Example: GB25LHVB04030800071801 Will be provided only if ledgers.type = FIAT . |
ledgers. code | String | The account code. Example: LHVBGB2L .Will be provided only if ledgers.type = FIAT . |
ledgers. accountNumberFormat | String | Speficies the account number format. Possible values: - IBAN - SCAN - SWIFT - ABA - BBAN - CBIT .Will be provided only if ledgers.type = FIAT . |
ledgers. address | String | The crypto wallet address. Will be provided only if ledgers.type = CRYPTO . |
ledgers. network | String | The crypto wallet network/protocol. Will be provided only if ledgers.type = CRYPTO . |
ledgers. tag | String | The crypto wallet tag (where applicable). Will be provided only if ledgers.type = CRYPTO . |
Updated about 2 months ago