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:

EnvironmentEndpoint
ProductionPOST https://api.bvnk.com/ledger/v1/wallets
SandboxPOST 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.

ParameterTypeRequiredDescription
currencyCodeStringYesThe currency code for the wallet.
nameStringYesThe name of the wallet.
customerReferenceStringYesThe unique reference to the customer who owns the wallet.
instructionObjectYesContains the information on the wallet type.
instruction.
type
StringYesType of the wallet. Currently supports FIAT only.
instruction.
virtualAccountRequired
BooleanYesIndicates whether a virtual account is required. Currently supports true only.

Response

Response codeDescription
201Wallet created successfully.
400Bad request.
403Forbidden.
{
    "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.

ParameterTypeDescription
idStringThe unique wallet ID.
accountReferenceStringThe account reference for this wallet.
customerReferenceStringThe customer reference for this wallet.
nameStringThe wallet name.
statusStringThe status of the wallet. Possible values:

- INACTIVE
- ACTIVE
balanceObjectInformation about the available balance within the wallet.
balance.
value
NumberThe available amount.
balance.
currencyCode
StringThe currency of the wallet.
ledgersObjectContains information about the ledger.
ledgers.
type
StringThe type of ledger. Possible values:

- FIAT
- CRYPTO.
ledgers.
accountNumber
StringThe account number. Example: GB25LHVB04030800071801

Will be provided only if ledgers.type = FIAT.
ledgers.
code
StringThe account code. Example: LHVBGB2L.

Will be provided only if ledgers.type = FIAT.
ledgers.
accountNumberFormat
StringSpeficies the account number format. Possible values:

- IBAN
- SCAN
- SWIFT
- ABA
- BBAN
- CBIT.Will be provided only if ledgers.type = FIAT.
ledgers.
address
StringThe crypto wallet address.

Will be provided only if ledgers.type = CRYPTO.
ledgers.
network
StringThe crypto wallet network/protocol.

Will be provided only if ledgers.type = CRYPTO.
ledgers.
tag
StringThe crypto wallet tag (where applicable).

Will be provided only if ledgers.type = CRYPTO.