Create a Customer Wallet

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.


📘

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.

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

USD EUR GBP

paymentMethods

ACH FEDWIRE SWIFT FASTER_PAYMENT SEPA_CT SEPA_INST

In the response, you get the Profile reference that you can assign to your Customer's wallet based on the currency and payment method.

{
    "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"
            ]
        }
    ]
}

Create a customer wallet

To create a customer wallet with an assigned wallet profile, send the POST /ledger/v1/wallets request using the following parameters:

{
    "currencyCode": "USD",
    "name": "ACH/FEDWIRE test",
    "customerReference": "09c04f1b-77b2-42cc-a0c0-da9748a3be11",
    "instruction": {
        "walletProfile": "2a3fe604-2b14-4009-90b3-1e48f1a38b11",
        "type": "FIAT",
        "virtualAccountRequired": true
    }
}
{
    "currencyCode": "USD",
    "name": "swift test",
    "customerReference": "09c04f1b-77b2-42cc-a0c0-da9748a3be11",
    "instruction": {
        "walletProfile": "18f9a1bf-0d77-45f5-b5ff-1e90411d88ce",
        "type": "FIAT",
        "virtualAccountRequired": true
    }
}

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

String

No

The profile you would like to assign to the virtual account

instruction.
virtualAccountRequired

Boolean

Yes

Indicates whether a virtual account is required. Currently supports true only

In the successful response, you get the details of the new wallet:

{
    "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"
        }
    ]
}

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


What’s Next

After creating a wallet, you can get information about it or make your first transfer: