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`.