Create a Customer Wallet

These endpoints allow an Embedded Partner to create a fiat or crypto 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`	Code for fiat and crypto currency. fiat: `USD` `EUR` `GBP` crypto (not all cryptocurrencies may be supported, as this depends on the specific jurisdiction. For example, for USA you can use only BTC, SOL, ETH, USDT, USDC, TRX): `BCH` `SHIB` `DOGE` `USDT` `POL` `PYUSD` `ALGO` `DAI` `BTC` `SOL` `BNB` `XRP` `ETH` `LINK` `LTC` `USDC` `TRX` `ADA`
`paymentMethods`	`ACH` `ACH_SAME_DAY` (If you request an ACH Same Day payout outside its available window, it will be process as a next-day payout. However, the ACH Same Day fee may still be incurred) `FEDWIRE` `SWIFT` `FASTER_PAYMENT` `SEPA_CT` `SEPA_INST`

Query Parameters

Values

currencyCodes

Code for fiat and crypto currency.

fiat:
- USD
- EUR
- GBP
crypto (not all cryptocurrencies may be supported, as this depends on the specific jurisdiction. For example, for USA you can use only BTC, SOL, ETH, USDT, USDC, TRX):
- BCH
- SHIB
- DOGE
- USDT
- POL
- PYUSD
- ALGO
- DAI
- BTC
- SOL
- BNB
- XRP
- ETH
- LINK
- LTC
- USDC
- TRX
- ADA

paymentMethods

ACH
ACH_SAME_DAY (If you request an ACH Same Day payout outside its available window, it will be process as a next-day payout. However, the ACH Same Day fee may still be incurred)
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"
            ]
        }
    ]
}

 {
    "profiles": [
        {
            "reference": "18f9a1bf-0d77-45f5-b5ff-1e90411d88ce",
            "currencyCodes": [
                "USD"
            ],
            "paymentMethods": [
                "SWIFT"
            ]
        },
        {
            "reference": "a0b8a34c-bfb9-43d8-9ee4-6eb076d107c0",
            "currencyCodes": [
                "BTC",
                "SOL",
                "ETH",
                "USDT",
                "USDC",
                "TRX"
            ],
            "paymentMethods": []
        },
        {
            "reference": "2a3fe604-2b14-4009-90b3-1e48f1a38b11",
            "currencyCodes": [
                "USD"
            ],
            "paymentMethods": [
                "ACH",
                "FEDWIRE"
            ]
        },
        {
            "reference": "c143fce7-a0e4-4475-86cd-ed37bc30efa5",
            "currencyCodes": [
                "EUR"
            ],
            "paymentMethods": [
                "SWIFT"
            ]
        }
    ]
}

{
  "reference": "f7fdb837-5053-45b0-86c8-96ece6fe02d0",
  "currencyCodes": [
      "BCH",
      "USDT",
      "DOGE",
      "PYUSD",
      "POL",
      "DAI",
      "BTC",
      "SOL",
      "FDUSD",
      "BNB",
      "XRP",
      "ETH",
      "USDC",
      "LTC",
      "TRX",
      "ADA"
  ],
  "paymentMethods": []
}

{
  "reference": "a0b8a34c-bfb9-43d8-9ee4-6eb076d107c0",
  "currencyCodes": [
      "USDT",
      "BTC",
      "SOL",
      "ETH",
      "USDC",
      "TRX"
  ],
  "paymentMethods": []
}

Create a customer wallet

To create a customer fiat or crypto 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
    }
}

{
    "currencyCode": "USDT",
    "name": "USDT Test",
    "customerReference": "fb8c0b12-6552-429e-955e-70af08733310",
    "instruction": {
        "walletProfile": "f7fdb837-5053-45b0-86c8-96ece6fe02d0",
        "type": "CRYPTO",
        "virtualAccountRequired": false
    }
}

Parameter	Description
`currencyCode`	Currency code for the wallet.
`name`	Name of the wallet.
`customerReference`	Unique reference to the customer who owns the wallet.
`instruction`	Information on the wallet type.
`instruction.type`	Type of the wallet: fiat or crypto.
`instruction.walletProfile`	Profile to assign to the virtual account.
`instruction.virtualAccountRequired`	Indication 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": "fb8c0b12-6552-429e-955e-70af0873331",
    "name": "USD ",
    "status": "ACTIVE",
    "balance": {
        "value": 0.00,
        "currencyCode": "USD"
    },
    "ledgers": [
        {
            "type": "FIAT",
            "accountNumber": "900981800909",
            "code": "101019644",
            "accountNumberFormat": "ABA"
        }
    ]
}

{
    "id": "a:25065234155735:vE9Q6zE:1",
    "accountReference": "1274ab69-540c-4499-8b32-f51930c9bfed",
    "customerReference": "fb8c0b12-6552-429e-955e-70af08733310",
    "name": "USDT Test",
    "status": "ACTIVE",
    "balance": {
        "value": 0,
        "currencyCode": "USDT"
    },
    "ledgers": [
        {
            "address": "1BoatSLRHtKNngkdXEeobR76b53LETtpyT",
            "network": "Ethereum",
            "tag": "eth"
        }
    ]
}

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.