Sandbox LoginProduction LoginStatus Page
Quickstart Guides

Step 2: Creating a Customer Wallet and Virtual Account

Suggest Edits

This endpoint allows an Embedded Partner to create a wallet for a specific Embedded Partner 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 an Embedded Partner, their Embedded Partner Customer, and their end-customers.

🚧

Early Access

Please note that this endpoint is currently in early access, 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.


Assigning a wallet profile

First, list the possible Wallet Profiles to retrieve the Profile reference for your Customer wallet. Assign the Profile based on the currency and payment method of your wallet.

EnvironmentEndpoint
ProductionGET https://api.bvnk.com/ledger/v1/wallets/profiles
SandboxGET https://api.sandbox.bvnk.com/ledger/v1/wallets/profiles
Query ParametersValues
currencyCodesUSD
EUR
GBP
paymentMethodsACH
FEDWIRE
SWIFT
FASTER_PAYMENT
SEPA_CT
SEPA_INST
{
    "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"
            ]
        }
    ]
}

Creating a customer wallet with an assigned wallet profile

Request:

EnvironmentEndpoint
ProductionPOST https://api.bvnk.com/ledger/v1/wallets
SandboxPOST https://api.sandbox.bvnk.com/ledger/v1/wallets

Creating a Customer Wallet with an assigned Wallet Profile:

curl --location 'https://api.sandbox.bvnk.com/ledger/v1/wallets' \
--header 'X-Idempotency-Key: 2786f1cd-83cc-4509-9679-f65ee01244e8' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="****", ts="1743606409", nonce="ejE5G3", mac="kuNbdfp3/78MfR9y6E3hYrp72HGg7/zL69uNEBhNxfs="' \
--data '{
    "currencyCode": "USD",
    "name": "ACH/FEDWIRE test",
    "customerReference": "09c04f1b-77b2-42cc-a0c0-da9748a3be11",
    "instruction": {
        "walletProfile": "2a3fe604-2b14-4009-90b3-1e48f1a38b11",
        "type": "FIAT",
        "virtualAccountRequired": true
    }
}'

curl --location 'https://api.sandbox.bvnk.com/ledger/v1/wallets' \
--header 'X-Idempotency-Key: 460e169f-9055-42c4-85d1-268ca33ac030' \
--header 'Content-Type: application/json' \
--header 'Authorization: Hawk id="****", ts="1743604930", nonce="d1GDM9", mac="08Zdm1FAlJKWx8rC8miiGniDweHcvtZ4uXVRMVGxEYY="' \
--data '{
    "currencyCode": "USD",
    "name": "swift test",
    "customerReference": "09c04f1b-77b2-42cc-a0c0-da9748a3be11",
    "instruction": {
        "walletProfile": "18f9a1bf-0d77-45f5-b5ff-1e90411d88ce",
        "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.
walletProfile		StringNoThe profile you would like to assign to the virtual account.
instruction.
virtualAccountRequired		BooleanYesIndicates whether a virtual account is required. Currently supports true only.

Response

Response CodeDescription
201Wallet created successfully.
400Bad request.
403Forbidden.

{
    "id": "a:25032877416178:1PL2yxP:1",
    "accountReference": "5bc49988-fe25-408f-bccc-3e0fe96cf322",
    "customerReference": null,
    "name": "USD ",
    "status": "ACTIVE",
    "balance": {
        "value": 0.00,
        "currencyCode": "USD"
    },
    "ledgers": [
        {
            "type": "FIAT",
            "accountNumber": "900981800909",
            "code": "101019644",
            "accountNumberFormat": "ABA"
        }
    ]
}

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.

Updated about 1 month ago