# BVNK API Documentation

> Complete API documentation for BVNK payment infrastructure—crypto payments, wallets, and financial services

This file contains all documentation content in a single document following the llmstxt.org standard.

## Charge customer fees

As a partner, you can add a markup fee to your customers' transactions, enabling you to collect additional revenue from your customers.

These customer fees (hereinafter, _customer fees_) are optional charges. They are separate from the transaction amount and transaction fees and are collected from your customer's wallet.

## Implement customer fees

To add a customer fee to a transaction, include the `customerFee` object in your API request:

```json Example Payload with customer Fee
{
    "type": "OUT",
     "fees": {
        "customerFee": {
            "currency": "USD",
            "amount": 1
        }
    }
}
```

The example use case for charging the customer fees may look as follows:

1. Send the [`GET /api/wallet`](../../api-explorer/endpoints/wallet-read) request to acquire the list of your existing wallets with details.

   In the response, find a wallet to which you plan to deposit fees and copy its `lsid` value.

   ```json Get wallets list
   [
       {
           "id": 3683091,
           "description": "USDC Wallet",
           "currency": {
               "id": 1773,
               "code": "USDC",
               "fiat": true,
               "icon": null,
               "name": "Euro",
               "withdrawalParameters": [],
               "options": {},
               "withdrawalFee": 0.4,
               "depositFee": 0,
               "supportsDeposits": true,
               "supportsWithdrawals": true,
               "quantityPrecision": 2,
               "pricePrecision": 5,
               "protocols": []
           },
           "lsid": "a:25041552279666:vpH2wtz:1",
           "status": "ACTIVE"
       }
   ]
   ```

   The selected wallet's currency should match the currency of the fees you are charging.

   You may use both fiat and crypto wallets, configuring an existing wallet or creating a new one for fees.
2. Designate the selected wallet as the fee destination by sending the [`PUT /platform/v1/fees/customer-fee-wallets`](../../api-explorer/endpoints/set-customer-fee-wallet) request. Include the following payload:
   ```json Example Request Payload
   {
       "destinationWalletId": "a:25041552279666:vpH2wtz:1",
       "currency": "USDC"
   }
   ```
   Here, "a:25041552279666:vpH2wtz:1" is `lsid` from step 1.
3. Check that your selected wallet can receive customer fees by sending the [`GET /platform/v1/fees/customer-fee-wallets`](../../api-explorer/endpoints/get-customer-fee-wallets) request.

   In the response, you receive the list of wallets that will be used for accepting customer fees. The wallet with the `lsid` specified earlier must be listed here.

   ```json Wallets to Accept customer Fees
   {
       "content": [
           {
               "destinationWalletId": "a:25041552279666:vpH2wtz:1",
               "currency": "USDC"
           },
           {
               "destinationWalletId": "a:38472618394521:kLm9xRs:1",
               "currency": "USDC"
           }
       ],
       "pageable": {
           "pageNumber": 0,
           "pageSize": 20,
           "sort": [],
           "offset": 0,
           "paged": true,
           "unpaged": false
       },
       "first": true,
       "last": true,
       "size": 20,
       "number": 0,
       "sort": [],
       "numberOfElements": 2,
       "empty": false
   }
   ```

   Now, your wallet is configured for receiving customer fees.
4. To apply the fee, when creating [payment requests](../../api-explorer/endpoints/payment-create), include the customer fee information in the `fees` object:
   <Tabs>
   <TabItem value="crypto" label="Crypto">
   ```json Example Payload with customer Fee for Crypto
   {
       "walletId": "a:25022613287255:zmHs0pg:1",
       "amount": 100,
       "currency": "USDC",
       "reference": "REF182597",
       "type": "OUT",
       "fees": {
           "customerFee": {
               "currency": "USDC",
               "amount": 1
           }
       }
   }
   ```
   </TabItem>
   <TabItem value="fiat" label="Fiat">

    ```json Example Payload with customer Fee for Fiat
    {
        "walletId": "a:24071743000626:go5SB1l:1",
        "amount": 1000,
        "currency": "USD",
        "reference": "REF182597",
        "method": "ACH",
        "fees": {
            "customerFee": {
                "amount": 0,
                "currency": "USD"
            }
        },
        "beneficiary": {
            "remittanceInformation": "Payment for services",
            "entity": {
                "type": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Dover",
                "dateOfBirth": "01-01-1980",
                "address": {
                    "addressLine1": "123 Main St",
                    "addressLine2": "Apt 4B",
                    "region": "California",
                    "city": "Los Angeles",
                    "country": "US",
                    "postCode": "90001"
                },
                "relationshipType": "SELF_OWNED"
            },
            "bankAccount": {
                "accountNumber": "2152209165",
                "accountType": "CHEQUE",
                "bank": {
                    "identificationCode": "CHASUS33",
                    "nid": "021000021",
                    "country": "US",
                    "address": {
                        "addressLine1": "383 MADISON AVENUE",
                        "region": "California",
                        "city": "New York",
                        "country": "US",
                        "postCode": "10001"
                    }
                }
            }
        }
    }
    ```
   </TabItem>
   </Tabs>

When implemented correctly, the fee-charging process works as follows:

1. The system calculates the total transaction amount (payment amount + customer fee)
2. During payment processing, the customer fee is:
   * Deducted from the customer's wallet.
   * Transferred to your designated fee wallet.
3. The full payment amount (excluding fees) is sent to the recipient

This approach ensures transparent fee management while maintaining accurate transaction accounting.

Here's an example of how the customer fee is calculated:

:::info 📘 Example calculation

When you receive the amount of $100 from customer Jane and charge a $0.50 partner's customer fee, Jane must have a minimum balance of $100.75 in her wallet (transaction amount $100 + BVNK fee $0.25 + customer fee $0.50). After a successful transaction,

* Jane's initial wallet balance was $100.75. The current balance is now $0.
* Amount credited to your designated fee wallet is $0.50.
:::

## Important considerations

* **Outgoing payments**: Currently, the customer fees are only supported for payment `type: OUT`.
  Make sure the customer's wallet has enough funds to cover the customer fee. If fees like network or customer fees cannot be covered, the transaction is cancelled.
* **Fee Structure**: Customer fees are implemented as a flat fee, a fixed predetermined price, per transaction.
* **Optional**: You are not required to charge customer fees. Transactions can be processed without additional fees if desired.

## Error handling

If the customer's wallet does not have enough funds for the customer fee, you have two options:

* Return an "insufficient funds" error to the user. In this case, the transaction is cancelled.
* Reduce the transaction amount to accommodate the fee. This ensures the total (transaction amount plus fee) does not exceed the available balance.

---

## Create a sandbox account

Before you can start building with BVNK's APIs, you'll need to create a sandbox account. The sandbox environment allows you to test your integration without using real funds or affecting production systems.

## Create your sandbox account

1. Go to [https://signup.sandbox.bvnk.com/create-dev-account](https://signup.sandbox.bvnk.com/create-dev-account).
2. Fill in the registration form with your details:
   - **Name**: Enter your first and last name.
   - **Work email**: Enter your primary email for account access. Addresses from public domains (like Gmail, Outlook, Yahoo, or Hotmail) are not permitted.
   - **Password**: Create a strong password for your account.
   - **Company name**: Enter your organization or company name.

3. Click **Sign Up** to proceed.

    ![BVNK Sandbox Signup Form](/img/bvnk/get-started/sign-up-sandbox.png)

4. Check your email inbox for a verification message from BVNK. If you don't see the email, check your spam or junk folder.
5. Copy the six-digit code from the email and enter it in the verification code field.

    ![Email Verification](/img/bvnk/get-started/confirm-email.png)

    Click **Continue** to complete the verification process.

    You'll be redirected to the sandbox portal dashboard.

Once verified, you'll have access to your sandbox dashboard. There, you can complete any additional company details if prompted. Your account is now ready for [API key generation](../generate-api-keys).

---

**Ready to start building?** Once your sandbox account is set up, you can:

- [Generate your API credentials](../generate-api-keys).
- [Create your first test wallet](../create-wallet).
- [Set up webhooks](../create-webhook-listener).

---

## Create wallets

BVNK offers the ability to create and manage both crypto and fiat wallets directly from within the BVNK portal, and via API. You can create wallets for your customers or for yourself. If you create a wallet for a customer, always specify the customer's ID and reference, otherwise the wallet is created for your own account.

![Wallet creation process](/img/bvnk/get-started/wallet-creation-flow.png)
{/*
```mermaid
%%{init: {'securityLevel': 'loose', 'themeVariables': {'clusterBkg': '#ffffff', 'clusterBorder': '#93c5fd', 'clusterTextColor': '#2563eb', 'lineColor': '#3b82f6', 'fontSize': '16px'}, 'flowchart': {'htmlLabels': true, 'useMaxWidth': false, 'padding': 8, 'rankSpacing': 36, 'nodeSpacing': 12, 'subGraphTitleMargin': {'top': 6, 'bottom': 14}}, 'themeCSS': ".cluster .cluster-label { font-size: 1.25rem !important; font-weight: 700 !important; fill: #2563eb !important; font-family: CircularXX, Inter, sans-serif !important; } .cluster .cluster-label span { font-size: 1.25rem !important; font-weight: 700 !important; color: #2563eb !important; font-family: CircularXX, Inter, sans-serif !important; } .cluster-label foreignObject, .cluster .cluster-label foreignObject { overflow: visible !important; } .cluster-label foreignObject > div, .cluster .cluster-label foreignObject > div { overflow: visible !important; }"}}%%
flowchart LR
  subgraph wf["Wallet Creation Flow"]
    direction LR
    S1["1. Request available wallet profiles and select one<code style='font-family:Consolas,ui-monospace,monospace'>GET /ledger/v2/wallets/profiles</code>"]
    S2["2. Pass the selected profile to create a wallet<code style='font-family:Consolas,ui-monospace,monospace'>POST /ledger/v2/wallets</code>"]
    S3["3. Receive wallet LSID in response and wait for wallet activation<code style='font-family:Consolas,ui-monospace,monospace'>&quot;id&quot;: &quot;a:2602136770550:lIlAoATM:1&quot;,</code><code style='font-family:Consolas,ui-monospace,monospace'>&quot;status&quot;: &quot;INACTIVE&quot;</code>"]
    S1 --> S2 --> S3
  end
  subgraph wh["Webhooks sent"]
    S4["4. The wallet gets activated and the webhook is sent<code style='font-family:Consolas,ui-monospace,monospace'>&quot;event&quot;: &quot;bvnk:ledger:wallet:create&quot;</code>"]
  end
  S3 -.-> S4

  classDef stepBox fill:#eff3fe,stroke:#cfe0ff,stroke-width:1px,color:#374151
  class S1,S2,S3,S4 stepBox

  linkStyle 0 stroke:#3b82f6,stroke-width:1.5px
  linkStyle 1 stroke:#3b82f6,stroke-width:1.5px
  linkStyle 2 stroke:#3b82f6,stroke-width:1.5px,stroke-dasharray:6 4
``` */}

## Retrieve wallet profiles

Before adding a wallet to your account, you must assign a wallet profile to it. The wallet profile is a template that defines the currency codes and payment methods available for a wallet.

To list the existing wallet profiles, send the [`GET /ledger/v2/wallets/profiles`](../../api-explorer/endpoints/wallet-profiles-2/) request. You can filter results with the optional `q` query parameter using [Lucene query syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html), for example `currency:USD`, `method:SWIFT`, or `customerId:550e8400-e29b-41d4-a716-446655440000 AND currency:USD`.

| Query parameter | Description |
| :--- | :--- |
| `q` | Optional search and filter expression. You can filter by:<code>currency</code>: see the list of supported currencies.<code>method</code>: see payment methods; values include <code>ACH</code>, <code>ACH_SAME_DAY</code>, <code>FEDWIRE</code>, <code>SWIFT</code>, <code>FASTER_PAYMENT</code>, <code>SEPA_CT</code>, <code>SEPA_INST</code>.<code>customerId</code>: Unique identifier for the customer in the form of a UUID. |

In the response, each profile has an `id` that you pass as  a "profileId" when you [create a wallet](#create-a-wallet-with-a-profile). Available currencies and methods depend on your account and jurisdiction.

<Tabs>
  <TabItem value="Wallet profiles">

  ```json Example response (wallet profiles)
  {
    "content": [
      {
        "id": "fiat:gbp:abcd1234",
        "currencies": ["GBP"],
        "methods": ["FASTER_PAYMENT"]
      },
      {
        "id": "fiat:eur:efgh5678",
        "currencies": ["EUR"],
        "methods": ["SWIFT"]
      },
      {
        "id": "fiat:usd:ijkm9012",
        "currencies": ["USD"],
        "methods": ["SWIFT"]
      },
      {
        "id": "fiat:usd:nlop3456",
        "currencies": ["USD"],
        "methods": ["ACH", "FEDWIRE"]
      },
      {
        "id": "fiat:qrst7890",
        "currencies": ["EUR"],
        "methods": ["SEPA_CT", "SEPA_INST"]
      },
      {
        "id": "crypto:custodial:uvxz1234",
        "currencies": [
          "USDT",
          "PYUSD",
          "POL",
          "BTC",
          "SOL",
          "BNB",
          "XRP",
          "ETH",
          "USDC",
          "USDG",
          "LTC",
          "TRX"
        ],
        "methods": []
      }
    ],
    "totalPages": 1
  }
  ```

</TabItem>
<TabItem value="Single profile (excerpt)">
  ```json One profile object from content[]
  {
    "id": "crypto:custodial:uvxz1234",
    "currencies": [
      "USDT",
      "PYUSD",
      "POL",
      "BTC",
      "SOL",
      "BNB",
      "XRP",
      "ETH",
      "USDC",
      "USDG",
      "LTC",
      "TRX"
    ],
    "methods": []
  }
  ```
</TabItem>
</Tabs>

## Create a wallet with a profile

To create a wallet, do the following:

<Tabs queryString="wallet-creation">
  <TabItem value="API" label="API">

    To create a fiat or crypto wallet with an [assigned wallet profile](#create-a-wallet-with-a-profile), send the [`POST /ledger/v2/wallets`](../../api-explorer/endpoints/ledger-wallet-create-v-2) request with a JSON body like the following. Use the `id` from [`GET /ledger/v2/wallets/profiles`](../../api-explorer/endpoints/wallet-profiles-2/) as `profileId`.

  <Tabs>
    <TabItem value="Direct fiat wallet">
        ```json
        {
            "currency": "USD",
            "name": "Swift Wallet",
            "profileId": "fiat:usd:ijkm9012"
        }
        ```
    </TabItem>
    <TabItem value="Fiat wallet for a customer">
        ```json
        {
            "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "currency": "USD",
            "name": "ACH/FEDWIRE test",
            "profileId": "fiat:usd:nlop3456"
        }
        ```
    </TabItem>
    <TabItem value="Crypto wallet for a customer">
        ```json
        {
            "customerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "currency": "USDT",
            "name": "USDT Test",
            "profileId": "crypto:custodial:uvxz1234"
        }
      ```
    </TabItem>
  </Tabs>

    | Parameter           | Required           | Description       |
    | :------------------ | :------------- | :-------|
    | `customerId`        |                | Unique identifier for the customer. Required if you create a wallet for your customer.               |
    | `currency`          | :white_check_mark: | Currency code for the wallet.                                                           |
    | `name`              | :white_check_mark:     |  Display name for the wallet.  |
    | `profileId`   | :white_check_mark:       |  Wallet profile `id` from [`GET /ledger/v2/wallets/profiles`](../../api-explorer/endpoints/wallet-profiles-2/).  |

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

    <Tabs>
      <TabItem value="Fiat Wallet">

        ```json Example Response for fiat wallet
        {
            "id": "a:26021236770550:llAoATM:1",
            "customer": {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "name": "My Wallet"
            },
            "status": "ACTIVE",
            "balance": {
                "amount": 0,
                "currency": "EUR"
            },
            "ledgers": [],
            "capabilities": {
                "safeguarded": true,
                "currencyType": "FIAT"
            }
        }
        ```

      </TabItem>
      <TabItem value="Crypto Wallet">

        ```json Example Response for crypto wallet
        {
            "id": "a:26021236770551:mmBoATM:1",
            "customer": {
                "id": "550e8400-e29b-41d4-a716-446655440000",
                "name": "BTC Wallet"
            },
            "status": "ACTIVE",
            "balance": {
                "amount": 0,
                "currency": "BTC"
            },
            "ledgers": [],
            "capabilities": {
                "safeguarded": true,
                "currencyType": "CRYPTO"
            }
        }
        ```

      </TabItem>
    </Tabs>

    The `id` of the created wallet is returned in a `Location` response header, for example `https://api.sandbox.bvnk.com/ledger/v2/wallets/{id}`.

    Wallets are not created immediately: a new wallet often appears as `INACTIVE` first , from there it automatically transitions to an `ACTIVE` state. The activation process can take several minutes. Poll [`GET /ledger/v2/wallets/{id}`](../../api-explorer/endpoints/ledger-wallet-read-v-2) or use the webhooks rather than creating duplicate wallets if activation is slow.

    When the wallet is created, the `ledgers` array is empty and the `balance` is `0`. The `ledgers` array will be populated with the  details after the wallet is activated and the [webhook is received](#receive-the-webhook).

    The wallet can also have the `TERMINATED` status. This means the wallet can no longer be used, and that state is final; BVNK can never reactivate it. All operations, including receiving pay-ins, sending payouts, and currency conversions, are blocked for the terminated wallets. You can only access its transaction history. In case of a **fiat wallet**, the associated virtual account will be permanently closed with the banking partner. To learn how to terminate a wallet, see the [Manage wallets](../manage-wallet) guide.

  </TabItem>

  <TabItem value="Portal" label="Portal">

    1. On the BVNK Portal, go to **Wallets** and click **Add Wallet**.
      ![](/img/bvnk/get-started/add-wallet-button.png)
    2. Select the currency, insert a unique name for this wallet and click **Create Wallet**.

        ![](/img/bvnk/get-started/create-wallet-form.png)

    The newly created wallet appears on the portal. If you click on the wallet, you can see the actions you can take on it.

    ![](/img/bvnk/get-started/wallet-created-list.png)

    :::info
    When you get portal access to your production BVNK account, fiat wallets will be automatically assigned to you during the onboarding process.
    :::

  </TabItem>
</Tabs>

## Retrieve wallets

Use the wallet endpoints to monitor status and balances. **`GET /ledger/v2/wallets` returns summaries only and does not include `ledgers`.** Full ledger and account details are returned by **`GET /ledger/v2/wallets/{id}`** for a single wallet.

### All wallets

To list all wallets, send the [`GET /ledger/v2/wallets`](../../api-explorer/endpoints/ledger-wallet-list-v-2) request.

The list response returns wallet summaries without `ledgers`. For ledgers and full account details, call [`GET /ledger/v2/wallets/{id}`](../../api-explorer/endpoints/ledger-wallet-read-v-2) with that wallet's `{id}`.

<details>
  <summary>Response</summary>
```json Response
{
  "content": [
    {
      "id": "a:25103169967870:RktIDUt:1",
      "customer": {
        "id": "d9a5465b-1f77-4113-87f7-c8290d2dd178",
        "name": "Some Wallet Name"
      },
      "status": "ACTIVE",
      "balance": {
        "amount": 9714.04,
        "currency": "USD"
      },
      "capabilities": {
        "safeguarded": false,
        "currencyType": "FIAT"
      }
    },
    {
      "id": "a:25103169967871:Qr7mK2a:1",
      "customer": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Acme Treasury"
      },
      "status": "INACTIVE",
      "balance": {
        "amount": 1304.0,
        "currency": "EUR"
      },
      "capabilities": {
        "safeguarded": true,
        "currencyType": "FIAT"
      }
    },
    {
      "id": "a:25103169967872:Tm2Lx8p:1",
      "customer": {
        "id": "4aa1b63f-8db2-4db9-a33e-8dbf7d5aa7d8",
        "name": "Northwind Operations"
      },
      "status": "INACTIVE",
      "balance": {
        "amount": 0.2571,
        "currency": "BTC"
      },
      "capabilities": {
        "safeguarded": false,
        "currencyType": "CRYPTO"
      }
    },
    {
      "id": "a:25103169967873:Ym9Vn4c:1",
      "customer": {
        "id": "2b54d745-e0dd-4ea8-97aa-df2cb9dbe203",
        "name": "Contoso Retail"
      },
      "status": "TERMINATED",
      "balance": {
        "amount": 0.0,
        "currency": "USDT"
      },
      "capabilities": {
        "safeguarded": true,
        "currencyType": "CRYPTO"
      }
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "hasNext": false
}
```
</details>

### Specific wallet

To retrieve wallet details by its unique identifier, send the [`GET /ledger/v2/wallets/{id}`](../../api-explorer/endpoints/ledger-wallet-read-v-2) request with the `{id}` specified in the path.

In the response, you receive full wallet details, including ledgers:

<Tabs>
  <TabItem value="Crypto" label="Crypto">

  ```json Response
  {
    "id": "a:26021236770551:mmBoATM:1",
    "customer": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Wallet"
    },
    "status": "ACTIVE",
    "balance": {
      "amount": "100.00",
      "currency": "BTC"
    },
    "ledgers": [
      {
        "type": "CRYPTO",
        "address": "tb1qk56vqrp9pzesjwf599mlqwzc7a6scwgq3y2ee6",
        "network": "BTC"
      }
    ],
    "capabilities": {
      "safeguarded": false,
      "currencyType": "CRYPTO"
    }
  }
  ```

  </TabItem>
  <TabItem value="Fiat" label="Fiat">

  ```json Response
  {
    "id": "a:26021236770550:llAoATM:1",
    "customer": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "My Wallet"
    },
    "status": "ACTIVE",
    "balance": {
      "amount": 1500.5,
      "currency": "EUR"
    },
    "ledgers": [
      {
        "type": "FIAT",
        "accountHolderName": "System Pay Services (Malta) Limited",
        "accountNumber": "DE10601202004579784373",
        "accountNumberFormat": "SWIFT",
        "paymentReferenceRequiredPrefix": "REF",
        "bank": {
          "identificationCode": "BBVAESMMXXX",
          "name": "Banco Bilbao Vizcaya Argentaria, S.A.",
          "address": {
            "street": "De San Nicolas 4",
            "city": "Bilbao",
            "country": "ES",
            "postalCode": "48005"
          }
        }
      }
    ],
    "capabilities": {
      "safeguarded": true,
      "currencyType": "FIAT"
    }
  }
  ```

  </TabItem>
</Tabs>
### Customer's wallets

To retrieve wallets for a specific customer, send the [`GET /ledger/v2/wallets`](../../api-explorer/endpoints/ledger-wallet-list-v-2) request and filter by customer ID using `q` and the Lucene syntax, for example:

```http
GET /ledger/v2/wallets?q=customerId:550e8400-e29b-41d4-a716-446655440000 AND status:ACTIVE
```

The above request returns all **active** wallets for your customer with ID `550e8400-e29b-41d4-a716-446655440000`.

In the response, you receive the list with detailed information on each customer wallet:

<details>
  <summary>Response</summary>
```json Response
{
  "content": [
    {
      "id": "a:25103169967870:RktIDUt:1",
      "customer": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "USD Wallet"
      },
      "status": "ACTIVE",
      "balance": {
        "amount": 9714.04,
        "currency": "USD"
      },
      "capabilities": {
        "safeguarded": false,
        "currencyType": "FIAT"
      }
    },
    {
      "id": "a:25103169967874:Pu3Nd8e:1",
      "customer": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Another Wallet"
      },
      "status": "ACTIVE",
      "balance": {
        "amount": 2450.75,
        "currency": "EUR"
      },
      "capabilities": {
        "safeguarded": true,
        "currencyType": "FIAT"
      }
    },
    {
      "id": "a:25103169967875:Zk6Qm1t:1",
      "customer": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Crypto Wallet"
      },
      "status": "ACTIVE",
      "balance": {
        "amount": 518.12,
        "currency": "USDT"
      },
      "capabilities": {
        "safeguarded": true,
        "currencyType": "CRYPTO"
      }
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 10
  },
  "hasNext": false
}
```
</details>

## Receive the webhook

To get notified when the a new wallet is created, listen to the [Ledger wallet creation notification](../../api-explorer/bvnk-webhooks/ledger-wallet-create).

---

**What's next?**

Now you have created a wallet, you can start sending and receiving payments.

- See the available [use cases](find-your-usecase.mdx) to select the one that best suits your needs.
- Configure a designated wallet for [customer fees](charge-customer-fees.mdx).

---

## Configure webhooks

Webhooks provide real-time, automated notifications for changes in your BVNK account.

Configure them for key events, including:

* Pay-ins received
* Payouts sent
* Refunds initiated
* Transaction status changes

This capability is essential for automating your workflows. For example, you can instantly credit a customer's wallet when a successful deposit webhook is received, eliminating the need for manual confirmation in the BVNK Portal.

For the detailed description list of webhooks, see the [Webhooks API Reference](../../api-explorer/bvnk-webhooks/bvnk-webhooks-api).

:::tip
Most of the webhook events are enabled by default. However, you may need to contact the BVNK Solutions team to enable the following events:

- [bvnk:payment:channel:transaction-on-hold](../../api-explorer/bvnk-webhooks/channel-transaction-on-hold/)
- [bvnk:payment:crypto:transaction-on-hold](../../api-explorer/bvnk-webhooks/crypto-transaction-on-hold/)
:::

## Create webhooks

To create a webhook, do the following:

1. Log in to the BVNK Portal.
2. On the sidebar, click **Integrations**, go to the **Webhooks** tab, and click **Add webhook**.

   ![](/img/bvnk/get-started/webhook-add-button.png)
3. In the **Add new webhook** dialogue, specify the following webhook settings:

   * **Description**: Provide a short, meaningful description for the webhook.
   * **Webhook URL to receive events**: Enter the Webhook URL to which the events will be sent.
   * **Events to send**: Select the events to send from the list provided.

   ![](/img/bvnk/get-started/webhook-events-selection.png)

   Here, you can select events for operations related to fiat and crypto.
4. Click **Add**.

The new active webhook appears in the list of webhooks where you can now manage the configuration going forward.

You're all set. You will receive webhooks containing the details of the event to which you have subscribed.

Also, see a [product demo](https://www.loom.com/share/801769cf55b649a5948590d13ede26bf?sid=b59e8813-49a4-4044-9327-867916088fd1) or read more in the [Help Centre article](https://help.bvnk.com/hc/en-us/articles/22943700946450-Webhook-Configuration-in-the-BVNK-Portal).

:::tip No strict serialisation
Do not strictly serialise the webhook fields that you do not need. Only apply the fields that you use in your platform.

For example, if you do not need the `metadata` field, you can omit it from the response.
:::

## Update webhooks

After you create a webhook, you can change its parameters, name or events.

1. Go to **Integration** > **Webhooks** and find the webhook you want to update.
2. In the selected webhook line, click three dots and click **Edit**.

   ![](/img/bvnk/get-started/webhook-edit.png)

   The **Update webhook** screen appears.
3. Change webhook parameters, for example, you can update its description or add and remove events.
4. Click **Update**.

***
<!--
## Explore available webhooks

You can subscribe to the following webhooks depending on your use case:

| Event Name | Triggered when | Relevant Documentation |
| :--- | :--- | :--- |
| **STATUS CHANGE WEBHOOKS** |  |  |
| `bvnk:payment:payin:status-change` | Status of an incoming fiat payment changes | [Fiat Pay-ins](../../use-cases/unprocessed/enable-pay-in-notifications) |
| `bvnk:payment:payout:status-change` | Status of an outgoing fiat payment changes | [Fiat Payouts](../../use-cases/unprocessed/enable-payout-notifications) |
| `bvnk:payment:transfer:status-change` | Status of an internal payment transfer changes | [Internal Transfers](../../use-cases/unprocessed/enable-internal-transfers-notifications) |
| **CHANNEL WEBHOOKS** |  |  |
| `bvnk:payment:channel:transaction-on-hold` | Channel transaction is placed on hold | [Transaction on Hold](../../use-cases/stablecoin-payments-for-platforms/exception-scenarios#transaction-on-hold) |
| `bvnk:payment:channel:transaction-detected` | Channel transaction is detected | [Transaction Detected and Confirmed](../../use-cases/stablecoin-payments-for-platforms/exception-scenarios#transaction-detected-and-confirmed) |
| `bvnk:payment:channel:transaction-confirmed` | Channel transaction is confirmed | [Transaction Detected and Confirmed](../../use-cases/stablecoin-payments-for-platforms/exception-scenarios#transaction-detected-and-confirmed) |
| **CRYPTO WEBHOOKS** |  |  |
| `bvnk:payment:crypto:refund-initiated` | Cryptocurrency payment refund is initiated | [Crypto Refunds](../../use-cases/stablecoin-payments-for-platforms/exception-scenarios#refund-initiated) |
| `bvnk:payment:crypto:transaction-late` | Cryptocurrency transaction is marked as late | [Transaction Late](../../use-cases/stablecoin-payments-for-platforms/exception-scenarios#transaction-late) |
| `bvnk:payment:crypto:transaction-settled` | Cryptocurrency transaction is settled | [Transaction Settlement](../../use-cases/stablecoin-payments-for-platforms/exception-scenarios) |
| `bvnk:payment:crypto:status-change` | Status of a cryptocurrency payment changes | * [Crypto Pay-ins](../../use-cases/stablecoin-payments-for-platforms/get-payment-overview)
|[Crypto Payouts](../../use-cases/stablecoin-payments-for-platforms/payout-overview) |
| `bvnk:payment:crypto:transaction-on-hold` | Cryptocurrency transaction is placed on hold | [Transaction on Hold](../../use-cases/stablecoin-payments-for-platforms/exception-scenarios#transaction-on-hold) |
| `bvnk:payment:crypto:transaction-confirmed` | Cryptocurrency transaction is confirmed | Transaction Confirmation |
| `bvnk:payment:crypto:transaction-detected` | Cryptocurrency transaction is detected | Transaction Detection |
| **CUSTOMER WEBHOOKS** |  |  |
| `bvnk:platform:customer:agreement-session-status-change` | Customer agreement session status changes | [Prepare Customer Agreements](../create-embedded-partner-customer/signing-customer-agreements) |
| `bvnk:platform:customer:status-change` | Customer's status changes | [Create a Customer via API](../create-embedded-partner-customer/creating-an-embedded-customer-company-api) |
| `bvnk:platform:customer:update` | Customer information is updated | [Create a Customer via API](../create-embedded-partner-customer/creating-an-embedded-customer-company-api) |
| `bvnk:platform:customer:document-status-change` | Customer document verification status changes | [Add Documents to Customers](../create-embedded-partner-customer/add-documents-to-customers) |
| `bvnk:platform:customer:questionnaire-status-change` | Customer questionnaire status changes | [Customer Questionnaires](../create-embedded-partner-customer/onboard-epc) |
| **LEDGER WEBHOOKS** |  |  |
| `bvnk:ledger:wallet:create` | New wallet is created in the ledger | [Enable Wallet Creation Notifications](../../use-cases/unprocessed/enable-wallet-creation-notifications) |
| `bvnk:ledger:report:ready` | Ledger report is ready for download | [Receive Transactions Report via Webhook](../receive-transactions-report-via-webhook) |
 -->

## Create webhook listener

BVNK sends webhooks for changes on transactions and other entities, so it's a good idea to set up a listener in your service to get the most out of our Payments API.

Webhooks are sent as an HTTP POST with `Content-Type: application/json` containing the payload of the object.

:::warning Important notes

* Always check the status of the payment on the API after you receive a webhook, as further details may be required, such as the final amount paid for the transaction about which you have been notified.
* After you receive the final webhook from BVNK, do not update transactions in your system to prevent duplicate transaction IDs from affecting your customers
:::

### Acknowledge events

BVNK expects the `200` status code upon receipt of a successfully sent webhook.

If your webhook script performs any logic after receiving a webhook, to prevent timeouts, you should return a `200` status code before completing the logic.

### Webhook retry policy

If BVNK does not receive a `200` status code, the webhook retry policy will kick in. This includes cases where the endpoint returns a non-2xx status code or fails to respond within the **10-second** timeout window. After 10 seconds without a successful response, the delivery attempt is considered failed and will trigger the retry process defined by the webhook policy.

The retry policy adds a delay before each retry, starting with a base delay and increasing it with each retry. The delay grows larger after each attempt, but will not exceed 15 minutes. The system will attempt up to 100 times, and after that, no further retries will occur.

To ensure safe and consistent processing, all webhook events include a unique identifier that receivers should use to implement idempotency. This prevents duplicate event handling if the same webhook is retried multiple times due to timeouts or failed responses. The receiving system should detect repeated event IDs and avoid performing the same business action more than once.

### Handle duplicate events

Callback endpoints might occasionally receive the same event more than once. We advise you to guard against duplicate event receipts. One way to do this is to log the events you've processed and then exclude the logged ones from further processing.

### Validate webhooks

The webhook also contains a signature to allow servers to verify the authenticity of the request using a server-side secret key. The key is displayed in the field Public Key when you create the hook. The signature is present in the headers as the `x-signature` header. See the examples for different languages below.
<!--
To calculate the signature, do the following:

1. Get the payload of the webhook.
2. Obtain the secret key: go to **Manage Account** > **Manage Merchants**, and click a Merchant Name to open its details.

![](/img/bvnk/get-started/secret-key-management.png)

3. Generate the signature using the Secret Key and payload components. See the examples for different languages below.

    :::note

      Some legacy webhooks may still require concatenation of the following items to create a signature:

        * Webhook URL
        * `content-type`
        * Webhook payload

        Note that these webhooks will be soon discontinued.
    ::: -->

<Tabs>
<TabItem value="Java">

    ```java

    public class Main {

      public static void main(String[] args) throws Exception {
        // Secret key from webhook configuration (used as string directly, not Base64 decoded)
        String secretKey = "JUL5QkQrpZYwW+Kf03QSrb70CG+ea/j8E/JfslENaXhd0AGBDbAtYYP2MdjkYDqiwjBtrtQXsUIbtAf7IGEGfg==";

        // From X-Signature header
        String signatureBase64 = "VWEtiJu/7dLrq0ZtXS0HbGDPy6Re86oZeTnEEc9mlxg=";

        // Compact JSON payload (no spaces/newlines) - this is what the hook service signs
        String payload = "{\"event\":\"bvnk:ledger:report:ready\",\"eventId\":\"0198a8bb-7d56-79ef-92b2-2aed247c21b4\",\"timestamp\":\"2025-08-14T13:18:36.374620938Z\",\"data\":{\"id\":\"8d942264-e27e-44d9-a048-5ed66ac5129f\",\"url\":\"https://bvnk-staging-reports.s3.eu-west-1.amazonaws.com/transaction/8d942264-e27e-44d9-a048-5ed66ac5129f_7b2f87b9-1335-4b1e-bbeb-6a59ba1dc6df.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250814T131836Z&X-Amz-SignedHeaders=host&X-Amz-Credential=AKIAZP6R7NJUFAGFGMNA%2F20250814%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=5c861e552b3e253be28f8e02c818b3c5e00269b9b50b6d4957d5281825d31a67\",\"type\":\"TRANSACTION\",\"status\":\"READY\"}}";

        // Use secret key as UTF-8 bytes directly (as hook service does)
        byte[] secretKeyBytes = secretKey.getBytes("UTF-8");
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKeyBytes, "HmacSHA256");

        // Initialize HMAC signature verification
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(secretKeySpec);

        // Generate signature for the payload
        byte[] computedSignature = mac.doFinal(payload.getBytes());
        String computedSignatureBase64 = java.util.Base64.getEncoder().encodeToString(computedSignature);

        // Decode received signature
        byte[] receivedSignature = java.util.Base64.getDecoder().decode(signatureBase64);

        // Verify signatures match
        boolean verified = Arrays.equals(computedSignature, receivedSignature);

      System.out.println("Expected signature: " + computedSignatureBase64);
      System.out.println("Received signature: " + signatureBase64);
      System.out.println("Signature is valid: " + verified);
    }
    }
    ```

</TabItem>
<TabItem value="Python">

    ```python
    #!/usr/bin/env python3
    """
    BVNK Webhook Signature Verification - Python
    This script verifies HMAC-SHA256 signatures from BVNK webhook payloads.
    """

    def verify_webhook_signature(secret_key, payload, signature_base64):
        """
        Verify HMAC-SHA256 signature for webhook payload

        Args:
            secret_key (str): The shared secret from webhook configuration
            payload (str): The JSON payload as received in webhook
            signature_base64 (str): The signature from X-Signature header

        Returns:
            bool: True if signature is valid, False otherwise
        """
        # Convert secret key to bytes using UTF-8 encoding
        secret_bytes = secret_key.encode('utf-8')

        # Convert payload to bytes using UTF-8 encoding
        payload_bytes = payload.encode('utf-8')

        # Generate HMAC-SHA256 signature
        computed_signature = hmac.new(
            secret_bytes,
            payload_bytes,
            hashlib.sha256
        ).digest()

        # Base64 encode the computed signature
        computed_signature_base64 = base64.b64encode(computed_signature).decode('ascii')

        # Decode the received signature
        received_signature = base64.b64decode(signature_base64)

        # Compare signatures using constant-time comparison
        return hmac.compare_digest(computed_signature, received_signature)

    def main():
        # Secret key from webhook configuration (used as string directly)
        secret_key = "JUL5QkQrpZYwW+Kf03QSrb70CG+ea/j8E/JfslENaXhd0AGBDbAtYYP2MdjkYDqiwjBtrtQXsUIbtAf7IGEGfg=="

        # From X-Signature header
        signature_base64 = "VWEtiJu/7dLrq0ZtXS0HbGDPy6Re86oZeTnEEc9mlxg="

        # Compact JSON payload (no spaces/newlines) - this is what the hook service signs
        payload = '{"event":"bvnk:ledger:report:ready","eventId":"0198a8bb-7d56-79ef-92b2-2aed247c21b4","timestamp":"2025-08-14T13:18:36.374620938Z","data":{"id":"8d942264-e27e-44d9-a048-5ed66ac5129f","url":"https://bvnk-staging-reports.s3.eu-west-1.amazonaws.com/transaction/8d942264-e27e-44d9-a048-5ed66ac5129f_7b2f87b9-1335-4b1e-bbeb-6a59ba1dc6df.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250814T131836Z&X-Amz-SignedHeaders=host&X-Amz-Credential=AKIAZP6R7NJUFAGFGMNA%2F20250814%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=5c861e552b3e253be28f8e02c818b3c5e00269b9b50b6d4957d5281825d31a67","type":"TRANSACTION","status":"READY"}}'

        # Verify the signature
        is_valid = verify_webhook_signature(secret_key, payload, signature_base64)

        # For debugging - compute expected signature
        secret_bytes = secret_key.encode('utf-8')
        payload_bytes = payload.encode('utf-8')
        computed_signature = hmac.new(secret_bytes, payload_bytes, hashlib.sha256).digest()
        expected_signature_base64 = base64.b64encode(computed_signature).decode('ascii')

        print(f"Expected signature: {expected_signature_base64}")
        print(f"Received signature: {signature_base64}")
        print(f"Signature is valid: {is_valid}")

    if __name__ == "__main__":
        main()
    ```

</TabItem>
<TabItem value="PHP">

  ```php
  <?php
  /**
  * BVNK Webhook Signature Verification - PHP
  * This script verifies HMAC-SHA256 signatures from BVNK webhook payloads.
  */

  /**
  * Verify HMAC-SHA256 signature for webhook payload
  *
  * @param string $secretKey The shared secret from webhook configuration
  * @param string $payload The JSON payload as received in webhook
  * @param string $signatureBase64 The signature from X-Signature header
  * @return bool True if signature is valid, false otherwise
  */
  function verifyWebhookSignature($secretKey, $payload, $signatureBase64) {
      // Generate HMAC-SHA256 signature using the secret key as UTF-8 bytes
      $computedSignature = hash_hmac('sha256', $payload, $secretKey, true);

      // Base64 encode the computed signature
      $computedSignatureBase64 = base64_encode($computedSignature);

      // Decode the received signature
      $receivedSignature = base64_decode($signatureBase64);

      // Compare signatures using constant-time comparison
      return hash_equals($computedSignature, $receivedSignature);
  }

  function main() {
      // Secret key from webhook configuration (used as string directly)
      $secretKey = "JUL5QkQrpZYwW+Kf03QSrb70CG+ea/j8E/JfslENaXhd0AGBDbAtYYP2MdjkYDqiwjBtrtQXsUIbtAf7IGEGfg==";

      // From X-Signature header
      $signatureBase64 = "VWEtiJu/7dLrq0ZtXS0HbGDPy6Re86oZeTnEEc9mlxg=";

      // Compact JSON payload (no spaces/newlines) - this is what the hook service signs
      $payload = '{"event":"bvnk:ledger:report:ready","eventId":"0198a8bb-7d56-79ef-92b2-2aed247c21b4","timestamp":"2025-08-14T13:18:36.374620938Z","data":{"id":"8d942264-e27e-44d9-a048-5ed66ac5129f","url":"https://bvnk-staging-reports.s3.eu-west-1.amazonaws.com/transaction/8d942264-e27e-44d9-a048-5ed66ac5129f_7b2f87b9-1335-4b1e-bbeb-6a59ba1dc6df.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250814T131836Z&X-Amz-SignedHeaders=host&X-Amz-Credential=AKIAZP6R7NJUFAGFGMNA%2F20250814%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=5c861e552b3e253be28f8e02c818b3c5e00269b9b50b6d4957d5281825d31a67","type":"TRANSACTION","status":"READY"}}';

      // Verify the signature
      $isValid = verifyWebhookSignature($secretKey, $payload, $signatureBase64);

      // For debugging - compute expected signature
      $computedSignature = hash_hmac('sha256', $payload, $secretKey, true);
      $expectedSignatureBase64 = base64_encode($computedSignature);

      echo "Expected signature: " . $expectedSignatureBase64 . "\n";
      echo "Received signature: " . $signatureBase64 . "\n";
      echo "Signature is valid: " . ($isValid ? "true" : "false") . "\n";
  }

  // Example usage in a webhook handler
  function handleWebhook() {
      // Get the payload from POST body
      $payload = file_get_contents('php://input');

      // Get the signature from headers
      $signatureBase64 = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

      // Your secret key from webhook configuration
      $secretKey = "YOUR_SECRET_KEY_HERE";

      // Verify the signature
      if (verifyWebhookSignature($secretKey, $payload, $signatureBase64)) {
          // Signature is valid - process the webhook
          $data = json_decode($payload, true);
          echo "Webhook verified and processed successfully\n";
          // Process your webhook data here
      } else {
          // Invalid signature
          http_response_code(401);
          echo "Invalid webhook signature\n";
      }
  }

  // Run the test
  main();
  ?>
  ```

</TabItem>
<TabItem value="JavaScript">

  ```javascript JavaScript
  const crypto = require('crypto');

  /**
   * Verify HMAC-SHA256 signature for webhook payload
   *
   * @param {string} secretKey - The shared secret from webhook configuration
   * @param {string} payload - The JSON payload as received in webhook
   * @param {string} signatureBase64 - The signature from X-Signature header
   * @returns {boolean} True if signature is valid, false otherwise
   */
  function verifyWebhookSignature(secretKey, payload, signatureBase64) {
      // Generate HMAC-SHA256 signature using the secret key as UTF-8 bytes
      const computedSignature = crypto
          .createHmac('sha256', secretKey)
          .update(payload, 'utf8')
          .digest();

      // Base64 encode the computed signature
      const computedSignatureBase64 = computedSignature.toString('base64');

      // Decode the received signature
      const receivedSignature = Buffer.from(signatureBase64, 'base64');

      // Compare signatures using constant-time comparison
      return crypto.timingSafeEqual(computedSignature, receivedSignature);
  }

  function main() {
      // Secret key from webhook configuration (used as string directly)
      const secretKey = "JUL5QkQrpZYwW+Kf03QSrb70CG+ea/j8E/JfslENaXhd0AGBDbAtYYP2MdjkYDqiwjBtrtQXsUIbtAf7IGEGfg==";

      // From X-Signature header
      const signatureBase64 = "VWEtiJu/7dLrq0ZtXS0HbGDPy6Re86oZeTnEEc9mlxg=";

      // Compact JSON payload (no spaces/newlines) - this is what the hook service signs
      const payload = '{"event":"bvnk:ledger:report:ready","eventId":"0198a8bb-7d56-79ef-92b2-2aed247c21b4","timestamp":"2025-08-14T13:18:36.374620938Z","data":{"id":"8d942264-e27e-44d9-a048-5ed66ac5129f","url":"https://bvnk-staging-reports.s3.eu-west-1.amazonaws.com/transaction/8d942264-e27e-44d9-a048-5ed66ac5129f_7b2f87b9-1335-4b1e-bbeb-6a59ba1dc6df.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250814T131836Z&X-Amz-SignedHeaders=host&X-Amz-Credential=AKIAZP6R7NJUFAGFGMNA%2F20250814%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=5c861e552b3e253be28f8e02c818b3c5e00269b9b50b6d4957d5281825d31a67","type":"TRANSACTION","status":"READY"}}';

      // Verify the signature
      const isValid = verifyWebhookSignature(secretKey, payload, signatureBase64);

      // For debugging - compute expected signature
      const computedSignature = crypto
          .createHmac('sha256', secretKey)
          .update(payload, 'utf8')
          .digest('base64');

      console.log(`Expected signature: ${computedSignature}`);
      console.log(`Received signature: ${signatureBase64}`);
      console.log(`Signature is valid: ${isValid}`);
  }

  // Example Express.js webhook handler
  function setupExpressWebhookHandler(app) {
      const express = require('express');

      // Middleware to get raw body for signature verification
      app.use('/webhook', express.raw({ type: 'application/json' }));

      app.post('/webhook', (req, res) => {
          const payload = req.body.toString('utf8');
          const signatureBase64 = req.headers['x-signature'];

          // Your secret key from webhook configuration
          const secretKey = "YOUR_SECRET_KEY_HERE";

          if (verifyWebhookSignature(secretKey, payload, signatureBase64)) {
              // Signature is valid - process the webhook
              const data = JSON.parse(payload);
              console.log('Webhook verified and processed successfully');
              // Process your webhook data here
              res.status(200).send('OK');
          } else {
              // Invalid signature
              console.log('Invalid webhook signature');
              res.status(401).send('Invalid signature');
          }
      });
  }

  // Browser version (if you need client-side verification - not recommended for security)
  async function verifyWebhookSignatureBrowser(secretKey, payload, signatureBase64) {
      // Convert secret key to ArrayBuffer
      const secretKeyBuffer = new TextEncoder().encode(secretKey);

      // Import the key for HMAC
      const key = await crypto.subtle.importKey(
          'raw',
          secretKeyBuffer,
          { name: 'HMAC', hash: 'SHA-256' },
          false,
          ['sign', 'verify']
      );

      // Convert payload to ArrayBuffer
      const payloadBuffer = new TextEncoder().encode(payload);

      // Generate signature
      const signatureBuffer = await crypto.subtle.sign('HMAC', key, payloadBuffer);

      // Convert to base64
      const computedSignatureBase64 = btoa(String.fromCharCode(...new Uint8Array(signatureBuffer)));

      // Decode received signature
      const receivedSignature = Uint8Array.from(atob(signatureBase64), c => c.charCodeAt(0));
      const computedSignature = new Uint8Array(signatureBuffer);

      // Compare signatures
      if (receivedSignature.length !== computedSignature.length) {
          return false;
      }

      let result = 0;
      for (let i = 0; i < receivedSignature.length; i++) {
          result |= receivedSignature[i] ^ computedSignature[i];
      }

      return result === 0;
  }

  // Run the test if this file is executed directly
  if (require.main === module) {
      main();
  }

  module.exports = {
      verifyWebhookSignature,
      verifyWebhookSignatureBrowser,
      setupExpressWebhookHandler
  };
  ```

</TabItem>
<TabItem value="C#">

  ```csharp
  using System;
  using System.Security.Cryptography;
  using System.Text;

  namespace BvnkWebhookVerification
  {
      public class WebhookVerifier
      {
          /// Verify HMAC-SHA256 signature for webhook payload
          public static bool VerifyWebhookSignature(string secretKey, string payload, string signatureBase64)
          {
              try
              {
                  // Convert secret key to bytes using UTF-8 encoding
                  byte[] secretKeyBytes = Encoding.UTF8.GetBytes(secretKey);

                  // Convert payload to bytes using UTF-8 encoding
                  byte[] payloadBytes = Encoding.UTF8.GetBytes(payload);

                  // Generate HMAC-SHA256 signature
                  using (var hmac = new HMACSHA256(secretKeyBytes))
                  {
                      byte[] computedSignature = hmac.ComputeHash(payloadBytes);

                      // Base64 encode the computed signature
                      string computedSignatureBase64 = Convert.ToBase64String(computedSignature);

                      // Decode the received signature
                      byte[] receivedSignature = Convert.FromBase64String(signatureBase64);

                      // Compare signatures using constant-time comparison
                      return CryptographicOperations.FixedTimeEquals(computedSignature, receivedSignature);
                  }
              }
              catch (Exception)
              {
                  return false;
              }
          }

          /// <summary>
          /// Alternative signature verification for older .NET versions without CryptographicOperations
          /// </summary>
          public static bool VerifyWebhookSignatureLegacy(string secretKey, string payload, string signatureBase64)
          {
              try
              {
                  byte[] secretKeyBytes = Encoding.UTF8.GetBytes(secretKey);
                  byte[] payloadBytes = Encoding.UTF8.GetBytes(payload);

                  using (var hmac = new HMACSHA256(secretKeyBytes))
                  {
                      byte[] computedSignature = hmac.ComputeHash(payloadBytes);
                      string computedSignatureBase64 = Convert.ToBase64String(computedSignature);

                      // Simple string comparison (less secure but works for older .NET)
                      return string.Equals(computedSignatureBase64, signatureBase64, StringComparison.Ordinal);
                  }
              }
              catch (Exception)
              {
                  return false;
              }
          }
      }

      class Program
      {
          static void Main(string[] args)
          {
              // Secret key from webhook configuration (used as string directly)
              string secretKey = "JUL5QkQrpZYwW+Kf03QSrb70CG+ea/j8E/JfslENaXhd0AGBDbAtYYP2MdjkYDqiwjBtrtQXsUIbtAf7IGEGfg==";

              // From X-Signature header
              string signatureBase64 = "VWEtiJu/7dLrq0ZtXS0HbGDPy6Re86oZeTnEEc9mlxg=";

              // Compact JSON payload (no spaces/newlines) - this is what the hook service signs
              string payload = @"{""event"":""bvnk:ledger:report:ready"",""eventId"":""0198a8bb-7d56-79ef-92b2-2aed247c21b4"",""timestamp"":""2025-08-14T13:18:36.374620938Z"",""data"":{""id"":""8d942264-e27e-44d9-a048-5ed66ac5129f"",""url"":""https://bvnk-staging-reports.s3.eu-west-1.amazonaws.com/transaction/8d942264-e27e-44d9-a048-5ed66ac5129f_7b2f87b9-1335-4b1e-bbeb-6a59ba1dc6df.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250814T131836Z&X-Amz-SignedHeaders=host&X-Amz-Credential=AKIAZP6R7NJUFAGFGMNA%2F20250814%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=5c861e552b3e253be28f8e02c818b3c5e00269b9b50b6d4957d5281825d31a67"",""type"":""TRANSACTION"",""status"":""READY""}}";

              // Verify the signature
              bool isValid = WebhookVerifier.VerifyWebhookSignature(secretKey, payload, signatureBase64);

              // For debugging - compute expected signature
              byte[] secretKeyBytes = Encoding.UTF8.GetBytes(secretKey);
              byte[] payloadBytes = Encoding.UTF8.GetBytes(payload);

              using (var hmac = new HMACSHA256(secretKeyBytes))
              {
                  byte[] computedSignature = hmac.ComputeHash(payloadBytes);
                  string expectedSignatureBase64 = Convert.ToBase64String(computedSignature);

                  Console.WriteLine($"Expected signature: {expectedSignatureBase64}");
                  Console.WriteLine($"Received signature: {signatureBase64}");
                  Console.WriteLine($"Signature is valid: {isValid}");
              }
          }
      }
  }
  ```

</TabItem>
<TabItem value="Ruby">

  ```ruby Ruby
  require 'openssl'
  require 'base64'

  class WebhookVerifier
    ##
    # Verify HMAC-SHA256 signature for webhook payload
    #
    # @param secret_key [String] The shared secret from webhook configuration
    # @param payload [String] The JSON payload as received in webhook
    # @param signature_base64 [String] The signature from X-Signature header
    # @return [Boolean] True if signature is valid, false otherwise
    def self.verify_webhook_signature(secret_key, payload, signature_base64)
      # Generate HMAC-SHA256 signature using the secret key as UTF-8 bytes
      computed_signature = OpenSSL::HMAC.digest('SHA256', secret_key, payload)

      # Base64 encode the computed signature
      computed_signature_base64 = Base64.strict_encode64(computed_signature)

      # Decode the received signature
      received_signature = Base64.strict_decode64(signature_base64)

      # Compare signatures using constant-time comparison
      OpenSSL.secure_compare(computed_signature, received_signature)
    rescue StandardError
      false
    end

    ##
    # Alternative signature verification for older Ruby versions without secure_compare
    def self.verify_webhook_signature_legacy(secret_key, payload, signature_base64)
      computed_signature = OpenSSL::HMAC.digest('SHA256', secret_key, payload)
      computed_signature_base64 = Base64.strict_encode64(computed_signature)

      # Simple string comparison (less secure but works for older Ruby)
      computed_signature_base64 == signature_base64
    rescue StandardError
      false
    end
  end

  def main
    # Secret key from webhook configuration (used as string directly)
    secret_key = 'JUL5QkQrpZYwW+Kf03QSrb70CG+ea/j8E/JfslENaXhd0AGBDbAtYYP2MdjkYDqiwjBtrtQXsUIbtAf7IGEGfg=='

    # From X-Signature header
    signature_base64 = 'VWEtiJu/7dLrq0ZtXS0HbGDPy6Re86oZeTnEEc9mlxg='

    # Compact JSON payload (no spaces/newlines) - this is what the hook service signs
    payload = '{"event":"bvnk:ledger:report:ready","eventId":"0198a8bb-7d56-79ef-92b2-2aed247c21b4","timestamp":"2025-08-14T13:18:36.374620938Z","data":{"id":"8d942264-e27e-44d9-a048-5ed66ac5129f","url":"https://bvnk-staging-reports.s3.eu-west-1.amazonaws.com/transaction/8d942264-e27e-44d9-a048-5ed66ac5129f_7b2f87b9-1335-4b1e-bbeb-6a59ba1dc6df.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20250814T131836Z&X-Amz-SignedHeaders=host&X-Amz-Credential=AKIAZP6R7NJUFAGFGMNA%2F20250814%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=5c861e552b3e253be28f8e02c818b3c5e00269b9b50b6d4957d5281825d31a67","type":"TRANSACTION","status":"READY"}}'

    # Verify the signature
    is_valid = WebhookVerifier.verify_webhook_signature(secret_key, payload, signature_base64)

    # For debugging - compute expected signature
    computed_signature = OpenSSL::HMAC.digest('SHA256', secret_key, payload)
    expected_signature_base64 = Base64.strict_encode64(computed_signature)

    puts "Expected signature: #{expected_signature_base64}"
    puts "Received signature: #{signature_base64}"
    puts "Signature is valid: #{is_valid}"
  end

  # Example Sinatra webhook handler
  def setup_sinatra_webhook_handler
    require 'sinatra'
    require 'json'

    post '/webhook' do
      # Read the raw body
      request.body.rewind
      payload = request.body.read

      # Get the signature from headers
      signature_base64 = request.env['HTTP_X_SIGNATURE'] || ''

      # Your secret key from webhook configuration
      secret_key = 'YOUR_SECRET_KEY_HERE'

      if WebhookVerifier.verify_webhook_signature(secret_key, payload, signature_base64)
        # Signature is valid - process the webhook
        data = JSON.parse(payload)
        puts 'Webhook verified and processed successfully'
        # Process your webhook data here
        status 200
        'OK'
      else
        # Invalid signature
        puts 'Invalid webhook signature'
        status 401
        'Invalid signature'
      end
    end
  end

  # Example Rails controller
  class WebhooksController < ApplicationController
    skip_before_action :verify_authenticity_token

    def handle_webhook
      payload = request.raw_post
      signature_base64 = request.headers['X-Signature'] || ''

      # Your secret key from webhook configuration
      secret_key = Rails.application.credentials.webhook_secret_key

      if WebhookVerifier.verify_webhook_signature(secret_key, payload, signature_base64)
        # Signature is valid - process the webhook
        data = JSON.parse(payload)
        Rails.logger.info 'Webhook verified and processed successfully'
        # Process your webhook data here
        head :ok
      else
        # Invalid signature
        Rails.logger.error 'Invalid webhook signature'
        head :unauthorized
      end
    rescue JSON::ParserError
      Rails.logger.error 'Invalid JSON in webhook payload'
      head :bad_request
    rescue StandardError => e
      Rails.logger.error "Webhook processing error: #{e.message}"
      head :internal_server_error
    end
  end

  # Run the test if this file is executed directly
  main if __FILE__ == $PROGRAM_NAME
  ```

</TabItem>
</Tabs>

:::warning Make sure you do not parse your HTTP request into an object and then serialize it.
Instead, provide the webhook raw payload as a string.
:::

The signature will be available in the `x-signature` header of the webhook. Every new webhook has a unique `x-signature` header value. Make sure you compare the hash to the correct header.

---

## Create a wallet

BVNK offers capabilities to create and manage crypto wallets directly from within the BVNK portal. 

:::warning
When you create a fiat wallet, it is not available right away. Before you can use it, request your Account Manager for the wallet verification.
:::

## Create a wallet

To create a wallet, do the following:

<Tabs queryString="wallet-creation">
  <TabItem value="API" label="API">
    
    To create a fiat or crypto wallet with an [assigned wallet profile](#assign-a-wallet-profile), send the [`POST /ledger/v1/wallets`](../../api-explorer/endpoints/create-customer-wallet) request using the following parameters:

  <Tabs>
    <TabItem value="ACH/FedWire Wallet Creation">
      ```json 
      {
          "currencyCode": "USD",
          "name": "ACH/FEDWIRE test",
          "customerReference": "09c04f1b-77b2-42cc-a0c0-da9748a3be11",
          "instruction": {
              "walletProfile": "2a3fe604-2b14-4009-90b3-1e48f1a38b11",
              "type": "FIAT",
              "virtualAccountRequired": true
          }
      }
      ```
    </TabItem>
    <TabItem value="SWIFT Wallet Creation">
      ```json 
      {
          "currencyCode": "USD",
          "name": "swift test",
          "customerReference": "09c04f1b-77b2-42cc-a0c0-da9748a3be11",
          "instruction": {
              "walletProfile": "18f9a1bf-0d77-45f5-b5ff-1e90411d88ce",
              "type": "FIAT",
              "virtualAccountRequired": true
          }
      }
      ```
    </TabItem>
    <TabItem value="Crypto Wallet Creation">
      ```json 
      {
          "currencyCode": "USDT",
          "name": "USDT Test",
          "customerReference": "fb8c0b12-6552-429e-955e-70af08733310",
          "instruction": {
              "walletProfile": "f7fdb837-5053-45b0-86c8-96ece6fe02d0",
              "type": "CRYPTO",
              "virtualAccountRequired": false
          }
      }
      ```
    </TabItem>
  </Tabs>

    | 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:

    <Tabs>
      <TabItem value="Fiat Wallet">
        
        ```json Example Response for fiat 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": []
        }
        ```

      </TabItem>
      <TabItem value="Crypto Wallet">
        
        ```json Example Response for crypto wallet
        {
            "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": []
        }
        ```
        
      </TabItem>
    </Tabs>

    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 the [Wallet Read API endpoint](../../api-explorer/endpoints/wallet-read).

    The wallet can also have the `TERMINATED` status. This means the wallet can no longer be used, and that state is final; BVNK can never reactivate it. All operations, including receiving pay-ins, sending payouts, and currency conversions, are blocked for the terminated wallets. You can only access its transaction history. In case of a **fiat wallet**, the associated virtual account will be permanently closed with the banking partner.

  </TabItem>

  <TabItem value="Portal" label="Portal">

    1. On the BVNK Portal, go to **Wallets** and click **Add Wallet**.
      ![](/img/bvnk/get-started/add-wallet-button.png)
    2. Select the currency, insert a unique name for this wallet and click **Create Wallet**.

        ![](/img/bvnk/get-started/create-wallet-form.png)

    The new wallet appears in the list. You also have a few functions available if you click on the wallet information:

    ![](/img/bvnk/get-started/wallet-created-list.png)

    :::info 
    When you get access to your production BVNK portal account, fiat wallets will be automatically assigned to you during the onboarding process.
    :::
  
  </TabItem>
</Tabs>

 ## Assign a wallet profile

To list the existing Wallet Profiles, send the [`GET /ledger/v1/wallets/profiles`](../../api-explorer/endpoints/wallet-profiles) request using the following query parameters.

| Query Parameters | Values |
| :--- | :--- |
| `currencyCodes` | Code for fiat and cryptocurrency. See the detailed [list of supported currencies](/bvnk/references/currencies). |
| `paymentMethods` | Payment methods available for the wallet. See the detailed [list of payment methods](/bvnk/references/payment-methods). |

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

<Tabs>
  <TabItem value="Fiat Wallets">

  ```json Fiat Wallets
  {
      "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"
              ]
          }
      ]
  }
  ```

</TabItem>
<TabItem value="Crypto Wallet (EU Entity)">
  ```json Crypto Wallet (EU Entity)
  {
    "reference": "f7fdb837-5053-45b0-86c8-96ece6fe02d0",
    "currencyCodes": [
        "USDT",
        "PYUSD",
        "POL",
        "BTC",
        "SOL",
        "BNB",
        "XRP",
        "ETH",
        "USDC",
        "LTC",
        "TRX"
    ],
    "paymentMethods": []
  }
  ```
</TabItem>
<TabItem value="Crypto Wallet (US Entity)">
  ```json Crypto Wallet (US Entity)
  {
    "reference": "a0b8a34c-bfb9-43d8-9ee4-6eb076d107c0",
    "currencyCodes": [
        "USDT",
        "BTC",
        "SOL",
        "ETH",
        "USDC",
        "TRX"
    ],
    "paymentMethods": []
  }
  ```
</TabItem>
</Tabs>

## Fetch wallets

The endpoint provides comprehensive information for each wallet, including status, balance, and other relevant details. This enables efficient monitoring and management of all payment channels linked to the customer, ensuring full operational visibility. You can list all wallets assigned to a customer and retrieve information for a specific wallet by providing its reference.

### All wallets

To list all the wallets associated with a specific customer, send the [`GET /ledger/v1/wallets`](../../api-explorer/endpoints/ledger-wallet-list) request.

In the response, you receive the detailed information on each wallet:

<details>
  <summary>Response</summary>
```json Response
{
    "content": [
        {
            "id": "a:25061762277338:4nJVWl1:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
            "name": "Jonsal",
            "status": "ACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "Embedded customer A",
                    "accountNumber": "900768107004",
                    "code": "101019644",
                    "accountNumberFormat": "ABA",
                    "paymentReference": null
                }
            ]
        },
        {
            "id": "a:25061762217894:7kqBQY6:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "9ba4c65c-8c81-4e39-80b6-a803d9e66efd",
            "name": "John Legend",
            "status": "INACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": []
        },
        {
            "id": "a:25061762124495:Sichkow:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "9ba4c65c-8c81-4e39-80b6-a803d9e66efd",
            "name": "USD",
            "status": "INACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": []
        },
        {
            "id": "a:25060450775603:v28lmzW:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "Dave's Wallet",
            "status": "ACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "EUR"
            },
            "ledgers": []
        },
        {
            "id": "a:25052770895915:fQcLGMh:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
            "name": "JL Wallet",
            "status": "ACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "Embedded customer A",
                    "accountNumber": "900679904231",
                    "code": "101019644",
                    "accountNumberFormat": "ABA",
                    "paymentReference": null
                }
            ]
        },
        {
            "id": "a:25052256822125:xAWTzSB:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "USDC Wallet",
            "status": "ACTIVE",
            "balance": {
                "value": 1106.71,
                "currencyCode": "USDC"
            },
            "ledgers": []
        },
        {
            "id": "a:25052233445967:xnrik2v:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "USDT Wallet",
            "status": "ACTIVE",
            "balance": {
                "value": 120.50,
                "currencyCode": "USDT"
            },
            "ledgers": []
        },
        {
            "id": "a:25052137356562:qjOSsJf:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
            "name": "USD Wallet NEW",
            "status": "TERMINATED",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "Embedded customer A",
                    "accountNumber": "900072464417",
                    "code": "101019644",
                    "accountNumberFormat": "ABA",
                    "paymentReference": null
                }
            ]
        },
        {
            "id": "a:25051268495394:hNyZppE:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "Bitcoin Wallet Test account # 1",
            "status": "INACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "BTC"
            },
            "ledgers": []
        },
        {
            "id": "a:25042472328513:DjpwMfa:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
            "name": "USD Wallet Test",
            "status": "ACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "Embedded customer A",
                    "accountNumber": "900222018455",
                    "code": "101019644",
                    "accountNumberFormat": "ABA",
                    "paymentReference": null
                }
            ]
        },
        {
            "id": "a:25042460023997:xgImmdY:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "ETH Wallet",
            "status": "INACTIVE",
            "balance": {
                "value": 0.23,
                "currencyCode": "ETH"
            },
            "ledgers": []
        },
        {
            "id": "a:25041166078335:oYJeFUK:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
            "name": "USDT Wallet",
            "status": "ACTIVE",
            "balance": {
                "value": 71.63,
                "currencyCode": "USDT"
            },
            "ledgers": []
        },
        {
            "id": "a:25040249187073:wR42W6d:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "USDC Wallet",
            "status": "INACTIVE",
            "balance": {
                "value": 200.00,
                "currencyCode": "USDC"
            },
            "ledgers": []
        },
        {
            "id": "a:25040150970798:mGX7Twm:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "Wallet EUR",
            "status": "INACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "EUR"
            },
            "ledgers": []
        },
        {
            "id": "a:25031066969227:zFSl3Ea:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
            "name": "USD Wallet 3",
            "status": "ACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "Embedded Customer A",
                    "accountNumber": "900554317794",
                    "code": "101019644",
                    "accountNumberFormat": "ABA",
                    "paymentReference": null
                }
            ]
        },
        {
            "id": "a:25031066539770:Ia9mdf9:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "9ba4c65c-8c81-4e39-80b6-a803d9e66efd",
            "name": "USD Wallet Customer B",
            "status": "INACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": []
        },
        {
            "id": "a:25030652262360:ewsQxR8:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
            "name": "USD Wallet 2",
            "status": "ACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "Embedded customer A",
                    "accountNumber": "900914731533",
                    "code": "101019644",
                    "accountNumberFormat": "ABA",
                    "paymentReference": null
                }
            ]
        },
        {
            "id": "a:25030559783181:81aaB4K:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "USD Swift",
            "status": "ACTIVE",
            "balance": {
                "value": 137.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "System Pay Services Solutions Spain S.L.",
                    "accountNumber": "ES250182851098200007418",
                    "code": "BBVAESMMXXX",
                    "accountNumberFormat": "SWIFT",
                    "paymentReference": "REF-CL1CDC7"
                }
            ]
        },
        {
            "id": "a:25030558827793:LO8IHmy:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": "7e38e85f-8e1b-486d-b24f-28e4192f57f6",
            "name": "USD Embedded Wallet",
            "status": "ACTIVE",
            "balance": {
                "value": 872.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "Embedded customer A",
                    "accountNumber": "900012647634",
                    "code": "101019644",
                    "accountNumberFormat": "ABA",
                    "paymentReference": null
                }
            ]
        },
        {
            "id": "a:25030548796673:JtdGolN:1",
            "accountReference": "f539c983-c8cd-4db0-98bb-2de9e79d0e64",
            "customerReference": null,
            "name": "USD Main Wallet",
            "status": "INACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": [
                {
                    "type": "FIAT",
                    "accountHolderName": "Commercial US",
                    "accountNumber": "900364186010",
                    "code": "101019644",
                    "accountNumberFormat": "ABA",
                    "paymentReference": null
                }
            ]
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": [],
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": false,
    "totalElements": 23,
    "totalPages": 2,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": [],
    "numberOfElements": 20,
    "empty": false
}
```
</details>

### Wallet by customer reference

To retrieve wallet details by customer reference, send the [`GET ledger/v1/wallets?customerReference={customerReference}` ](../../api-explorer/endpoints/ledger-wallet-list) request with the `{customerReference}` specified in the path.

In the response, you receive the list with detailed information on each customer wallet:

<details>
  <summary>Response</summary>
```json Response
{
    "content": [
        {
            "id": "a:24101151618956:Xlfn0oR:1",
            "accountReference": "ceb9400d-eee2-4cc0-89dc-1b3548f7291d",
            "customerReference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
            "name": "My USD Wallet",
            "status": "INACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": []
        },
        {
            "id": "a:24101151422432:gCl7SeI:1",
            "accountReference": "ceb9400d-eee2-4cc0-89dc-1b3548f7291d",
            "customerReference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
            "name": "My USD Wallet 2",
            "status": "INACTIVE",
            "balance": {
                "value": 0.00,
                "currencyCode": "USD"
            },
            "ledgers": []
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": [],
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": true,
    "totalElements": 2,
    "totalPages": 1,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": [],
    "numberOfElements": 2,
    "empty": false
}
```
</details>

### Wallet by Wallet ID

To retrieve wallet details by its unique identifier, send the [`GET ledger/v1/wallets/{id}`](../../api-explorer/endpoints/wallet-read) request with the `{id}` specified in the path.

In the response, you receive the detailed information on the  wallet:

<details>
  <summary>Response</summary>
```json Response
{
    "id": "a:24101151422432:gCl7SeI:1",
    "accountReference": "ceb9400d-eee2-4cc0-89dc-1b3548f7291d",
    "customerReference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
    "name": "My USD Wallet 2",
    "status": "INACTIVE",
    "balance": {
        "value": 1000.00,
        "currencyCode": "USD"
    },
    "ledgers": []
}
```
</details>

## Wallet webhook

To get notified when the a new wallet is created, listen to the [Ledger wallet creation notification](../../api-explorer/bvnk-webhooks/ledger-wallet-create).

---

**What's next?**

Now, when you have a wallet, you can start sending and receiving payments. 

- See the available [use cases](find-your-usecase.mdx) to select the one that best suits your needs.
- Configure a designated wallet for [customer fees](charge-customer-fees.mdx).

---

## Select your delivery model

This article outlines the available BVNK delivery models.

Not sure which model is right for you? Take our interactive quiz to find out:

<!-- <DeliveryModelQuiz />

## Find Your Solution (Including Self-Managed)

Looking for a complete solution including self-managed options? This quiz includes Layer1 for self-hosted solutions: -->

<DeliveryModelQuizWithLayer1 />

## Delivery models

<Tabs queryString="delivery-model">
  <TabItem value="direct" label="Direct">

    The direct model is the most basic delivery option.

    You contract directly with BVNK and access payment capabilities through the BVNK portal or API for your own use. You maintain full control over your payment flow and can customize it as needed.

    ![](/img/bvnk/get-started/direct-model.png)

    

    *Legal entity relationships in the Direct model*

    

    **Who is it for:** Companies that need to send, receive, or hold stablecoins for their customers.

    **Flow of funds:** Payments are sent from and to your treasury.

    **Integration options:** BVNK Portal or API.

    **Onboarding:** BVNK onboards you as the direct customer.

    **Use cases**:

    - [Send stablecoin payments](../../use-cases/stablecoin-payments-for-platforms/payout-overview)
    - [Receive payments](../../use-cases/stablecoin-payments-for-platforms/get-payment-overview)
    - [Convert funds (on-ramp)](../../use-cases/on-off-ramp/on-ramp-overview)
    - [Receive, send, and store funds with Virtual Accounts](../../use-cases/virtual-accounts/va-overview)

  </TabItem>
  <TabItem value="custom-embedded" label="Embedded">

    

    You embed our payment capabilities into your platform via API integration and give your customers access to payments on leading blockchains and schemes.

    ![](/img/bvnk/get-started/custom-embedded-model.png)

    

    *Legal entity relationships in the Embedded model*

    

    **Who is it for:** Larger enterprises, such as platforms or marketplaces, seeking to embed stablecoins directly into their customer-facing ecosystem.

    **Flow of funds:** You can move funds on behalf of your customers, or they can move funds directly on your platform.

    **Integration options:** BVNK Portal or API

    **Onboarding:**
    - BVNK onboards you as a partner.
    - BVNK onboards your customers.
    - You submit onboarding docs for your customers.

    **Payment Instructions:**
    - A partner integrates via API.
    - A customer can send payment instructions via your platform.

    **Use cases**:

    - [Send stablecoin payments](../../use-cases/stablecoin-payments-for-platforms/payout-overview)
    - [Receive payments](../../use-cases/stablecoin-payments-for-platforms/get-payment-overview)
    - [Send payments via customers' wallets](../../use-cases/stablecoin-payments-for-platforms/epc-stablecoin-overview)
    - [Convert funds (on-ramp)](../../use-cases/on-off-ramp/on-ramp-overview)

  </TabItem>
  <!-- <TabItem value="embedded-express" label="Embedded Express">

  Embedded Express lets you provide embedded services (a stablecoin service for your customers using BVNK’s license) via our Express application—a themeable front end that your customers interact with directly. This offers a streamlined way to deliver branded stablecoin wallets to your customers. Enterprise partners can issue wallets with minimal effort, enabling their customers to access the benefits of stablecoins without added complexity.

  **Benefits for partners**:

  - **Fast time to market**: Launch stablecoin services quickly with minimal integration. In the simplest case, you require little to no development, enabling a faster go-live than a fully custom solution.

  - **Simpler contracting and onboarding**: No extended technical services agreement or lengthy due diligence is required, reducing the time and effort to get started.

  - **Reduced operational complexity**: You do not need to manage compliance, licensing, KYT, downtime, updates, maintenance, or regulatory data changes.

  - **Branded customer experience**: BVNK offers a customizable user interface that matches your brand. Your customers see your logo and brand colors throughout the stablecoin wallet experience, creating a seamless extension of your platform.

    ![legal entity relationships](/img/bvnk/get-started/embedded-express-model.svg)

    

    *Legal entity relationships in the Embedded Express model*

    

    **Flow of funds**: Your customers have stablecoin wallets to hold, send, and receive cryptocurrencies; and ability to earn rewards and spend on stablecoin-backed card.

    **Integration options**: Customer-facing, co-branded portal with your color scheme and logo.

    **Onboarding:** BVNK onboards your embedded customers. Onboarding can be managed in the Express UI, or you may share KYC documentation via API.

    **Payment Instructions**: Only the embedded customer can initiate payments from the Express experience. Partners cannot access Express customers' wallets or create payment instructions via API for these wallets.

    If you would like to enable this capability for your customers, contact your Account Manager.

    **Use cases**:

    - [Store funds in your wallet](../../use-cases/xpress-store-funds/express-overview)
    - [Send stablecoin payments](../../use-cases/stablecoin-payments-for-platforms/payout-overview)
    - [Receive stablecoin payments](../../use-cases/stablecoin-payments-for-platforms/get-payment-overview)

  </TabItem> -->
</Tabs>

---

## Find your use case

Use this table to quickly identify which BVNK use case matches your business needs. Compare use cases to understand the target industries, currency flows, required delivery models, and available product features. Click the use case link to view detailed implementation guides, or use the Model links to learn more about the delivery models (Direct or Embedded) that support each use case.

<style>{`
  .use-case-table table {
    table-layout: fixed;
    width: 100%;
  }
  .use-case-table table th,
  .use-case-table table td {
    width: 16.66%;
  }
`}</style>

| **Use case** | **Use it to** | **For who?** | **Currency flow** | **Delivery model** | **Capabilities** |
|:----------:|-------------|----------|----------|----------|----------|
| **[Send stablecoin payments](../use-cases/stablecoin-payments-for-platforms/payout-overview.mdx)** | Pay out winnings and earning to customersSend stablecoins from fiat balanceSend stablecoins as a salary to employees and contractors | Gaming PlatformCFD / FX brokersTrading PlatformsNeobanksPayment Service Providers (PSPs) | fiat → cryptocrypto → crypto | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) | SendReceiveConvert |
| **[Receive stablecoin payments](../use-cases/stablecoin-payments-for-platforms/get-payment-overview.mdx)** | Collect payments from your users in stablecoins, while you still receive fiatAllow your users to top up their account in stablecoins  | Payment Processing NetworksPayment Service Providers | crypto → fiatfiat → stablecoins | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) | SendReceiveConvert |
| **[Send stablecoin via customers' wallets](../use-cases/stablecoin-payments-for-platforms/epc-stablecoin-overview.mdx)** | Allow stablecoin payouts from your customers to their users from a pre-funded fiat balance | Payment Service Providers | crypto → cryptofiat → stablecoins | [Embedded](delivery-models.mdx?delivery-model=custom-embedded) | SendReceiveConvertStore |
| **[Convert funds (on-ramp)](../use-cases/on-off-ramp/on-ramp-overview.mdx)** | Allow your customers to pay out in crypto directly from your platform | Payment Service Providers Employer of Record servicesMarketplacesNeobanks | crypto → fiatfiat → crypto | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) | SendReceiveConvert |
| **[Provide virtual accounts for your customers](../use-cases/virtual-accounts/va-overview.mdx?va=cVA)** | Enable customers to send and receive fiat funds for crypto tradingProcess 3rd party payments with optional stablecoin pre-funding | Payment Service ProvidersEmployer of Record servicesMarketplacesNeobanksCFD / FX brokersTrading Platforms | fiat → fiat | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) | SendReceiveStore |
| **[Receive, send, and store funds with Virtual Accounts](../use-cases/virtual-accounts/va-overview.mdx?va=VA)** | Create payment accounts with unique vIBAN for your businessReceive deposits in stablecoin and pay in fiat | Payment Service ProvidersEmployer of Record servicesMarketplacesNeobanksCFD / FX brokersTrading Platforms | fiat → fiat | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) | SendReceiveStore |
{/* | **[Enable Express wallets for customers](../use-cases/xpress-store-funds/express-overview.mdx)** | Start providing stablecoin services with a fast onboarding processOffer stablecoin storage and management with stored-value balances to your customers | Payment Service Providers (PSPs)Platforms and marketplacesNeobanks and financial services | fiat → stablecoinscrypto → crypto | [Embedded Express](delivery-models.mdx?delivery-model=embedded-express) | SendReceiveConvertStore | */}

<!-- | You are | You want to | To |Currency flow |Model
|----------|----------|-------------|----------|----------|
| Gaming PlatformCFD / FX brokersTrading PlatformsNeobanksPayment Service Providers (PSPs) | **[Send stablecoin payments to your customers](../use-cases/stablecoin-payments-for-platforms/payout-overview.mdx)** |Pay out winnings and earnings to customersSend stablecoins from fiat balanceAllow your customers to send (withdraw) stablecoins to / from my platfrom to top-up NDC crypto walletsSend stablecoins as a salary to employees and contractors  |fiat -> cryptocrypto -> same cryptocrypto -> different crypto | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) |
| Payment Processing NetworksPayment Service Providers | **[Receive stablecoin payments from customers](../use-cases/stablecoin-payments-for-platforms/get-payment-overview.mdx)** | Collect payments from your users in stablecoins, while you still receive fiatAllow your users to top up their account in stablecoins  | crypto -> fiatfiat -> stablecoins | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) |
| Payment Service Providers | **[Send payments from customers' wallets](../use-cases/stablecoin-payments-for-platforms/epc-stablecoin-overview.mdx)** | Allow your customers to pay and receive crypto directly from your platform | crypto -> cryptofiat -> stablecoins | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) |
| Payment Service Providers Employer of Record servicesMarketplacesNeobanks | **[Automatically convert fiat to crypto and send to customers' wallets](../use-cases/on-off-ramp/on-ramp-overview.mdx)** | Allow your customers to pay out in crypto directly from your platform | crypto -> fiatfiat -> crypto | [Direct](delivery-models.mdx?delivery-model=direct)[Embedded](delivery-models.mdx?delivery-model=custom-embedded) | -->

---

## Create API keys

BVNK uses **Hawk authentication** for secure API access. Hawk is a cryptographic scheme that provides request integrity and authentication without requiring you to send your secret key with each request. Instead, you use your Hawk Auth ID and Secret Key to generate a signature for each API request. This approach ensures that your credentials remain secure even if your requests are intercepted.

Once the BVNK sandbox account is active, create API keys to call BVNK endpoints:

1. Log in to the [BVNK Portal](https://app.sandbox.bvnk.com/login).

2. On the sidebar, select **Integrations** and click **Generate API Key**.
   If 2FA is not enabled in your account yet, you'll be requested to configure it in an authenticator app.

   ![](/img/bvnk/get-started/enable-2fa.png)

3. In the **Generate new API key** window, specify the following parameters:

   * **Name**: Enter the description to identify the key in future.
   * **Allowed IP addresses**: Specify whitelisted IPs that your service will use to restrict IP addresses that can query the API. This improves security by ensuring that only requests from your own servers or trusted networks can authenticate with the API. **This must be set to enable withdrawals**.

   You can specify:

    * Static IP address, for example, `83.104.30.154`, or
    * Range of addresses using the CIDR (Classless Inter-Domain Routing) format, for example, `83.104.30.0/24`

        <details>
        <summary>Using CIDR notation</summary>

        CIDR format defines a network prefix and the size of the address block. It consists of an IP address, followed by a slash (/), and then a number (prefix length). The prefix length tells you how many bits of the address are fixed (the network part). The remaining bits are available for host addresses within that network.

        For example:

        * `83.104.30.0/24`: Prefix length `/24` means the first 24 bits (or first three octets) are fixed. This covers all IPs from `83.104.30.0` to `83.104.30.255` (256 addresses will have API access).

        * `83.104.0.0/16`. Prefix length `/16` means the first 16 bits (or first two octets) are fixed. This covers 83.104.0.0 to 83.104.255.255 (65,536 addresses will have API access).

        Avoid using overly broad ranges (like `/8` or `/0`), as this significantly weakens security as the access is provided to over 16 million addresses.
        </details>

   * **Withdrawals**: Click the toggle to enable or disable the use of these keys for withdrawals and payouts.
   If withdrawals are disabled, you will only be able to use these keys to collect payments. **Allowed IP addresses** must also be specified to enable withdrawals.

   ![](/img/bvnk/get-started/generate-key.png)

4. Click **Continue**. You will be prompted to enter the 6-digit code from a configured F2A app.

   ![](/img/bvnk/get-started/confirm-key.png)

5. API Keys are now generated, and the Hawk Auth ID and Secret Key should be saved.

  ![](/img/bvnk/get-started/generated-api-key.png)

:::warning Save your keys immediately
Once you've created the keys, you'll see the `Hawk Auth ID` and `Hawk Auth Key`. Store these credentials privately, as you won't be able to access the `Hawk Auth Key` again once you navigate away from this page.
:::

---

**What's next?**

Next, you can:

- [Create your first wallet](../create-wallet) for payment operations or request it from your Account Manager.
- [Create accounts](../create-embedded-partner-customer/creating-an-embedded-customer-company-api) for your customers and [onboard them](../create-embedded-partner-customer/onboard-epc) to ensure regulatory compliance.
- Find your use case and [start building](../find-your-usecase).

---

## Get started with BVNK

Begin seamless and efficient stablecoin payments with BVNK. This page outlines the five steps from initial setup to going live:

1. [Contact your Account Manager](#contact-your-account-manager).
2. [Design your implementation](#design-your-implementation).
2. [Create a sandbox account](#create-a-sandbox-account) on the BVNK Portal.
3. [Integrate with BVNK services](#integrate-with-bvnk-services) and test your integration.
4. [Apply for production access and go live](#go-live).

## Contact your Account Manager

Schedule a kick-off meeting with your [Account Manager](https://bvnk.com/contact) to discuss your requirements and preferred integration approach.

## Design your implementation

Collaborate with your Account Manager and Solutions Consultant during the discovery and integration phase to:

- [Decide on the delivery model](delivery-models.mdx). Manage stablecoins and compliance yourself, or delegate to BVNK.
- Define your payment flows, set up fees, and fee schedules.
- [Find the right use case](find-your-usecase.mdx) to match your needs.

## Create a sandbox account

Your sandbox is a test environment that mirrors the production platform but operates with test data and virtual funds. Use it to:

- Test API integrations safely.
- Experiment with different features.
- Validate your implementation before going live.

To build and test your integration in the sandbox environment, you need a [BVNK sandbox account](create-sandbox-account.mdx). After you sign in to your account on the BVNK Portal, you can:

- [Generate API keys](generate-api-keys.mdx) for API requests.
- [Configure webhooks](create-webhook-listener.mdx) for real-time notifications about transactions and other events.
- [Create accounts](create-embedded-partner-customer/creating-an-embedded-customer-company-api.mdx) for your customers and [onboard them](create-embedded-partner-customer/onboard-epc.mdx) to ensure regulatory compliance. Only for the [Embedded model](../delivery-models/?delivery-model=custom-embedded).
- [Create crypto wallets](create-wallet.mdx) for your customers or request fiat wallets from BVNK's Solutions team.
- Send and request payments.
- Generate transaction reports.
- Manage your customers and contacts.

## Integrate with BVNK services

Check our [API reference](../../api-explorer/api-overview/overview) to integrate the BVNK functionality into your platform.

To validate your integration in the sandbox environment:

- [Set up a Metamask Ethereum wallet for ETH and USDT ERC20](set-up-metamask-ethereum-wallet-for-eth-and-usdt-erc20-tokens.mdx).
- [Set up a TronLink wallet for TRX and USDT TRC20](set-up-tronlink-wallet-for-trx-and-usdt-trc20-tokens.mdx).

## Go live

After building and testing your integration in the sandbox environment, you are ready to go live.

Contact your Account Manager to activate your live account.

:::important
Sandbox configuration doesn't automatically transfer to your live account. You must manually replicate your setup. Before going live, verify:

- API keys are configured in the live environment.
- Webhook URLs are set up to ensure real-time notifications.
- Transaction limits and settings meet operational needs.
:::

Test your integration in the sandbox environment before full launch.

---

## Manage wallets

To manage a wallet lifecycle, use [`POST /ledger/v2/wallets/{walletId}/actions`](../../api-explorer/endpoints/ledger-wallet-execute-action).

You can execute the following actions:

- `TERMINATE`: Permanently terminates the wallet. This action cannot be reversed. The wallet balance must be **zero** (0) before termination.
    For fiat wallets, the linked ledgers are also closed, and the associated Virtual Account is removed. Crypto wallets do not use that mechanism.
- `BLOCK`: Temporarily blocks a wallet and prevents activity.
- `UNBLOCK`: Removes a previously applied block.

![](/img/bvnk/get-started/wallet-states.png)

In the payload, specify the `action` value and include a non-empty `comment` describing why the action is being performed.

<Tabs>
  <TabItem value="Block" label="BLOCK">

  ```json Request
  {
    "action": "BLOCK",
    "comment": "Temporarily blocked during compliance review."
  }
  ```

  </TabItem>
  <TabItem value="Unblock" label="UNBLOCK">

  ```json Request
  {
    "action": "UNBLOCK",
    "comment": "Compliance review completed. Wallet access restored."
  }
  ```

  </TabItem>
  <TabItem value="Terminate" label="TERMINATE">

  ```json Request
  {
    "action": "TERMINATE",
    "comment": "Customer requested account closure."
  }
  ```

  </TabItem>
</Tabs>

If successful, the endpoint returns `204 No Content`.

Common error scenarios:

- `400 Bad Request`: for example, if you attempt to run `TERMINATE` when the wallet has a non-zero balance.
- `409 Conflict`: for example, if you attempt to run `BLOCK` or `UNBLOCK` on a wallet that is already terminated.

---

## Try fiat payments in simulator

The sandbox environment provides a consistent simulation experience for pay-ins and payouts across all customer accounts. This ensures predictable behaviour regardless of the underlying partner or integration method.

The simulation also supports testing in cases where a partner's sandbox environment is limited or unavailable. This allows you to validate payment flows and integration logic in a controlled setting before going live.

Note that this functionality is not enabled for all wallets. If you experience any issues when trying to use this simulator, contact Support.

## Pay-in simulator

To simulate pay-ins with different currencies and payment methods, in the sandbox environment, send the [`POST /payment/v2/payins/simulation`](../../api-explorer/endpoints/simulate-payin-v-2/) request with the following payload:

<Tabs>
  <TabItem value="gbp" label="GBP local">
    ```json
    {
        "walletId": "acc:23090539331497:bVsk6:0",
        "remittanceInformation": "Invoice INV-2024-00142",
        "method": "FASTER_PAYMENT",
        "amount": 60.50,
        "currency": "GBP",
        "originator": {
            "name": "James Whitfield",
            "bankAccount": {
                "accountNumber": "GB87SYPE04082500000904",
                "accountNumberFormat": "IBAN",
                "bankCode": "SRLGGB2L"
            }
        }
    }
    ```
  </TabItem>
  <TabItem value="eur" label="EUR local">
    ```json
    {
        "walletId": "acc:23090539331497:bVsk6:0",
        "remittanceInformation": "Payment for order 78432",
        "method": "SEPA_INST",
        "amount": 100,
        "currency": "EUR",
        "originator": {
            "name": "Sophie Muller",
            "bankAccount": {
                "accountNumber": "IE29AIBK93115212345678",
                "accountNumberFormat": "IBAN",
                "bankCode": "AIBKIE2D"
            }
        }
    }
    ```
  </TabItem>
  <TabItem value="usd" label="USD local">
    ```json
    {
        "walletId": "acc:23090539331497:bVsk6:0",
        "remittanceInformation": "Ref 90215 - Monthly subscription",
        "method": "ACH",
        "amount": 120.60,
        "currency": "USD",
        "originator": {
            "name": "Michael Torres",
            "bankAccount": {
                "accountNumber": "026009593",
                "accountNumberFormat": "ABA",
                "bankCode": "BOFAUS3N"
            }
        }
    }
    ```
  </TabItem>
  <TabItem value="usd-swift" label="USD SWIFT">
    ```json
    {
        "walletId": "acc:23090539331497:bVsk6:0",
        "remittanceInformation": "Wire transfer - Contract 2024-A1",
        "method": "SWIFT",
        "amount": 2000.40,
        "currency": "USD",
        "originator": {
            "name": "Horizon Trading Ltd",
            "bankAccount": {
                "accountNumber": "US64BOFA0260095931234567890",
                "accountNumberFormat": "IBAN",
                "bankCode": "BOFAUS3N"
            }
        }
    }
    ```
  </TabItem>
</Tabs>

| Parameter | Description |
| :-------- | :---------- |
| `walletId` | Your wallet id. |
| `remittanceInformation` | Reference for the payment. |
| `method` | Payment method to be utilised for the pay-in. Optional.If it is not provided, the logic will be based on other dynamically determined attributes and routed for the specific wallet.If provided, use the following methods for each currency:* GBP: `FASTER_PAYMENT` or `SWIFT`* EUR: `SEPA_CT`, `SEPA_INST`, or `SWIFT`* USD: `ACH`, `ACH_SAME_DAY`, `FEDWIRE`, `CUBIX`, or `SWIFT` |
| `amount` | The amount of the pay-in transaction. |
| `currency` | Currency code (ISO-4217 format) for the pay-in transaction. |
| `originator.name` | Name of the sender of the pay-in. |
| `originator.bankAccount` | Bank account details of the sender of the pay-in. |
| `originator.bankAccount.accountNumber` | Account number of the sender of the pay-in. |
| `originator.bankAccount.accountNumberFormat` | Format type of the bank account number. For example `IBAN` can be used for SWIFT, and `ABA`—for local USD rails.Possible values: `SCAN`, `IBAN`, `SWIFT`, `ABA`, `CUBIX` |
| `originator.bankAccount.bankCode` | Bank code of the sender of the pay-in. |

The details of a `beneficiary` are unnecessary for simulating a pay-in because `walletId` provides specific information for the wallet to be credited.

It is also advisable to subscribe to the pay-in webhook to stay informed about changes to the wallet balance resulting from the simulated pay-in. See [Configure webhooks](../create-webhook-listener) for more information.

:::info 📘 Not all USD wallets support all payment methods (see the process of Wallet Profiles). All payment methods and currencies are subject to change and enhancements with further optionality.
:::

## Payout simulator

The standard payout flow is shown on the diagram:

![](/img/bvnk/test-integration/payout-simulator-flow.png)

In the BVNK simulator, you can test the following behaviours:

| Flow | Customer Reference Prefix | Description |
| :--- | :------------------------ | :---------- |
| NORMAL | Not Applicable | Standard process that does not require a prefix to simulate a payout. |
| FAILED | `FAILED` | This flow is used to simulate a failure on the banking partner side such as the payment scheme rejecting the payout. |
| RETURN | `RETURN` | This process simulates a successful payout, followed by a return event.In this scenario, the payout initially appears to be successful, as it has been submitted to the beneficiary's bank. However, the bank ultimately rejects the payment, or the customer decides to reverse the transaction. |

To test the previously mentioned behaviors in the sandbox environment, you can input the **customer reference prefix** from the flow you want to simulate. If you do not include a customer reference prefix, the system will default to the `NORMAL` flow as the expected behavior. For instance, if you wish to simulate a failed flow when requesting a payout, the reference should be formatted as `FAILED<my-own-reference>`.

---

## Add Ethereum wallet for ETH and USDT/USDC

To simulate payment transactions using the Payments API in sandbox, set up a MetaMask Ethereum wallet and add test tokens to it. This process allows you to experiment with and verify the API's functionality in a sandbox environment.

## Install MetaMask extension

1. [Install Metamask extension](https://metamask.io/download/) for your browser, Chrome is recommended. Follow the steps carefully and save your password and recovery codes in a safe place.

![](/img/bvnk/test-integration/metamask-1-install.png)

2. Optional. Pin the extension to your browser by clicking the puzzle icon > pin icon next to MetaMask.

![](/img/bvnk/test-integration/metamask-2-pin.png)

3. Click the fox-head icon to open your MetaMask wallet and log in.

![](/img/bvnk/test-integration/metamask-3-open.png)

4. By default, the Ethereum Mainnet network is selected. To change to another one, click the **Networks** dropdown at the top.

![](/img/bvnk/test-integration/metamask-4-networks.png)

5. The **Select a network** tab opens. Click the slider to show test networks, then select **Sepolia**.

![](/img/bvnk/test-integration/metamask-5-testnet.png)

6. The SepoliaETH token name indicates that you are on the Sepolia Network. Now you can receive funds and test Ethereum transactions in the sandbox.

![](/img/bvnk/test-integration/metamask-6-sepolia.png)

***

## Add tokens

<Tabs>
  <TabItem value="usdt" label="USDT">

  To add USDT ERC20 tokens to the wallet, do the following:

  1. Import tokens by adding the smart contract to your wallet. For that, in your MetaMask wallet, on the **Tokens** tab, click **Import tokens**.

  	![](/img/bvnk/test-integration/metamask-7-import-tokens.png)

  2. The import tokens screen opens. In the **Token contract address** field, add `0x3429519eE7cDbB13B49161F1Eb6e1B026939113A`.

     The **Token symbol** and **Token Decimal** are auto-completed. If not, enter **USDT** and **6** respectively.

  	![](/img/bvnk/test-integration/metamask-8-token-contract.png)

  3. When the prompt appears, click **Import**.

  	![](/img/bvnk/test-integration/metamask-9-import-prompt.png)

  USDT ERC20 is now added to your wallet, and you can complete USDT transactions once you have received test funds.

  ![](/img/bvnk/test-integration/metamask-10-usdt-added.png)

  ETH and USDT ERC20 on the Sepolia Network are now available on your MetaMask wallet. Get some test funds loaded and happy testing!

  ![](/img/bvnk/test-integration/metamask-11-complete.png)

  </TabItem>
  <TabItem value="usdc" label="USDC">

  To add USDC ETHEREUM tokens to the wallet, do the following:

  1. Import tokens by adding the smart contract to your wallet. For that, in your MetaMask wallet, on the **Tokens** tab, click **Import tokens**.

  	![](/img/bvnk/test-integration/usdc-import-tokens.png)

  2. The import tokens screen opens. Configure the fields as follows:

     - **Token contract address**: `0x6988F886eC2706893d37eE169722DdB02135eF78`
     - **Token symbol**: USDC

  	![](/img/bvnk/test-integration/usdc-add-address.png)

  	Click **Next**.

  3. When the prompt appears, click **Import**.

  	![](/img/bvnk/test-integration/usdc-import-confirmation.png)

  USDC ETHEREUM is now added to your wallet, and you can complete USDC transactions once you have received test funds.

  ![](/img/bvnk/test-integration/usdc-token-imported.png)

  </TabItem>
</Tabs>

---

## Add TronLink wallet for TRX and USDT

To simulate payment transactions using the Payments API in sandbox, set up a TronLink wallet and add test tokens to it. This process allows you to experiment with and verify the API's functionality in a sandbox environment.

## Install TronLink extension

1. Go to [Chrome Web Store](https://chromewebstore.google.com/detail/tronlink/ibnejdfjmmkpcnlpebklmnkoeoihofec), and on the TronLink extension page, click **Add to Chrome**.
2. Optional. Pin the extension to your browser by clicking the **Puzzle** icon > **Pin** icon next to **TronLink**.

   ![](/img/bvnk/test-integration/tronlink-1-pin.png)

3. Click the **TronLink** icon to open the extension, and then click **Create Wallet**. Follow the steps carefully and save your password and recovery codes in a safe place.

   ![](/img/bvnk/test-integration/tronlink-2-create-wallet.png)

4. By default, the Tron Mainnet network is selected. To change to another one, click the **Networks** dropdown at the top.

   ![](/img/bvnk/test-integration/tronlink-3-networks.png)

5. The **Networks** tab opens. Select **TRON Nile Testnet**.

   On the first run, the test networks are hidden. To enable them, go to **Settings** > **Networks** and click the **Show Test Networks** toggle.

   ![](/img/bvnk/test-integration/tronlink-4-testnet.png)

   The **TRON Nile Testnet** (TRX) at the top indicates you are now on the Nile TestNet. Now you can receive funds and test transactions in the sandbox.

   ![](/img/bvnk/test-integration/tronlink-5-nile-testnet.png)

***

## Add TRON to your wallet

To activate your TronLink account, add TRON test coins to it. For that,

1. In the TronLink extension, copy the wallet address.

   ![](/img/bvnk/test-integration/tronlink-nile-testnet-address.png)

2. Go to [Nile Testnet](https://nileex.io/join/getJoinPage) and enter your TronLink wallet address.

![](/img/bvnk/test-integration/tronlink-6-nile-testnet-faucet.png)

   2000 test Tron coins will be sent to your wallet.

## Add BVNK USDT TRC20

To add USDT TRC20 tokens to your TronLink wallet, import the tokens created by BVNK by adding the smart contract to your wallet.

To add a smart token, do the following:

1. Go to [Tronscan](https://nile.tronscan.org/), and click **Connect Wallet** on the top right.

   ![](/img/bvnk/test-integration/tronlink-7-connect-wallet.png)

2. In the **Search** bar, enter `TY1DBj7Ys1bDcK37kwATaQpHxdTCnYrr1f`.\
   The **LAYER1** token appears. This is a BVNK test USDT token that can be used as a USDT TRC20.

   ![](/img/bvnk/test-integration/tronlink-8-token-search.png)

3. Go to the **Contract** tab > **Write Contract**, and select **mint**.

   Enter the amount of tokens to receive (for example, 50.000), and click **Send**

   ![](/img/bvnk/test-integration/tronlink-10-mint.png)

4. The **Trigger Smart Contract** window will appear in the browser. Click **Sign**.

   ![](/img/bvnk/test-integration/tronlink-11-sign.png)

   
5. Once the transaction has gone through, open your TronLink extension in Chrome, and next to **Assets**, click the "**+**" sign.

![](/img/bvnk/test-integration/tronlink-12-add-assets.png)

6. In the **Assets** list, in the **New** section, select **LAYER1**, and click the "**+**" sign.

   ![](/img/bvnk/test-integration/tronlink-13-select-layer1.png)

You now have BVNK LAYER 1 (USDT TRC20) Testnet tokens that can be used in transactions via API and the BVNK portal for both payments in and out.

You've successfully acquired BVNK LAYER 1 (USDT TRC20) Testnet tokens. These tokens are designed for testing purposes and can be utilised in various ways:

* Simulate transactions through the API.
* Test payment flows within the BVNK Portal.
* Experiment with both incoming and outgoing payments.

This allows you to thoroughly evaluate the platform's functionality in a risk-free environment before engaging with real assets.

---

## Create an internal transfer

This endpoint is used to facilitate internal transfers. You can transfer both fiat and crypto funds.

The transfer can be initiated according to the following scenarios:

- Between a partner and a customer
- Between customers of the same partner

:::note
This capability is only available as part of the [Virtual Account use cases](/bvnk/use-cases/virtual-accounts/va-overview) and cannot be used separately.
:::

## Initiate a transfer

1. Create a transfer by sending the [`POST /payment/v2/transfers`](/bvnk/api-explorer/endpoints/transfer-create-v-2) request with the following body parameters:

   ```json Request
   {
     "reference": "REF558628",
     "walletId": "a:25032550863140:zKwR3P9:1",
     "amount": 111,
     "currency": "USD",
     "beneficiary": {
       "walletId": "a:25021926815866:4jlPfFg:1",
     },
     "metadata": {
       "memberId": "987654321"
     }
   }
   ```

   For the detailed description of fields, see the API Reference.

2. To check the status of the transfer and know when it's completed successfully or failed, you can

   * Listen to the transfer webhook.
   * Send the [`GET /payment/v2/transfers/{transferId}`](/bvnk/api-explorer/endpoints/transfer-read-v-2) request.

   In the successful response, you receive the details on the transfer and its status.

   ```json Response
   {
     "id": "ae29acc3-c54a-11f0-90b6-21c3f364ff25",
     "reference": "REF558628",
     "status": "COMPLETED",
     "type": "payment:transfer",
     "method": "BOOK",
     "fees": {
       "processingFee": {
         "amount": 0,
         "currency": "USD"
       }
     },
     "originator": {
       "amount": 1.11,
       "currency": "USD",
       "entity": {
         "legalName": "3Com",
         "type": "COMPANY"
       },
       "walletId": "a:25032550863140:zKwR3P9:1"
     },
     "beneficiary": {
       "amount": 1.11,
       "currency": "USD",
       "entity": {
         "legalName": "4COM",
         "type": "COMPANY"
       },
       "walletId": "a:25021926815866:4jlPfFg:1"
     },
     "metadata": {
       "memberId": "987654321"
     },
     "createdAt": "2025-11-19T13:21:38.870144Z",
     "updatedAt": "2025-11-19T13:21:38.870144Z",
   }
   ```

## Transfer webhook

You can listen to this webhook to get notified when the status of the transfer changes. See the [Transfer webhook](/bvnk/api-explorer/bvnk-webhooks/payment-transfer-status-change-v-2/) documentation for more details.

---

## Currencies

BVNK supports a wide range of currencies which is always evolving. This page provides a comprehensive overview of all currently supported currencies and their specifications.

## Fiat currencies

| Currency Code | Currency Name | Account Number Format (Local) | Account Number Format (SWIFT) | Use for | Decimals |
| :-----------: | :------------:| :----------------:| :----------------:| :------:| :------: |
| USD | US Dollar | ABA, CUBIX | Any format (e.g., IBAN) | Deposits / Payouts | 2 |
| EUR | Euro | IBAN | Any format (e.g., IBAN) | Deposits / Payouts | 2 |
| GBP | British Pound | IBAN, SCAN | Any format (e.g., IBAN) | Deposits / Payouts | 2 |

## Crypto currencies

Crypto transactions must obtain enough confirmations on the relevant blockchain before they are considered complete. BVNK will wait for the `Required confirmations` detailed below to be reached.

:::info
The available cryptocurrencies depend on the specific jurisdiction.
:::

<Tabs>
<TabItem value="eeacustomers" label="EEA Customers" default>

Currency Code
Currency Name
Network
Required confirmations
Use for
Decimals

Stablecoins

EURC
Euro Coin
ETHEREUM
12
Deposits / Payouts
6

USDC
USD Coin
ARBITRUM
300
Deposits / Payouts
6

USDC
USD Coin
BASE
10
Deposits / Payouts
6

USDC
USD Coin
BINANCE
4
Deposits / Payouts
6

USDC
USD Coin
ETHEREUM
4
Deposits / Payouts
6

USDC
USD Coin
POLYGON
4
Deposits / Payouts
6

USDC
USD Coin
SOLANA
32
Deposits / Payouts
6

USDG
Global Dollar
SOLANA
32
Deposits / Payouts
9

Other

BNB
Binance Coin
BINANCE
4
Deposits / Payouts
12

BTC
Bitcoin

1
Deposits / Payouts
8

ETH
Ethereum

4
Deposits / Payouts
8

LTC
Litecoin

4
Deposits / Payouts
8

POL
Polygon
POLYGON
4
Deposits / Payouts
8

SOLANA
Solana

32
Deposits / Payouts
8

TRX
Tronix

4
Deposits / Payouts
5

XRP
Ripple

When includedin validated ledger
Deposits / Payouts
6

</TabItem>
<TabItem value="row" label="RoW Customers" default>

Currency Code
Currency Name
Network
Required confirmations
Use for
Decimals

Stablecoins

EURC
Euro Coin
ETHEREUM
12
Deposits / Payouts
6

PYUSD
PayPal USD
ETHEREUM
4
Deposits / Payouts
6

USDC
USD Coin
ARBITRUM
300
Deposits / Payouts
6

USDC
USD Coin
BASE
10
Deposits / Payouts
6

USDC
USD Coin
BINANCE
4
Deposits / Payouts
6

USDC
USD Coin
ETHEREUM
4
Deposits / Payouts
6

USDC
USD Coin
POLYGON
4
Deposits / Payouts
6

USDC
USD Coin
SOLANA
32
Deposits / Payouts
6

USDG
Global Dollar
SOLANA
32
Deposits / Payouts
9

USDT
Tether USD
BINANCE
4
Deposits / Payouts
6

USDT
Tether USD
ETHEREUM
4
Deposits / Payouts
6

USDT
Tether USD
POLYGON
4
Deposits / Payouts
6

USDT
Tether USD
TRON
4
Deposits / Payouts
6

Other

BNB
Binance Coin
BINANCE
4
Deposits / Payouts
12

BTC
Bitcoin

1
Deposits / Payouts
8

ETH
Ethereum

4
Deposits / Payouts
8

LTC
Litecoin

4
Deposits / Payouts
8

POL
Polygon
POLYGON
4
Deposits / Payouts
8

SOLANA
Solana

32
Deposits / Payouts
8

TRX
Tronix

4
Deposits / Payouts
5

XRP
Ripple

When includedin validated ledger
Deposits / Payouts
6

</TabItem>
<TabItem value="uscustomers" label="US Customers">

Currency Code
Currency Name
Network
Required confirmations
Use for
Decimals

Stablecoins

EURC
Euro Coin
ETHEREUM
12
Deposits / Payouts
6

PYUSD
PayPal USD
ETHEREUM
12
Deposits / Payouts
6

USDC
USD Coin
ARBITRUM
300
Deposits / Payouts
6

USDC
USD Coin
BASE
10
Deposits / Payouts
6

USDC
USD Coin
BINANCE
4
Deposits / Payouts
6

USDC
USD Coin
ETHEREUM
4
Deposits / Payouts
6

USDC
USD Coin
POLYGON
4
Deposits / Payouts
6

USDC
USD Coin
SOLANA
32
Deposits / Payouts
6

USDG
Global Dollar
SOLANA
32
Deposits / Payouts
9

USDT
Tether USD
BINANCE
4
Deposits / Payouts
6

USDT
Tether USD
ETHEREUM
4
Deposits / Payouts
6

USDT
Tether USD
POLYGON
4
Deposits / Payouts
6

USDT
Tether USD
TRON
4
Deposits / Payouts
6

Other

BNB
Binance Coin
BINANCE
12
Deposits / Payouts
12

BTC
Bitcoin

1
Deposits / Payouts
8

ETH
Ethereum

4
Deposits / Payouts
8

LTC
Litecoin

12
Deposits / Payouts
8

POL
Polygon
POLYGON
12
Deposits / Payouts
8

SOLANA
Solana

32
Deposits / Payouts
8

TRX
Tronix

4
Deposits / Payouts
5

XRP
Ripple

1
Deposits / Payouts
6

</TabItem>
<TabItem value="sandbox" label="Sandbox">

Currency Code
Currency Name
Network
Required confirmations
Testnet
Use for
Decimals

Stablecoins

USDC
USD Coin
ETHEREUM
4
Sepolia
Deposits / Payouts
6

USDC
USD Coin
POLYGON
4
Amoy
Deposits / Payouts
6

USDT
Tether USD
ETHEREUM
4
Sepolia
Deposits / Payouts
6

USDT
Tether USD
TRON
4
Nile
Deposits / Payouts
6

Other

ETH
Ethereum

4
Sepolia
Deposits / Payouts
8

TRX
Tronix

4
Nile
Deposits / Payouts
5

</TabItem>
</Tabs>

---

## Date and time

Date and times are encoded into UNIX epoch timestamps, including milliseconds, for example, `1566203005000` is `Monday, August 19, 2019 8:23:25 AM`.

---

## Glossary

<center> [A](#a) &bull; [B](#b) &bull; [C](#c) &bull; [D](#d) &bull; [E](#e) &bull; [F](#f) &bull; [H](#h) &bull; [I](#i) &bull; [K](#k) &bull; [M](#m) &bull; [N](#n) &bull; [O](#o) &bull; [P](#p) &bull; [Q](#q) &bull; [R](#r) &bull; [S](#s) &bull; [T](#t) &bull; [V](#v) &bull; [W](#w) </center>

## A

### Account

A registered entity on the BVNK platform that manages wallets, processes payments, and oversees API credentials. In the Direct model, an account identifies the business contracting directly with BVNK. See [Select your delivery model](../../get-started/delivery-models).

### Address

Also, a blockchain address or a crypto address. A unique identifier on a specific blockchain network where digital assets can be sent or received. See [Integrate Channels](../../use-cases/stablecoin-payments-for-platforms/create-channel).

### Associate

A person linked to a business customer during onboarding, such as a director, ultimate beneficial owner (UBO), or authorised representative. At least one representative, UBO, and a director must be specified when onboarding a business customer. See [Business requirements](../../get-started/compliance-requirements/embedded-compliance-requirements-businesses).

## B

### Balance

The amount of funds available in a wallet. A balance includes the currency code and the current value. Each wallet maintains its own balance, which is updated as transactions are processed. See [List Wallet Balances](../../api-explorer/endpoints/wallet-balance-list).

### Beneficiary

The entity that receives the transaction. Can be an individual or a business. See [Verify Beneficiary's Name](../../api-explorer/endpoints/verify-beneficiary).

### Blockchain address

The destination for a crypto payout. A blockchain address is a unique identifier on a specific blockchain network where digital assets are sent. See [Initiate Payout](../../api-explorer/endpoints/payout-create-v-2).

## C

{/* ### Card

A virtual stablecoin-backed card linked to wallet balances, enabling spend. Cards are available as part of the Embedded Express model and are issued to customers by default. See [Enable Express wallets for customers](../../use-cases/xpress-store-funds/express-overview). */}

### CDD

Customer due diligence is the process of collecting and verifying customer information during onboarding. This includes employment status, source of funds, intended use of account, and politically exposed person (PEP) status. See [Individual requirements](../../get-started/compliance-requirements/compliance-requirements-for-individuals2).

### Channel

A dedicated, permanent, and unique address that can receive crypto funds at any time. Opposed to a temporary address that can be used for a single transaction. See [Integrate Channels](../../use-cases/stablecoin-payments-for-platforms/create-channel) and [Create Channel](../../api-explorer/endpoints/channel-create).

### Crypto

A cryptocurrency is a digital currency that uses cryptography for security. It is decentralised and operates independently of a central bank. See [Currencies](../currencies).

### Crypto gateway

BVNK's crypto payment processing service that handles the creation and management of crypto payments through Payment Links. It supports pay-ins, payouts, and fiat-to-crypto and crypto-to-fiat currency conversions. See [Create Payment](../../api-explorer/endpoints/payment-create).

### Customer

Previously called Embedded Partner Customer (EPC). Legacy terms also include nested or underlying customers.

An individual or business that uses BVNK's services through a partner. See [Create a customer](../../get-started/create-embedded-partner-customer/creating-an-embedded-customer-company-api).

### Customer fee

An optional markup that a partner adds to customer transactions. Customer fees are distinct from transaction amounts and BVNK processing fees, and are withdrawn from the customer's wallet to the partner's designated fee wallet. See [Charge customer fees](../../get-started/charge-customer-fees).

## D

### Digital asset

A cryptocurrency asset or a stablecoin. See [Currencies](../currencies).

### Direct model

A delivery model where BVNK has a direct relationship with a [partner](#partner). See [Select your delivery model](../../get-started/delivery-models).

## E
{/*
### Embedded express

A BVNK-hosted, co-branded wallet experience delivered via link or SDK. BVNK owns the regulated user flows, and partners get rapid rollout with limited customisation and no write actions on user accounts. See [Enable Express wallets for customers](../../use-cases/xpress-store-funds/express-overview). */}

### Embedded model

A delivery model where BVNK embeds its services into a partner's platform. See [Select your delivery model](../../get-started/delivery-models).

### Endpoint

Also called an API endpoint. A URL used to send requests to BVNK's servers. See [API overview](../../api-explorer/api-overview/overview).

## F

### Fiat

A government-issued currency that is not backed by a physical commodity, such as USD, EUR, or GBP. BVNK supports fiat currencies for pay-ins, payouts, and conversions to and from crypto. See [Currencies](../currencies).

## H

### Hosted payments page

Or Hosted page. A hosted checkout experience embedded in your platform interface. See [Integrate Payment Links](../../use-cases/stablecoin-payments-for-platforms/get-payment).

## I

### Idempotency

A property of certain API endpoints that lets you safely retry requests without duplicating actions. To use idempotency, include a unique `X-Idempotency-Key` header (or `Idempotency-Key` for v2 endpoints) with your request. Only successful requests are cached; failed requests may be retried without risk of conflict. See [Idempotency](../../api-explorer/api-overview/idempotency).

## K

### KYC/KYB

Know your customer (KYC) and know your business (KYB). Verification processes that BVNK performs to confirm the identity and legitimacy of individual and business customers during onboarding. These checks are a regulatory requirement and a critical component of the risk management process. See [Individual requirements](../../get-started/compliance-requirements/compliance-requirements-for-individuals2) and [Business requirements](../../get-started/compliance-requirements/embedded-compliance-requirements-businesses).

## M

### Mass payouts

A function enabling you to upload a CSV file and trigger multiple payouts in a single batch.

### Merchant

The legacy term for a partner that uses BVNK's services directly. Same as [Account](#account). See [Create Merchant ID](../../api-explorer/endpoints/merchant-id-create).

### Metadata

Additional information about a transaction included in a request or response. See [Metadata](../../api-explorer/api-overview/metadata).

```json Metadata Example
{
    "metadata": {
        "orderId": "PO-2025-001",
        "internalUserId": "user-456",
        "reason": "Customer withdrawal"
    }
}
```

## N

### Network

A blockchain protocol used to process crypto transactions. BVNK supports multiple networks, including Ethereum, Tron, Solana, and Bitcoin. The network affects transaction speed, fees, and confirmation requirements. See [Currencies](../currencies).

## O

### Onboarding

The process of setting up a customer to use BVNK's services integrated into the [partner](#partner)'s platform. The onboarding process typically involves a collaborative review by BVNK's Compliance and Onboarding teams to ensure full adherence to Know Your Business (KYB) standards. See [Gather compliance data for onboarding](../../get-started/create-embedded-partner-customer/onboard-epc).

### On-ramp

A service that allows you to buy crypto with fiat currency. See [Convert funds (on-ramp)](../../use-cases/on-off-ramp/on-ramp-overview).

### Originator

The entity that initiates the transaction. For example, a customer who wants to buy crypto with fiat currency. See [Provide additional party information](../../use-cases/stablecoin-payments-for-platforms/provide-user-information-for-payments).

## P

### Partner

Formerly, an Embedded Partner or EP. Anyway, that's... You for BVNK.

A Business that embeds BVNK's services into their platform for themselves or their customers. See [Add customers](../../get-started/create-embedded-partner-customer/creating-an-embedded-customer-company-api).

### Pay-in

A request to move fiat funds from a customer to your wallet. See [Receive payments](../../use-cases/stablecoin-payments-for-platforms/get-payment-overview).

### Payout

A request to move crypto funds from your wallet to the beneficiary. See [Send stablecoin payments](../../use-cases/stablecoin-payments-for-platforms/payout-overview) and [Initiate Payout](../../api-explorer/endpoints/payout-create-v-2).

### Payment link

A link created and shared via the BVNK API to collect crypto pay‑ins and process payouts. See [Integrate Payment Links](../../use-cases/stablecoin-payments-for-platforms/get-payment) and [Create Payment](../../api-explorer/endpoints/payment-create).

### Payments API

BVNK's API for integrating crypto and fiat payments into a partner's platform. The Payments API supports pay-ins, payouts, conversions, and channels. See [API overview](../../api-explorer/api-overview/overview).

### Peg

Also, pegged. A fixed value relationship between a stablecoin and a fiat currency, where the stablecoin maintains a stable exchange rate relative to the fiat currency. For example, USDC is pegged to USD at a 1:1 ratio.

### Processing fee

A fee charged by BVNK for processing the transaction.

## Q

### Quote

A price estimate for converting currency between wallets. A quote includes the exchange rate, the amount to be converted, and an expiry time. You can create an estimate quote to preview the conversion, or create and accept a quote to execute the conversion. See [Create Quote](../../api-explorer/endpoints/quote-create).

## R

{/* ### Rewards

A built-in ability for wallet balances to automatically accrue yield. Rewards are enabled by default for all Embedded Express wallets and require no additional setup. Partners can configure how reward income is shared with their customers. See [Enable Express wallets for customers](../../use-cases/xpress-store-funds/express-overview). */}

### Refund

A request to reverse a payment. It is initiated by the [originator](#originator) and is processed by the [beneficiary](#beneficiary). See [Refund payments](../../use-cases/virtual-accounts/refund-payments) and [Refund Pay-in](../../api-explorer/endpoints/refund-payin).

### Reference

A unique identifier for a transaction. BVNK may use the following fields to reference a transaction:

- `paymentReference`: Actual description of the payment. The reference text is propagated along with the transfer, so the beneficiary could see it.
- `customerReference`: Unique identifier of the customer. If the underlying customer is provided, this field would contain `customerId` called `customerReference` on the BVNK side.
- `transactionReference`: Unique transaction ID generated by BVNK.

## S

### Stablecoin

A cryptocurrency that is pegged to a fiat currency or a commodity. For example, USDC, USDT, etc. See [Currencies](../currencies).

## T

### Transaction

A record of a financial operation processed through BVNK, such as a pay-in, payout, fee, internal transfer, or channel deposit. Each transaction includes an amount, currency, status, and a unique identifier. See [Reconcile transactions](../../reconciliation/reconcile-transactions) and [List Transactions](../../api-explorer/endpoints/wallet-list-transactions).

### Transfer

Also, internal transfer. A transfer between two wallets within the same account. See [Create internal transfer](../../use-cases/create-internal-transfer) and [API endpoint: Create Internal Transfer](../../api-explorer/endpoints/transfer-create).

### Travel rule

A regulatory requirement under the EU's MiCA regulation that extends traditional payment information-sharing standards to crypto and stablecoin transactions. The travel rule requires collecting and sharing information about the parties involved in a transaction, such as the originator and beneficiary. See [Provide additional party information](../../use-cases/stablecoin-payments-for-platforms/provide-user-information-for-payments).

## V

### Virtual Account

A BVNK-managed payment account that includes a virtual IBAN (vIBAN) and a wallet. Virtual accounts are used to send, hold, and receive funds in one place. See [Virtual accounts overview](../../use-cases/virtual-accounts/va-overview).

### Verification of Payee (VoP)

VoP is a Single Euro Payments Area (SEPA) service that verifies a beneficiary's name against their IBAN to prevent fraud and errors. See [Send fiat payments](../../use-cases/virtual-accounts/initiate-payment-2#request-vop).

## W

### Wallet

A container that stores value and maintains balances in either fiat or crypto. You can connect various payment instruments, such as crypto addresses, to a wallet. Wallets are the core building block for processing payments, conversions, and transfers in BVNK. See [Create a wallet](../../get-started/create-wallet) and [Create Wallet](../../api-explorer/endpoints/create-customer-wallet).

### Wallet profile

A configuration that defines the currency codes and payment methods available for a wallet. Wallet profiles are assigned when a wallet is created and determine which payment rails the wallet can use. See [Create a wallet with a profile](../../get-started/create-wallet#create-a-wallet-with-a-profile) and [List Wallet Profiles](../../api-explorer/endpoints/wallet-profiles).

### Webhook

A URL that allows you to receive notifications from BVNK. See [Create webhook listener](../../get-started/create-webhook-listener) for more information.

---

## Industry references

This is a definitive list of industries and sub-industries which can be included in the payload when creating a customer.

## Retrieve industry references

To get the complete list of industries, send the [`GET /platform/v1/accounts/industries`](../../api-explorer/endpoints/get-industries) request.

In the response, you receive the existing industry reference.

## List of references

The JSON response contains the following attributes:

**Parent industry category**:

| Attribute | Description                                                                            |
| --------- | -------------------------------------------------------------------------------------- |
| `name`      | Name of the industry. For example, "Accommodation and food services"                   |
| `children`  | Array of sub-industries associated with the parent one.                                |

**Children categories**:

| Attribute |  Description                                                                    |
| --------- |  ------------------------------------------------------------------------------ |
| `reference` |  Unique identifier of the sub-industry. "30ea15fc-06d8-11ef-b6e1-027612b7f6b5". |
| `name`      |  Name of the sub-industry. For example,"Food/Beverages".                        |

```json
{
    "name": "Accommodation and food services",
    "children": [
        {
            "reference": "30ea15fc-06d8-11ef-b6e1-027612b7f6b5",
            "name": "Food/Beverages"
        },
        {
            "reference": "30ea5818-06d8-11ef-b6e1-027612b7f6b5",
            "name": "Supermarkets/Convenience Store"
        }
    ]
}
```

The following table contains all industry references for both sandbox and production environments with their corresponding NACE and NAICS codes:

| Name | Sandbox Reference | Production Reference | NACE Code (Related NACE 1, NACE 2, NACE 3) | NAICS Code |
|------|-------------------|----------------------|-----------|------------|
| **Accommodation and food services** | | | | |
| Food/Beverages | 30ea15fc-06d8-11ef-b6e1-027612b7f6b5 | 56e66027-06fa-11ef-bbf8-02d3d923cf2b | 1089 (4634, 5621) | 311 |
| Hospitality | 30ea17fd-06d8-11ef-b6e1-027612b7f6b5 | 56e66349-06fa-11ef-bbf8-02d3d923cf2b | 5510 (5610, 5630, 5520) | 72 |
| Recreational Facilities/Services (Spas, Saunas etc) | 30ea1a02-06d8-11ef-b6e1-027612b7f6b5 | 56e66697-06fa-11ef-bbf8-02d3d923cf2b | 9329 (9313) | 7139 |
| Supermarkets/Convenience Store | 30ea5818-06d8-11ef-b6e1-027612b7f6b5 | 56e66ce7-06fa-11ef-bbf8-02d3d923cf2b | 4711 (4639, 4729) | 445 |
| **Adult** | | | | |
| Escort/Sex workers advertising | 30eaed17-06d8-11ef-b6e1-027612b7f6b5 | 56e6729e-06fa-11ef-bbf8-02d3d923cf2b | 9609 (7312) | 81299 |
| High Street Sex Shop | 30ea7552-06d8-11ef-b6e1-027612b7f6b5 | 56e66f7b-06fa-11ef-bbf8-02d3d923cf2b | 4778 (4761) | 459999 |
| Massage Parlours | 30eb0852-06d8-11ef-b6e1-027612b7f6b5 | 56e673ed-06fa-11ef-bbf8-02d3d923cf2b | 9604 (9602) | 81219 |
| Online Adult Services | 30ebb7bc-06d8-11ef-b6e1-027612b7f6b5 | 56e6790e-06fa-11ef-bbf8-02d3d923cf2b | 9609 (6312) | 81299 |
| Online Sex Shop | 30eab905-06d8-11ef-b6e1-027612b7f6b5 | 56e67159-06fa-11ef-bbf8-02d3d923cf2b | 4791 (4649) | 459999 |
| Phone Chat | 30eb1ccf-06d8-11ef-b6e1-027612b7f6b5 | 56e67536-06fa-11ef-bbf8-02d3d923cf2b | 9609 (8220) | 561422 |
| Pornographic video sharing and pornography website | 30eb3d15-06d8-11ef-b6e1-027612b7f6b5 | 56e6767c-06fa-11ef-bbf8-02d3d923cf2b | 6312 (5911) | 51929 |
| Strip Club | 30eb7b12-06d8-11ef-b6e1-027612b7f6b5 | 56e677c4-06fa-11ef-bbf8-02d3d923cf2b | 9329 (5630) | 7139 |
| **Arms and Defense** | | | | |
| Manufacture and supply of military fighting vehicles | 30ec17af-06d8-11ef-b6e1-027612b7f6b5 | 56e67ba5-06fa-11ef-bbf8-02d3d923cf2b | 3040 (2910) | 336992 |
| Manufacture and supply of weapons and ammunition | 30ec4337-06d8-11ef-b6e1-027612b7f6b5 | 56e67cef-06fa-11ef-bbf8-02d3d923cf2b | 2540 (2529, 2051) | 332994 |
| Military equipment | 30ec7fb7-06d8-11ef-b6e1-027612b7f6b5 | 56e67e4e-06fa-11ef-bbf8-02d3d923cf2b | 3040 (2599) | 3369 |
| **Cash Intensive Business and High Value Dealers** | | | | |
| Art Market/Art Collectables/Galleries and Antiques | 30ed78c0-06d8-11ef-b6e1-027612b7f6b5 | 56e6a0eb-06fa-11ef-bbf8-02d3d923cf2b | 4778 (9003) | 459920 |
| Auctioneers | 30ee7396-06d8-11ef-b6e1-027612b7f6b5 | 56e6a8e3-06fa-11ef-bbf8-02d3d923cf2b | 8299 (4779) | 4251 |
| Builders/Building materials | 30ee9302-06d8-11ef-b6e1-027612b7f6b5 | 56e6aa27-06fa-11ef-bbf8-02d3d923cf2b | 4752 (4673, 2361) | 236 |
| Cash and Valuables-in-Transit | 30ecbbde-06d8-11ef-b6e1-027612b7f6b5 | 56e680d8-06fa-11ef-bbf8-02d3d923cf2b | 8010 (8020) | 56161 |
| Construction | 30ed4a59-06d8-11ef-b6e1-027612b7f6b5 | 56e69f22-06fa-11ef-bbf8-02d3d923cf2b | 4120 (4399, 7111, 4312) | 23 |
| Fast Moving consumer goods | 30ef0945-06d8-11ef-b6e1-027612b7f6b5 | 56e6aeb1-06fa-11ef-bbf8-02d3d923cf2b | 4639 (4649) | 45 |
| Jewellery/Gold and Diamonds Dealers | 30ecf51a-06d8-11ef-b6e1-027612b7f6b5 | 56e69b9f-06fa-11ef-bbf8-02d3d923cf2b | 4777 (3212, 4648) | 42394 |
| Motor Vehicles and Boat Traders | 30edc563-06d8-11ef-b6e1-027612b7f6b5 | 56e6a25a-06fa-11ef-bbf8-02d3d923cf2b | 4511 (4540) | 441 |
| Nail Bars/Salon | 30ede2a4-06d8-11ef-b6e1-027612b7f6b5 | 56e6a3a6-06fa-11ef-bbf8-02d3d923cf2b | 9602 | 81211 |
| Precious metals dealers that purchase metals from pawnbrokers and other secondary sources | 30ece137-06d8-11ef-b6e1-027612b7f6b5 | 56e68243-06fa-11ef-bbf8-02d3d923cf2b | 4672 (2441) | 42394 |
| Scrap Metals Dealers/Warehouse | 30ee09b8-06d8-11ef-b6e1-027612b7f6b5 | 56e6a4ea-06fa-11ef-bbf8-02d3d923cf2b | 4677 (3831, 3811) | 42393 |
| Storage facilities | 30ee2985-06d8-11ef-b6e1-027612b7f6b5 | 56e6a62e-06fa-11ef-bbf8-02d3d923cf2b | 5210 (4941, 5320) | 4931 |
| Tour and Travel companies | 30eebc77-06d8-11ef-b6e1-027612b7f6b5 | 56e6ab63-06fa-11ef-bbf8-02d3d923cf2b | 7912 (7911, 7990) | 5615 |
| Used motor vehicles dealers or auctions | 30eed232-06d8-11ef-b6e1-027612b7f6b5 | 56e6acaa-06fa-11ef-bbf8-02d3d923cf2b | 4511 (4519) | 4411 |
| Wholesale Duty Goods (e.g. Alcohol and tobacco) | 30ee3a08-06d8-11ef-b6e1-027612b7f6b5 | 56e6a768-06fa-11ef-bbf8-02d3d923cf2b | 4634 (4635) | 424 |
| **Charities/Non-profit organisation** | | | | |
| Animal Charities | 30ef5367-06d8-11ef-b6e1-027612b7f6b5 | 56e6b416-06fa-11ef-bbf8-02d3d923cf2b | 9499 (7500, 9104) | 813312 |
| Art and Culture Charities | 30ef79aa-06d8-11ef-b6e1-027612b7f6b5 | 56e6b54d-06fa-11ef-bbf8-02d3d923cf2b | 9499 (9001, 9002) | 813219 |
| Education Charities | 30f02713-06d8-11ef-b6e1-027612b7f6b5 | 56e6b695-06fa-11ef-bbf8-02d3d923cf2b | 9499 (8559, 8560) | 813219 |
| Environment Charities | 30f044ce-06d8-11ef-b6e1-027612b7f6b5 | 56e6b7fc-06fa-11ef-bbf8-02d3d923cf2b | 9499 (3900) | 813312 |
| Health Charities | 30f0572f-06d8-11ef-b6e1-027612b7f6b5 | 56e6b960-06fa-11ef-bbf8-02d3d923cf2b | 9499 (8690) | 813212 |
| Humanitarian support | 30ef4384-06d8-11ef-b6e1-027612b7f6b5 | 56e6b2c0-06fa-11ef-bbf8-02d3d923cf2b | 8899 (8810) | 6242 |
| International Charities | 30f06a53-06d8-11ef-b6e1-027612b7f6b5 | 56e6baa3-06fa-11ef-bbf8-02d3d923cf2b | 9499 (8899) | 8133 |
| Political Charities | 30f0a95b-06d8-11ef-b6e1-027612b7f6b5 | 56e6bbd8-06fa-11ef-bbf8-02d3d923cf2b | 9492 (9499) | 813319 |
| Religious Charities | 30f0abe3-06d8-11ef-b6e1-027612b7f6b5 | 56e6bd0a-06fa-11ef-bbf8-02d3d923cf2b | 9491 (9499) | 8131 |
| **Crowdfunding** | | | | |
| Donation or rewards platforms | 30f0cc57-06d8-11ef-b6e1-027612b7f6b5 | 56e6bfca-06fa-11ef-bbf8-02d3d923cf2b | 6311 (8299) | 813219 |
| Investment, equity or debt platforms | 30f1213b-06d8-11ef-b6e1-027612b7f6b5 | 56e6c242-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6611) | 5239 |
| Loan-based or peer-to-peer platforms | 30f13f60-06d8-11ef-b6e1-027612b7f6b5 | 56e6c37a-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6492) | 5222 |
| Non-Profit crowdfunding platform | 30f113b0-06d8-11ef-b6e1-027612b7f6b5 | 56e6c100-06fa-11ef-bbf8-02d3d923cf2b | 6619 (8899) | 813219 |
| **Cryptocurrency business** | | | | |
| Crypto OTC Trading | 30f19298-06d8-11ef-b6e1-027612b7f6b5 | 56e6c689-06fa-11ef-bbf8-02d3d923cf2b | 6619 (4791) | 5239 |
| Cryptocurrency ATM | 30f1a174-06d8-11ef-b6e1-027612b7f6b5 | 56e6c7cf-06fa-11ef-bbf8-02d3d923cf2b | 6619 (4799) | 5223 |
| Cryptocurrency Investment Advisory | 30f1df20-06d8-11ef-b6e1-027612b7f6b5 | 56e6ca53-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6630) | 52394 |
| Custodian wallet providers | 30f1a3e2-06d8-11ef-b6e1-027612b7f6b5 | 56e6c913-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6311) | 52399 |
| Unlicensed VC exchange | 30f20aa4-06d8-11ef-b6e1-027612b7f6b5 | 56e6ccdd-06fa-11ef-bbf8-02d3d923cf2b | 6619 | 5239 |
| Virtual Currency Administrators or Miners | 30f1f3d0-06d8-11ef-b6e1-027612b7f6b5 | 56e6cb98-06fa-11ef-bbf8-02d3d923cf2b | 6311 (6499) | 5182 |
| **Entertainment** | | | | |
| Media production/online publishing/animation | 30f29530-06d8-11ef-b6e1-027612b7f6b5 | 56e6cf4b-06fa-11ef-bbf8-02d3d923cf2b | 5911 (6010) | 5162 |
| Motion pictures/film, broadcast media | 30f2e949-06d8-11ef-b6e1-027612b7f6b5 | 56e6dc56-06fa-11ef-bbf8-02d3d923cf2b | 5911 (5914) | 5121 |
| Movie production | 30f2ec48-06d8-11ef-b6e1-027612b7f6b5 | 56e6dda3-06fa-11ef-bbf8-02d3d923cf2b | 5911 (5912) | 5121 |
| Music stores, musical instruments | 30f2d696-06d8-11ef-b6e1-027612b7f6b5 | 56e6db06-06fa-11ef-bbf8-02d3d923cf2b | 4759 (3220) | 459999 |
| Radio, television, stereo | 30f2d49d-06d8-11ef-b6e1-027612b7f6b5 | 56e6d97c-06fa-11ef-bbf8-02d3d923cf2b | 4743 (2640) | 5131 |
| Social Media platforms | 30f2d221-06d8-11ef-b6e1-027612b7f6b5 | 56e6d0f2-06fa-11ef-bbf8-02d3d923cf2b | 6312 (6311) | 516210 |
| **Extractive Sector** | | | | |
| Extraction of Natural Gas | 30f33a2c-06d8-11ef-b6e1-027612b7f6b5 | 56e6e17b-06fa-11ef-bbf8-02d3d923cf2b | 620 (3521) | 2111 |
| Extraction of crude Petroleum | 30f315b9-06d8-11ef-b6e1-027612b7f6b5 | 56e6e035-06fa-11ef-bbf8-02d3d923cf2b | 610 (910) | 2111 |
| Mining and Quarrying | 30f3693f-06d8-11ef-b6e1-027612b7f6b5 | 56e6e2bc-06fa-11ef-bbf8-02d3d923cf2b | 899 (729, 510) | 21 |
| **Financial Services** | | | | |
| Alternative banking platforms (ABPs) | 30f7d0b1-06d8-11ef-b6e1-027612b7f6b5 | 56e70c81-06fa-11ef-bbf8-02d3d923cf2b | 6419 (6619, 6201) | 522 |
| Asset Finance | 30f4b66e-06d8-11ef-b6e1-027612b7f6b5 | 56e6f099-06fa-11ef-bbf8-02d3d923cf2b | 6491 (7711) | 5222 |
| Authorised Bank | 30f46a4d-06d8-11ef-b6e1-027612b7f6b5 | 56e6eda5-06fa-11ef-bbf8-02d3d923cf2b | 6419 (6411) | 5221 |
| Authorised Insurance Firm | 30f47f65-06d8-11ef-b6e1-027612b7f6b5 | 56e6ef22-06fa-11ef-bbf8-02d3d923cf2b | 6511 (6512, 6520) | 5241 |
| Authorised Payment Institution (API) | 30f3a36b-06d8-11ef-b6e1-027612b7f6b5 | 56e6e528-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6499) | 5223 |
| Brokerage services to Funds | 30f4e70a-06d8-11ef-b6e1-027612b7f6b5 | 56e6f20e-06fa-11ef-bbf8-02d3d923cf2b | 6612 (6611) | 5231 |
| Building Society | 30f3ec75-06d8-11ef-b6e1-027612b7f6b5 | 56e6e8d5-06fa-11ef-bbf8-02d3d923cf2b | 6419 (4110) | 5221 |
| CFDs/Forex trading/Brokers | 30f86906-06d8-11ef-b6e1-027612b7f6b5 | 56e71ee0-06fa-11ef-bbf8-02d3d923cf2b | 6612 (6492) | 5231 |
| Consumer Credit Providers | 30f52efd-06d8-11ef-b6e1-027612b7f6b5 | 56e6f6c3-06fa-11ef-bbf8-02d3d923cf2b | 6492 (8291) | 5222 |
| Corporate Finance | 30f5457f-06d8-11ef-b6e1-027612b7f6b5 | 56e6f83d-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6621) | 5231 |
| Credit Card | 30f57fc5-06d8-11ef-b6e1-027612b7f6b5 | 56e6fa51-06fa-11ef-bbf8-02d3d923cf2b | 6619 (1812) | 5222 |
| Credit Unions | 30f40acb-06d8-11ef-b6e1-027612b7f6b5 | 56e6ea55-06fa-11ef-bbf8-02d3d923cf2b | 6419 (9420) | 52213 |
| Discretionary and advisory investment management | 30f59466-06d8-11ef-b6e1-027612b7f6b5 | 56e6fbd7-06fa-11ef-bbf8-02d3d923cf2b | 6630 (6619) | 52394 |
| Electronic money institution (EMI) | 30f812d5-06d8-11ef-b6e1-027612b7f6b5 | 56e70dcb-06fa-11ef-bbf8-02d3d923cf2b | 6419 (6209) | 5223 |
| Execution-only stockbrokers | 30f61068-06d8-11ef-b6e1-027612b7f6b5 | 56e6fed7-06fa-11ef-bbf8-02d3d923cf2b | 6612 (6619) | 5231 |
| Financial Advisors | 30f630bb-06d8-11ef-b6e1-027612b7f6b5 | 56e7001b-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6629) | 52394 |
| Informal Value Transfer System (FINCEN definition) | 30f85922-06d8-11ef-b6e1-027612b7f6b5 | 56e71d97-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6499) | 5223 |
| Invoice Finance | 30f66497-06d8-11ef-b6e1-027612b7f6b5 | 56e70151-06fa-11ef-bbf8-02d3d923cf2b | 6492 (8291) | 5222 |
| Life assurance, and life-related pensions and investment products | 30f66732-06d8-11ef-b6e1-027612b7f6b5 | 56e70289-06fa-11ef-bbf8-02d3d923cf2b | 6511 (6530) | 524113 |
| Money Services Business (MSB) | 30f83498-06d8-11ef-b6e1-027612b7f6b5 | 56e70f2d-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6499) | 5223 |
| Motor Finance | 30f69e50-06d8-11ef-b6e1-027612b7f6b5 | 56e703cc-06fa-11ef-bbf8-02d3d923cf2b | 6491 (4511) | 5222 |
| Name-passing brokers in inter-professional markets | 30f6dc3d-06d8-11ef-b6e1-027612b7f6b5 | 56e70508-06fa-11ef-bbf8-02d3d923cf2b | 6612 (6619) | 5231 |
| Non-life providers of investment fund products | 30f75d62-06d8-11ef-b6e1-027612b7f6b5 | 56e7064b-06fa-11ef-bbf8-02d3d923cf2b | 6512 (6622) | 5259 |
| PSD/EMD Agent | 30f5b372-06d8-11ef-b6e1-027612b7f6b5 | 56e6fd58-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6499) | 5223 |
| Penny stock or microcap securities (US SEC definition) | 30f50d6e-06d8-11ef-b6e1-027612b7f6b5 | 56e6f54a-06fa-11ef-bbf8-02d3d923cf2b | 6612 (6619) | 5239 |
| Private Equity | 30f760b3-06d8-11ef-b6e1-027612b7f6b5 | 56e70791-06fa-11ef-bbf8-02d3d923cf2b | 6430 (6630) | 5239 |
| Retail Banking | 30f837aa-06d8-11ef-b6e1-027612b7f6b5 | 56e716fc-06fa-11ef-bbf8-02d3d923cf2b | 6419 (6499) | 5221 |
| Shell Banks | 30f4e9bb-06d8-11ef-b6e1-027612b7f6b5 | 56e6f3cd-06fa-11ef-bbf8-02d3d923cf2b | 6419 (6499) | 5221 |
| Syndicated Loan | 30f79309-06d8-11ef-b6e1-027612b7f6b5 | 56e708cb-06fa-11ef-bbf8-02d3d923cf2b | 6492 (6619) | 5222 |
| Trade Finance | 30f7b3ac-06d8-11ef-b6e1-027612b7f6b5 | 56e70a01-06fa-11ef-bbf8-02d3d923cf2b | 6492 (6619) | 5222 |
| Unlicensed MSB | 30f854ec-06d8-11ef-b6e1-027612b7f6b5 | 56e71a80-06fa-11ef-bbf8-02d3d923cf2b | 6619 | 5223 |
| Unregulated Foreign Exchange Provider | 30f4343b-06d8-11ef-b6e1-027612b7f6b5 | 56e6ec13-06fa-11ef-bbf8-02d3d923cf2b | 6619 | 5239 |
| Virtual Asset Service Providers (VASPs) | 30f3e91f-06d8-11ef-b6e1-027612b7f6b5 | 56e6e79d-06fa-11ef-bbf8-02d3d923cf2b | 6619 (6499) | 5239 |
| Wealth Management and Private Bank | 30f3a5b3-06d8-11ef-b6e1-027612b7f6b5 | 56e6e669-06fa-11ef-bbf8-02d3d923cf2b | 6630 (6619) | 52394 |
| Wholesale Banking - Capital Markets | 30f85769-06d8-11ef-b6e1-027612b7f6b5 | 56e71c40-06fa-11ef-bbf8-02d3d923cf2b | 6419 (6612) | 5221 |
| Wholesale Markets | 30f7cdb3-06d8-11ef-b6e1-027612b7f6b5 | 56e70b43-06fa-11ef-bbf8-02d3d923cf2b | 4690 (4611, 4619) | 42 |
| **Gambling Business** | | | | |
| Arcades | 30f8a1d9-06d8-11ef-b6e1-027612b7f6b5 | 56e722bd-06fa-11ef-bbf8-02d3d923cf2b | 9329 (7721) | 713120 |
| Bettings | 30f8f01e-06d8-11ef-b6e1-027612b7f6b5 | 56e723f5-06fa-11ef-bbf8-02d3d923cf2b | 9200 (9319) | 7132 |
| Bingo | 30f94758-06d8-11ef-b6e1-027612b7f6b5 | 56e72589-06fa-11ef-bbf8-02d3d923cf2b | 9200 | 7132 |
| Casino | 30f9b94b-06d8-11ef-b6e1-027612b7f6b5 | 56e7283c-06fa-11ef-bbf8-02d3d923cf2b | 9200 (5510) | 7132 |
| Casino - ship based, poker | 30f98d5e-06d8-11ef-b6e1-027612b7f6b5 | 56e726d9-06fa-11ef-bbf8-02d3d923cf2b | 9200 (5010) | 7132 |
| Crypto Gambling (e.g., bitcoin Casino) | 30f9cc9e-06d8-11ef-b6e1-027612b7f6b5 | 56e7297e-06fa-11ef-bbf8-02d3d923cf2b | 9200 (6312) | 7132 |
| Fantasy sports, iGaming, video games | 30fa23af-06d8-11ef-b6e1-027612b7f6b5 | 56e7302a-06fa-11ef-bbf8-02d3d923cf2b | 9200 (5821) | 7132 |
| Gambling software | 30f9fc37-06d8-11ef-b6e1-027612b7f6b5 | 56e72ac8-06fa-11ef-bbf8-02d3d923cf2b | 5829 (6201) | 5132 |
| Gaming machine | 30fa0e37-06d8-11ef-b6e1-027612b7f6b5 | 56e72c37-06fa-11ef-bbf8-02d3d923cf2b | 3240 (3399) | 3399 |
| Lotteries | 30fa1e4c-06d8-11ef-b6e1-027612b7f6b5 | 56e72d97-06fa-11ef-bbf8-02d3d923cf2b | 9200 | 7132 |
| Remote/Online | 30fa2141-06d8-11ef-b6e1-027612b7f6b5 | 56e72ee8-06fa-11ef-bbf8-02d3d923cf2b | 4791 (5310) | 51929 |
| Sports Betting | 30f89f97-06d8-11ef-b6e1-027612b7f6b5 | 56e72159-06fa-11ef-bbf8-02d3d923cf2b | 9200 (9319) | 7132 |
| Unlicensed Gambling business (remote and non-remote) | 30fa469c-06d8-11ef-b6e1-027612b7f6b5 | 56e731aa-06fa-11ef-bbf8-02d3d923cf2b | 9200 | 7132 |
| **Independent legal professionals (firm and sole practitioner)** | | | | |
| Accountancy Services | 30fad312-06d8-11ef-b6e1-027612b7f6b5 | 56e73b45-06fa-11ef-bbf8-02d3d923cf2b | 6920 (7022, 6311) | 541211 |
| Auditor | 30fa6c0c-06d8-11ef-b6e1-027612b7f6b5 | 56e73483-06fa-11ef-bbf8-02d3d923cf2b | 6920 (7010) | 541211 |
| Corporate Structures formation company | 30fae32a-06d8-11ef-b6e1-027612b7f6b5 | 56e73ca4-06fa-11ef-bbf8-02d3d923cf2b | 6910 (8211) | 5411 |
| External Accountant | 30fb124c-06d8-11ef-b6e1-027612b7f6b5 | 56e73dec-06fa-11ef-bbf8-02d3d923cf2b | 6920 | 541219 |
| Individuals who provide tax advice and/or aggressive tax schemes | 30fb4033-06d8-11ef-b6e1-027612b7f6b5 | 56e73f2d-06fa-11ef-bbf8-02d3d923cf2b | 6920 (7022) | 541213 |
| Insolvency practitioner | 30fa6f39-06d8-11ef-b6e1-027612b7f6b5 | 56e7366b-06fa-11ef-bbf8-02d3d923cf2b | 6910 (6621) | 541199 |
| Legal Services Firm | 30fb8a58-06d8-11ef-b6e1-027612b7f6b5 | 56e74073-06fa-11ef-bbf8-02d3d923cf2b | 6910 (6920) | 5411 |
| Notaries | 30fa8ecd-06d8-11ef-b6e1-027612b7f6b5 | 56e737f9-06fa-11ef-bbf8-02d3d923cf2b | 6910 (8423) | 541199 |
| Tax Adviser | 30fbac75-06d8-11ef-b6e1-027612b7f6b5 | 56e741fa-06fa-11ef-bbf8-02d3d923cf2b | 6920 (7022) | 541213 |
| Trust and Company Services Providers (TCSPs) | 30fab353-06d8-11ef-b6e1-027612b7f6b5 | 56e73970-06fa-11ef-bbf8-02d3d923cf2b | 6910 (6430, 7490) | 5411 |
| **Manufacturing** | | | | |
| Automotive, accessories | 30fc76a0-06d8-11ef-b6e1-027612b7f6b5 | 56e7507a-06fa-11ef-bbf8-02d3d923cf2b | 4532 (4531, 4520) | 4413 |
| Electronic manufacturing, consumer electronics | 30fcaca1-06d8-11ef-b6e1-027612b7f6b5 | 56e754a0-06fa-11ef-bbf8-02d3d923cf2b | 2640 (2611) | 334 |
| Railroad manufacture | 30fc9849-06d8-11ef-b6e1-027612b7f6b5 | 56e75348-06fa-11ef-bbf8-02d3d923cf2b | 3020 (3317, 4212) | 3365 |
| Shipbuilding, heavy machinery | 30fc78b1-06d8-11ef-b6e1-027612b7f6b5 | 56e751f0-06fa-11ef-bbf8-02d3d923cf2b | 3011 (3315, 3012) | 3366 |
| Telecommunications, mechanical, industrial engineering, semiconductors | 30fc5ef1-06d8-11ef-b6e1-027612b7f6b5 | 56e74d2d-06fa-11ef-bbf8-02d3d923cf2b | 6110 (6120, 7112, 3342) | 517 |
| **Online Services** | | | | |
| Network security | 30fd90ec-06d8-11ef-b6e1-027612b7f6b5 | 56e75897-06fa-11ef-bbf8-02d3d923cf2b | 6203 (9511, 8020) | 5415 |
| Online service providers | 30fd928c-06d8-11ef-b6e1-027612b7f6b5 | 56e759f9-06fa-11ef-bbf8-02d3d923cf2b | 6311 (6391) | 51929 |
| Streaming, hosting, cloud services | 30fd8ec8-06d8-11ef-b6e1-027612b7f6b5 | 56e75742-06fa-11ef-bbf8-02d3d923cf2b | 6311 (5913) | 5182 |
| **Other Companies** | | | | |
| Aviation/Aerospace/airline | 30fdce2c-06d8-11ef-b6e1-027612b7f6b5 | 56e774af-06fa-11ef-bbf8-02d3d923cf2b | 5110 (3030, 3316, 5121) | 481 |
| Business Consultancy | 30fdbd8f-06d8-11ef-b6e1-027612b7f6b5 | 56e764bf-06fa-11ef-bbf8-02d3d923cf2b | 7022 (7021) | 541611 |
| Chemicals/Biotechnology | 30fdcb6a-06d8-11ef-b6e1-027612b7f6b5 | 56e77226-06fa-11ef-bbf8-02d3d923cf2b | 2059 (2014, 7211) | 3254 |
| Commodity Trading Companies | 30fdb6bb-06d8-11ef-b6e1-027612b7f6b5 | 56e75cb6-06fa-11ef-bbf8-02d3d923cf2b | 4612 (4672) | 5231 |
| Computers, hardware, software, IT | 30fdc9e7-06d8-11ef-b6e1-027612b7f6b5 | 56e770a3-06fa-11ef-bbf8-02d3d923cf2b | 6201 (6202, 9511) | 5415 |
| Dating/Matchmaking websites | 30fdbbfb-06d8-11ef-b6e1-027612b7f6b5 | 56e7620d-06fa-11ef-bbf8-02d3d923cf2b | 9609 (6312) | 51929 |
| Direct Selling (MLM) | 30fdbefb-06d8-11ef-b6e1-027612b7f6b5 | 56e766b6-06fa-11ef-bbf8-02d3d923cf2b | 4799 (4619) | 4599 |
| Fashion, cloth, shoes, apparel, clothing stores, leather goods | 30fdba4d-06d8-11ef-b6e1-027612b7f6b5 | 56e7604f-06fa-11ef-bbf8-02d3d923cf2b | 4771 (1419, 4642) | 4591 |
| Football Sector | 30fdc20b-06d8-11ef-b6e1-027612b7f6b5 | 56e769b7-06fa-11ef-bbf8-02d3d923cf2b | 9312 (9311) | 7112 |
| Freelance Platforms/GIG Economy | 30fdc050-06d8-11ef-b6e1-027612b7f6b5 | 56e76874-06fa-11ef-bbf8-02d3d923cf2b | 7810 (7820, 7830) | 51929 |
| General trading companies operating in free trade zones | 30fdc364-06d8-11ef-b6e1-027612b7f6b5 | 56e76b3a-06fa-11ef-bbf8-02d3d923cf2b | 4690 (5210) | 42 |
| Graphic Design/Web design | 30fdc6ca-06d8-11ef-b6e1-027612b7f6b5 | 56e76e1b-06fa-11ef-bbf8-02d3d923cf2b | 7410 (1813) | 54143 |
| Holding Companies | 30fdb8ac-06d8-11ef-b6e1-027612b7f6b5 | 56e75e57-06fa-11ef-bbf8-02d3d923cf2b | 6420 (7010) | 5511 |
| Human resources/staffing/recruiting/payroll services | 30fdcf8c-06d8-11ef-b6e1-027612b7f6b5 | 56e775ec-06fa-11ef-bbf8-02d3d923cf2b | 7810 (7830) | 5613 |
| Marine services, fishery | 30fdc525-06d8-11ef-b6e1-027612b7f6b5 | 56e76c91-06fa-11ef-bbf8-02d3d923cf2b | 311 (1020, 321) | 1141 |
| Packing, containers, warehousing, facilities services/logistics | 30fdccdc-06d8-11ef-b6e1-027612b7f6b5 | 56e7736e-06fa-11ef-bbf8-02d3d923cf2b | 5229 (5210, 8292, 5224) | 493 |
| Printing/Photography/Publishing | 30fdc85c-06d8-11ef-b6e1-027612b7f6b5 | 56e76f64-06fa-11ef-bbf8-02d3d923cf2b | 1812 (1723, 1811) | 323 |
| **Pharmaceutical and Medicine** | | | | |
| Alternative medicines | 30fdd491-06d8-11ef-b6e1-027612b7f6b5 | 56e779a3-06fa-11ef-bbf8-02d3d923cf2b | 4774 (8690) | 621399 |
| Cannabidiol (CBD) Distributor | 30fdd5fc-06d8-11ef-b6e1-027612b7f6b5 | 56e77ae8-06fa-11ef-bbf8-02d3d923cf2b | 4646 (4645) | 424 |
| Cannabidiol (CBD) Manufacturer | 30fdd76c-06d8-11ef-b6e1-027612b7f6b5 | 56e77c27-06fa-11ef-bbf8-02d3d923cf2b | 2120 (128, 2110) | 325 |
| Cannabidiol (CBD) Retailer | 30fdd8d6-06d8-11ef-b6e1-027612b7f6b5 | 56e77d65-06fa-11ef-bbf8-02d3d923cf2b | 4773 (4775) | 459999 |
| Medical, dental equipment and supplies | 30fdda4d-06d8-11ef-b6e1-027612b7f6b5 | 56e77e9e-06fa-11ef-bbf8-02d3d923cf2b | 4646 (3250) | 3391 |
| Nutraceuticals | 30fdd2d5-06d8-11ef-b6e1-027612b7f6b5 | 56e77872-06fa-11ef-bbf8-02d3d923cf2b | 1089 (4729) | 311999 |
| **Public Sector** | | | | |
| Civic/social organization/defence and space | 30fde5a5-06d8-11ef-b6e1-027612b7f6b5 | 56e78875-06fa-11ef-bbf8-02d3d923cf2b | 9499 (8810) | 8134 |
| Consulate | 30fddd22-06d8-11ef-b6e1-027612b7f6b5 | 56e78101-06fa-11ef-bbf8-02d3d923cf2b | 9900 (8421) | 92 |
| Diplomatic mission | 30fdde9a-06d8-11ef-b6e1-027612b7f6b5 | 56e78239-06fa-11ef-bbf8-02d3d923cf2b | 9900 (8422) | 92 |
| Embassies | 30fde018-06d8-11ef-b6e1-027612b7f6b5 | 56e7836e-06fa-11ef-bbf8-02d3d923cf2b | 9900 (8411) | 92 |
| Govt administration/relations/Judiciary/Legislative office | 30fde2d2-06d8-11ef-b6e1-027612b7f6b5 | 56e785dc-06fa-11ef-bbf8-02d3d923cf2b | 8411 (8412, 8413) | 92 |
| International Affairs, Trade and development | 30fde431-06d8-11ef-b6e1-027612b7f6b5 | 56e78721-06fa-11ef-bbf8-02d3d923cf2b | 9900 (8421) | 92 |
| Museums | 30fde184-06d8-11ef-b6e1-027612b7f6b5 | 56e784a8-06fa-11ef-bbf8-02d3d923cf2b | 9102 (9103) | 7121 |
| **Real Estate Activities** | | | | |
| Other letting and operating of own or leased real estate | 30fbc49a-06d8-11ef-b6e1-027612b7f6b5 | 56e74470-06fa-11ef-bbf8-02d3d923cf2b | 6820 (6810) | 5311 |
| Real estate agencies | 30fbc985-06d8-11ef-b6e1-027612b7f6b5 | 56e745c6-06fa-11ef-bbf8-02d3d923cf2b | 6831 (6832) | 5312 |
| Renting and operating of Housing Association real estate | 30fbdb1d-06d8-11ef-b6e1-027612b7f6b5 | 56e74708-06fa-11ef-bbf8-02d3d923cf2b | 6820 (8790) | 5311 |
| **Wildlife** | | | | |
| Illegal Wildlife Trade | 30fc0ad0-06d8-11ef-b6e1-027612b7f6b5 | 56e7497a-06fa-11ef-bbf8-02d3d923cf2b | 4623 (9900) | 424 |
| Wildlife Trade | 30fc3549-06d8-11ef-b6e1-027612b7f6b5 | 56e74ac7-06fa-11ef-bbf8-02d3d923cf2b | 4623 (149, 170) | 424 |

---

## Monthly expected volumes

This is a definitive list of Expected Monthly Volume values which can be included in the payload when creating a customer.

## Retrieve monthly expected volumes

To get the list with monthly expected volumes, send the [`GET accounts/monthly-expected-volumes`](../../api-explorer/endpoints/get-monthly-expected-volumes) request.

In the response, you receive the existing ranges.

| Attribute   | Description                                                                                 |
| ----------- | ------------------------------------------------------------------------------------------- |
| `reference` | Unique identifier for the volume range. For example, "ef779c41-547e-11ef-8b9c-027612b7f6b5" |
| `name`      | Name/description of the volume range. For example, "0 - 500 000.00 EUR"                     |
| `min`       | Minimum expected volume within the range. For example, 0                                    |
| `max`       | Maximum expected volume for within range. For example, 500.000.                             |

<Tabs>
  <TabItem value="SANDBOX">

    ```json SANDBOX
    [
        {
            "reference": "ef779c41-547e-11ef-8b9c-027612b7f6b5",
            "name": "0 - 500 000.00 EUR",
            "min": 0,
            "max": 500000
        },
        {
            "reference": "ef77a16d-547e-11ef-8b9c-027612b7f6b5",
            "name": "500 000.00 - 2 000 000.00 EUR",
            "min": 500000,
            "max": 2000000
        },
        {
            "reference": "ef77a2bc-547e-11ef-8b9c-027612b7f6b5",
            "name": "2 000 000.00 - 5 000 000.00 EUR",
            "min": 2000000,
            "max": 5000000
        },
        {
            "reference": "ef77a3db-547e-11ef-8b9c-027612b7f6b5",
            "name": "More than 5 000 000.00 EUR",
            "min": 5000000,
            "max": 5000000
        },
        {
            "reference": "ef77a4f8-547e-11ef-8b9c-027612b7f6b5",
            "name": "I'm not sure",
            "min": 0,
            "max": 500000
        }
    ]
    ```

    | Name                            | Minimum | Maximum | Reference                            |
    | ------------------------------- | ------- | ------- | ------------------------------------ |
    | 0 - 500 000.00 EUR              | 0       | 500000  | ef779c41-547e-11ef-8b9c-027612b7f6b5 |
    | 500 000.00 - 2 000 000.00 EUR   | 500000  | 2000000 | ef77a16d-547e-11ef-8b9c-027612b7f6b5 |
    | 2 000 000.00 - 5 000 000.00 EUR | 2000000 | 5000000 | ef77a2bc-547e-11ef-8b9c-027612b7f6b5 |
    | More than 5 000 000.00 EUR      | 5000000 | 5000000 | ef77a3db-547e-11ef-8b9c-027612b7f6b5 |
    | I'm not sure                    | 0       | 500000  | ef77a4f8-547e-11ef-8b9c-027612b7f6b5 |
  </TabItem>
  <TabItem value="PRODUCTION">

    ```json PRODUCTION
    [
        {
            "reference": "d8805674-53fa-11ef-9628-02d3d923cf2b",
            "name": "0 - 500 000.00 EUR",
            "min": 0,
            "max": 500000
        },
        {
            "reference": "d8805cd2-53fa-11ef-9628-02d3d923cf2b",
            "name": "500 000.00 - 2 000 000.00 EUR",
            "min": 500000,
            "max": 2000000
        },
        {
            "reference": "d8805ea7-53fa-11ef-9628-02d3d923cf2b",
            "name": "2 000 000.00 - 5 000 000.00 EUR",
            "min": 2000000,
            "max": 5000000
        },
        {
            "reference": "d8805fdd-53fa-11ef-9628-02d3d923cf2b",
            "name": "More than 5 000 000.00 EUR",
            "min": 5000000,
            "max": 5000000
        },
        {
            "reference": "d8806120-53fa-11ef-9628-02d3d923cf2b",
            "name": "I'm not sure",
            "min": 0,
            "max": 500000
        }
    ]
    ```

    | Name                            | Minimum | Maximum | Reference                            |
    | ------------------------------- | ------- | ------- | ------------------------------------ |
    | 0 - 500 000.00 EUR              | 0       | 500000  | d8805674-53fa-11ef-9628-02d3d923cf2b |
    | 500 000.00 - 2 000 000.00 EUR   | 500000  | 2000000 | d8805cd2-53fa-11ef-9628-02d3d923cf2b |
    | 2 000 000.00 - 5 000 000.00 EUR | 2000000 | 5000000 | d8805ea7-53fa-11ef-9628-02d3d923cf2b |
    | More than 5 000 000.00 EUR      | 5000000 | 5000000 | d8805fdd-53fa-11ef-9628-02d3d923cf2b |
    | I'm not sure                    | 0       | 500000  | d8806120-53fa-11ef-9628-02d3d923cf2b |

  </TabItem>
  </Tabs>

---

## Payment schemes

BVNK provides multiple payment schemes to facilitate seamless digital asset transactions. This reference page covers all available payment options and their features.

:::info Cut-off time (COT)
Settlements arrive within the stated timeframes only if payments are submitted by the stipulated cut-off time (COT).
:::

## Payment schemes

<Tabs>
<TabItem value="us" label="US" default>

| Scheme | Description | Settlement | COT (working days) | Currency |
| :--- | :--- | :--- | :--- | :---: |
| `ACH` | Electronic network for processing low-value, batch transactions including direct deposits and bill payments. | Next business day (T+1) if submitted by COT | GMT 01:45–08:00pm | USD |
| `ACH_SAME_DAY` | Faster ACH processing, typically settling same business day. If requested outside the available window, processed as next-day (fee may still apply). | Same day (T+0) if submitted by COT | GMT 01:45–08:00pm | USD |
| `FEDWIRE` | Real-time gross settlement system operated by the U.S. Federal Reserve for high-value, time-critical transactions. | Within one business day if submitted by COT | GMT 01:45–08:00pm | USD |
| `RTP` | Real-Time Payments network enabling instant fund transfers between participating U.S. banks, 24/7. | Instant | 24/7 | USD |
| `FEDNOW` | Federal Reserve instant payment system providing 24/7 real-time payment capabilities. | Instant | 24/7 | USD |

</TabItem>
<TabItem value="europe" label="Europe">

| Scheme | Description | Settlement | COT (working days) | Currency |
| :--- | :--- | :--- | :--- | :---: |
| `SEPA_CT` | SEPA Credit Transfer for euro-denominated bank transfers across Europe with uniform standards. | 1–2 business days if submitted by COT | GMT 07:00am–02:00pm | EUR |
| `SEPA_INST` | SEPA Instant Payment for real-time euro transfers across Europe, 24/7. May incur a small fee. | Seconds if submitted by COT | GMT 07:00am–02:00pm | EUR |
| `SWIFT` | Global messaging network for secure international financial transactions between banks worldwide. | 1–5 business days if submitted by COT | GMT 07:00am–02:00pm | USD, EUR, GBP |

</TabItem>
<TabItem value="uk" label="UK">

| Scheme | Description | Settlement | COT (working days) | Currency |
| :--- | :--- | :--- | :--- | :---: |
| `FASTER_PAYMENT` | UK service enabling near-instantaneous bank transfers, typically settling within seconds to hours. | Minutes to hours if submitted by COT | GMT 07:00am–02:00pm | GBP |

</TabItem>
<TabItem value="internal" label="Internal">

| Scheme | Description | Settlement | COT | Currency |
| :--- | :--- | :--- | :--- | :---: |
| `BOOK` | Internal transfer of funds between accounts within the same financial institution. | Instant | N/A | USD, EUR, GBP |

</TabItem>
</Tabs>

:::tip COT in other timezones

**US** (ACH, ACH_SAME_DAY, FEDWIRE):
| Timezone | Winter (Standard) | Summer (Daylight) |
| :--- | :--- | :--- |
| PT | 05:45am-12:00pm PST | 06:45am-01:00pm PDT |
| ET | 08:45am-03:00pm EST | 09:45am-04:00pm EDT |

**Europe and UK** (SEPA, SWIFT, FASTER_PAYMENT):
| Timezone | Winter (Standard) | Summer (Daylight) |
| :--- | :--- | :--- |
| PT | 11:00pm-06:00am PST | 12:00am-07:00am PDT |
| ET | 02:00am-09:00am EST | 03:00am-10:00am EDT |
:::

## Transaction limits

In most cases, the supported payment schemes have daily limits that are practically unlimited. For example, for local USD transactions (ACH, FEDWIRE, RTP, FEDNOW), our bank partners set an overall cap of approximately $50 million with no specific limits at the customer level.

But note that `SEPA_INST` has a maximum transaction limit of €250,000 per transaction.

Contact your account manager to learn the specific limits for a particular payment scheme or to request an increase.

There is no **minimum** transaction amount, however zero-value transactions are not permitted.

---

## Third-party providers

## PSD2: What it is and why it's important

The revised Payment Services Directive (PSD2) was enacted on 13 January 2018 across Europe and the UK. PSD2 introduced new rights for certain third-party providers (TPPs) to directly access payment service users' online payment accounts in certain circumstances and requires Account Servicing Payment Service Providers (ASPSPs), to permit access through a dedicated interface built on APIs.

## What will you be able to do?

To meet our PSD2 requirements, BVNK will allow Third-Party Providers (TPPs) certain access:

* Account Information Services (AIS): Account Information from BVNK accounts will be able to be shared with other financial institutions, upon the account owner's consent.\
  *E.g.: a budgeting application that consolidates account information from multiple banks and financial institutions will be able to import data from BVNK virtual accounts.*

  [Read more on AIS on the Open Banking website.](https://standards.openbanking.org.uk/customer-experience-guidelines/introduction/customer-journey-consent/v3-1-5/)

* Payment Initiation Services (PIS): payments to other financial institutions will be able to be initiated directly from other bank accounts, with the owner's consent.\
  *E.g.: a payment of a credit card balance can be made from a mobile application and biometric authentication, with the money coming out of a BVNK virtual account.*

  [Read more on PIS on the Open Banking website.](https://standards.openbanking.org.uk/customer-experience-guidelines/payment-initiation-services/latest/)

## Register your interest

If you are interested, please fill in [the form](https://docs.google.com/forms/d/e/1FAIpQLSfMS90jgvzC_zosrA-rMxVfWT4dYRavIsJv9blVr41yeZuD9A/viewform?embedded=true) below:

<iframe
  src="https://docs.google.com/forms/d/e/1FAIpQLSfMS90jgvzC_zosrA-rMxVfWT4dYRavIsJv9blVr41yeZuD9A/viewform?embedded=true"
  width="760"
  height="675"
  frameBorder="0"
  marginHeight="0"
  marginWidth="0"
  title="Register your interest in Account Information and Payment Initiation Services (AIS and PIS)"
  style={{ border: 'none', width: '100%', maxWidth: '760px' }}
>
  Loading…
</iframe>

---

## Uptime and incident handling

## Our commitment to uptime

At BVNK, we understand the critical importance of maintaining consistent and reliable service. We are dedicated to providing an **uptime of 99.90% availability**. This commitment is not just a goal; it's an integral part of our service promise.

99.9 % uptime/availability results in the following periods of allowed downtime/unavailability:

* Daily: 1m 26s
* Weekly: 10m 4.8s
* Monthly: 43m 28s
* Quarterly: 2h 10m 24s
* Yearly: 8h 41m 38s

## What is an incident?

In the context of our services, an incident is defined as any unexpected event that disrupts our business operational processes or reduces the quality of the service we provide. Recognising the potential impact of such events, we have put robust measures in place to minimise their occurrence and severity.

### Monitoring and immediate response

Our systems are under continuous surveillance with sophisticated monitoring tools. Our goal is to ensure that any system outages are detected as quickly as possible. In the event of an incident, our on-call engineers are promptly notified via an escalation management tool. This rapid response is a cornerstone of our incident management protocol.

### 24/7 engineer availability

We ensure that there is always an engineer on duty, 24 hours a day, 7 days a week, 365 days a year. This round-the-clock availability guarantees that expert help is always at hand to address and resolve any issues as swiftly as possible.

### Stay informed

To keep our customers informed about, planned interruptions due to maintenance, uptime and any incidents, we communicate actively through our status page [https://bvnk.status.io/](https://bvnk.status.io/). We encourage you to subscribe to this service to stay updated with the latest information regarding the status of our systems.

### Learning and improvement

Following any incident, we engage in a thorough learning process to understand and address the root cause. This includes conducting a Post-Mortem for every incident, which is completed within 48 hours of resolution. The key outcome of this process is to identify and implement actions that drive continuous improvement in our systems and processes.

### Continuous improvement

We believe in the power of learning from incidents. The most important outcome of our Post-Mortem process is not just understanding what happened, but ensuring that the actions identified are implemented. This commitment to continuous improvement helps us in enhancing our systems and reducing the likelihood of future incidents.

---

## Webhook signature validator

When implementing BVNK's webhook system, signature validation is critical for security. The BVNK Webhook Signature Validator is a client-side tool that helps developers verify webhook signatures from BVNK's payment processing system. This tool allows you to:

- Validate webhook signatures without sending sensitive data to any external servers.
- Troubleshoot signature validation issues in your implementation.
- Compare your generated signatures against signatures received from BVNK.
- Identify configuration problems in your webhook handling code.

:::warning Security Note
All validation happens in your browser—no sensitive information is transmitted to any server, making this tool safe to use with production credentials.
:::

---

## How to use the validator

### Gather required information

Before using the validator, collect the following information:

| Field | Description |
|-------|-------------|
| **Secret Key** | Your unique webhook secret key provided by BVNK |
| **Webhook URL** | The complete URL where you receive webhooks (**Standard** only) |
| **Received Signature** | The signature value from the `X-Signature` header of the webhook |
| **Content Type** | The content type of the webhook, typically `application/json` (**Standard** only) |
| **JSON Payload** | The complete body content of the webhook |

### Enter information into the validator

1. Select the appropriate tab for your webhook type.
2. Enter your **Secret Key** in the designated field.
3. For **Standard** webhooks: Input the complete **Webhook URL**, including the protocol (`https://`).
4. Paste the **Received Signature** exactly as it appears in the `X-Signature` header.
5. For **Standard** webhooks: Verify the **Content Type** matches.
6. Paste the **JSON Payload** exactly as received, maintaining the same formatting (raw format).
7. Click the **"Validate Signature"** button.

The tool will process the information locally in your browser and display the results showing whether the signature is valid or invalid.

### Review diagnostic information

If the signature validation fails, review the diagnostic information section, which provides:

| Diagnostic Field | Description |
|------------------|-------------|
| **Webhook Path** | Shows the extracted path from the URL (**Standard** only) |
| **String Used for Generating Signature** | Displays the exact string that was used to create the signature |
| **Generated Signature** | The signature calculated by the tool |
| **Received Signature** | The signature you entered for comparison |

---

## Choose your webhook type

BVNK uses two different signature formats depending on the webhook service. Select the appropriate validator for your integration:

<Tabs>
  <TabItem value="standard" label="Standard Webhooks (Hex HMAC-SHA256)" default>

This validator is for webhooks that use **hexadecimal HMAC-SHA256** signatures. The signature is generated from the combination of webhook path, content type, and payload.

```json
{
    "source": "payment",
    "event": "statusChanged",
    ...
}
```

<iframe 
  src="/tools/bvnk-webhook-validator.html" 
  style={{
    width: '100%', 
    height: '520px', 
    border: '1px solid #e5e7eb', 
    borderRadius: '12px',
    backgroundColor: 'white'
  }}
  title="BVNK Webhook Signature Validator"
/>

  </TabItem>
  <TabItem value="hook-service" label="New Hook Service (Base64 HMAC-SHA256)">

This validator is for the new webhook service that uses **Base64 encoded HMAC-SHA256** signatures. The signature is generated solely from the payload.

```json
{
    "event": "bvnk:payment:crypto:status-change",
}
```

<iframe 
  src="/tools/bvnk-webhook-validator-hook-service.html" 
  style={{
    width: '100%', 
    height: '420px', 
    border: '1px solid #e5e7eb', 
    borderRadius: '12px',
    backgroundColor: 'white'
  }}
  title="New Service Webhook Validator"
/>

  </TabItem>
</Tabs>

---

## Troubleshooting tips

<details>
<summary>Signature mismatch issues</summary>

- Ensure your **Secret Key** is entered exactly as provided by BVNK.
- Verify that your JSON payload maintains the **exact formatting** as received (no extra spaces or line breaks).
- Check that the **Content Type** matches exactly.
- For webhooks with query parameters, ensure the tool is extracting the correct path.

</details>

<details>
<summary>Common formatting problems</summary>

- **Whitespace differences**: The payload must match character-for-character, including all whitespace
- **Encoding issues**: Ensure special characters in the payload are preserved
- **URL encoding**: The webhook path should not include query parameters in the signature calculation

</details>

<details>
<summary>Comparing signatures</summary>

Use the diagnostic information to compare:
1. The **Generated Signature** from the tool
2. The **Received Signature** you entered

If they differ, check:
- Are you using the correct webhook type (Standard vs. New Hook Service)?
- Is your secret key correct?
- Is the payload exactly as received?

</details>

---

## BVNK Main API


Welcome to the BVNK Main API documentation. This API enables seamless and secure transactions, including payments, channels, and digital wallet operations.

## Getting Started

Before you begin, make sure you have:
- Created an account on the [BVNK Merchant Portal](https://app.sandbox.bvnk.com)
- Generated your API keys (Hawk Auth ID and Secret Key)
- Reviewed the authentication requirements

## API Environments

- **Production**: `https://api.bvnk.com`
- **Sandbox**: `https://api.sandbox.bvnk.com`

## Overview Articles

- [Overview](/bvnk/api-explorer/api-overview/overview)
- [Authentication](/bvnk/api-explorer/api-overview/authentication)
- [Errors](/bvnk/api-explorer/api-overview/errors)
- [Idempotency](/bvnk/api-explorer/api-overview/idempotency)
- [Metadata](/bvnk/api-explorer/api-overview/metadata)
- [Pagination](/bvnk/api-explorer/api-overview/pagination)

## API Endpoints

For detailed API endpoint documentation, see the [API Reference](/api/bvnk-main-api).

---

## Authentication

Most interactions with the BVNK Crypto Payments API require the use of the API keys.

Before moving forward, make sure you have already created your `Hawk Auth ID` and `Hawk Auth Key` as described in [Generate API Keys](../../../get-started/generate-api-keys), as you won't be able to progress without them.

## HAWK Authentication

BVNK employs Hawk Authentication to ensure the authenticity of requests made to our APIs. The [Hash-based Message Authentication Code (HMAC)](https://www.okta.com/identity-101/hmac/) is calculated using SHA256.

While HAWK supports optional payload validation for POST and PUT data, along with response payload validation, these features are not activated for the BVNK API and can be disregarded.

Below, you will find code examples for the most commonly used programming languages.

:::warning
These snippets are ready to use but to reflect your specific requirements, adjust the following:

* `method`
* `url`
* `Hawk Auth ID`
* `Hawk Auth Key`
:::

<Tabs>
<TabItem value="java" label="Java">

```java

/**
 * Main class demonstrates the generation of a Hawk authentication header.
 */
public class Main {
    // The credentials used to generate the Auth headers
    static String id = "<<Hawk Auth ID>>";
    static String key = "<<Hawk Auth Key>>";
    static String algorithm = "HmacSHA256"; // The hashing algorithm used.

    // The request to be performed
    static String method = "GET";
    static String url = "https://api.sandbox.bvnk.com/api/v1/merchant";

    public static void main(String[] args) throws Exception {
        String header = hawkHeader(url, method, id, key, algorithm);
        System.out.println(header);
    }

    /**
     * This method generates a timestamp of the current time in seconds
     *
     * @return A timestamp in seconds
     */
    public static long getTimestampInSeconds() {
        return System.currentTimeMillis() / 1000;
    }

    /**
     * This method creates a string of random alphanumeric characters
     *
     * @param length The required length of the string
     * @return A string of random characters
     */
    public static String generateNonce(int length) {
        String possible = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";

        StringBuilder text = new StringBuilder(length);
        Random rnd = new SecureRandom();
        for (int i = 0; i < length; i++) {
            text.append(possible.charAt(rnd.nextInt(possible.length())));
        }
        return text.toString();
    }

    /**
     * This method generates a normalized string out of the header options
     *
     * @param type    The request type
     * @param ts      The timestamp in seconds
     * @param nonce   The generated nonce
     * @param method  The HTTP method of the call
     * @param url     The URL of the request
     * @param host    The host
     * @param port    The port
     * @param hash    The hash
     * @return A normalized string containing all parts to be hashed
     */
    public static String generateNormalizedString(String type, long ts, String nonce, String method, String url, String host, String port, String hash) {
        String headerVersion = "1";

        return "hawk." + headerVersion + "." +
                type + "\n" +
                ts + "\n" +
                nonce + "\n" +
                method.toUpperCase() + "\n" +
                url + "\n" +
                host.toLowerCase() + "\n" +
                port + "\n" +
                hash + "\n" +
                "\n";
    }

    /**
     * This method generates the request Message Authentication Code (MAC) using the MAC-SHA256 hashing algorithm
     *
     * @param type    The type to generate
     * @param key     The key used to generate the Auth header
     * @param options The options used to generate the code
     * @return a request MAC
     */
    public static String generateRequestMac(String type, String key, String options) {
        byte[] hmacSha256 = HmacUtils.hmacSha256(key, options);
        return Base64.getEncoder().encodeToString(hmacSha256);
    }

    /**
     * This method generates the Hawk authentication header
     *
     * @param uri  A full URI string
     * @param method The HTTP method (GET, POST, etc.)
     * @param id   The ID from the credentials
     * @param key  The key from the credentials
     * @param algorithm The algorithm from the credentials
     * @throws URISyntaxException Will throw an error if the provided URI string is of an invalid type.
     * @return The Hawk authorization header
     */
    public static String hawkHeader(String uri, String method, String id, String key, String algorithm) throws URISyntaxException {
        // Application time
        long timestamp = getTimestampInSeconds();

        // Generate the nonce
        String nonce = generateNonce(6);

        // Parse URI
        URI parsedUri = new URIBuilder(uri).build();
        String host = parsedUri.getHost();
        String port = String.valueOf(parsedUri.getPort() == -1 ? (parsedUri.getScheme().equals("http") ? 80 : 443) : parsedUri.getPort());
        String resource = parsedUri.getPath() + (parsedUri.getQuery() != null ? "?" + parsedUri.getQuery() : "");

        // Prepare artifacts object to be used in MAC generation
        String options = generateNormalizedString("header", timestamp, nonce, method, resource, host, port, "");

        // Generate the MAC
        String mac = generateRequestMac("header", key, options);

        // Construct Authorization header
        return "Hawk id=\"" + id + "\", ts=\"" + timestamp + "\", nonce=\"" + nonce + "\", mac=\"" + mac + "\"";
    }
}
```

</TabItem>
<TabItem value="csharp" label="C#">

```csharp
using System;
using System.Security.Cryptography;
using System.Text;
using System.Linq;

public class MainClass
{
    // The credentials used to generate the Auth headers
    private static string id = "<<Hawk Auth ID>>";
    private static string key = "<<Hawk Auth Key>>";
    private static string algorithm = "HMACSHA256";

    // The request to be performed
    private static string method = "GET";
    private static string url = "https://api.sandbox.bvnk.com/api/v1/merchant";

    public static void Main(string[] args)
    {
        try
        {
            string header = HawkHeader(url, method, id, key, algorithm);
            Console.WriteLine(header);
        }
        catch (Exception e)
        {
            Console.Error.WriteLine("Error occurred:");
            Console.Error.WriteLine(e);
        }
    }

    /// <summary>
    /// Generates a timestamp of the current time in seconds.
    /// </summary>
    /// <returns>A timestamp in seconds.</returns>
    public static long GetTimestampInSeconds()
    {
        DateTimeOffset dto = DateTimeOffset.Now;
        return dto.ToUnixTimeSeconds();
    }

    /// <summary>
    /// Creates a string of random alphanumeric characters.
    /// </summary>
    /// <param name="length">The required length of the string.</param>
    /// <returns>A string of random characters.</returns>
    public static string GenerateNonce(int length)
    {
        const string chars = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
        var random = new Random();
        return new string(Enumerable.Repeat(chars, length).Select(s => s[random.Next(s.Length)]).ToArray());
    }

    /// <summary>
    /// Generates a normalized string out of the header options.
    /// </summary>
    /// <returns>A normalized string containing all parts to be hashed.</returns>
    public static string GenerateNormalizedString(string type, long ts, string nonce, string method, string url, string host, string port, string hash)
    {
        string headerVersion = "1";
        return $"hawk.{headerVersion}.{type}\n{ts}\n{nonce}\n{method.ToUpper()}\n{url}\n{host.ToLower()}\n{port}\n{hash}\n\n";
    }

    /// <summary>
    /// Generates the request Message Authentication Code (MAC).
    /// </summary>
    /// <returns>A request MAC generated from the HMAC-SHA256 hashing algorithm.</returns>
    public static string GenerateRequestMac(string type, string key, string options)
    {
        using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key));
        byte[] hashBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(options));
        return Convert.ToBase64String(hashBytes);
    }

    /// <summary>
    /// Generates the hawk authorization header.
    /// </summary>
    /// <returns>A Hawk authorization header including the Hawk Auth ID, timestamp, nonce, and MAC.</returns>
    public static string HawkHeader(string uriStr, string method, string id, string key, string algorithm)
    {
        long timestamp = GetTimestampInSeconds();
        string nonce = GenerateNonce(6);

        var uri = new UriBuilder(uriStr);
        string host = uri.Host;
        string port = uri.Port.ToString();
        string resource = uri.Path + (uri.Query.Length > 0 ? uri.Query : "");

        string options = GenerateNormalizedString("header", timestamp, nonce, method, resource, host, port, "");
        string mac = GenerateRequestMac("header", key, options);

        return $"Hawk id=\"{id}\", ts=\"{timestamp}\", nonce=\"{nonce}\", mac=\"{mac}\"";
    }
}
```

</TabItem>
<TabItem value="javascript" label="JavaScript">

```javascript
const Hawk = require("hawk");

/**
 * The method to generate the hawk auth header
 * @param uri The full uri of the request
 * @param method The request method used
 * @param options The request options including credentials
 * @returns a Hawk authorization header including the Hawk Auth ID, time stamp, nonce, and MAC
 */
function hawkHeader(url, method, options) {
  const { header } = Hawk.client.header(url, method, options);
  return header;
}

// The credentials used to generate the Auth headers
const credentials = {
  id: "<<Hawk Auth ID>>",
  key: "<<Hawk Auth Key>>",
  algorithm: "sha256", // The hashing algorith used.
};

// The request to be performed
const request = {
  method: "GET",
  url: "/api/v1/merchant",
  host: "https://api.sandbox.bvnk.com",
};

console.log(
  hawkHeader(`${request.host}${request.url}`, request.method, {
    credentials,
  })
);

```

</TabItem>
<TabItem value="php" label="PHP">

```php
<?php

/**
 * This function generates a timestamp of the current time in seconds
 * 
 * @return int A timestamp in seconds
 */
function getTimestampInSeconds() {
    return time();
}

/**
 * This function creates a string of random alphanumeric characters
 * 
 * @param int $length The required length of the string
 * @return string A string of random characters
 */
function generateNonce($length) {
    $characters = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
    $randomString = '';
    for ($i = 0; $i < $length; $i++) {
        $randomString .= $characters[rand(0, strlen($characters) - 1)];
    }
    return $randomString;
}

/**
 * This function generates a normalized string out of the header options
 * 
 * @param string $type The request type
 * @param array $options The options array
 * @return string A normalized string containing all parts to be hashed
 */
function generateNormalizedString($type, $options) {
    $headerVersion = "1";

    $normalized = "hawk." .
        $headerVersion . "." .
        $type . "\n" .
        $options['ts'] . "\n" .
        $options['nonce'] . "\n" .
        strtoupper($options['method']) . "\n" .
        $options['resource'] . "\n" .
        strtolower($options['host']) . "\n" .
        $options['port'] . "\n" .
        ($options['hash'] ?? '') . "\n";

    $normalized .= "\n";

    return $normalized;
}

/**
 * This function generates the request Message Authentication Code (MAC) using the MAC-SHA256 hashing algorithm
 * 
 * @param string $type The type to generate
 * @param array $credentials The credentials used to generate the Auth header
 * @param array $options The options used to generate the code
 * @return string a request MAC
 */
function generateRequestMac($type, $credentials, $options) {
    $normalized = generateNormalizedString($type, $options);
    return base64_encode(hash_hmac($credentials['algorithm'], $normalized, $credentials['key'], true));
}

/**
 * This function generates the Hawk authentication header
 * 
 * @param string $uri A full URI string
 * @param string $method The HTTP method (GET, POST, etc.)
 * @param array $options Array containing credentials and other options
 * @throws Exception Will throw an exception if the provided arguments are of an invalid type.
 * @return string The Hawk authorization header
 */
function hawkHeader($uri, $method, $options) {
    // Validate inputs
    if (
        !$uri ||
        !is_string($uri) ||
        !$method ||
        !is_string($method) ||
        !$options ||
        !is_array($options)
    ) {
        throw new Exception("Invalid argument type");
    }

    // Application time
    $timestamp = getTimestampInSeconds();

    // Validate credentials
    $credentials = $options['credentials'];
    if (
        !$credentials ||
        !$credentials['id'] ||
        !$credentials['key'] ||
        !$credentials['algorithm']
    ) {
        throw new Exception("Invalid credentials");
    }

    // Calculate signature to hash
    $artifacts = [
        'ts' => $timestamp,
        'nonce' => generateNonce(6),
        'method' => $method,
        'resource' => parse_url($uri, PHP_URL_PATH) . (parse_url($uri, PHP_URL_QUERY) ? '?' . parse_url($uri, PHP_URL_QUERY) : ''),
        'host' => parse_url($uri, PHP_URL_HOST),
        'port' => parse_url($uri, PHP_URL_PORT) ?? (parse_url($uri, PHP_URL_SCHEME) === "http" ? 80 : 443),
    ];

    // Generate the MAC
    $mac = generateRequestMac("header", $credentials, $artifacts);

    // Construct Authorization header
    $header = 'Hawk id="' . $credentials['id'] . '", ts="' . $artifacts['ts'] . '", nonce="' . $artifacts['nonce'] . '", mac="' . $mac . '"';

    return $header;
}

// The credentials used to generate the Auth headers
$credentials = [
    'id' => "<<Hawk Auth ID>>",
    'key' => "<<Hawk Auth Key>>",
    'algorithm' => "sha256", // The hashing algorithm used.
];

// The request to be performed
$request = [
    'method' => "GET",
    'url' => "/api/v1/merchant",
    'host' => "https://api.sandbox.bvnk.com",
];

// Print Hawk Auth header
echo hawkHeader($request['host'] . $request['url'], $request['method'], ['credentials' => $credentials]);

?>
```

</TabItem>
<TabItem value="ruby" label="Ruby">

```ruby
require 'openssl'
require 'base64'
require 'uri'

# Generates a timestamp of the current time in seconds
# @return [Integer] A timestamp in seconds
def get_timestamp_in_seconds
  Time.now.to_i
end

# Creates a string of random alphanumeric characters
# @param length [Integer] The required length of the string
# @return [String] A string of random characters
def generate_nonce(length)
  possible = ('A'..'Z').to_a + ('a'..'z').to_a + ('0'..'9').to_a
  (0...length).map { possible[rand(possible.length)] }.join
end

# Generates a normalized string out of the header options
# @param type [String] The request type
# @param options [Hash] The options hash
# @return [String] A normalized string containing all parts to be hashed
def generate_normalized_string(type, options)
  header_version = "1"
  normalized = "hawk." +
  header_version +
  "." +
  type +
  "\n" +
  options[:ts].to_s +
  "\n" +
  options[:nonce] +
  "\n" +
  (options[:method] || "").upcase +
  "\n" +
  (options[:resource] || "") +
  "\n" +
  options[:host].downcase +
  "\n" +
  options[:port].to_s +
  "\n" +
  (options[:hash] || "") +
  "\n"

  normalized += "\n"
  normalized
end

# Generates the request Message Authentication Code (MAC) using the MAC-SHA256 hashing algorithm
# @param type [String] The type to generate
# @param credentials [Hash] The credentials used to generate the Auth header
# @param options [Hash] The options used to generate the code
# @return [String] a request MAC
def generate_request_mac(type, credentials, options)
  normalized = generate_normalized_string(type, options)
  hmac = OpenSSL::HMAC.new(credentials[:key], credentials[:algorithm])
  hmac.update(normalized)
  Base64.strict_encode64(hmac.digest)
end

# Generates the Hawk authentication header
# @param uri [String] A full URI string
# @param method [String] The HTTP method (GET, POST, etc.)
# @param options [Hash] Hash containing credentials and other options
# @raise [RuntimeError] If the provided arguments are of an invalid type.
# @return [String] The Hawk authorization header
def hawk_header(uri, method, options)
  uri = URI(uri) if uri.is_a? String
  timestamp = get_timestamp_in_seconds

  credentials = options[:credentials]
  if credentials.nil? || credentials[:id].nil? || credentials[:key].nil? || credentials[:algorithm].nil?
    raise "Invalid credentials"
  end

  artifacts = {
    ts: timestamp,
    nonce: generate_nonce(6),
    method: method,
    resource: uri.path + (uri.query.nil? ? '' : "?#{uri.query}"),
    host: uri.host,
    port: uri.port || (uri.scheme == "http" ? 80 : 443)
  }

  mac = generate_request_mac("header", credentials, artifacts)
  header = "Hawk id=\"#{credentials[:id]}\", ts=\"#{artifacts[:ts]}\", nonce=\"#{artifacts[:nonce]}\", mac=\"#{mac}\""

  header
end

credentials = {
  id: "<<Hawk Auth ID>>",
  key: "<<Hawk Auth Key>>",
  algorithm: "sha256",
}

request = {
  method: "GET",
  url: "/api/v1/merchant",
  host: "https://api.sandbox.bvnk.com",
}

header = hawk_header("#{request[:host]}#{request[:url]}", request[:method], {
  credentials: credentials
})

puts header
```

</TabItem>
<TabItem value="python" label="Python">

```python

# This function generates a timestamp of the current time in seconds
def get_timestamp_in_seconds():
    return int(time.time())

# This function creates a string of random alphanumeric characters
def generate_nonce(length):
    return ''.join(random.choice(string.ascii_letters + string.digits) for _ in range(length))

# This function generates a normalized string out of the header options
def generate_normalized_string(type, options):
    header_version = "1"
    normalized = f'hawk.{header_version}.{type}\n{options["ts"]}\n{options["nonce"]}\n{options["method"].upper()}\n{options["resource"]}\n{options["host"].lower()}\n{options["port"]}\n{options["hash"]}\n\n'
    return normalized

# This method generates the request Message Authentication Code (MAC) using the MAC-SHA256 hashing algorithm
def generate_request_mac(type, credentials, options):
    normalized = generate_normalized_string(type, options)
    hmac_obj = hmac.new(credentials['key'].encode(), normalized.encode(), hashlib.sha256)
    return base64.b64encode(hmac_obj.digest()).decode()

# This method generates the Hawk authentication header
def hawk_header(uri, method, options):
    # Validate inputs
    if not uri or not isinstance(uri, str) or not method or not isinstance(method, str) or not options or not isinstance(options, dict):
        raise ValueError("Invalid argument type")

    # Application time
    timestamp = get_timestamp_in_seconds()

    # Validate credentials
    credentials = options['credentials']
    if not credentials or not credentials['id'] or not credentials['key'] or not credentials['algorithm']:
        raise ValueError("Invalid credentials")

    # Parse URI if it is a string
    parsed_uri = urllib.parse.urlparse(uri)

    # Prepare artifacts object to be used in MAC generation
    artifacts = {
        'ts': timestamp,
        'nonce': generate_nonce(6),
        'method': method,
        'resource': parsed_uri.path + parsed_uri.query, # Maintains trailing '?'
        'host': parsed_uri.hostname,
        'port': parsed_uri.port if parsed_uri.port else (80 if parsed_uri.scheme == 'http' else 443),
        'hash': ''
    }

    # Generate the MAC
    mac = generate_request_mac('header', credentials, artifacts)

    # Construct Authorization header
    header = f'Hawk id="{credentials["id"]}", ts="{artifacts["ts"]}", nonce="{artifacts["nonce"]}", mac="{mac}"'

    return header

# The credentials used to generate the Auth headers
credentials = {
  'id': "<<Hawk Auth ID>>",
  'key': "<<Hawk Auth Key>>",
  'algorithm': "sha256", # The hashing algorithm used.
}

# The request to be performed
request = {
  'method': "GET",
  'url': "/api/v1/merchant",
  'host': "https://api.sandbox.bvnk.com",
}

print(hawk_header(f'{request["host"]}{request["url"]}', request["method"], {'credentials': credentials}))
```

</TabItem>
<TabItem value="node" label="Node.js">

```node
const crypto = require("crypto");

const generateHawkAuthorization = (url, method, hawkId, hawkSecret) => {
    // Generate Hawk authorization header
    const timestamp = Math.floor(Date.now() / 1000);
    const nonce = Math.random().toString(36).substring(7);
    const parsedUrl = new URL(url); 
    const path = parsedUrl.pathname + parsedUrl.search;
    const host = parsedUrl.host;
    const port = parsedUrl.port || (parsedUrl.protocol === 'https:' ? '443' : '80');

    // Create normalized request string
    const normalized = `hawk.1.header\n${timestamp}\n${nonce}\n${method}\n${path}\n${host}\n${port}\n\n\n`;

    // Generate MAC
    const mac = crypto.createHmac('sha256', hawkSecret)
        .update(normalized)
        .digest('base64');

    // Format Hawk header
    return `Hawk id="${hawkId}", ts="${timestamp}", nonce="${nonce}", mac="${mac}"`
}
```

</TabItem>
</Tabs>

:::warning
The HTTP method and endpoint URL significantly influence the generation of the correct hash values in your authorization header. It's crucial to ensure these values are dynamically updated to align with your actual requests. Otherwise, your requests may fail.
:::

---

## Errors

The BVNK API responds with detailed information in the event of a failed request. Below is a comprehensive list of payment error codes, along with brief descriptions on how to address them. This resource serves as a valuable reference for developers, enabling them to efficiently troubleshoot and address errors in their applications' integration with BVNK's API.

The errors are returned in the following format:

<Tabs>
<TabItem value="json" label="JSON">
    ```json Example Response for Payouts
    {
        "code": "bvnk:payment:0005",
        "status": "Bad Request",
        "message": "Beneficiary details validation failed",
        "details": {
            "documentLink": "../api-overview/errors",
            "errors": {
                "requestBody": [
                    "Address country required"
                ]
            }
        }
    }
    ```
</TabItem>
<TabItem value="array" label="Array of Errors">
    ```json Array of Errors
    {
        "requestId": "cd8b277efeeccdea4067a4030ecc4e45",
        "errorList": [
            {
                "requestId": null,
                "code": "MER-PAY-2012",
                "parameter": "amount",
                "message": "insufficient funds"
            }
        ]
    }
    ```
</TabItem>
</Tabs>

Here,

- `code`: Error code that identifies the specific error type. See the list of codes and descriptions below.
- `status`: HTTP status associated with the error, such as `400`, `403`.
- `message`: Human-readable explanation of the error and guidance on how to resolve it. In most cases, error details are propagated into this field (often similar to `details.error`).
- `details`: Structured information about why the request failed. This field is most common for Bad Request (400) errors, but it can be null when the details have been propagated to the message or are otherwise unavailable.

  For example, the above payout response appears if you specify `countryCode: null` in the request. The `requestBody` contains specific information about the missing field.
- `details.documentLink`: Link to this article where you can learn more about the caught error.

## 0001-0099

### Fiat payouts

| **Code**  | **Message** | **Description**    |
| :-------: | :---------- | :----------------- |
| BVNK:PAYMENT:0001 | Received Bad Request                                                                                                                    | The system received a request with invalid parameters or missing required information. Check the request format, parameters, and ensure all required fields are correctly filled.                                                                                                                                                                                                                                                 |
| BVNK:PAYMENT:0002 | Payout with the given identifier could not be found                                                                                     | The system was unable to locate the requested payout using the provided ID. Verify that the payout ID is correct and exists in the system.                                                                                                                                                                                                                                                                                        |
| BVNK:PAYMENT:0003 | Forbidden → received request with wrong authentication details                                                                          | The request was rejected due to an authentication failure. Ensure your API keys, tokens, or credentials are valid and correctly included in the request header.                                                                                                                                                                                                                                                                   |
| BVNK:PAYMENT:0004 | Error while receiving or validating beneficiary                                                                                         | The beneficiary details could not be retrieved, or failed validation checks. This may occur due to missing or malformed fields (name, address, account identifiers), failed KYC/KYB or sanctions screening, or temporary downstream connectivity errors. Verify beneficiary data to ensure the required fields and formats (e.g., IBAN/ABA) are accurate. Confirm the beneficiary is allowed, and retry once issues are resolved. |
| BVNK:PAYMENT:0005 | Validation of the beneficiary has failed                                                                                                | The beneficiary did not pass mandatory validation rules. Typical reasons include invalid account identifiers, an unsupported destination, a mismatched currency/network, or a compliance screening failure. Correct the beneficiary information (names, address, account numbers, tags/memos where required) or select a different, validated beneficiary before retrying.                                                        |
| BVNK:PAYMENT:0006 | Payout with the idempotency key already exists                                                                                          | A payout using the provided idempotency key already exists. For idempotent safety, the platform rejects creating a new payout with the same key. If you intend to retry the same request, use the original response; otherwise, generate a new, unique idempotency key for a new payout.                                                                                                                                          |
| BVNK:PAYMENT:0007 |  Insufficient funds | A wallet does not have sufficient funds to complete the requested transaction. |
| BVNK:PAYMENT:0008 | The payment method is not supported                                                                                                     | The platform does not currently support the payment method specified in the request. Review the documentation for a list of supported payment methods.                                                                                                                                                                                                                                                                            |
| BVNK:PAYMENT:0009 | Specific functionality is not enabled for this account or wallet                                                                        | The specific functionality or flow is not enabled or provisioned for this account or wallet. Check your permissions and product enablement. If the feature is available, enable it in the portal; otherwise, contact support to request access.                                                                                                                                                                                   |
| BVNK:PAYMENT:0010 | The virtual account has been disabled for this given wallet. Customer should use a different wallet or choose different payment method. | The virtual account assigned to the specified wallet is disabled. Use a different wallet or select an alternative payment method. If you need this virtual account re-enabled, review the wallet configuration and contact support or your account manager.                                                                                                                                                                       |
| **Mass Payouts**      |                                                                                                                                         |                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| BVNK:PAYMENT:0030 | Could not find a single payment within a given payout batch                                                                             | The referenced payout batch contains no payments matching your query, or the payments have not been associated with the batch yet. Verify the payout batch identifier, ensure the batch was created successfully, and confirm that items were added and not removed by validation. If you are filtering, check the date/status filters to ensure you are querying the correct environment (sandbox vs. production).               |
| BVNK:PAYMENT:0031 | Could not find specific payout batch                                                                                                    | The payout batch could not be located. The batch identifier may be invalid, belong to another account, or the batch may have been archived/expired. Double-check the batch ID/token and your account permissions, then try again. If the batch was created recently, allow a short delay and retry.                                                                                                                               |
| BVNK:PAYMENT:0032 | Cannot delete a single payout from a batch, as it has started processing already                                                        | Once batch processing has started, individual payouts become immutable. Deletions are only permitted while the batch is in a pre‑processing state. To remove items, cancel the whole batch if supported, or create a new batch without the unwanted payout.                                                                                                                                                                       |
| BVNK:PAYMENT:0033 | Cannot update a single payout from a batch, as it has started processing already                                                        | Individual payout updates are blocked after batch processing begins. Modify items only before submission. If you need changes, cancel the batch (where supported) and recreate it with corrected payout details, or submit a follow‑up adjustment as a new payout.                                                                                                                                                                |

### Fees

| **Code**           | **Message**                                       | **Description**                                                                                                                                                 |
| :-----------------: | :------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BVNK:FEES:0001 | Invalid wallet selected on client request.        | The wallet selected in the client request is invalid. Check that the wallet identifier is correctly formatted and belongs to a valid wallet type.               |
| BVNK:FEES:0002 | Provided wallet not found for a specific account. | The system was unable to find the specified wallet associated with the requested account. Verify that the wallet exists and is correctly linked to the account. |
| BVNK:FEES:0003 | Invalid customer fee wallet configuration.        | The customer fee wallet configuration contains invalid settings or parameters. Review and correct the fee wallet configuration in your account settings.        |

***

## 1000-1999

| **Code**         | **Message**                           | **Description**                                                                                                                                             |
| :---------------: | :------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MER-PAY-1000 | Not authorized to perform this action | A user or merchant is not authorised to perform the requested action. This can occur due to insufficient permissions or invalid authentication credentials. |

***

## 2000-2999

:::warning
Should you encounter any of the errors outlined in this section, be aware that your payment or transaction attempt will not be successful. The system will reject the transaction at the API level, consequently preventing the creation of a failed transaction record. Therefore, you will not find any evidence of the unsuccessful operation within the Portal.
:::

| **Code**         | **Message**                                                                                                                              | **Description**                                                                                                                                                                     |
| :---------------: | :--------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| MER-PAY-2000 | Invalid parameter value                                                                                                                  | The request parameters fail validation. This includes JSON parsing errors, missing required parameters, invalid data types, or constraint violations on request fields.             |
| MER-PAY-2001 | Amount x.xx \<currency> failed is less than minimum limit of x.xx \<currency>                                                            | The payment amount fails validation. This occurs when the amount is below the minimum limit or above the maximum limit for the specified currency.                                  |
| MER-PAY-2002 | Payment has no quote                                                                                                                     | An error occurs when a payment operation requires an exchange quote, but none is found. This typically occurs when attempting to process payments that require currency conversion. |
| MER-PAY-2003 | Exchange quote \<id> for payment \<id> has status ACCEPTED so cannot be accepted                                                         | An error is given when attempting to modify a quote that has already been finalised. Once a quote is in a final state, it cannot be changed.                                        |
| MER-PAY-2004 | Payment has expired                                                                                                                      | An error occurs when attempting to process a payment that has exceeded its expiration time. Expired payments cannot be processed and need to be recreated.                          |
| MER-PAY-2005 | Instruction validation failed message                                                                                                    | The payment instruction data is invalid. This includes validation failures for payment addresses, amounts, or other instruction-specific parameters.                                |
| MER-PAY-2006 | Merchant not found                                                                                                                       | An error occurs when the Merchant ID provided in the payment request cannot be found in the account.                                                                                |
| MER-PAY-2008 | Payment not found                                                                                                                        | An error occurs when the payment ID cannot be found.                                                                                                                                |
| MER-PAY-2009 | Invalid request message                                                                                                                  | Error given for general request validation failures.                                                                                                                                |
| MER-PAY-2010 | A payment with reference \<reference> already exists. Please enter a unique reference.                                                   | An error was given when a payment was already created using this reference. All references need to be unique.                                                                       |
| MER-PAY-2011 | Currency \<currency> is disabled                                                                                                         | An error occurs when creating a payment with a disabled currency that is not available for trade.                                                                                   |
| MER-PAY-2012 | Insufficient funds                                                                                                                       | A wallet does not have sufficient funds to complete the requested transaction.                                                                                                      |
| MER-PAY-2014 | Exchange quote \<id> for payment \<id> can no longer be accepted as acceptance has expired                                               | A quote is accepted after it has expired.                                                                                                                                           |
| MER-PAY-2015 | Crypto instruction not found for payment \<id>                                                                                           | A required crypto payment instruction cannot be found for the specified payment.                                                                                                    |
| MER-PAY-2016 | Merchant not authorised to perform this action                                                                                           | A merchant is not authorised to perform the requested action.                                                                                                                       |
| MER-PAY-2017 | Cannot cancel payment with external id \<id> and status PROCESSING                                                                       | An attempt is made to cancel a payment and the status is not COMPLETE or PENDING.                                                                                                   |
| MER-PAY-2018 | Resource modified by another request                                                                                                     | A concurrent modification conflict arises. This happens when multiple requests attempt to modify the same resource simultaneously.                                                  |
| MER-PAY-2019 | Currency \<currency> not found                                                                                                           | The specified currency is not found in the system.                                                                                                                                  |
| MER-PAY-2024 | protocol \<protocol> not found for currency \<currency>                                                                                  | The specified protocol is not found or not supported for the given currency.                                                                                                        |
| MER-PAY-2025 | Please enter your own wallet address, not the address that you paid into originally.                                                     | The provided refund address fails validation checks.                                                                                                                                |
| MER-PAY-2027 | address \<address> has failed validation for currency: \<currency>, protocol: \<protocol> and tag: \<tag>                                | The crypto payout receive address format is invalid.                                                                                                                                |
| MER-PAY-2028 | We couldn't process your payout request to this address: \<address> this time, please try another address.                               | The crypto payout receiving address is rejected due to risk and compliance reasons.                                                                                                 |
| MER-PAY-2029 | Protocol with code \<protocol> not found                                                                                                 | The specified protocol code is not found in the system.                                                                                                                             |
| MER-PAY-2030 | Unable to find protocol \<protocol> for currency code \<currency>                                                                        | The specified protocol cannot be found for the given currency code.                                                                                                                 |
| MER-PAY-2031 | Account not enabled for flow: \<flow>. Please check your permissions or contact support for more information.                            | The account is not enabled for the specific payment flow being requested.                                                                                                           |
| MER-PAY-2033 | Multiple protocols found for currency \<currency> Please specify which one to use: \<protocols>.                                         | Multiple protocols are available for a currency, but no specific protocol is selected, rendering automatic selection impossible.                                                    |
| MER-PAY-2035 | mass payout data row validation failed                                                                                                   | One or more rows in a mass payout file fail validation checks.                                                                                                                      |
| MER-PAY-2036 | \<rows> payments uploaded. This exceeds the maximum number of \<max_rows> rows. Please reduce your file to \<max_rows> rows.             | A mass payout file contains more rows than the system maximum allows.                                                                                                               |
| MER-PAY-2037 | Failed to process mass upload file. File name already exists.                                                                            | Attempting to upload a mass payout file with a filename that already exists.                                                                                                        |
| MER-PAY-2038 | Failed to process mass upload file. File is required.                                                                                    | A required mass payout file is not provided.                                                                                                                                        |
| MER-PAY-2039 | Failed to process mass upload file. One of Merchant id or Wallet id fields have to be provided.                                          | A mass payout request is missing both the required merchant ID and wallet ID parameters.                                                                                            |
| MER-PAY-2040 | Failed to process mass upload file. Header is invalid.                                                                                   | The mass payout file contains invalid or missing required headers.                                                                                                                  |
| MER-PAY-2041 | Deleting mass payout item with status CREATED is not allowed.                                                                            | An error is given when attempting to delete a mass payout item that is not in a deletable state.                                                                                    |
| MER-PAY-2042 | Updating mass payout item with status \<status> is not allowed.                                                                          | An error is given when attempting to edit a mass payout item that is not in an editable state.                                                                                      |
| MER-PAY-2043 | One of merchantId or walletId properties have to be provided, both are missing                                                           | A request requires a merchant ID or a wallet ID, but neither is provided.                                                                                                           |
| MER-PAY-2044 | network \<network> not found                                                                                                             | The specified blockchain network is not valid or supported.                                                                                                                         |
| MER-PAY-2045 | Payout details currency \<currency> and network \<network> mismatch from previously provided currency \<currency> and network \<network> | The payout details do not match the details previously provided for the estimate.                                                                                                   |
| MER-PAY-2046 | protocol not found for currency \<currency> and network \<network>                                                                       | The specified protocol and network combination is not valid or supported.                                                                                                           |
| MER-PAY-2047 | Estimate cannot be modified. Payment with uuid \<uuid> already created for estimate \<estimate id>.                                      | An error is given when attempting to accept an estimate that already has an associated payment.                                                                                     |
| MER-PAY-2048 | Failed to process mass upload file. File is empty.                                                                                       | The uploaded mass payout file contains no data rows.                                                                                                                                |
| MER-PAY-2049 | Recipient address is not associated with a contact. You will assign or add a contact to it on the next step.                             | The specified contact cannot be found for the given address or criteria.                                                                                                            |
| MER-PAY-2050 | Recipient address is associated with more than 1 contact. You'll be asked to choose which contact to use for this transaction.           | Multiple matching contacts are found for the provided address.                                                                                                                      |
| MER-PAY-2051 | Crypto account \<crypto account> is not verified. Please verify your crypto account before using it                                      | An error occurs when attempting to use an unverified cryptocurrency account that requires verification.                                                                             |
| MER-PAY-2052 | This country is unavailable. If you require this region, please reach out to your account manager.                                       | Geographical screening encounters an error or fails due to regional restrictions.                                                                                                   |
| MER-PAY-2053 | The payment can not be processed.                                                                                                        | Geographical screening determines that the payment cannot be processed due to regional restrictions.                                                                                |
| MER-PAY-2054 | Payment direction 'IN' is not compatible with flow 'EMBEDDED_CRYPTO'                                                                     | An error is given when attempting to use an unsupported payment direction with an embedded crypto flow.                                                                             |
| MER-PAY-2055 | mesh client invalid request message                                                                                                      | A request to the mesh client is invalid or malformed.                                                                                                                               |
| MER-PAY-2056 | Customer not found for reference: \<customer reference>                                                                                  | The specified customer cannot be found in the system.                                                                                                                               |
| MER-PAY-2057 | required header missing                                                                                                                  | A required HTTP header is missing from the request.                                                                                                                                 |
| MER-PAY-2058 | Cannot confirm/accept payment \<uuid> as it has been cancelled                                                                           | An error is given when attempting to perform operations on a payment that has been cancelled.                                                                                       |
| MER-PAY-2059 | Wallet with ID \<walletId> not found                                                                                                     | The specified wallet ID does not exist.                                                                                                                                             |

***

## 3000-3999

### Network

| **Code**      | **Message**                                                    | **Description**                                                                                                                                                                                                                           |
| :------------: | :------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BVNK-3001 | Received Bad Request                                           | The system received a request with invalid parameters or missing required information. Check the request format, parameters, and ensure all required fields are properly filled and formatted correctly.                                  |
| BVNK-3003 | Forbidden → received request with wrong authentication details | Access to the requested resource is denied due to authentication failure. Ensure your API keys, tokens, or credentials are valid, correctly included in the request header, and have the necessary permissions to perform this operation. |
| BVNK-3040 | Transfer not found                                             | The requested transfer could not be located in the system. Verify that the transfer identifier is correct and exists within your account. If you recently initiated the transfer, it may still be processing.                             |

### Customers

| **Code**         | **Message**                                     | **Description**                                                           |
| :--------------- | :---------------------------------------------- | :------------------------------------------------------------------------ |
| MER-PAY-3003 | Resource not found                              | Error given when a requested static resource or endpoint cannot be found. |
| MER-PAY-3XXX | Unexpected error - please contact administrator | Error given for unexpected or unhandled exceptions.                       |

***

## 4001-4999

### Wallets

| **Code**             | **Message**                                                                                                        | **Description**                                                                                                                                                                                                                                                                      |
| :-------------------: | :----------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BVNK:LEDGER:4001 | Received Bad Request                                                                                               | The system received a request with invalid parameters or missing required information. Check the request format, ensure all required fields are properly filled, and validate that parameter values meet the expected format and constraints.                                        |
| BVNK:LEDGER:4003 | FORBIDDEN! You don't have the necessary permissions to access this resource.                                       | Access to the requested resource is denied due to insufficient permissions. This could be due to missing capabilities when creating a customer wallet, or because the customer has been rejected in the system. Verify your account permissions and customer status before retrying. |
| BVNK:LEDGER:4004 | Wallet creation request with the same idempotency key and account reference exists                                 | A wallet creation request with the same idempotency key and account reference already exists in the system. Idempotency keys must be unique for each new wallet creation. Check your records to find the existing wallet or use a new idempotency key for a new wallet.              |
| BVNK:LEDGER:4005 | Wallet creation request with missing data, one of the customer reference and external reference has to be provided | The wallet creation request is missing essential identifying information. Either a customer reference or an external reference must be provided in the request. Review your request data and include at least one of these required reference identifiers.                           |

### Customers

| **Code**         | **Message**                                                                   | **Description**                                                |
| :---------------: | :---------------------------------------------------------------------------- | :------------------------------------------------------------- |
| MER-PAY-4011 | Customer fee wallet not found. Please contact support if you need assistance. | The customer fee wallet has not been set. Configuration error. |
| MER-PAY-4XXX | Unexpected error - please contact administrator                               | Error given for unexpected or unhandled exceptions.            |

### Rules

| Error Code                  | Message                             | Description                                                                                                                                                                                                 |
| ---------------------------: | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bvnk:payment:rules:4001 | Wallet configuration already exists | A wallet configuration with the specified parameters already exists in the system. This error occurs when attempting to create a duplicate wallet configuration that conflicts with an existing one.        |
| bvnk:payment:rules:4002 | Address validation error            | The provided wallet address failed validation checks. This error indicates that the address format is invalid, doesn't match the expected format for the specified network, or contains invalid characters. |
| bvnk:payment:rules:4003 | Invalid currency                    | The specified currency code is not recognized or supported by the system. Ensure you're using a valid currency identifier that matches the supported currencies for your account.                           |
| bvnk:payment:rules:4004 | Unsupported network                 | The blockchain network specified in the request is not supported by the payment rules system. Check the list of supported networks and use a valid network identifier.                                      |
| bvnk:payment:rules:4005 | Invalid party details               | The party details provided in the request contain invalid or missing information. This includes issues with party identification, contact information, or other required party-specific data.               |
| bvnk:payment:rules:4006 | Data integrity violation            | A data integrity constraint has been violated. This error occurs when the provided data conflicts with existing database constraints or business rules that ensure data consistency.                        |
| bvnk:payment:rules:4007 | Invalid fee type                    | The fee type specified in the request is not valid or supported. Check the documentation for valid fee type values and ensure you're using the correct fee structure for your configuration.                |
| bvnk:payment:rules:4008 | Invalid destination type            | The destination type provided is invalid or not supported for the current operation. Verify that you're using a supported destination type for your wallet configuration.                                   |
| bvnk:payment:rules:4016 | Invalid request format              | The request format is malformed or contains invalid structure. This error indicates issues with JSON formatting, missing required fields, or incorrect data types in the request payload.                   |
| bvnk:payment:rules:4009 | Wallet not found                    | The specified wallet could not be found in the system. Verify that the wallet ID or identifier exists and that you have the necessary permissions to access it.                                             |
| bvnk:payment:rules:4010 | Wallet configuration not found      | The requested wallet configuration does not exist. This error occurs when trying to access, modify, or delete a wallet configuration that is not present in the system.                                     |
| bvnk:payment:rules:4011 | Wallet configuration already active | The wallet configuration is already in an active state and cannot be modified or activated again. Check the current status of the configuration before attempting to change it.                             |
| bvnk:payment:rules:4012 | Currency mismatch                   | There is a mismatch between the expected currency and the provided currency. Ensure that all currency references in your request are consistent and match the wallet's configured currency.                 |
| bvnk:payment:rules:4013 | Wallet status validation error      | The wallet status validation failed. This error occurs when the current wallet status doesn't allow the requested operation or when the wallet is in an invalid state for the action being performed.       |
| bvnk:payment:rules:4014 | Wallet configuration state error    | The wallet configuration is in an invalid state for the requested operation. This may occur when trying to perform actions on configurations that are pending, disabled, or in transition states.           |
| bvnk:payment:rules:4015 | Invalid customer fee configuration  | The customer fee configuration contains invalid parameters or values. Check that fee amounts, percentages, and fee structure parameters are within acceptable ranges and properly formatted.                |

## 5000-5999

### Wallets

| **Code**             | **Message**              | **Description**                                                                                                                                                                                                          |
| :-------------------: | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| BVNK:LEDGER:5001 | Wallet not found         | The requested wallet could not be located in the system. Verify that the wallet identifier is correct and exists within your account.                                                                                    |
| BVNK:LEDGER:5050 | Wallet balance not found | The system could not retrieve balance information for the specified wallet. Ensure the wallet exists and has been properly initialized with a balance.                                                                   |
| BVNK:LEDGER:5040 | Bad Request              | The request contained invalid data, malformed parameters, or violated validation constraints. Review your request format and ensure all required fields contain valid data.                                              |
| BVNK:LEDGER:5051 | Wallet creation failed   | The wallet creation process failed to complete successfully. This could be due to system constraints, validation issues, or conflicts with existing data. Check the request details and try again with valid parameters. |

### Customers

| **Code**         | **Message**                                                                                                                                               | **Description**                                                               |
| :---------------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------- |
| MER-PAY-5001 | The requested wallet could not be located in the system.                                                                                                  | Verify that the wallet identifier is correct and exists within your account.  |
| MER-PAY-5050 | The system could not retrieve balance information for the specified wallet.                                                                               | Ensure the wallet exists and has been properly initialized with a balance.    |
| MER-PAY-5040 | The request contained invalid data, malformed parameters, or violated validation constraints.                                                             | Review your request format and ensure all required fields contain valid data. |
| MER-PAY-5051 | The wallet creation process failed to complete successfully. This could be due to system constraints, validation issues, or conflicts with existing data. | Check the request details and try again with valid parameters.                |

### Rules

| **Code**                    | **Message**             | **Description**                                                                                                                                                                                |
| :--------------------------: | :---------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| bvnk:payment:rules:5001 | Feature not implemented | The requested feature or functionality is not yet implemented in the current version of the payment rules system. This feature may be available in future releases.                            |
| bvnk:payment:rules:5003 | Wallet validation error | Wallet validation services are currently unavailable. This error indicates a temporary issue with external validation services or network connectivity problems affecting wallet verification. |
| bvnk:payment:rules:5004 | Internal error          | An unexpected internal server error occurred while processing the request. This indicates a system-level issue that should be reported to technical support for investigation.                 |

---

## Idempotency

Some API endpoints support idempotency, allowing you to safely retry requests without duplicating actions.

To use this feature, include an `X-Idempotency-Key` header in your request. The key must be a unique, UUID-formatted 36-character alphanumeric value.

A request with a new idempotency key will be processed. If you resend the same request with identical credentials and idempotency key, BVNK returns a 400 `Bad Request` status and indicates that a request with this ID already exists. This feature is especially useful for critical operations such as transferring funds, creating payment orders, or updating resources.

For example, if a payment order request times out due to a network issue, you can repeat the call with the same idempotency key to ensure only one payment order is created. Only successful requests are cached. Failed requests are not stored, so you can retry them without risk of conflict.

```curl Idempotent Request
curl --request POST \
     --url https://api.sandbox.bvnk.com/ledger/v1/wallets \
     --header 'X-Idempotency-Key: 1e74002e-74a1-48fd-b707-147c3187a3e1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
```

:::info For v.2 endpoints, use `Idempotency-Key` header instead of `X-Idempotency-Key`.
   
```bash
curl --request POST \
     --url https://api.sandbox.bvnk.com/payment/v2/transfers \
     --header 'Idempotency-Key: 1e74002e-74a1-48fd-b707-147c3187a3e1' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
   --data '
```
:::

---

## Metadata

You can include custom metadata in some requests. For example, in the payout requests the metadata will be associated with the payout and included in webhook events related to this payout.

To add metadata, include a top-level JSON object with the key `metadata`. The value of this key should be another JSON object containing your desired key-value pairs.

```json Example Request with Metadata
{
    ...
    "customerId": "ba388054-4512-441e-a9c4-cbe9b0fe0332",
    "metadata": {
        "orderId": "PO-2025-001",
        "internalUserId": "user-456",
        "reason": "Customer withdrawal"
    }
}
```

When adding metadata to your request, keep the following in mind:

* You can include up to 10 separate key-value pairs.
* Each metadata key and value must have at least one character.
* Each metadata key can be up to 40 characters long. Each value can contain a maximum of 255 characters.
* Metadata keys can only contain:
  * Uppercase letters (A-Z)
  * Lowercase letters (a-z)
  * Numbers (0-9)
  * Underscores (\_)
  * Hyphens (-)
* Metadata values cannot contain the characters "\<>".

The provided metadata will also be returned in the status endpoint for reference.

---

## Overview

The BVNK RESTful API is designed to enable seamless and secure transactions, including payments, channels, and digital wallet operations. The API operates over HTTP, and all requests and responses are formatted as JSON objects.

To gain access to the API, create an account on the BVNK Portal. Once you've completed the signup process and acknowledged our terms, create API keys (Hawk Auth ID and Secret Key).

BVNK API has two environments:

* Production: `https://api.bvnk.com/`
* Sandbox: `https://api.sandbox.bvnk.com/`

Note that items cannot be transferred between these environments. The sandbox environment is limited to test your integration safely before going live. You can request access to the Production API via the Portal.

You can download and use the BVNK OpenAPI Specification. This file contains the complete API specification that you can use with API clients, code generators, and AI tools. Right-click the link and select **Save link as...** to download the file.

---

## Pagination

By default, most of the "List" endpoints return paginated results. Use the query parameters `page` and `size` to control the number of results displayed.

```curl Pagination Example
curl --request GET \
     --url 'https://api.sandbox.bvnk.com/ledger/v1/wallets? page=2&size=30&sort=currencyCode%2Cdesc&offset=1' \
     --header 'accept: application/json'
```

| Parameter | Description                                                                                    |
| :-------- | :--------------------------------------------------------------------------------------------- |
| `page`    | Page number. Starts from "0".                                                                  |
| `size`    | Number of records on the page returned in the response. Maximum number: 100. Example, `2`.     |
| `sort`    | Sorting criteria. Format: `property,<asc/desc>`. Default sort order is ascending.              |
| `offset`  | Starting point for pagination. Use instead of `page`, for example for cursor-based pagination. |

In the response, the `pageable` object may be returned. The object provides detailed info on the pagination.

```json
{
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "empty": true,
            "unsorted": true,
            "sorted": false
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": true,
    "totalPages": 1,
    "totalElements": 2,
    "first": true,
    "size": 20,
    "number": 0,
    "sort": {
        "empty": true,
        "unsorted": true,
        "sorted": false
    },
    "numberOfElements": 2,
    "empty": false
}
```

| Attribute          | Description                                                                                                    |
| ------------------ | -------------------------------------------------------------------------------------------------------------- |
| `pageNumber`       | Current page number, for example, `0` for the first page.                                                      |
| `pageSize`         | Number of records per page, for example, `2`.                                                                  |
| `sort.empty`       | Indication whether the sort criteria is empty. `true` means no sorting.                                        |
| `sort.sorted`      | Indication whether the results are sorted. `false` means no sorting.                                           |
| `sort.unsorted`    | Indication whether the results are unsorted. `true` means no sorting.                                          |
| `offset`           | Offset of the first record, for example, `0`, which means no offset is applied.                                |
| `paged`            | Indication whether the results are paginated. `true` for paginated.                                            |
| `unpaged`          | Indication whether the results are not paginated (false).                                                      |
| `last`             | Indication whether this is the last page of results. `false` means there are more pages after the current one. |
| `totalPages`       | Total number of pages, for example, `10`.                                                                      |
| `totalElements`    | Total number of elements across all pages, foe example, `20` elements.                                         |
| `first`            | Indication whether this is the first page.  `true` for yes.                                                    |
| `size`             | Number of elements per page, for example, `2`.                                                                 |
| `number`           | Current page number, foe example, `0` for the first page.                                                      |
| `sort.empty`       | Indication whether the sort criteria is empty. `true` means no criteria.                                       |
| `sort.sorted`      | Indication whether the results are sorted. (false).                                                            |
| `sort.unsorted`    | Indication whether the results are unsorted. `true` for unsorted.                                              |
| `numberOfElements` | Number of elements on the current page, for example, `2` items.                                                |
| `empty`            | Indication whether the page is empty. `false` means the page contains elements.                                |

---

## Postman Collection

You can easily test our API before you start developing your app using our Postman Collection.\
This usually helps out immensely prior to any development process has even started.

[Download the Postman app](https://www.postman.com/downloads/) and import the collection by downloading it below:

  

**Note:** The Postman collection is automatically generated from our OpenAPI specification and matches the structure of the API documentation sidebar. Each new build ensures the collection stays up-to-date with any API changes.

## How to setup the collection

1. Click the button above to download the Postman collection file
2. Open Postman and click **Import** → **File** → Select the downloaded collection file
3. The collection includes pre-configured variables for `baseUrl`, `hawk_auth_id`, and `hawk_auth_key`
4. Update the collection variables with your HAWK AUTH ID and HAWK AUTH KEY that were displayed when you created your API keys
5. Set the `baseUrl` variable to either:
   - `api.sandbox.bvnk.com` for sandbox environment
   - `api.bvnk.com` for production environment

![](https://files.readme.io/3587036-Environment.png "Environment.png")

## Pick an API action from the list

To test individual endpoints and send requests, explore them on the left-hand side of your Postman.

![](https://files.readme.io/23e5af9-API.png "API.png")

---

## Agreement status change notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Agreement status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

**Event URN:** `bvnk:customers:agreements:status-change`

Fired when an agreement is accepted or rejected by the customer.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./agreement-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./agreement-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Associate documents status change notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Associate documents status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

**Event URN:** `bvnk:customers:associates:documents:status-change`

Fired when the status of one or more associate documents changes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./associate-documents-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./associate-documents-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Associate status change notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Associate status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

**Event URN:** `bvnk:customers:associates:status-change`

Fired when an associate's onboarding validation state changes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./associate-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./associate-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## BVNK Webhooks API

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"BVNK Webhooks API"}
>
</Heading>

BVNK Webhooks API provides real-time notifications for various events across the BVNK platform.
This API specification describes the webhook events that BVNK sends to your configured endpoints.

:::tip No strict serialisation
Do not strictly serialise the webhook fields that you do not need. Only apply the fields that you use in your platform.

For example, if you do not need the `metadata` field, you can omit it from the response.
:::

## Webhook Categories

- **Status Change Webhooks**: Fiat and crypto payment status changes
- **Channel Webhooks**: Crypto channel lifecycle and transaction events
- **Crypto Webhooks**: Cryptocurrency transaction lifecycle events
- **Customer Webhooks**: Customer management and compliance events
- **Ledger Webhooks**: Wallet creation and reporting events
- **Digital Asset Webhooks**: Deposit and withdrawal status changes

## Authentication

All webhooks include an `x-signature` header for verification using HMAC-SHA256.
The signature is calculated using your webhook secret key and the raw JSON payload.

## Response Requirements

Your webhook endpoint must respond with HTTP 200 status code to acknowledge receipt.
The retry policy adds a delay before each retry, starting with a base delay and increasing the time between retries. The delay grows larger after each attempt, but will not exceed 15 minutes. The system will attempt up to 100 times, and after that, no further retries will occur.

## Retry policy

If BVNK does not receive a `200` status code, the webhook retry policy will kick in. This includes cases where the endpoint returns a non-2xx status code or fails to respond within the 10-second timeout window. After 10 seconds without a successful response, the delivery attempt is considered failed and will trigger the retry process defined by the webhook policy.

The retry policy adds a delay before each retry, starting with a base delay and increasing it with each retry. The delay grows larger after each attempt, but will not exceed 15 minutes. The system will attempt up to 100 times, and after that, no further retries will occur.

To ensure safe and consistent processing, all webhook events include a unique identifier that receivers should use to implement idempotency. This prevents duplicate event handling if the same webhook is retried multiple times due to timeouts or failed responses. The receiving system should detect repeated event IDs and avoid performing the same business action more than once.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"API Key: WebhookSignature"}
      value={"WebhookSignature"}
    >
      
      
      HMAC-SHA256 signature for webhook verification.
      The signature is calculated using your webhook secret key and the raw JSON payload.
      
      Example verification in different languages:
      
      **JavaScript:**
      ```javascript
      const crypto = require('crypto');
      const signature = crypto
        .createHmac('sha256', secretKey)
        .update(payload, 'utf8')
        .digest('base64');
      ```
      
      **Python:**
      ```python

      signature = base64.b64encode(
        hmac.new(secretKey.encode('utf-8'), payload.encode('utf-8'), hashlib.sha256).digest()
      ).decode('ascii')
      ```
      
      
      
        
          
            
              
                Security Scheme Type:
              
                apiKey
              
            
              
                Header parameter name:
              
                x-signature
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Channel created

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Channel created"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The `bvnk:payment:channel:created` webhook is triggered when a new crypto payment **channel** is successfully created for a wallet.

The payload describes the channel configuration (currencies, chain address, redirect URL, linked contact, and flags). Use it to sync channel records in your systems when channels are created via API or BVNK UIs.

For channels created on an **customer's wallet**, the payload includes `embeddedCustomerDetails` with a `reference` to the customer. Channels on standard wallets omit `embeddedCustomerDetails`.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-created.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-created.StatusCodes.json")}
>
  
</StatusCodes>

---

## Channel transaction confirmed

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Channel transaction confirmed"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The `bvnk:payment:channel:transaction-confirmed` webhook is triggered when a new channel transaction is confirmed on chain, and the transaction has been processed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-transaction-confirmed.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-transaction-confirmed.StatusCodes.json")}
>
  
</StatusCodes>

---

## Channel transaction detected

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Channel transaction detected"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The `bvnk:payment:channel:transaction-detected` webhook is triggered when a new channel transaction is detected, and the transaction has not yet been confirmed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-transaction-detected.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-transaction-detected.StatusCodes.json")}
>
  
</StatusCodes>

---

## Channel transaction placed on hold

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Channel transaction placed on hold"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

The `bvnk:payment:channel:transaction-on-hold` webhook is triggered when a transaction sent to a channel is placed on hold under BVNKs compliance programme. If the payment is released, you will receive the `bvnk:payment:channel:transaction-confirmed` event.

:::tip
Please contact the BVNK Solutions team to enable this webhook event.
:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-transaction-on-hold.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-transaction-on-hold.StatusCodes.json")}
>
  
</StatusCodes>

---

## Company documents status change notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Company documents status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

**Event URN:** `bvnk:customers:documents:status-change`

Fired when the status of one or more company-level documents changes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./company-documents-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./company-documents-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Cryptocurrency refund initiated

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cryptocurrency refund initiated"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when a cryptocurrency payment refund is initiated.
This webhook indicates that a refund process has been started for a crypto payment.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./crypto-refund-initiated.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./crypto-refund-initiated.StatusCodes.json")}
>
  
</StatusCodes>

---

## Cryptocurrency payment status change

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cryptocurrency payment status change"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when the status of a cryptocurrency payment changes.
This webhook provides real-time updates on crypto payment processing status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./crypto-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./crypto-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Cryptocurrency transaction late

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cryptocurrency transaction late"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when a cryptocurrency transaction is received after the payment has expired or been completed.
This webhook indicates that funds were received for a payment that is no longer active.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./crypto-transaction-late.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./crypto-transaction-late.StatusCodes.json")}
>
  
</StatusCodes>

---

## Cryptocurrency transaction on hold

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cryptocurrency transaction on hold"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when a cryptocurrency transaction is placed on hold under BVNK's compliance program.
This webhook indicates that the transaction requires manual review before processing.

:::tip
Please contact the BVNK Solutions team to enable this webhook event.
:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./crypto-transaction-on-hold.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./crypto-transaction-on-hold.StatusCodes.json")}
>
  
</StatusCodes>

---

## Cryptocurrency transaction settled

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Cryptocurrency transaction settled"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when a cryptocurrency transaction is settled.
This webhook indicates that the transaction has been fully processed and settled.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./crypto-transaction-settled.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./crypto-transaction-settled.StatusCodes.json")}
>
  
</StatusCodes>

---

## Customer document status change notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Customer document status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when a customer document verification status changes.
This webhook provides real-time updates on document compliance status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./customer-document-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./customer-document-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Customer status change notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Customer status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when a customer's status changes to `INFO_REQUIRED`, `PENDING`, `VERIFIED`, or `REJECTED`.

This webhook provides real-time updates on customer onboarding and compliance status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./customer-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./customer-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Customer update notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Customer update notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when customer information is updated. This is usually done by a verification provider's link when customer data is populated from the verification provider.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./customer-update.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./customer-update.StatusCodes.json")}
>
  
</StatusCodes>

---

## Customer status change notification(Bvnk-webhooks)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Customer status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

**Event URN:** `bvnk:customers:status-change`

Fired when a customer's onboarding status changes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./customers-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./customers-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Ledger report ready notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Ledger report ready notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when a ledger report is ready for download.
This webhook provides real-time updates on report generation completion.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./ledger-report-ready.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ledger-report-ready.StatusCodes.json")}
>
  
</StatusCodes>

---

## Ledger wallet creation notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Ledger wallet creation notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

A wallet creation webhook provides real-time notifications to your system when a new wallet is successfully created.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./ledger-wallet-create.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ledger-wallet-create.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fiat pay-in status change notification (v2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fiat pay-in status change notification (v2)"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when the status of an incoming fiat payment changes (version 2).
This webhook provides real-time updates on pay-in processing status with enhanced data structure.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-payin-status-change-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-payin-status-change-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fiat payment status change notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fiat payment status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when the status of an incoming fiat payment changes.
This webhook provides real-time updates on payment processing status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-payin-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes>
  
</StatusCodes>

---

## Fiat payout status change notification (v2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fiat payout status change notification (v2)"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when the status of an outgoing fiat payment changes (version 2).
This webhook provides real-time updates on payout processing status with enhanced data structure.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-payout-status-change-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-payout-status-change-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fiat payout status change notification (v1)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fiat payout status change notification (v1)"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when the status of an outgoing fiat payment changes (version 1).
This webhook provides real-time updates on payout processing status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-payout-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-payout-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Internal transfer status change notification (v2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Internal transfer status change notification (v2)"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Triggered when the status of an internal payment transfer changes (version 2).
This webhook provides real-time updates on internal transfer processing status with enhanced data structure.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-transfer-status-change-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-transfer-status-change-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Internal transfer status change notification

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Internal transfer status change notification"}
>
</Heading>

<MethodEndpoint
  method={"event"}
  path={"webhook"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::caution deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

:::

Triggered when the status of an internal payment transfer changes.
This webhook provides real-time updates on internal transfer processing status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-transfer-status-change.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-transfer-status-change.StatusCodes.json")}
>
  
</StatusCodes>

---

## Accept Assigned Agreement

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Accept Assigned Agreement"}
>
</Heading>

<MethodEndpoint
  method={"patch"}
  path={"/onboarding/v1/assigned-agreements/{assignedAgreementId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Accepts an assigned agreement. Agreement status transitions from `PENDING` to `ACCEPTED`.

Use the `assignedAgreementId` returned by `GET /onboarding/v1/assigned-agreements?applicationId={id}`. All assigned agreements must be accepted before onboarding can complete.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./accept-onboarding-assigned-agreement.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./accept-onboarding-assigned-agreement.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./accept-onboarding-assigned-agreement.StatusCodes.json")}
>
  
</StatusCodes>

---

## Bulk Respond to Customer Agreements (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Bulk Respond to Customer Agreements (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v2/customers/{customerId}/agreements/actions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Accepts or rejects up to 50 assigned agreements in a single request.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./bulk-respond-customer-assigned-agreements-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./bulk-respond-customer-assigned-agreements-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./bulk-respond-customer-assigned-agreements-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## BVNK API Endpoints

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"BVNK API Endpoints"}
>
</Heading>

The BVNK API is designed to facilitate seamless and secure transactions including payments, channels, and digital wallet transactions.

  <Heading
    id={"authentication"}
    as={"h2"}
    className={"openapi-tabs__heading"}
    children={"Authentication"}
  >
  </Heading><SchemaTabs
    className={"openapi-tabs__security-schemes"}
  >
    <TabItem
      label={"API Key: Hawk"}
      value={"Hawk"}
    >
      
      
      Hawk Payload (see: https://github.com/hueniverse/hawk)
      
      
        
          
            
              
                Security Scheme Type:
              
                apiKey
              
            
              
                Header parameter name:
              
                Authorization
              
            
          
        
      
    </TabItem><TabItem
      label={"HTTP: Bearer Auth"}
      value={"BearerAuth"}
    >
      
      
      Bearer token for authentication.
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                bearer
              
            
              
                Bearer format:
              
                JWT
              
            
          
        
      
    </TabItem><TabItem
      label={"HTTP: Basic Auth"}
      value={"ApiKeyAuth"}
    >
      
      
      HTTP Basic authentication using your API credentials. Provide your API ID as the username and your API Key as the password; the client sends `Authorization: Basic base64(API_ID:API_KEY)`.
      
      
        
          
            
              
                Security Scheme Type:
              
                http
              
            
              
                HTTP Authorization Scheme:
              
                basic
              
            
          
        
      
    </TabItem>
  </SchemaTabs>

---

## Create Channel

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Channel"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v2/channel"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a channel through which your customers can send crypto payments.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-create.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-create.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Channels

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Channels"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/channel"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all channels related to a Wallet ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./channel-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Channel Payments

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Channel Payments"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/channel/payment"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of payments to a channel on a specific Wallet ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./channel-payment-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-payment-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-payment-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Channel Payment

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Channel Payment"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/channel/payment/{uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a specific payment made into a channel.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./channel-payment-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-payment-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-payment-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Channel

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Channel"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/channel/{uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a specific channel by its UUID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./channel-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Channel Spot Rate

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Channel Spot Rate"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v2/channel/{uuid}/spot"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Poll the current spot rate for a channel. Use this endpoint if you are building your own UI and need to display the live conversion rate to customers.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./channel-spot-rate.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./channel-spot-rate.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./channel-spot-rate.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Agreement Signing Session.

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Agreement Signing Session."}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v1/customers/agreement/sessions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-agreement-session.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-agreement-session.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Business Customer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Business Customer"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/onboarding/v1/applications"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a business customer onboarding application in a single request. Submit company details, associates, and business profile together. BVNK enriches the submission and routes it to the onboarding orchestrator.

Jurisdiction guidance:
- EU flows require associate nationality, birth country, and biometric/selfie evidence.
- US flows require US tax identifiers where applicable and may require additional fields for control persons.
- `stateCode` for US addresses is planned for a future release and is not yet enforced.

Onboarding completes automatically once required company documents, associate identification documents, required questionnaires, and assigned agreements are all submitted and accepted for processing.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-business-customer-onboarding-application.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-business-customer-onboarding-application.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Customer Associate (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Customer Associate (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v2/customers/{customerId}/associates"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates an associate under a customer onboarding application. The `entity` payload is discriminated by `type`: use `PERSON` for a natural person (UBO, director, signatory, account representative) or `BUSINESS_REGISTRATION` for a registered-business owner.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-customer-associate-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-customer-associate-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-customer-associate-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Customer (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Customer (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v2/customers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Starts a new customer onboarding application. Submit either a `company` or `individual` payload together with the `useCase`. Requires realm role `ROLE_USER` or `ROLE_UNDERLYING_CUSTOMER_EDIT`.

Jurisdiction guidance:
- EU flows require associate nationality, birth country, and biometric/selfie evidence.
- US flows require US tax identifiers where applicable and may require additional fields for control persons.
- `stateCode` for US addresses is planned for a future release and is not yet enforced.

Onboarding completes automatically once required company documents, associate identification documents, required questionnaires, and assigned agreements are all submitted and accepted for processing.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-customer-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-customer-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-customer-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Fiat Wallet

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Fiat Wallet"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/ledger/v1/wallets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a fiat wallet for a specific Customer, generating a unique virtual account tied to the wallet.

---

For more information, how to apply it in the Embedded Wallets flow, refer to the [Create a customer wallet](https://docs.bvnk.com/docs/step-2-creating-a-customer-wallet-and-virtual-account#/create-a-customer-wallet) guide.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-customer-wallet.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-customer-wallet.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-customer-wallet.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Customer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Customer"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v1/customers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Creates an Embedded Partner Customer account. The customer can be 'Individual' or 'Company'.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./create-customer.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-customer.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-customer.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Express Session

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Express Session"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v1/wallet-sessions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a wallet session URL for Embedded Express customers, allowing them to access their branded stablecoin wallet. The URL is returned in `walletSessionUrl` and can be shared via web view, redirect, or other integration methods. Each session link is time-bound and user-specific for security. BVNK verifies the user's identity before granting access. For details on the customer experience, consult your Account Manager.

To maintain consistent branding, include the optional `theme` object with each session creation. This ensures your customer sees your colors and logo in their wallet interface.

The endpoint automatically manages onboarding based on the customer's status with BVNK:

• New customers receive an onboarding link.

• Existing BVNK customers who have not used Express receive an Express registration link.

• Existing Express customers receive a login link.

• Customers with an active session token can access the wallet interface directly.

For existing BVNK customers receiving an Express link for the first time, ensure the link is accessible only by the intended customer.

Use this endpoint to enable Express features for your customers.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-express-session.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-express-session.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Report Schedule

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Report Schedule"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/ledger/v1/report-schedules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a new scheduled report that will be automatically generated and delivered according to the specified frequency and delivery preferences. Each user can create only one schedule per account.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./create-report-schedule.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./create-report-schedule.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete Customer Associate (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Customer Associate (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/platform/v2/customers/{customerId}/associates/{associateId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes an associate from a customer onboarding application. Safe to call before the application transitions to a terminal state.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-customer-associate-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-customer-associate-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-customer-associate-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Remove a Document

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Remove a Document"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/platform/v1/customers/documents/{documentReference}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Deletes a specified document from a Customer's profile.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-document.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-document.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-document.StatusCodes.json")}
>
  
</StatusCodes>

---

## Delete Report Schedule

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Delete Report Schedule"}
>
</Heading>

<MethodEndpoint
  method={"delete"}
  path={"/ledger/v1/report-schedules/{scheduleId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Deletes an existing report schedule. Only the user who created the schedule can delete it. Once deleted, no further reports will be generated according to this schedule.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./delete-report-schedule.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./delete-report-schedule.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./delete-report-schedule.StatusCodes.json")}
>
  
</StatusCodes>

---

## Download Customer Document (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Download Customer Document (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{customerId}/documents/{documentId}/content"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Downloads a customer document as a binary file attachment.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./download-customer-document-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./download-customer-document-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./download-customer-document-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Estimate Refund Fee

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Estimate Refund Fee"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v1/payins/{transactionReference}/refund/estimate"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns the estimated processing fee and the maximum remaining refundable balance for the pay-in. The fee will be deducted from your wallet when issuing a refund. The fee amount may vary depending on the merchant contract with BVNK.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./estimate-refund-fee.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./estimate-refund-fee.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./estimate-refund-fee.StatusCodes.json")}
>
  
</StatusCodes>

---

## Retrieve Agreement Session Status

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retrieve Agreement Session Status"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/customers/agreement/sessions/{reference}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Returns the current status of an agreement session using its reference ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-agreement-session-status.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-agreement-session-status.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-agreement-session-status.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fetch Agreements

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fetch Agreements"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v1/agreement"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch all required agreement documents needed to onboard an Embedded Partner Merchant.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-agreements.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-agreements.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-agreements.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Customer Agreement Content (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer Agreement Content (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{customerId}/agreements/{assignedAgreementId}/content"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a short-TTL presigned URL for downloading the agreement document.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-customer-agreement-content-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-agreement-content-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-agreement-content-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Customer Agreement (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer Agreement (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{customerId}/agreements/{assignedAgreementId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a single assigned agreement by id.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-customer-assigned-agreement-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-assigned-agreement-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-assigned-agreement-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Customer Associate (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer Associate (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{customerId}/associates/{associateId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a single associate by id.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-customer-associate-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-associate-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-associate-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Customer Document (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer Document (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{customerId}/documents/{documentId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a single customer document by id.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-customer-document-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-document-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-document-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Customer Documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer Documents"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/customers/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Retrieves the details of the specific document added for the Customer. If no parameters are specified, retrieves the array of available documents.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-customer-documents.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-documents.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-documents.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Customer Fee Wallets

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer Fee Wallets"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/fees/customer-fee-wallets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the list of available wallets that can receive customer fees.

For more information, refer to [Customer fees](https://docs.bvnk.com/docs/charge-customer-fees#/).

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-fee-wallets.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-fee-wallets.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Required Information

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Required Information"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/customers/{customerReference}/info-required"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Retrieves detailed information about what documents and data are required for customer onboarding when their status is `INFO_REQUIRED`. This endpoint provides specific requirements for documents, questionnaires, and additional data needed to complete the onboarding process.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-customer-info-required.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-info-required.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-info-required.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Customer (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a customer by id, including the submitted onboarding body (`company` or `individual`). Person associates are inlined under `company.associates`; business-registration associates remain accessible via `GET /platform/v2/customers/{customerId}/associates/{associateId}`.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-customer-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Customer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Customer"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/customers/{customerReference}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-customer-with-external-status.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-customer-with-external-status.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-customer-with-external-status.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Document Download URL

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Document Download URL"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/customers/documents/{documentReference}/url"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Retrieves a temporary URL for document download.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-document-url.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-document-url.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-document-url.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Industries

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Industries"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/accounts/industries"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a definitive list of industries and sub-industries, which can be included in the payload when creating a customer.

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-industries.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-industries.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Monthly Expected Volumes

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Monthly Expected Volumes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/accounts/monthly-expected-volumes"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a definitive list of Expected Monthly Volume values, which can be included in the payload when creating a customer.

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-monthly-expected-volumes.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-monthly-expected-volumes.StatusCodes.json")}
>
  
</StatusCodes>

---

## Retrieve Application Status

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retrieve Application Status"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/onboarding/v1/applications/{onboardingId}/status"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the current onboarding application state, including associates' validation status, outstanding required documents, questionnaire definitions, validation errors, and agreement statuses.

- Associate `validationStatus=INVALID` means outstanding requirements still exist; inspect `requiredDocuments`, `questionnaireDefinitions`, and `validationErrors`.
- On rejection, `rejectLabels` and `clientComment` describe why resubmission is required.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-onboarding-application-status.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-onboarding-application-status.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-onboarding-application-status.StatusCodes.json")}
>
  
</StatusCodes>

---

## Retrieve Assigned Agreements

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retrieve Assigned Agreements"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/onboarding/v1/assigned-agreements"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns agreements assigned to an onboarding application. All assigned agreements must reach `ACCEPTED` status for onboarding to proceed.

Use this endpoint with the onboarding application ID: `GET /onboarding/v1/assigned-agreements?applicationId={onboardingId}`.

Assigned agreements can be accepted at any point after customer creation (before or after document uploads); there is no ordering dependency.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-onboarding-assigned-agreements.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-onboarding-assigned-agreements.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-onboarding-assigned-agreements.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Questionnaire Definition

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Questionnaire Definition"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/customers/questionnaire/definitions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Fetches quiestionnaire schemas with questions, answer types, option lists. You can render the questionnaire in  your UI. 

 Questionnaires include the following sections:**Nature of Business**: mandatory details related to company operations)**Document Requirements**: key compliance documents 

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-questionnaire-definitions.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-questionnaire-definitions.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-questionnaire-definitions.StatusCodes.json")}
>
  
</StatusCodes>

---

## Search Questionnaire Submissions

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search Questionnaire Submissions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/customers/questionnaires"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v1
If you already have an integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Returns previously submitted questionnaire answer sets matching the supplied filters

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./get-questionnaires.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-questionnaires.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-questionnaires.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Supported Timezones

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Supported Timezones"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v1/report-schedules/timezones"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all supported timezones that can be used when creating or updating report schedules. Each timezone includes both the IANA timezone identifier and a human-readable label with UTC offset.

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./get-supported-timezones.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./get-supported-timezones.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Wallet

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Wallet"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/ledger/v2/wallets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a crypto or fiat wallet associated with a wallet profile. You can create wallets for yourself or for your customers.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./ledger-wallet-create-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./ledger-wallet-create-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ledger-wallet-create-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Execute Wallet Action

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Execute Wallet Action"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/ledger/v2/wallets/{id}/actions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Executes a lifecycle action on a wallet: TERMINATE, BLOCK, or UNBLOCK. A non-empty comment explaining the reason is required.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./ledger-wallet-execute-action.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./ledger-wallet-execute-action.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ledger-wallet-execute-action.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Wallets

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Wallets"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v2/wallets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Shows all *Direct* and *Customer* wallet types. Results are summaries only (**ledgers are not included**); use `GET /ledger/v2/wallets/{id}` to retrieve a single wallet with full details including ledgers.

The endpoint uses the [Lucene query syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html), for example, `GET https://api.bvnk.com/ledger/v2/wallets?q=customerId:550e8400-e29b-41d4-a716-446655440000 AND status:(ACTIVE OR INACTIVE)` returns all active and inactive wallets for that customer.

**Note:** Field names in the `q` search expression are case-sensitive. If you use a field that is not recognised, it is ignored.

Operator `OR` is only supported within the same field (group alternatives with parentheses), not across different fields.

- Supported: `?q=currency:(USD OR EUR)`
- Not supported: `?q=currency:USD OR customerId:550e8400-e29b-41d4-a716-446655440000`

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./ledger-wallet-list-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./ledger-wallet-list-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ledger-wallet-list-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## List all Customer Wallets

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List all Customer Wallets"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v1/wallets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of wallets for your Embedded Partner Customers (EPCs).

• **Without parameters**: Returns all wallets associated with all your customers.

• **With `customerReference` parameter**: Returns wallets for a specific customer only. Usage: `https://api.bvnk.com/ledger/v1/wallets?customerReference=550e8400-e29b-41d4-a716-446655440000
`.

**Deprecated:** use `GET /ledger/v2/wallets` instead.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./ledger-wallet-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./ledger-wallet-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ledger-wallet-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Wallet

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Wallet"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v2/wallets/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a single fiat or crypto wallet by its ID. You can retrieve your own or your customer's wallet.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./ledger-wallet-read-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./ledger-wallet-read-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ledger-wallet-read-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Wallet(Endpoints)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Wallet"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v1/wallets/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a specific wallet by its ID.

**Deprecated:** use `GET /ledger/v2/wallets/{id}` instead.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./ledger-wallet-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./ledger-wallet-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./ledger-wallet-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Customers

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Customers"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v1/customers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Retrieves the full list of Customers.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-account-customers.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-account-customers.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-account-customers.StatusCodes.json")}
>
  
</StatusCodes>

---

## Fetch Country Codes

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Fetch Country Codes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/country"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Fetch list of all countries and associated ISO codes.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-countries.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-countries.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-countries.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Crypto Currencies

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Crypto Currencies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/currency/crypto"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all cryptocurrencies available on the BVNK platform. This list represents cryptocurrencies that end users can select whilst making a payment.

Also, see [Currencies](https://docs.bvnk.com/bvnk/references/currencies/) for the comprehensive list of available currencies.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-currencies-crypto.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-currencies-crypto.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-currencies-crypto.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Wallet Currencies

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Wallet Currencies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/currency/deposit"}
  context={"endpoint"}
>
  
</MethodEndpoint>

These are the currencies that can be used to create a new wallet.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-currencies-deposit.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-currencies-deposit.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-currencies-deposit.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Fiat Currencies

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Fiat Currencies"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/currency/fiat"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all display fiat currencies available on BVNK's Crypto Payments API.
This list refers to currencies merchants can display on a payment page to an end user. It does not represent the list of currencies that can be held on the platform in wallets.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-currencies-fiat.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-currencies-fiat.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-currencies-fiat.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Customer Agreements (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Customer Agreements (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{customerId}/agreements"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a paginated list of agreements assigned to a customer. All assigned agreements must reach `ACCEPTED` status for onboarding to proceed.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-customer-assigned-agreements-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-customer-assigned-agreements-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-customer-assigned-agreements-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Customer Associates (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Customer Associates (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{customerId}/associates"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a paginated list of associates for a customer.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-customer-associates-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-customer-associates-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-customer-associates-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Customer Documents (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Customer Documents (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers/{customerId}/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns a paginated list of documents associated with a customer.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-customer-documents-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-customer-documents-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-customer-documents-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Exchange Rates

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Exchange Rates"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/currency/values/{baseCurrency}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Lists available exchange rates for a given currency.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-exchange-rates.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-exchange-rates.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-exchange-rates.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Report Schedules

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Report Schedules"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v1/report-schedules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a paginated list of report schedules for the authenticated user's account. Returns all schedules created by the user with their current configuration and delivery preferences.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./list-report-schedules.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./list-report-schedules.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./list-report-schedules.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Merchant ID

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Merchant ID"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v1/merchant"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Generate a Merchant ID for your account to process pay-ins and pay-outs through our API.

A Merchant ID is essential as it designates the account wallet where incoming pay-ins will be settled. For instance, if a Merchant ID is associated with a EUR wallet ID, any incoming USDT payment will be automatically converted to EUR and deposited in the designated EUR wallet.

Vice versa, any outgoing USDT payment will be automatically converted and withdrawn from the designated EUR wallet.

For further information, please visit https://docs.bvnk.com/docs/creating-your-first-merchant to learn more about creating your first Merchant ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./merchant-id-create.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./merchant-id-create.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Merchant IDs

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Merchant IDs"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v1/merchant"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves merchant IDs setup on your account.

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./merchant-id-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./merchant-id-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Accept an Estimated Payout

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Accept an Estimated Payout"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v1/pay/estimate/{externalId}/accept"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Accepts the current estimate and converts it into a pending crypto payment.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./pay-estimate-accept.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./pay-estimate-accept.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./pay-estimate-accept.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update an Existing Estimate Payout

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update an Existing Estimate Payout"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v1/pay/estimate/{externalId}/update"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Refreshes the quote using the latest exchange rates and fees. Call periodically (e.g., every 30 seconds) with either `walletRequiredAmount` or `paidRequiredAmount` to recalculate the other.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./pay-estimate-update.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./pay-estimate-update.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./pay-estimate-update.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create an Estimate Payout

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create an Estimate Payout"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v1/pay/estimate"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves latest exchange rates, fees and network costs for a crypto payout without creating an actual payout. Provide either `walletRequiredAmount` (amount to send) or `paidRequiredAmount` (amount the recipient should receive). See the [Estimate Crypto Payouts](https://docs.bvnk.com/docs/estimate-crypto-payouts#/) guide for details.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./pay-estimate.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./pay-estimate.StatusCodes.json")}
>
  
</StatusCodes>

---

## Accept Payment

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Accept Payment"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v1/pay/{uuid}/accept/summary"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Accepts a pending payment with currency or payout information.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payment-accept.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-accept.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-accept.StatusCodes.json")}
>
  
</StatusCodes>

---

## Confirm Payment

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Confirm Payment"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v1/pay/{uuid}/confirm/summary"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Confirms a two-step payout.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payment-confirm.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-confirm.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-confirm.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Payment

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Payment"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v1/pay/summary"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates an incoming (type IN) or outcoming (type OUT) crypto payment.

Alternatively, it creates a crypto payment that is either sent via a Customer's wallet or deposited into it. For more information, see the [Make Crypto Payments](https://docs.bvnk.com/docs/create-a-crypto-payout#/) guide.

There are two flows depending on specifying `payOutDetails`: 

 - If you add `PayOutDetails` with all its child parameters, the payment is successfully created and the funds are sent to the specified wallet, with no further actions needed.

 - If not included in the request, in the response you receive `redirectUrl`. This is a link to a page, where to you can redirect your Customer so they can finalize the payment.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-create.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-create.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Payments

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Payments"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v1/pay/summary"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of payments on a specific Wallet ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payment-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Validate Address

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Validate Address"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v1/pay/validate"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Validates that a crypto address is correct.

Use this endpoint to validate that an address exists, is correctly formatted, and includes all the required data. This endpoint can help prevent your end users losing funds when submitting a payout.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-out-validate.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-out-validate.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Payment

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Payment"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v1/pay/{uuid}/summary"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves details of a specific payment using the UUID of the payment.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payment-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Activate or Deactivate Payment Rule

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Activate or Deactivate Payment Rule"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v1/rules/{id}/actions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Activates or deactivates a payment rule. If you linked a rule to an incorrect wallet, you can deactivate it. Deactivated rules will not trigger automated actions but remain in your account for reference.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payment-rule-action.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-rule-action.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-rule-action.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create on-ramp payment rule

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create on-ramp payment rule"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v1/rules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a rule that links a crypto wallet to a fiat virtual account to automatically handle on-ramp (fiat → crypto) flow. The `trigger` field defines the flow to activate:

 - `payment:payin:fiat` — on-ramp

For more information, see the [Automate Fiat-to-Crypto Transfers](https://docs.bvnk.com/docs/automate-fiat-to-crypto-transfers#/) guide.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-rule-create.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-rule-create.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Payment Rules by Wallet

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Payment Rules by Wallet"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/payment/v1/rules/{walletId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of payment rules applied to a specific wallet by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payment-rule-list-by-wallet.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-rule-list-by-wallet.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-rule-list-by-wallet.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Payment Rules

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Payment Rules"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/payment/v1/rules"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of all payment rules configured for your account.

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-rule-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-rule-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update Payment Rule

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Payment Rule"}
>
</Heading>

<MethodEndpoint
  method={"patch"}
  path={"/payment/v1/rules/{id}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Partially updates a previously created payment rule. Only properties included in the request are updated; omitted fields remain unchanged. Setting a nullable property to null clears it.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payment-rule-update.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-rule-update.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-rule-update.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update Payment

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Payment"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v1/pay/{uuid}/update/summary"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates a pending payment with currency or payout information.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payment-update.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payment-update.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payment-update.StatusCodes.json")}
>
  
</StatusCodes>

---

## Confirm Beneficiary's Name

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Confirm Beneficiary's Name"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v2/payouts/{Id}/actions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Confirms a payout when the beneficiary name check returns a mismatch warning. If not confirmed within five minutes, the action expires. In this case, make a new payout.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payout-confirm-beneficiary-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payout-confirm-beneficiary-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payout-confirm-beneficiary-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Initiate Payout (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Initiate Payout (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v2/payouts"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a payout to business or individual customers.

In case of payment in Euro, the transaction is subject to **Verification of Payee** (VoP): if the beneficiary's name in the request doesn't match the name in the beneficiary's bank account, the status 202 Verification Failed is returned. To proceed with the payment, you must [Confirm Beneficiary's name](https://docs.bvnk.com/reference/payoutconfirmbeneficiaryv2#/). For the details, refer to the [Initiate Payouts (v.2)](https://docs.bvnk.com/docs/initiate-payment-2#/) guide.

We recommend sending as much beneficiary and bank information as you can. Complete details help correspondent banks and payment networks process the payout and reduce the risk of delays or rejections.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payout-create-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payout-create-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payout-create-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Proof of Payment in PDF

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Proof of Payment in PDF"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/payment/v2/payouts/{transactionId}/proof-of-payment"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a Proof of Payment PDF report for a fiat wallet payout. The proof of payment is available only for completed fiat payouts.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payout-get-proof-of-payment-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payout-get-proof-of-payment-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payout-get-proof-of-payment-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Retrieve Payout (v.2).

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Retrieve Payout (v.2)."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/payment/v2/payouts/{transactionId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a specific payout. You can also use this endpoint to check the status of the crypto or fiat payout.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payout-get-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payout-get-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payout-get-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Payout

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Payout"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/payment/v1/payouts/{transactionReference}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::caution deprecated

This endpoint is deprecated. Please use the `GET /payment/v2/payouts/:transactionId` endpoint instead.

:::

Retrieves a specific payout.

You can also use this endpoint to check the status of the crypto or fiat payout.

**Note**: The PENDING_APPROVAL status is only relevant for **fiat payouts**.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./payout-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./payout-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./payout-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Accept Quote

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Accept Quote"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/api/v1/quote/accept/{uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Executes a quote.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./quote-accept.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./quote-accept.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./quote-accept.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Quote

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Quote"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/v1/quote"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a quote to convert currency between wallets.

For wallet-to-wallet payment quotes, the payment processing is synchronous. You can expect the following statuses in the response:

| When | `quoteStatus` | `paymentStatus` |
|------|-------------|---------------|
| **Successful payment**|| |
| Getting an estimate | `ESTIMATE` | `PENDING` |
| Creating a quote | `PENDING` | `PENDING` |
| Accepting the quote | `PAYMENT_OUT_PROCESSED` | `SUCCESS` |
|**Failed payment**|| |
| Pay-in fails | `PAYMENT_IN_FAILED` | `FAILED` |
| Conversion fails | `CONVERSION_FAILED` | `FAILED` |
| Pay-out fails | `PAYMENT_OUT_FAILED` | `FAILED` |

If you don't receive `"paymentStatus": "SUCCESS"` in the response, you can call `/api/v1/quote/{uuid}` to check the conversion progress.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./quote-create.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./quote-create.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./quote-create.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Quotes

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Quotes"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v1/quote/{merchantId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves all quotes on a specific Merchant ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./quote-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./quote-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./quote-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Quote

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Quote"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/v1/quote/{uuid}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a specific quote.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./quote-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./quote-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./quote-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Exchange Rate

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Exchange Rate"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/currency/convert/{fromCode}/{toCode}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Provides a last traded price from connected liquidity providers between two assets.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./read-exchange-rate.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./read-exchange-rate.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./read-exchange-rate.StatusCodes.json")}
>
  
</StatusCodes>

---

## Refund Pay-in

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Refund Pay-in"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v1/payins/{transactionReference}/refund"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Initiates seamless one-click refund processing for any previous pay-in. Once accepted, a refund transaction appears in your  portal and can be acquired via API. 

 Upon activation, the system automatically generates a new transaction according to our standard workflow. You can request multiple refunds for the same transaction, as long as the total refunded amount doesn't exceed what was originally paid in.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./refund-payin.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./refund-payin.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./refund-payin.StatusCodes.json")}
>
  
</StatusCodes>

---

## Respond to Customer Agreement (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Respond to Customer Agreement (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v2/customers/{customerId}/agreements/{assignedAgreementId}/actions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Accepts or rejects a single assigned agreement. Agreement status transitions from `PENDING` to `ACCEPTED` or `REJECTED`. All assigned agreements must be accepted before onboarding can complete.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./respond-customer-assigned-agreement-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./respond-customer-assigned-agreement-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./respond-customer-assigned-agreement-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Search Customers (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Search Customers (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/platform/v2/customers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Searches customers associated with the caller's account, with optional filters and pagination. Requires realm role `ROLE_USER_READ`.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./search-customers-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./search-customers-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./search-customers-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Set Wallet for Customer Fees

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Set Wallet for Customer Fees"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/platform/v1/fees/customer-fee-wallets"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Sets up the customer fee wallet for a specific currency. The customer fee wallet is where the collected customer fees will be credited when processing transactions. For more information, refer to [Customer fees](https://docs.bvnk.com/docs/charge-customer-fees#/).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./set-customer-fee-wallet.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./set-customer-fee-wallet.StatusCodes.json")}
>
  
</StatusCodes>

---

## Simulate Pay-in (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Simulate Pay-in (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v2/payins/simulation"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Simulates pay-ins with different currencies and payment methods in the sandbox environment.

This version allows specifying originator entity details (individual or company) for more comprehensive testing scenarios.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./simulate-payin-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./simulate-payin-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Simulate Pay-in

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Simulate Pay-in"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v1/payins/simulate"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::caution deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

:::

Simulates pay-ins with different currencies and payment methods in the sandbox environment.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./simulate-payin.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./simulate-payin.StatusCodes.json")}
>
  
</StatusCodes>

---

## Submit Associate Questionnaires

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Submit Associate Questionnaires"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/onboarding/v1/associates/{associateId}/questionnaires"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Submits questionnaire responses for an associate. Always source questionnaire IDs, section IDs, item IDs, and accepted values from `questionnaireDefinitions` returned by onboarding status response (`GET /onboarding/v1/applications/{onboardingId}/status`), as structures vary by jurisdiction and risk profile.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./submit-onboarding-associate-questionnaires.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./submit-onboarding-associate-questionnaires.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./submit-onboarding-associate-questionnaires.StatusCodes.json")}
>
  
</StatusCodes>

---

## Submit Questionnaire

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Submit Questionnaire"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/platform/v1/customers/{customerReference}/questionnaires"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Submit questionnaire answers provided by your customers. BVNK validates completeness asynchronously and transitions the customer to the next onboarding state when all required answers are present. In case some answers are missing, BVNK specifies them and waits for all the answers to be submitted

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./submit-questionnaire-responses.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./submit-questionnaire-responses.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./submit-questionnaire-responses.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Internal Transfer (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Internal Transfer (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v2/transfers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates an internal stablecoin and fiat transfer between EPC and EP wallets.

Payment combinations:

- Crypto to crypto

- Fiat to fiat

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./transfer-create-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./transfer-create-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./transfer-create-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Internal Transfer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Internal Transfer"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/payment/v1/transfers"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::caution deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

:::

Create an internal Fiat transfer to an existing beneficiary wallet.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./transfer-create.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./transfer-create.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./transfer-create.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Transfer (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Transfer (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/payment/v2/transfers/{transferId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a specific transfer details.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./transfer-read-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./transfer-read-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./transfer-read-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Transfer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Transfer"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/payment/v1/transfers/{transactionReference}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::caution deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

:::

Retrieves a specific transfer details.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./transfer-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./transfer-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./transfer-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Transfer Beneficiaries

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Transfer Beneficiaries"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/payment/v1/transfers/{walletId}/beneficiaries"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of beneficiaries eligible for transfers for a specified wallet.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./transfers-beneficiary-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./transfers-beneficiary-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./transfers-beneficiary-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update Agreement Session Status

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Agreement Session Status"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/platform/v1/customers/agreement/sessions/{reference}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Updates the signing status of an agreement session. Typically used after user submission to mark the session as SIGNED or DECLINED.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-agreement-session.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-agreement-session.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-agreement-session.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update Customer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Customer"}
>
</Heading>

<MethodEndpoint
  method={"patch"}
  path={"/platform/v1/customers/{customerReference}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Updates customer information for individual customers. You can update contact information (email and phone), address details, and date of birth.

Only include the fields in your request that you want to update.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-customer.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-customer.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-customer.StatusCodes.json")}
>
  
</StatusCodes>

---

## Update Existing Report Schedule

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Update Existing Report Schedule"}
>
</Heading>

<MethodEndpoint
  method={"put"}
  path={"/ledger/v1/report-schedules/{scheduleId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Updates an existing scheduled report with new frequency and delivery preferences. Only the user who created the schedule can update it.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./update-report-schedule.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./update-report-schedule.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./update-report-schedule.StatusCodes.json")}
>
  
</StatusCodes>

---

## Upload Associate Identification Documents (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Upload Associate Identification Documents (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v2/customers/{customerId}/associates/{associateId}/identification-documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Uploads 1-3 identification and address verification documents for a specific associate as `multipart/form-data`.

Use `associateId` returned by the create-associate or list-associates endpoint.

Jurisdiction guidance:
- EU: selfie/liveness and proof of address are generally mandatory.
- US: selfie may be optional while tax and control-person requirements can apply.

If a submitted document is rejected, resubmit a corrected file through the same endpoint; the previous rejected document is replaced.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./upload-associate-identification-documents-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./upload-associate-identification-documents-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./upload-associate-identification-documents-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Upload Company Documents (v.2)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Upload Company Documents (v.2)"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v2/customers/{customerId}/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Uploads 1-3 company-level KYB documents for a customer as `multipart/form-data`.

The `metadata` field is a JSON array and `files` contains one file per metadata entry in matching order.

Use this endpoint for initial mandatory KYB files and for conditional/risk-triggered requests (for example Source of Wealth, AML policy, or regulatory licence). If a document is rejected later, re-upload the corrected file to this endpoint to replace the rejected submission.

Best practice: upload documents sequentially and add a 1-second delay to reduce rate-limit pressure.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./upload-customer-company-documents-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./upload-customer-company-documents-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./upload-customer-company-documents-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Upload Documents to Customer

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Upload Documents to Customer"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v1/customers/{customerReference}/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::info Customers API v2
The [new customer onboarding flow](../../../get-started/create-embedded-partner-customer/create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Attach one or more documents to a customer's profile. This can be either a company customer (with optional linkage to a specific associate) or an individual customer. Files must be base64-encoded before submission.

- For company-level documents, omit `customerPersonReference`.
- For associate-level documents, provide the `customerPersonReference`.
- The customer must be in `INFO_REQUIRED` status.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./upload-customer-documents.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./upload-customer-documents.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./upload-customer-documents.StatusCodes.json")}
>
  
</StatusCodes>

---

## Upload Associate Identity Documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Upload Associate Identity Documents"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/onboarding/v1/associates/{associateId}/identification-documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Uploads identity and address verification documents for a specific associate as `multipart/form-data`.

Use `associateId` from the onboarding status response (`GET /onboarding/v1/applications/{onboardingId}/status`).

Jurisdiction guidance:
- EU: selfie/liveness and proof of address are generally mandatory.
- US: selfie may be optional while tax and control-person requirements can apply.

If a submitted document is rejected, resubmit a corrected file through the same endpoint; the previous rejected document is replaced.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./upload-onboarding-associate-identification-documents.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./upload-onboarding-associate-identification-documents.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./upload-onboarding-associate-identification-documents.StatusCodes.json")}
>
  
</StatusCodes>

---

## Upload Company Documents

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Upload Company Documents"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/onboarding/v1/applications/{onboardingId}/documents"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Uploads company-level KYB documents for an onboarding application as `multipart/form-data`.

The `metadata` field is a JSON array and `files` contains one file per metadata entry in matching order.

Use this endpoint for initial mandatory KYB files and for conditional/risk-triggered requests (for example Source of Wealth, AML policy, or regulatory licence). If a document is rejected later, re-upload the corrected file to this endpoint to replace the rejected submission.

Best practice: upload documents sequentially and add a 1-second delay to reduce rate-limit pressure.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./upload-onboarding-company-documents.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./upload-onboarding-company-documents.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./upload-onboarding-company-documents.StatusCodes.json")}
>
  
</StatusCodes>

---

## Verify Beneficiary's Name

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Verify Beneficiary's Name"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/platform/v1/beneficiaries/verification"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Verifies the beneficiary's name. You can call this endpoint before creating a payout via [`POST /payment/v2/payouts`](https://docs.bvnk.com/reference/payoutcreatev2#/) to verify the beneficiary's name and receive a verification ID that can be used in subsequent payout requests.

When using this endpoint, make sure you specify the same beneficiary's names as you will use in the payload of the [Initiate Payout](https://docs.bvnk.com/reference/payoutcreatev2#/) request.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./verify-beneficiary.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./verify-beneficiary.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Wallet Balances

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Wallet Balances"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/wallet/balances"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves the balances of your wallets on platform.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./wallet-balance-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-balance-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-balance-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Create Crypto Wallet

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Create Crypto Wallet"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/api/wallet"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a crypto wallet on the BVNK platform.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-create.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-create.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Transactions

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Transactions"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v1/transactions"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a paginated list of transactions for a specific wallet. Supports filtering by `walletId` and optional date range.

The date range can be applied to the `createdAt` or `updatedAt` timestamp, determined by the `filterMode`. If omitted, the `filterMode` defaults to `CREATED_AT`.

Refer to the [Fiat payments guide](https://docs.bvnk.com/docs/listing-transactions).

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./wallet-list-transactions.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-list-transactions.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-list-transactions.StatusCodes.json")}
>
  
</StatusCodes>

---

## List Wallets

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"List Wallets"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/wallet"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves a list of wallets on your account. Displays the first 10 wallets without max set to higher

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./wallet-list.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-list.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-list.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Wallet Profiles

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Wallet Profiles"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v2/wallets/profiles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns available wallet profiles based on optional filters for currency codes and payment methods. For more information on how to apply it in the Embedded Wallets flow, refer to the [Assign a wallet profile](https://docs.bvnk.com/docs/step-2-creating-a-customer-wallet-and-virtual-account#/assign-a-wallet-profile) guide.

The endpoint uses the [Lucene query syntax](https://lucene.apache.org/core/2_9_4/queryparsersyntax.html), for example, `GET https://api.bvnk.com/ledger/v2/wallets/profiles?q=customerId:550e8400-e29b-41d4-a716-446655440000 AND currency:USD` returns USD wallet profiles for that customer.

**Note:** Field names in the `q` search expression are case-sensitive. If you use a field that is not recognised, it is ignored.

Operator `OR` is only supported within the same field (group alternatives with parentheses), not across different fields.

- Supported: `?q=currency:(USD OR EUR)`
- Not supported: `?q=currency:USD OR customerId:550e8400-e29b-41d4-a716-446655440000`

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./wallet-profiles-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-profiles-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-profiles-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Wallet Profiles(Endpoints)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Wallet Profiles"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/ledger/v1/wallets/profiles"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Returns available wallet profiles based on optional filters for currency codes and payment methods.

For more information, how to apply it in the Embedded Wallets flow, refer to the [Assign a wallet profile](https://docs.bvnk.com/docs/step-2-creating-a-customer-wallet-and-virtual-account#/assign-a-wallet-profile) guide.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./wallet-profiles.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-profiles.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-profiles.StatusCodes.json")}
>
  
</StatusCodes>

---

## Get Wallet(3)

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Get Wallet"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/wallet/{walletId}"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Retrieves detailed information about a specific wallet.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./wallet-read.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-read.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-read.StatusCodes.json")}
>
  
</StatusCodes>

---

## Transactions Report V2

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Transactions Report V2"}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/api/transaction/v2/report"}
  context={"endpoint"}
>
  
</MethodEndpoint>

:::caution deprecated

This endpoint has been deprecated and may be replaced or removed in future versions of the API.

:::

Report all transactions from wallet in specified format. Report will be generated and sent to main account email in the specified format.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails
  {...require("./wallet-transaction-report-v-2.ParamsDetails.json")}
>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-transaction-report-v-2.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-transaction-report-v-2.StatusCodes.json")}
>
  
</StatusCodes>

---

## Generate Transactions Report

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Generate Transactions Report"}
>
</Heading>

<MethodEndpoint
  method={"post"}
  path={"/ledger/v1/reports"}
  context={"endpoint"}
>
  
</MethodEndpoint>

Creates a report of all transactions from a wallet in the specified format and sends it via the preferred delivery method: WEBHOOK or EMAIL.

**Note**: Reports are delivered instantly but the data has a one-hour lag for Production environment and eight-hour delay in sandbox. For example, a report requested at 9:00 AM will include transactions only up to 8:00 AM.

See the [Receive Transactions Report via Webhook](https://docs.bvnk.com/docs/receive-transaction-history-report-via-webhook) guide for more information.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
>
  <Translate id="theme.openapi.request.title">Request</Translate>
</Heading>

<ParamsDetails>
  
</ParamsDetails>

<RequestSchema
  {...require("./wallet-transaction-report.RequestSchema.json")}
>
  
</RequestSchema>

<StatusCodes
  {...require("./wallet-transaction-report.StatusCodes.json")}
>
  
</StatusCodes>

---

## For individual customers

This article provides a comprehensive summary of the required fields, document types, and applicable conditions for onboarding individual customers to our platform.

To onboard an individual to the BVNK platform, submit the following information. Requirements differ by onboarding model:

- **BVNK-Managed**: You submit structured data and raw identity documents (ID front/back, selfie, proof of address). BVNK performs identity verification (ID&V) via partner services.
- **Partner-managed**: Available to regulated partners with an appropriate AML programme. You perform ID&V on your side and pass verification metadata (document type, number, expiry, liveness timestamp, address verification type) plus a risk score and EDD attestation to BVNK. No ID documents, selfies, or proofs of address are uploaded.

<Tabs groupId="onboardingModel">
<TabItem value="bvnkManaged" label="BVNK-Managed">

## Required personal information

#### Personal information

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| First Name  `individual.firstName` | ✅ |  | John |
| Last Name  `individual.lastName` | ✅ |  | Syme |
| Date of Birth  `individual.dateOfBirth` | ✅ |  | 1990-05-15 |
| Nationality  `individual.nationality` | ✅ | ISO 3166-1 Alpha-2 | US |
| Country of Birth  `individual.birthCountryCode` | ✅ | ISO 3166-1 Alpha-2 | US |

#### Contact information

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| Email Address  `individual.emailAddress` | ✅ |  | user@example.com |

#### Address information

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| Street Address  `individual.address.addressLine1` | ✅ |  | 221B Baker Street |
| City  `individual.address.city` | ✅ |  | Syracuse |
| Postal Code  `individual.address.postalCode` | ✅ |  | 12345 |
| State  `individual.address.stateCode` | ☑️ Conditional | Mandatory for US residents | New York |
| Country  `individual.address.countryCode` | ✅ | ISO 3166-1 Alpha-2 | US |

#### Tax identification

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| Tax ID Number  `individual.taxIdentification.number` | ✅ | Social Security Number (SSN) or ITIN for the US residents. tax number for rest of the world | 123-45-6789 |

#### Customer Due Diligence Information (CDD)

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| Intended Use of Account  `individual.cdd.intendedUseOfAccount` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `INVESTMENTS` |
| Employment Status  `individual.cdd.employmentStatus` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `SALARIED` |
| Source of Funds  `individual.cdd.sourceOfFunds` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `SALARY` |
| PEP Status  `individual.cdd.pepStatus` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `NOT_PEP` |
|Estimated Yearly Income  `individual.cdd.estimatedYearlyIncome`|	☑️ Conditional	|Mandatory for US residents. See the [API reference](../../../api-explorer/endpoints/create-customer) for the list of supported values.	|`INCOME_0_TO_50K`|
|Employment Industry Sector  `individual.cdd.employmentIndustrySector`	|☑️ Conditional	|Mandatory for US residents. See the [Industry references](../../../references/industy-references) for the complete list.	|`AGRICULTURE_FORESTRY_FISHING_HUNTING`|

```json Example: personal information
{
  "type": "INDIVIDUAL",
  "individual": {
    "description": "My First Embedded Customer",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1990-05-12",
    "nationality": "GR",//Mandatory for EU
    "birthCountryCode": "GR",
    "emailAddress": "john.doe@example.com",
    "address": {
      "addressLine1": "123 Main St",
      "city": "Amsterdam",
      "postalCode": "1095AS",
      // "stateCode": "NY", - Mandatory for US
      "countryCode": "NL"
    },
    "taxIdentification": {
      "number": "123456789",
      "taxResidenceCountryCode": "NL"
    },
    "cdd": {
      "employmentStatus": "SALARIED",
      "sourceOfFunds": "SALARY",
      "pepStatus": "NOT_PEP",
      "intendedUseOfAccount": "TRANSFERS_OWN_WALLET",
      "expectedMonthlyVolume": {
        "amount": "5000",
        "currency": "EUR"
      }
    }
  },
  "signedAgreementSessionReference": "XYZ"
}
```

## Identity verification

BVNK routes each customer to the appropriate identity verification path automatically. You do not need to determine which path applies.

<Tabs groupId="identityVerificationPath">
<TabItem value="ssnHolders" label="SSN holders (US residents)">

BVNK first attempts non-documentary identity verification of holders of a Social Security Number (SSN). No document is required from the customer at this stage.

- If the check passes, identity verification is complete. No identity document or selfie is required.
- If the check fails, the customer is placed in the `INFO_REQUIRED` status. An identity document and selfie are required to proceed.
- If Enhanced Due Diligence (EDD) is triggered automatically, an identity document and selfie are required regardless of the non-documentary outcome.

</TabItem>
<TabItem value="nonSsnHolders" label="Non-SSN holders">

Documentary verification is performed. An identity document and selfie are always required.

</TabItem>
</Tabs>

## Required documents

Each individual onboarding requires three documents:

- Identity document
- Selfie
- Proof of Address document, where applicable

### Identity documents

Submit one of the following document types together with a selfie.

| Document           | subType required       | Notes                        |
|--------------------|-----------------------|------------------------------|
| Passport  `PASSPORT` | `FRONT_SIDE` only | Single-sided |
| National ID card  `ID_CARD` | `FRONT_SIDE` + `BACK_SIDE` | Both sides required |
| Driver's licence  `DRIVERS` | `FRONT_SIDE` + `BACK_SIDE` | Both sides required |
| Residence permit  `RESIDENCE_PERMIT` | `FRONT_SIDE` + `BACK_SIDE` | Both sides required |
| Selfie  `SELFIE` |  | Must be added to every submission |

:::warning
Include a selfie image as `SELFIE` together with the identity document.
:::

:::warning Important
For double-sided documents, always upload `"subType": "FRONT_SIDE"` first, then `"subType": "BACK_SIDE"`. Verification can only be completed once both sides are submitted.
:::

To ensure a smooth onboarding process, all submitted documents must meet the following standards:

<Columns layout="auto">
  <Column>
    **Document requirements**:

    * The document must be valid and not expired.
    * It must be free from visible damage such as scratches, stains, or tears.
    * The applicant's full name, date of birth, MRZ (Machine Readable Zone), and other key details must be clearly visible.
    * The document must belong to the individual being onboarded.
  </Column>

  <Column>
    **An ID document must include**:

    * Full name, date of birth, a clear photograph, and (if applicable) a signature.
    * A unique document number and validity details: issue or expiry date.

    If the document contains information on both sides, images of both the front and back must be provided.

  </Column>

  <Column>
    **Photo requirements**:

    * The document image must be a high-quality original photo or scan. Screenshots or images from social media are not allowed.
    * Accepted formats: JPG, JPEG, PNG, or PDF.
    * The image must be in color, with a minimum resolution of 300 DPI or file size of at least 100 KB.
    * All document details must be readable.
    * The entire document, including all corners, must be visible—no cropping, obstructions, or foreign elements.
    * The image must not be digitally altered or edited.
    * Digital documents are not accepted unless explicitly allowed.
  </Column>
</Columns>

### Address verification

BVNK automatically verifies addresses during onboarding. The verification method depends on the customer's country of residence:

- **Non-documentary automatic check**: BVNK attempts to verify the customer's address using data sources for supported countries. No document is required from the customer. This check is triggered automatically when you submit the KYC pack: the personal and CDD information described earlier.

  The following EU countries support non-documentary address verification:

  - Austria
  - Belgium
  - Denmark
  - Finland
  - France
  - Germany
  - Italy
  - Netherlands
  - Norway
  - Poland
  - Portugal
  - Spain
  - Sweden
  - Switzerland

  Individuals from all other EU/EEA countries require a Proof of Address document.

- **Proof of Address document (PoA)**: If non-documentary verification is unavailable or fails, BVNK requires a Proof of Address document and provides a WebSDK link for document collection.

BVNK selects the verification method automatically; you do not need to choose the process.

:::warning
If your customers reside outside the EU/EEA, contact your BVNK integration manager to confirm the address verification behaviour for your programme.
:::

#### Collect a Proof of Address document

If a PoA document is required and not provided, BVNK returns a WebSDK link in the API response. You have two options:

- **Option A**: Redirect the customer to the BVNK WebSDK URL provided in the API response. The customer uploads their PoA document using BVNK's hosted interface. No further API calls are required.
- **Option B**: Collect the document in your interface and submit it to BVNK using the document upload API endpoint.

#### Proof of Address documents

Proof of Address (or sometimes Proof of Residence) refer to the same requirement. When submitting a PoA document via the API ([Option B](#collect-a-proof-of-address-document)), use one of the following `documentType` values:

| `documentType` value | Document category         | Accepted examples  |
| :------------------- | :------------------------ | :------------------- |
| `UTILITY_BILL`       | Utility provider documents| Electricity, water, gas, heating, or sewerage bill; home phone or internet bill (not mobile or wireless); TV bill (not satellite) |
| `BANK_STATEMENT`     | Bank documents           | Bank statement; bank letter or correspondence; mortgage payment document; passbook                     |

:::warning
When submitting a PoA document via the API, do not use `"documentType": "PROOF_OF_RESIDENCE"`. This value won't be accepted by the API.
:::

Your customers may provide additional document types, including government-issued statements, employer letters, and lease agreements via the BVNK WebSDK ([Option A](#collect-a-proof-of-address-document)). Note that these types are not available as direct API enum values.

All PoA documents must:
- Be issued within the last 3 months.
- Clearly show the customer's full name and residential address.
- Not use a PO box address.
- Be submitted in JPG, PNG, or PDF format (max 50 MB).

</TabItem>
<TabItem value="partnerManaged" label="Partner-managed">

Under the Partner-managed model, you perform identity verification on your side and submit verification metadata to BVNK together with the customer's personal and CDD data. No ID documents, selfies, or proofs of address are uploaded.

## Required personal information

#### Personal information

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| First Name  `individual.firstName` | ✅ |  | Walton |
| Last Name  `individual.lastName` | ✅ |  | Simmons |
| Date of Birth  `individual.dateOfBirth` | ✅ |  | 1985-08-15 |
| Nationality  `individual.nationality` | ☑️ Conditional | Mandatory for EU. ISO 3166-1 Alpha-2. | AT |
| Country of Birth  `individual.birthCountryCode` | ☑️ Conditional | Mandatory for EU. ISO 3166-1 Alpha-2. | IT |

#### Contact information

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| Email Address  `individual.emailAddress` | ✅ |  | wsimmons@example.com |
| Phone Number  `individual.phoneNumber` | ✅ |  | +1234567890 |

#### Address information

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| Street Address  `individual.address.addressLine1` | ✅ |  | 123 Main Street |
| City  `individual.address.city` | ✅ |  | New York |
| Postal Code  `individual.address.postalCode` | ✅ |  | 10001 |
| State  `individual.address.stateCode` | ☑️ Conditional | Mandatory for US residents | NY |
| Country  `individual.address.countryCode` | ✅ | ISO 3166-1 Alpha-2 | US |

#### Tax identification

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| Tax ID Number  `individual.taxIdentification.number` | ✅ | Social Security Number (SSN) or ITIN for the US residents. tax number for rest of the world | 123-45-6789 |

#### Customer Due Diligence Information (CDD)

| Field / Type | Required | Notes / Conditions | Example |
| :--- | :---: | :--- | :--- |
| Intended Use of Account  `individual.cdd.intendedUseOfAccount` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `GOODS_SERVICES` |
| Employment Status  `individual.cdd.employmentStatus` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `SALARIED` |
| Source of Funds  `individual.cdd.sourceOfFunds` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `SALARY` |
| PEP Status  `individual.cdd.pepStatus` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `NOT_PEP` |
| Expected Monthly Volume  `individual.cdd.expectedMonthlyVolume` | ☑️ Conditional | Object `{ amount, currency }`. Mandatory for EU residents. | `{ "amount": "10000.01", "currency": "USD" }` |
| Estimated Yearly Income  `individual.cdd.estimatedYearlyIncome` | ☑️ Conditional | Mandatory for US residents. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. | `INCOME_0_TO_50K` |
| Employment Industry Sector  `individual.cdd.employmentIndustrySector` | ☑️ Conditional | Mandatory for US residents. See the [Industry references](../../../references/industy-references/) for the complete list. | `AGRICULTURE_FORESTRY_FISHING_HUNTING` |

## Reliance metadata

The `reliance` object transmits pre-verified ID&V outcomes and the risk attestation to BVNK in place of raw documents.

#### Identity document metadata

| Field | Required | Notes / Conditions |
| :--- | :---: | :--- |
| Type  `reliance.identityDocumentMetadata.type` | ✅ | Not required for US residents when SSN is provided. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Number  `reliance.identityDocumentMetadata.number` | ✅ | Document number. |
| Expiry Date  `reliance.identityDocumentMetadata.expiryDate` | ☑️ Conditional | Format `YYYY-MM-DD`. Mandatory for all document types except `ID_CARD` and `OTHER`. |
| Issue Date  `reliance.identityDocumentMetadata.issueDate` | ❌ | Format `YYYY-MM-DD`. |
| Issuing Country Code  `reliance.identityDocumentMetadata.issuingCountryCode` | ✅ | ISO 3166-1 Alpha-2. |
| KYC Timestamp  `reliance.identityDocumentMetadata.kycTimestamp` | ✅ | ISO 8601 timestamp of the KYC identity verification. |

#### Biometric / liveness

| Field | Required | Notes / Conditions |
| :--- | :---: | :--- |
| Liveness Timestamp  `reliance.biometricLiveness.livenessTimestamp` | ☑️ Conditional | ISO 8601. Mandatory for EU residents. |

#### Address verification

| Field | Required | Notes / Conditions |
| :--- | :---: | :--- |
| Type  `reliance.addressVerification.type` | ✅ | See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |

#### Attestation

| Field | Required | Notes / Conditions |
| :--- | :---: | :--- |
| Risk Score  `reliance.attestation.riskScore` | ✅ | Your internal risk rating for this customer. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| EDD Completed  `reliance.attestation.eddCompleted` | ✅ | Boolean (`true`, `false`). Confirms EDD has been performed where required. BVNK doesn't verify attestations in this flow. |

```json Example: Partner-managed individual onboarding
{
  "type": "individual",
  "individual": {
    "description": "Investments",
    "firstName": "Walton",
    "lastName": "Simmons",
    "dateOfBirth": "1985-08-15",
    "nationality": "AT",
    "birthCountryCode": "IT",
    "emailAddress": "wsimmons@example.com",
    "phoneNumber": "+1234567890",
    "address": {
      "addressLine1": "123 Main Street",
      "postalCode": "10001",
      "city": "New York",
      "countryCode": "US"
    },
    "taxIdentification": {
      "number": "123-45-6789",
      "taxResidenceCountryCode": "US"
    },
    "cdd": {
      "employmentStatus": "SALARIED",
      "sourceOfFunds": "SALARY",
      "pepStatus": "NOT_PEP",
      "intendedUseOfAccount": "GOODS_SERVICES",
      "expectedMonthlyVolume": {
        "amount": "10000.01",
        "currency": "USD"
      },
      "estimatedYearlyIncome": "INCOME_0_TO_50K",
      "employmentIndustrySector": "AGRICULTURE_FORESTRY_FISHING_HUNTING"
    },
    "reliance": {
      "identityDocumentMetadata": {
        "type": "PASSPORT",
        "number": "AB1234567",
        "issueDate": "2015-10-01",
        "expiryDate": "2030-12-31",
        "issuingCountryCode": "GB",
        "kycTimestamp": "2025-11-20T15:30:45.123Z"
      },
      "biometricLiveness": {
        "livenessTimestamp": "2025-11-20T15:30:45.123Z"
      },
      "addressVerification": {
        "type": "NON_DOC"
      },
      "attestation": {
        "riskScore": "LOW",
        "eddCompleted": true
      }
    }
  },
  "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1"
}
```

:::warning
Any attempt to upload customer documents via [`POST /platform/v1/customers/{customerReference}/documents`](../../../api-explorer/endpoints/upload-customer-documents) is rejected under the Partner-managed model — identity verification has already been performed on your side.
:::

</TabItem>
</Tabs>

## Appendix

### Non-MTL US States

Additional mandatory requirements apply to Social Security Number (SSN) holders whose state of domicile is not covered by BVNK's Money Transmitter License (MTL).

| Field | Allowed values |
| --- | --- |
| `estimated_yearly_income` | `INCOME_0_TO_50K`, `INCOME_50K_TO_100K`, `INCOME_100K_TO_250K`, `INCOME_250K_TO_500K`, `INCOME_500K_TO_750K`, `INCOME_750K_TO_1M`, `INCOME_ABOVE_1M` |
| `employment_industry_sector` | `INVESTMENT`, `HEDGE_FUND`, `MONEY_SERVICE_BUSINESS`, `STO_ISSUER`, `PRECIOUS_METALS`, `NON_PROFIT`, `REGISTERED_INVESTMENT_ADVISOR`, `AGRICULTURE_FORESTRY_FISHING_HUNTING`, `MINING`, `UTILITIES`, `CONSTRUCTION`, `MANUFACTURING`, `WHOLESALE_TRADE`, `RETAIL_TRADE`, `TRANSPORTATION_WAREHOUSING`, `INFORMATION`, `FINANCE_INSURANCE`, `REAL_ESTATE_RENTAL_LEASING`, `PROFESSIONAL_SCIENTIFIC_TECHNICAL_SERVICES`, `MANAGEMENT_OF_COMPANIES_ENTERPRISES`, `ADMINISTRATIVE_SUPPORT_WASTE_MANAGEMENT_REMEDIATION_SERVICES`, `EDUCATIONAL_SERVICES`, `HEALTH_CARE_SOCIAL_ASSISTANCE`, `ARTS_ENTERTAINMENT_RECREATION`, `ACCOMMODATION_FOOD_SERVICES`, `OTHER_SERVICES`, `PUBLIC_ADMINISTRATION`, `NOT_CLASSIFIED`, `ADULT_ENTERTAINMENT`, `AUCTIONS`, `AUTOMOBILES`, `BLOCKCHAIN`, `CRYPTO`, `DRUGS`, `EXPORT_IMPORT`, `E_COMMERCE`, `FINANCIAL_INSTITUTION`, `GAMBLING`, `INSURANCE`, `MARKET_MAKER`, `SHELL_BANK`, `TRAVEL_TRANSPORT`, `WEAPONS` |

BVNK's onboarding orchestration surfaces these fields at the point of the customer creation where applicable. You do not need to determine eligibility in your integration.

---

## For business customers

This article provides a comprehensive summary of the required fields, document types, identity verification requirements, and applicable conditions for onboarding business customers (companies) to our platform.

To onboard a company to the BVNK platform, submit the following information.

## Overview

Requirements differ along two dimensions:

- **Jurisdiction**: the BVNK entity that contracts with the customer:
  - **US** — System Pay Services (US), Inc., a Delaware-incorporated company (NMLS ID 2531294), registered as a Money Services Business with FinCEN and licensed as a money transmitter in various US states.
  - **EU** — System Pay Services (Malta) Ltd (C66961), authorised by the Malta Financial Services Authority (MFSA) as an Electronic Money Institution and as a Crypto-Asset Service Provider under MiCA (Regulation (EU) 2023/1114).
- **Onboarding model**:
  - **BVNK-Managed**: you provide documents and structured data, BVNK performs ID&V.
  - **Partner-managed**: you perform ID&V and pass verification metadata + risk attestations to BVNK.

  The applicable onboarding model depends on the type of business and the licensing setup of the Embedded Partner. Contact the BVNK Solutions team to confirm which model applies to your integration.

For the technical integration, payload structures, and endpoint reference, see the companion API Integration Guide.

## Business entity information

<Tabs groupId="onboardingModel">
  <TabItem value="bvnkManaged" label="BVNK-Managed">

#### Company profile

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Legal Entity Name  `company.name` | ✅ | ✅ | Verified against business registry records. Must match formation documents exactly. |
| Registration Number  `company.registrationNumber` | ☑️ | ✅ | Cross-referenced with the relevant national business registry. Optional for US if EIN is provided. |
| Entity Type  `company.entityType` | ✅ | ✅ | Determines downstream document and ownership disclosure requirements. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported entity types. |
| Incorporation Date  `company.incorporationDate` | ✅ | ✅ | Entities incorporated &lt;2 years ago may trigger additional scrutiny (business plan, SoW, supporting invoices). |
| Industry  `company.industryReference` | ✅ | ✅ | UUID from Industry API (NAICS supported). Determines whether vertical-specific requirements apply. Refer to available [Industry reference codes](../../../references/industy-references). |
| Tax ID  `company.taxNumber` | ✅ | ☑️ | Mandatory for US entities (EIN). Verified against IRS records. |
| Tax Residence Country  `company.taxResidenceCountryCode` | ✅ | ❌ | Mandatory for US entities. Establishes US tax nexus and triggers US-specific associate requirements. |

#### Registered address

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Street Address  `address.addressLine1` | ✅ | ✅ | Verified against business registry. |
| City  `address.city` | ✅ | ✅ | Part of full address verification. |
| Post / Zip Code  `address.postalCode` | ✅ | ✅ | Part of full address verification. |
| State / Province  `address.stateCode` | ✅ | ❌ | Required for US addresses. |
| Country  `address.countryCode` | ✅ | ✅ |  Decline if in a controlled or prohibited jurisdiction. To get the list of countries, use the [Fetch Country Codes](../../../api-explorer/endpoints/list-countries) endpoint. |
| Operational Address  `company.operationalAddress` | ☑️ | ☑️ | Required if different from registered address. |

#### Business profile

The `businessProfile` object captures business context, CDD data, and nature-of-business information at customer creation.

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Description  `businessProfile.description` | ✅ | ✅ | Brief narrative of business activities. Used by Compliance to assess consistency with declared industry. |
| Website  `businessProfile.website` | ✅ | ✅ | Reviewed for risk indicators, consistency with declared activity, and exposure to prohibited content. |
| Regulated Status  `businessProfile.isRegulated` | ✅ | ✅ | Triggers requirement for AML Policy and Proof of Regulatory License if `true`. |
| Source of Funds  `businessProfile.sourceOfFunds` | ✅ | ✅ | Structured enum. Documentary evidence may be requested during compliance review. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Intended Use of Account  `businessProfile.intendedUseOfAccount` | ✅ | ✅ | Screened for high-risk purposes (e.g. third-party money transmission). Must align with declared business model. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Monthly Expected Volume  `businessProfile.monthlyExpectedVolumes` | ✅ | ✅ | Volume range provided as a string enum (e.g. `FROM_0_TO_10K`). See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for supported values. *A UUID-based reference via the Volumes API (`company.monthlyExpectedVolumesReference`) will replace this field in a future release.* |

:::info Nature of Business Questionnaire
Previously required for business customers in v1. **Deprecated in v2.** All business context is now captured via the structured `businessProfile` fields above.
:::

## Associates

Associates are individuals linked to the business.

Business customers must include associated natural persons. The following minimum roles must be declared:

- One Authorised Signatory / Representative
- One Director (EU) or Control Person (US)
- At least one and all UBOs above the applicable threshold (25% for onboarding and CDD, 10% for EDD)

### Associate roles

The following values are accepted in the associate `roles` field. Each associate must be assigned at least one role.

| Role | Requirement | Validation / why we collect it |
| --- | :---: | --- |
| Authorised Signatory  `REPRESENTATIVE` | ✅ At least one | Person legally authorised to bind the company and execute agreements. If not a director, evidence of signing authority is required (Board Resolution, PoA, or Articles provision). |
| Director / Control Person  `DIRECTOR` | ✅ At least one | EU: verified against the company registry. US: person with significant management control. Sanctions, PEP, and adverse media screening applied. |
| UBO / Beneficial Owner  `BUSINESS_OWNER` | ✅ At least one above threshold | CDD threshold: ≥25%. EDD threshold: ≥10%. If no individual above threshold, the most senior executive must be designated as Person with Significant Control. |
| Account Representative  `ACCOUNT_REPRESENTATIVE` | ❌ | Operational point of contact for the partnership. |

The same person can hold multiple roles, for example, Authorised Signatory + UBO + Director.

### Personal information (all associates)

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| First Name  `firstName` | ✅ | ✅ | Must match government-issued ID exactly. Used for sanctions and adverse media screening. |
| Last Name  `lastName` | ✅ | ✅ | Must match government-issued ID exactly. |
| Date of Birth  `dateOfBirth` | ✅ | ✅ | Used for identity matching and screening disambiguation. |
| Nationality  `nationality` | ☑️ | ✅ | US: required for Control Persons. EU: all nationalities including dual must be declared. Screened against [prohibited nationality lists](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime). |
| Country of Birth  `birthCountryCode` | ☑️ | ✅ | US: required for Control Persons. Used for sanctions screening. |
| Country of Residence  `address.countryCode` | ✅ | ✅ |  To get the list of countries, use the [Fetch Country Codes](../../../api-explorer/endpoints/list-countries) endpoint. |
| Email Address  `emailAddress` | ✅ | ✅ | Primary communication channel for verification flows. |
| Residential Address  `address` | ✅ | ✅ | Full address required. Must be a physical residential address. |
| State / Province  `address.stateCode` | ☑️ | ❌ | Required for US addresses. |

### Tax identification (all associates)

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Tax ID Number  `taxIdentification.number` | ✅ | ✅ | SSN mandatory for US persons, verified against database. EU: national tax ID. |
| Tax ID Country  `taxIdentification.country` | ✅ | ✅ |  Establishes tax residency. |

### Identity verification (associates)

Under the BVNK-Managed model, raw documents are uploaded for BVNK to check via verification partners.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| ID Document Upload | ✅ | ✅ | Front/back image of passport, national ID card, driver's license, or residence permit. Verified items: authenticity, data extraction, expiry, and name/DOB matching. |
| Selfie / Liveness Upload | ✅ | ✅ | Biometric selfie matched against ID document photo. Liveness detection prevents spoofing. |
| Address Document Upload | ✅ | ✅ | Utility bill, bank statement, or government correspondence dated within 3 months. Address must match declared residential address. |

#### Individual CDD

When associates are onboarded as standalone individual customers (not in a business context), additional CDD fields apply.

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Employment Status  `cdd.employmentStatus` | ✅ | ✅ | Used to assess plausibility of declared source of funds. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Source of Funds  `cdd.sourceOfFunds` | ✅ | ✅ | High-risk sources trigger SoF documentary request. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Intended Use of Account  `cdd.intendedUseOfAccount` | ✅ | ✅ | Screened for high-risk use cases. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Expected Monthly Volume  `cdd.expectedMonthlyVolume` | ❌ | ☑️ Questionnaire | EU BVNK-Managed: covered in questionnaire or defaults. |
| PEP Status  `cdd.pepStatus` | ☑️ Questionnaire | ☑️ Questionnaire | Collected via questionnaire. Positive PEP triggers EDD. |

### UBO-specific requirements

UBOs above the ownership threshold must complete identity verification.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Basic data + residential address | ❌ (address) | ✅ | EU always requires full residential address. Sanctions, PEP, and adverse media screening applied. |
| ID Verification | ✅ | ✅ | US: SSN mandatory for US residents, verified against database. EU: full ID verification (document or metadata under Partner-managed). |
| Ownership threshold | 25% (std) / 10% (high) | 25% (std) / 10% (high) | Standard CDD: ≥25% ownership or voting rights. EDD (high-risk): ≥10%. Full ownership chain required if held through intermediaries. |

## Business documents (KYB)

Documents are uploaded via `POST /onboarding/v1/applications/{id}/documents` (company) or via Portal.

#### Entity documents

| Document | US | EU | Why we collect it |
| --- | :---: | :---: | --- |
| Certificate of Incorporation | ✅ | ✅ | Confirms legal formation. Must show filing stamp or registration date. Legal name must match declared name. |
| Memorandum of Association | ✅ | ✅ | Confirms governance structure, powers, and objects of the entity. |
| Articles of Association | ✅ | ✅ | Confirms internal governance and signatory authority. *Submitted as a separate document type; may be combined with Memorandum where jurisdictionally equivalent.* |
| Source of Funds (Entity) | ✅ | ✅ | Bank statements (3 months activity) or equivalent. |
| Proof of Address (Entity) | ✅ | ✅ | Utility bill, lease, tax statement, or official government correspondence. Dated within 3 months. Required if operational address differs from registered. |
| Proof of Directorship | ✅ | ✅ | Official registry extract or certified register of directors. Not older than 6 months. |
| Corporate / Group Structure | ✅ | ✅ | Ownership chart showing all corporate shareholders through to UBOs. Certified by legal counsel or CA. Not older than 6 months. |
| Source of Wealth (Entity) | ☑️ | ☑️ | Triggered by high-risk rating or EDD. Audited accounts, financial statements, loan agreements, or bank statements showing capitalisation history. |
| Proof of Regulatory License | ☑️ | ☑️ | Required if entity operates in a regulated industry. Must be current and match declared jurisdiction. |
| Proof of Business Activity | ☑️ | ☑️ | Triggered when web presence is limited, entity is newly incorporated (&lt;2 years), or nature of business is unclear. |
| Shareholder Ownership Doc | ☑️ | ☑️ | Required when ownership is complex (trusts, foundations, nominees, >3 layers, offshore entities). |

  </TabItem>
  <TabItem value="partnerManaged" label="Partner-managed">

#### Company profile

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Legal Entity Name  `company.name` | ✅ | ✅ | Verified against business registry records. Must match formation documents exactly. |
| Registration Number  `company.registrationNumber` | ☑️ | ✅ | Cross-referenced with the relevant national business registry. Optional for US if EIN is provided. |
| Entity Type  `company.entityType` | ✅ | ✅ | Determines downstream document and ownership disclosure requirements. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported entity types. |
| Incorporation Date  `company.incorporationDate` | ✅ | ✅ | Entities incorporated &lt;2 years ago may trigger additional scrutiny (business plan, SoW, supporting invoices). |
| Industry  `company.industryReference` | ✅ | ✅ | UUID from Industry API (NAICS supported). Determines whether vertical-specific requirements apply. Refer to available [Industry reference codes](../../../references/industy-references). |
| Tax ID  `company.taxNumber` | ✅ | ☑️ | Mandatory for US entities (EIN). Verified against IRS records. |
| Tax Residence Country  `company.taxResidenceCountryCode` | ✅ | ❌ | Mandatory for US entities. Establishes US tax nexus and triggers US-specific associate requirements. |

#### Registered address

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Street Address  `address.addressLine1` | ✅ | ✅ | Verified against business registry. |
| City  `address.city` | ✅ | ✅ | Part of full address verification. |
| Post / Zip Code  `address.postalCode` | ✅ | ✅ | Part of full address verification. |
| State / Province  `address.stateCode` | ✅ | ❌ | Required for US addresses. |
| Country  `address.countryCode` | ✅ | ✅ |  Decline if in a controlled or prohibited jurisdiction. To get the list of countries, use the [Fetch Country Codes](../../../api-explorer/endpoints/list-countries) endpoint. |
| Operational Address  `company.operationalAddress` | ☑️ | ☑️ | Required if different from registered address. |

#### Entity-level CDD

For Partner-managed onboarding, additional business context is provided through structured CDD fields rather than the `businessProfile` object alone.

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Monthly Expected Volume  `company.monthlyExpectedVolumesReference` | ✅ | ✅ | UUID from Volumes API. Establishes baseline for transaction monitoring. |
| Intended Use of Account  `cdd.intendedUseOfAccount` | ✅ | ✅ | Partner attests intended use. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| PEP Status, Entity  `cdd.pepStatus` | ✅ | ✅ | Partner attests whether any person in the ownership or control structure is a PEP. |

#### Partner risk attestation

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Risk Score  `company.reliance.attestation.riskScore` | ✅ | ✅ | Partner's customer-level risk rating. Input to BVNK's independent risk assessment. Possible values: `LOW`, `MEDIUM`, or `HIGH`. |
| EDD Completed  `company.reliance.attestation.eddCompleted` | ✅ | ✅ | If `false` and BVNK rates the customer `HIGH`, BVNK-side EDD is triggered. |

#### Associates

Associates are individuals linked to the business.

Business customers must include associated natural persons. The following minimum roles must be declared:

- One Authorised Signatory / Representative
- One Director (EU) or Control Person (US)
- At least one and all UBOs above the applicable threshold (25% for onboarding and CDD, 10% for EDD)

##### Associate roles

The following values are accepted in the associate `roles` field. Each associate must be assigned at least one role.

| Role | Requirement | Validation / why we collect it |
| --- | :---: | --- |
| Authorised Signatory  `REPRESENTATIVE` | ✅ At least one | Person legally authorised to bind the company and execute agreements. If not a director, evidence of signing authority is required (Board Resolution, PoA, or Articles provision). |
| Director / Control Person  `DIRECTOR` | ✅ At least one | EU: verified against the company registry. US: person with significant management control. Sanctions, PEP, and adverse media screening applied. |
| UBO / Beneficial Owner  `BUSINESS_OWNER` | ✅ At least one above threshold | CDD threshold: ≥25%. EDD threshold: ≥10%. If no individual above threshold, the most senior executive must be designated as Person with Significant Control. |
| Account Representative  `ACCOUNT_REPRESENTATIVE` | Optional | Operational point of contact for the partnership. |

The same person can hold multiple roles, for example, Authorised Signatory + UBO + Director.

##### Personal information (all associates)

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| First Name  `firstName` | ✅ | ✅ | Must match government-issued ID exactly. Used for sanctions and adverse media screening. |
| Last Name  `lastName` | ✅ | ✅ | Must match government-issued ID exactly. |
| Date of Birth  `dateOfBirth` | ✅ | ✅ | Format: `YYYY-MM-DD`. Used for identity matching and screening disambiguation. |
| Nationality  `nationality` | ☑️ | ✅ | US: required for Control Persons. EU: all nationalities including dual must be declared. Screened against [prohibited nationality lists](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime). |
| Country of Birth  `birthCountryCode` | ☑️ | ✅ | US: required for Control Persons. Used for sanctions screening. |
| Country of Residence  `address.countryCode` | ✅ | ✅ |  To get the list of countries, use the [Fetch Country Codes](../../../api-explorer/endpoints/list-countries) endpoint. |
| Email Address  `emailAddress` | ✅ | ✅ | Primary communication channel for verification flows. |
| Residential Address  `address` | ✅ | ✅ | Full address required. Must be a physical residential address. |
| State / Province  `address.stateCode` | ☑️ | ❌ | Required for US addresses. |

##### Tax identification (all associates)

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Tax ID Number  `taxIdentification.number` | ✅ | ✅ | SSN mandatory for US persons, verified against database. EU: national tax ID. |
| Tax ID Country  `taxIdentification.country` | ✅ | ✅ |  Establishes tax residency. |

:::note US Partner-managed (SSN)
When SSN is provided under US Partner-managed, ID metadata fields become optional.
:::

##### Identity verification (associates)

Under the Partner-managed model, verification metadata is passed confirming the partner has performed ID&V.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| ID Metadata  `reliance.identityDocumentMetadata` | ☑️ | ✅ | Type, number, expiry date, issuing country, IDV timestamp. Confirms the partner has performed document verification. **US: optional if SSN has been provided.** |
| Biometric / Liveness Metadata  `reliance.biometricLiveness` | ❌ | ✅ | Liveness timestamp confirms partner performed biometric check. |
| Address Verification Metadata  `reliance.addressVerification` | ✅ | ✅ | Type: `DOC` (documentary) or `NON_DOC` (database/electronic). US: confirm residential address is valid and not a PO Box. EU: full address verification required. |

##### Individual CDD

When associates are onboarded as standalone individual customers (not in a business context), additional CDD fields apply.

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Employment Status  `cdd.employmentStatus` | ✅ | ✅ | Used to assess plausibility of declared source of funds. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Source of Funds  `cdd.sourceOfFunds` | ✅ | ✅ | High-risk sources trigger SoF documentary request. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Intended Use of Account  `cdd.intendedUseOfAccount` | ✅ | ✅ | Screened for high-risk use cases. See the [API reference](../../../api-explorer/endpoints/create-customer-v-2) for the list of supported values. |
| Expected Monthly Volume  `cdd.expectedMonthlyVolume` | ❌ | ✅ | EU Partner-managed: object `{amount, currency}` mandatory. |
| PEP Status  `cdd.pepStatus` | ✅ | ✅ | Partner must attest status (e.g. `NOT_PEP`). Positive PEP triggers EDD. |

##### Director-specific requirements

Directors are collected and verified against the company registry. Verification depth depends on risk level.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Basic data (name, DOB, nationality, residence) | ✅ | ✅ | Cross-referenced against the company's registry of directors. Sanctions, PEP, and adverse media screening applied to all directors. |
| Residential Address | ❌ | ✅ | EU: required for high-risk customers under EDD. |
| ID Verification Metadata | ❌ | ✅ | EU: required for high-risk customers under EDD. |

##### UBO-specific requirements

UBOs above the ownership threshold must complete identity verification.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Basic data + residential address | ❌ (address) | ✅ | EU always requires full residential address. Sanctions, PEP, and adverse media screening applied. |
| ID Verification | ✅ (SSN mandatory) | ✅ | US: SSN mandatory for US residents, verified against database. EU: full ID verification (document or metadata under Partner-managed). |
| Ownership threshold | 25% (std) / 10% (high) | 25% (std) / 10% (high) | Standard CDD: ≥25% ownership or voting rights. EDD (high-risk): ≥10%. Full ownership chain required if held through intermediaries. |

#### Business documents (KYB)

Documents are uploaded via `POST /onboarding/v1/applications/{id}/documents` (company) or via Portal.

##### Entity documents

| Document | US | EU | Why we collect it |
| --- | :---: | :---: | --- |
| Certificate of Incorporation | ✅ | ❌ | Confirms legal formation. Must show filing stamp or registration date. Legal name must match declared name. |
| Memorandum of Association | ❌ | ❌ | Confirms governance structure, powers, and objects of the entity. |
| Articles of Association | ❌ | ❌ | Confirms internal governance and signatory authority. *Submitted as a separate document type; may be combined with Memorandum where jurisdictionally equivalent.* |
| Source of Funds (Entity) | ☑️ | ☑️ | Attestation sufficient at CDD level. Documentary evidence required under EDD — see [Company EDD](#company-edd). |
| Proof of Address (Entity) | ❌ | ✅ | Utility bill, lease, tax statement, or official government correspondence. Dated within 3 months. Required if operational address differs from registered. |
| Proof of Directorship | ❌ | ❌ | Official registry extract or certified register of directors. Not older than 6 months. |
| Corporate / Group Structure | ❌ | ❌ | Ownership chart showing all corporate shareholders through to UBOs. Certified by legal counsel or CA. Not older than 6 months. |
| Proof of Regulatory License | ❌ | ❌ | Required if entity operates in a regulated industry. Must be current and match declared jurisdiction. |
| Proof of Business Activity | ❌ | ❌ | Triggered when web presence is limited, entity is newly incorporated (&lt;2 years), or nature of business is unclear. |
| Shareholder Ownership Doc | ❌ | ❌ | Required when ownership is complex (trusts, foundations, nominees, >3 layers, offshore entities). |

:::note Partner-managed philosophy
Under Partner-managed, BVNK relies on the partner's KYB programme. The minimum doc set reflects what BVNK still needs for its own records and regulatory obligations (e.g. Certificate of Incorporation for US Partner-managed under MTL requirements; Proof of Address for EU Partner-managed under MiCA).
:::

  </TabItem>
</Tabs>

## Enhanced due diligence

Enhanced due diligence (EDD) requirements apply when the BVNK customer risk rating is **HIGH** and EDD has not been completed by the Embedded Partner (`reliance.attestation.eddCompleted: false`).

### Company EDD

| Requirement | US | EU | What we accept |
| --- | :---: | :---: | --- |
| Company Source of Wealth | ✅ | ✅ | Loan agreements, financial statements, tax returns, bank statements, or commercial database verification (e.g. Creditsafe). |
| Source of Funds (Entity) | ✅ | ✅ | Document required when EDD applies (replaces the CDD attestation sufficient for standard risk). |
| Director & UBO Address Verification | ❌ | ✅ | Commercial database check or documentary evidence (utility bill, bank statement). |
| UBO Source of Wealth | ❌ | ✅ | Tax returns, investment portfolio statements, share certificates, or open-source research. |
| Verification of Professional Activity | ❌ | ✅ | Payslips, employment contracts, invoices (if self-employed), or open-source review. |
| Proof of Entity Address | ✅ | ❌ | Bank statement or other documentary evidence showing the entity's physical address. |

## Review process

### Application review

BVNK reviews applications once all required data, documents, and associate verification have been submitted. Onboarding completes automatically when all conditions are satisfied — there is no separate “submit” call. See the API Integration Guide (Section 10) for completion mechanics.

### Decisioning

Applications result in one of three outcomes: **VERIFIED**, **REJECTED**, or remain in **SUBMITTED** state pending additional information. BVNK sends webhook notifications at each status transition.

### Requests for information (RFI)

When BVNK requires additional information, a consolidated RFI is issued. To minimise RFIs:

- Submit all formation, ownership, and address documents upfront.
- Clearly substantiate the nature of business, especially where web presence is limited.
- For regulated entities, include AML policy and license documentation with the initial submission.
- Pre-screen business physical addresses for virtual or registered agent addresses.

## Best practices

- **Pre-screen addresses.** Confirm the physical address is not a virtual office or registered agent. Wyoming and Delaware addresses in particular require scrutiny.
- **Collect ownership attestation early.** Have the control person certify UBOs above the threshold to avoid follow-up document requests.
- **Document the nature of business.** Ensure the website or supporting documents substantiate what the business does. For new businesses, provide a business plan or pitch deck.
- **Source of funds upfront.** Proactively submit bank statements showing 3 months of transactional activity for BVNK-Managed; provide attestation for Partner-managed CDD.
- **Web presence.** If the business has limited or no web presence, attach invoices, contracts, marketing materials, or bank statements as supplementary evidence.
- **Use structured `businessProfile` fields.** The Nature of Business Questionnaire is deprecated in v2 — all business context is captured via structured fields.

---

## For business customers(Compliance-requirements)

This article provides a comprehensive summary of the required fields, document types, identity verification requirements, and applicable conditions for onboarding business customers (companies) to our platform.

To onboard a company to the BVNK platform, submit the following information.

## Overview

Requirements differ along two dimensions:

- **Jurisdiction**: the BVNK entity that contracts with the customer:
  - **US** — System Pay Services (US), Inc., a Delaware-incorporated company (NMLS ID 2531294), registered as a Money Services Business with FinCEN and licensed as a money transmitter in various US states.
  - **EU** — System Pay Services (Malta) Ltd (C66961), authorised by the Malta Financial Services Authority (MFSA) as an Electronic Money Institution and as a Crypto-Asset Service Provider under MiCA (Regulation (EU) 2023/1114).
- **Onboarding model**:
  - **BVNK-Managed**: you provide documents and structured data, BVNK performs ID&V.
  - **Partner-managed**: you perform ID&V and pass verification metadata + risk attestations to BVNK.

  The applicable onboarding model depends on the type of business and the licensing setup of the Embedded Partner. Contact the BVNK Solutions team to confirm which model applies to your integration.

For the technical integration, payload structures, and endpoint reference, see the companion API Integration Guide.

## Business entity information

<Tabs groupId="onboardingModel">
  <TabItem value="bvnkManaged" label="BVNK-Managed">

#### Company profile

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Legal Entity Name (`company.name`) | ✅ | ✅ | Verified against business registry records. Must match formation documents exactly. |
| Registration Number (`company.registrationNumber`) | ☑️ | ✅ | Cross-referenced with the relevant national business registry. Optional for US if EIN is provided. |
| Entity Type (`company.entityType`) | ✅ | ✅ | Determines downstream document and ownership disclosure requirements. See the [Appendix](#accepted-entity-types) for the list of supported entity types. |
| Incorporation Date (`company.incorporationDate`) | ✅ | ✅ | Entities incorporated &lt;2 years ago may trigger additional scrutiny (business plan, SoW, supporting invoices). |
| Industry (`company.industryReference`) | ✅ | ✅ | UUID from Industry API (NAICS supported). Determines whether vertical-specific requirements apply. Refer to available [Industry reference codes](../../../references/industy-references). |
| Tax ID (`company.taxNumber`) | ✅ | ☑️ | Mandatory for US entities (EIN). Verified against IRS records. |
| Tax Residence Country (`company.taxResidenceCountryCode`) | ✅ | ❌ | Mandatory for US entities. Establishes US tax nexus and triggers US-specific associate requirements. |

#### Registered address

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Street Address (`address.addressLine1`) | ✅ | ✅ | Verified against business registry. |
| City (`address.city`) | ✅ | ✅ | Part of full address verification. |
| Post / Zip Code (`address.postalCode`) | ✅ | ✅ | Part of full address verification. |
| State / Province (`address.stateCode`) | ✅ | ❌ | Required for US addresses. |
| Country (`address.countryCode`) | ✅ | ✅ |  Decline if in a controlled or prohibited jurisdiction. To get the list of countries, use the [Fetch Country Codes](../../../api-explorer/endpoints/list-countries) endpoint. |
| Operational Address (`company.operationalAddress`) | ☑️ | ☑️ | Required if different from registered address. |

#### Business profile

The `businessProfile` object captures business context, CDD data, and nature-of-business information at customer creation.

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Description (`businessProfile.description`) | ✅ | ✅ | Brief narrative of business activities. Used by Compliance to assess consistency with declared industry. |
| Website (`businessProfile.website`) | ✅ | ✅ | Reviewed for risk indicators, consistency with declared activity, and exposure to prohibited content. |
| Regulated Status (`businessProfile.isRegulated`) | ✅ | ✅ | Triggers requirement for AML Policy and Proof of Regulatory License if `true`. |
| Source of Funds (`businessProfile.sourceOfFunds`) | ✅ | ✅ | Structured enum. Documentary evidence may be requested during compliance review. See the [Appendix](#business-source-of-funds-businessprofilesourceoffunds) for the list of supported values. |
| Intended Use of Account (`businessProfile.intendedUseOfAccount`) | ✅ | ✅ | Screened for high-risk purposes (e.g. third-party money transmission). Must align with declared business model. See the [Appendix](#business-intended-use-of-account-businessprofileintendeduseofaccount--cddintendeduseofaccount) for the list of supported values. |
| Monthly Expected Volume (`businessProfile.monthlyExpectedVolumes`) | ✅ | ✅ | Volume range provided as a string enum (e.g. `FROM_0_TO_10K`). See the [Appendix](#business-monthly-expected-volume-businessprofilemonthlyexpectedvolumes) for supported values. *A UUID-based reference via the Volumes API (`company.monthlyExpectedVolumesReference`) will replace this field in a future release.* |

:::info Nature of Business Questionnaire
Previously required for business customers in v1. **Deprecated in v2.** All business context is now captured via the structured `businessProfile` fields above.
:::

## Associates

Associates are individuals linked to the business.

Business customers must include associated natural persons. The following minimum roles must be declared:

- One Authorised Signatory / Representative
- One Director (EU) or Control Person (US)
- At least one and all UBOs above the applicable threshold (25% for onboarding and CDD, 10% for EDD)

### Associate roles

The following values are accepted in the associate `roles` field. Each associate must be assigned at least one role.

| Role | Parameter name | Requirement | Validation / why we collect it |
| --- | --- | --- | --- |
| `REPRESENTATIVE` | Authorised Signatory | ✅ At least one | Person legally authorised to bind the company and execute agreements. If not a director, evidence of signing authority is required (Board Resolution, PoA, or Articles provision). |
| `DIRECTOR` | Director / Control Person | ✅ At least one | EU: verified against the company registry. US: person with significant management control. Sanctions, PEP, and adverse media screening applied. |
| `BUSINESS_OWNER` | UBO / Beneficial Owner | ✅ At least one above threshold | CDD threshold: ≥25%. EDD threshold: ≥10%. If no individual above threshold, the most senior executive must be designated as Person with Significant Control. |
| `ACCOUNT_REPRESENTATIVE` | Account Representative | ❌ | Operational point of contact for the partnership. |

The same person can hold multiple roles, for example, Authorised Signatory + UBO + Director.

### Personal information (all associates)

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| First Name (`firstName`) | ✅ | ✅ | Must match government-issued ID exactly. Used for sanctions and adverse media screening. |
| Last Name (`lastName`) | ✅ | ✅ | Must match government-issued ID exactly. |
| Date of Birth (`dateOfBirth`) | ✅ | ✅ | Used for identity matching and screening disambiguation. |
| Nationality (`nationality`) | ☑️ | ✅ | US: required for Control Persons. EU: all nationalities including dual must be declared. Screened against [prohibited nationality lists](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime). |
| Country of Birth (`birthCountryCode`) | ☑️ | ✅ | US: required for Control Persons. Used for sanctions screening. |
| Country of Residence (`address.countryCode`) | ✅ | ✅ |  To get the list of countries, use the [Fetch Country Codes](../../../api-explorer/endpoints/list-countries) endpoint. |
| Email Address (`emailAddress`) | ✅ | ✅ | Primary communication channel for verification flows. |
| Residential Address (`address`) | ✅ | ✅ | Full address required. Must be a physical residential address. |
| State / Province (`address.stateCode`) | ☑️ | ❌ | Required for US addresses. |

### Tax identification (all associates)

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Tax ID Number (`taxIdentification.number`) | ✅ | ✅ | SSN mandatory for US persons, verified against database. EU: national tax ID. |
| Tax ID Country (`taxIdentification.country`) | ✅ | ✅ |  Establishes tax residency. |

### Identity verification (associates)

Under the BVNK-Managed model, raw documents are uploaded for BVNK to check via verification partners.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| ID Document Upload | ✅ | ✅ | Front/back image of passport, national ID card, driver's license, or residence permit. Verified items: authenticity, data extraction, expiry, and name/DOB matching. |
| Selfie / Liveness Upload | ✅ | ✅ | Biometric selfie matched against ID document photo. Liveness detection prevents spoofing. |
| Address Document Upload | ✅ | ✅ | Utility bill, bank statement, or government correspondence dated within 3 months. Address must match declared residential address. |

#### Individual CDD

When associates are onboarded as standalone individual customers (not in a business context), additional CDD fields apply.

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Employment Status (`cdd.employmentStatus`) | ✅ | ✅ | Used to assess plausibility of declared source of funds. See the [Appendix](#individual-employment-status-cddemploymentstatus) for the list of supported values. |
| Source of Funds (`cdd.sourceOfFunds`) | ✅ | ✅ | High-risk sources trigger SoF documentary request. See the [Appendix](#individual-source-of-funds-cddsourceoffunds) for the list of supported values. |
| Intended Use of Account (`cdd.intendedUseOfAccount`) | ✅ | ✅ | Screened for high-risk use cases. See the [Appendix](#individual-intended-use-of-account-cddintendeduseofaccount) for the list of supported values. |
| Expected Monthly Volume (`cdd.expectedMonthlyVolume`) | ❌ | ☑️ Questionnaire | EU BVNK-Managed: covered in questionnaire or defaults. |
| PEP Status (`cdd.pepStatus`) | ☑️ Questionnaire | ☑️ Questionnaire | Collected via questionnaire. Positive PEP triggers EDD. |

### UBO-specific requirements

UBOs above the ownership threshold must complete identity verification.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Basic data + residential address | ❌ (address) | ✅ | EU always requires full residential address. Sanctions, PEP, and adverse media screening applied. |
| ID Verification | ✅ (SSN mandatory) | ✅ | US: SSN mandatory for US residents, verified against database. EU: full ID verification (document or metadata under Partner-managed). |
| Ownership threshold | 25% (std) / 10% (high) | 25% (std) / 10% (high) | Standard CDD: ≥25% ownership or voting rights. EDD (high-risk): ≥10%. Full ownership chain required if held through intermediaries. |

## Business documents (KYB)

Documents are uploaded via `POST /onboarding/v1/applications/{id}/documents` (company) or via Portal.

#### Entity documents

| Document | US | EU | Why we collect it |
| --- | :---: | :---: | --- |
| Certificate of Incorporation | ✅ | ✅ | Confirms legal formation. Must show filing stamp or registration date. Legal name must match declared name. |
| Memorandum of Association | ✅ | ✅ | Confirms governance structure, powers, and objects of the entity. |
| Articles of Association | ✅ | ✅ | Confirms internal governance and signatory authority. *Submitted as a separate document type; may be combined with Memorandum where jurisdictionally equivalent.* |
| Source of Funds (Entity) | ✅ | ✅ | Bank statements (3 months activity) or equivalent. |
| Proof of Address (Entity) | ✅ | ✅ | Utility bill, lease, tax statement, or official government correspondence. Dated within 3 months. Required if operational address differs from registered. |
| Proof of Directorship | ✅ | ✅ | Official registry extract or certified register of directors. Not older than 6 months. |
| Corporate / Group Structure | ✅ | ✅ | Ownership chart showing all corporate shareholders through to UBOs. Certified by legal counsel or CA. Not older than 6 months. |
| Source of Wealth (Entity) | ☑️ | ☑️ | Triggered by high-risk rating or EDD. Audited accounts, financial statements, loan agreements, or bank statements showing capitalisation history. |
| Proof of Regulatory License | ☑️ | ☑️ | Required if entity operates in a regulated industry. Must be current and match declared jurisdiction. |
| Proof of Business Activity | ☑️ | ☑️ | Triggered when web presence is limited, entity is newly incorporated (&lt;2 years), or nature of business is unclear. |
| Shareholder Ownership Doc | ☑️ | ☑️ | Required when ownership is complex (trusts, foundations, nominees, >3 layers, offshore entities). |

  </TabItem>
  <TabItem value="partnerManaged" label="Partner-managed">

#### Company profile

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Legal Entity Name (`company.name`) | ✅ | ✅ | Verified against business registry records. Must match formation documents exactly. |
| Registration Number (`company.registrationNumber`) | ☑️ | ✅ | Cross-referenced with the relevant national business registry. Optional for US if EIN is provided. |
| Entity Type (`company.entityType`) | ✅ | ✅ | Determines downstream document and ownership disclosure requirements. See the [Appendix](#accepted-entity-types) for the list of supported entity types. |
| Incorporation Date (`company.incorporationDate`) | ✅ | ✅ | Entities incorporated &lt;2 years ago may trigger additional scrutiny (business plan, SoW, supporting invoices). |
| Industry (`company.industryReference`) | ✅ | ✅ | UUID from Industry API (NAICS supported). Determines whether vertical-specific requirements apply. Refer to available [Industry reference codes](../../../references/industy-references). |
| Tax ID (`company.taxNumber`) | ✅ | ☑️ | Mandatory for US entities (EIN). Verified against IRS records. |
| Tax Residence Country (`company.taxResidenceCountryCode`) | ✅ | ❌ | Mandatory for US entities. Establishes US tax nexus and triggers US-specific associate requirements. |

#### Registered address

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Street Address (`address.addressLine1`) | ✅ | ✅ | Verified against business registry. |
| City (`address.city`) | ✅ | ✅ | Part of full address verification. |
| Post / Zip Code (`address.postalCode`) | ✅ | ✅ | Part of full address verification. |
| State / Province (`address.stateCode`) | ✅ | ❌ | Required for US addresses. |
| Country (`address.countryCode`) | ✅ | ✅ |  Decline if in a controlled or prohibited jurisdiction. To get the list of countries, use the [Fetch Country Codes](../../../api-explorer/endpoints/list-countries) endpoint. |
| Operational Address (`company.operationalAddress`) | ☑️ | ☑️ | Required if different from registered address. |

#### Entity-level CDD

For Partner-managed onboarding, additional business context is provided through structured CDD fields rather than the `businessProfile` object alone.

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Monthly Expected Volume (`company.monthlyExpectedVolumesReference`) | ✅ | ✅ | UUID from Volumes API. Establishes baseline for transaction monitoring. |
| Intended Use of Account (`cdd.intendedUseOfAccount`) | ✅ | ✅ | Partner attests intended use. See the [Appendix](#business-intended-use-of-account-businessprofileintendeduseofaccount--cddintendeduseofaccount) for the list of supported values. |
| PEP Status, Entity (`cdd.pepStatus`) | ✅ | ✅ | Partner attests whether any person in the ownership or control structure is a PEP. |

#### Partner risk attestation

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Risk Score (`company.reliance.attestation.riskScore`) | ✅ | ✅ | Partner's customer-level risk rating. Input to BVNK's independent risk assessment. Possible values: `LOW`, `MEDIUM`, or `HIGH`. |
| EDD Completed (`company.reliance.attestation.eddCompleted`) | ✅ | ✅ | If `false` and BVNK rates the customer `HIGH`, BVNK-side EDD is triggered. |

#### Associates

Associates are individuals linked to the business.

Business customers must include associated natural persons. The following minimum roles must be declared:

- One Authorised Signatory / Representative
- One Director (EU) or Control Person (US)
- At least one and all UBOs above the applicable threshold (25% for onboarding and CDD, 10% for EDD)

##### Associate roles

The following values are accepted in the associate `roles` field. Each associate must be assigned at least one role.

| Role | Parameter name | Requirement | Validation / why we collect it |
| --- | --- | --- | --- |
| `REPRESENTATIVE` | Authorised Signatory | ✅ At least one | Person legally authorised to bind the company and execute agreements. If not a director, evidence of signing authority is required (Board Resolution, PoA, or Articles provision). |
| `DIRECTOR` | Director / Control Person | ✅ At least one | EU: verified against the company registry. US: person with significant management control. Sanctions, PEP, and adverse media screening applied. |
| `BUSINESS_OWNER` | UBO / Beneficial Owner | ✅ At least one above threshold | CDD threshold: ≥25%. EDD threshold: ≥10%. If no individual above threshold, the most senior executive must be designated as Person with Significant Control. |
| `ACCOUNT_REPRESENTATIVE` | Account Representative | Optional | Operational point of contact for the partnership. |

The same person can hold multiple roles, for example, Authorised Signatory + UBO + Director.

##### Personal information (all associates)

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| First Name (`firstName`) | ✅ | ✅ | Must match government-issued ID exactly. Used for sanctions and adverse media screening. |
| Last Name (`lastName`) | ✅ | ✅ | Must match government-issued ID exactly. |
| Date of Birth (`dateOfBirth`) | ✅ | ✅ | Format: `YYYY-MM-DD`. Used for identity matching and screening disambiguation. |
| Nationality (`nationality`) | ☑️ | ✅ | US: required for Control Persons. EU: all nationalities including dual must be declared. Screened against [prohibited nationality lists](https://help.bvnk.com/hc/en-us/articles/11100445499666-BVNK-Acceptable-Use-Policy-Financial-Crime). |
| Country of Birth (`birthCountryCode`) | ☑️ | ✅ | US: required for Control Persons. Used for sanctions screening. |
| Country of Residence (`address.countryCode`) | ✅ | ✅ |  To get the list of countries, use the [Fetch Country Codes](../../../api-explorer/endpoints/list-countries) endpoint. |
| Email Address (`emailAddress`) | ✅ | ✅ | Primary communication channel for verification flows. |
| Residential Address (`address`) | ✅ | ✅ | Full address required. Must be a physical residential address. |
| State / Province (`address.stateCode`) | ☑️ | ❌ | Required for US addresses. |

##### Tax identification (all associates)

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Tax ID Number (`taxIdentification.number`) | ✅ | ✅ | SSN mandatory for US persons, verified against database. EU: national tax ID. |
| Tax ID Country (`taxIdentification.country`) | ✅ | ✅ |  Establishes tax residency. |

:::note US Partner-managed (SSN)
When SSN is provided under US Partner-managed, ID metadata fields become optional.
:::

##### Identity verification (associates)

Under the Partner-managed model, verification metadata is passed confirming the partner has performed ID&V.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| ID Metadata (`reliance.identityDocumentMetadata`) | ☑️ | ✅ | Type, number, expiry date, issuing country, IDV timestamp. Confirms the partner has performed document verification. **US: optional if SSN has been provided.** |
| Biometric / Liveness Metadata (`reliance.biometricLiveness`) | ❌ | ✅ | Liveness timestamp confirms partner performed biometric check. |
| Address Verification Metadata (`reliance.addressVerification`) | ✅ | ✅ | Type: `DOC` (documentary) or `NON_DOC` (database/electronic). US: confirm residential address is valid and not a PO Box. EU: full address verification required. |

##### Individual CDD

When associates are onboarded as standalone individual customers (not in a business context), additional CDD fields apply.

| Field | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Employment Status (`cdd.employmentStatus`) | ✅ | ✅ | Used to assess plausibility of declared source of funds. See the [Appendix](#individual-employment-status-cddemploymentstatus) for the list of supported values. |
| Source of Funds (`cdd.sourceOfFunds`) | ✅ | ✅ | High-risk sources trigger SoF documentary request. See the [Appendix](#individual-source-of-funds-cddsourceoffunds) for the list of supported values. |
| Intended Use of Account (`cdd.intendedUseOfAccount`) | ✅ | ✅ | Screened for high-risk use cases. See the [Appendix](#individual-intended-use-of-account-cddintendeduseofaccount) for the list of supported values. |
| Expected Monthly Volume (`cdd.expectedMonthlyVolume`) | ❌ | ✅ | EU Partner-managed: object `{amount, currency}` mandatory. |
| PEP Status (`cdd.pepStatus`) | ✅ | ✅ | Partner must attest status (e.g. `NOT_PEP`). Positive PEP triggers EDD. |

##### Director-specific requirements

Directors are collected and verified against the company registry. Verification depth depends on risk level.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Basic data (name, DOB, nationality, residence) | ✅ | ✅ | Cross-referenced against the company's registry of directors. Sanctions, PEP, and adverse media screening applied to all directors. |
| Residential Address | ❌ | ✅ | EU: required for high-risk customers under EDD. |
| ID Verification Metadata | ❌ | ✅ | EU: required for high-risk customers under EDD. |

##### UBO-specific requirements

UBOs above the ownership threshold must complete identity verification.

| Check | US | EU | Validation / why we collect it |
| --- | :---: | :---: | --- |
| Basic data + residential address | ❌ (address) | ✅ | EU always requires full residential address. Sanctions, PEP, and adverse media screening applied. |
| ID Verification | ✅ (SSN mandatory) | ✅ | US: SSN mandatory for US residents, verified against database. EU: full ID verification (document or metadata under Partner-managed). |
| Ownership threshold | 25% (std) / 10% (high) | 25% (std) / 10% (high) | Standard CDD: ≥25% ownership or voting rights. EDD (high-risk): ≥10%. Full ownership chain required if held through intermediaries. |

#### Business documents (KYB)

Documents are uploaded via `POST /onboarding/v1/applications/{id}/documents` (company) or via Portal.

##### Entity documents

| Document | US | EU | Why we collect it |
| --- | :---: | :---: | --- |
| Certificate of Incorporation | ✅ | ❌ | Confirms legal formation. Must show filing stamp or registration date. Legal name must match declared name. |
| Memorandum of Association | ❌ | ❌ | Confirms governance structure, powers, and objects of the entity. |
| Articles of Association | ❌ | ❌ | Confirms internal governance and signatory authority. *Submitted as a separate document type; may be combined with Memorandum where jurisdictionally equivalent.* |
| Source of Funds (Entity) | ☑️ | ☑️ | Attestation sufficient at CDD level. Documentary evidence required under EDD — see [Company EDD](#company-edd). |
| Proof of Address (Entity) | ❌ | ✅ | Utility bill, lease, tax statement, or official government correspondence. Dated within 3 months. Required if operational address differs from registered. |
| Proof of Directorship | ❌ | ❌ | Official registry extract or certified register of directors. Not older than 6 months. |
| Corporate / Group Structure | ❌ | ❌ | Ownership chart showing all corporate shareholders through to UBOs. Certified by legal counsel or CA. Not older than 6 months. |
| Proof of Regulatory License | ❌ | ❌ | Required if entity operates in a regulated industry. Must be current and match declared jurisdiction. |
| Proof of Business Activity | ❌ | ❌ | Triggered when web presence is limited, entity is newly incorporated (&lt;2 years), or nature of business is unclear. |
| Shareholder Ownership Doc | ❌ | ❌ | Required when ownership is complex (trusts, foundations, nominees, >3 layers, offshore entities). |

:::note Partner-managed philosophy
Under Partner-managed, BVNK relies on the partner's KYB programme. The minimum doc set reflects what BVNK still needs for its own records and regulatory obligations (e.g. Certificate of Incorporation for US Partner-managed under MTL requirements; Proof of Address for EU Partner-managed under MiCA).
:::

  </TabItem>
</Tabs>

## Enhanced due diligence

Enhanced due diligence (EDD) requirements apply when the BVNK customer risk rating is **HIGH** and EDD has not been completed by the Embedded Partner (`reliance.attestation.eddCompleted: false`).

### Company EDD

| Requirement | US | EU | What we accept |
| --- | :---: | :---: | --- |
| Company Source of Wealth | ✅ | ✅ | Loan agreements, financial statements, tax returns, bank statements, or commercial database verification (e.g. Creditsafe). |
| Source of Funds (Entity) | ✅ | ✅ | Document required when EDD applies (replaces the CDD attestation sufficient for standard risk). |
| Director & UBO Address Verification | ❌ | ✅ | Commercial database check or documentary evidence (utility bill, bank statement). |
| UBO Source of Wealth | ❌ | ✅ | Tax returns, investment portfolio statements, share certificates, or open-source research. |
| Verification of Professional Activity | ❌ | ✅ | Payslips, employment contracts, invoices (if self-employed), or open-source review. |
| Proof of Entity Address | ✅ | ❌ | Bank statement or other documentary evidence showing the entity's physical address. |

## Review process

### Application review

BVNK reviews applications once all required data, documents, and associate verification have been submitted. Onboarding completes automatically when all conditions are satisfied — there is no separate “submit” call. See the API Integration Guide (Section 10) for completion mechanics.

### Decisioning

Applications result in one of three outcomes: **VERIFIED**, **REJECTED**, or remain in **SUBMITTED** state pending additional information. BVNK sends webhook notifications at each status transition.

### Requests for information (RFI)

When BVNK requires additional information, a consolidated RFI is issued. To minimise RFIs:

- Submit all formation, ownership, and address documents upfront.
- Clearly substantiate the nature of business, especially where web presence is limited.
- For regulated entities, include AML policy and license documentation with the initial submission.
- Pre-screen business physical addresses for virtual or registered agent addresses.

## Best practices

- **Pre-screen addresses.** Confirm the physical address is not a virtual office or registered agent. Wyoming and Delaware addresses in particular require scrutiny.
- **Collect ownership attestation early.** Have the control person certify UBOs above the threshold to avoid follow-up document requests.
- **Document the nature of business.** Ensure the website or supporting documents substantiate what the business does. For new businesses, provide a business plan or pitch deck.
- **Source of funds upfront.** Proactively submit bank statements showing 3 months of transactional activity for BVNK-Managed; provide attestation for Partner-managed CDD.
- **Web presence.** If the business has limited or no web presence, attach invoices, contracts, marketing materials, or bank statements as supplementary evidence.
- **Use structured `businessProfile` fields.** The Nature of Business Questionnaire is deprecated in v2 — all business context is captured via structured fields.

## Appendix

### Supported document types

Document types used in `POST /documents` calls. See the API Integration Guide for the upload format.

| Type | Description |
| --- | --- |
| `CERTIFICATE_OF_INCORPORATION` | Certificate of incorporation or business formation |
| `MEMORANDUM` | Memorandum of Association |
| `ARTICLE_OF_ASSOCIATION` | Articles of Association |
| `PROOF_OF_DIRECTORSHIP` | Directors' registry or proof of directorship |
| `CORPORATE_STRUCTURE` | Corporate/group structure or shareholder registry |
| `PROOF_OF_OPERATIONAL_ADDRESS` | Utility bill, lease contract, or equivalent |
| `SOURCE_OF_FUNDS` | Bank statements or equivalent SoF evidence |
| `SOURCE_OF_WEALTH` | Audited accounts, tax returns, loan agreements |
| `PROOF_OF_REGULATORY_LICENSE` | Current regulatory licence |
| `AML_POLICY` | AML policy signed by Director/MLRO/Compliance Officer |
| `SHAREHOLDER_OWNERSHIP` | Ownership documentation for complex structures |
| `PASSPORT` / `ID_CARD` / `DRIVERS` / `RESIDENCE_PERMIT` | Government-issued ID for associates |
| `SELFIE` | Biometric selfie/liveness for associate verification |
| `UTILITY_BILL` | Proof of residential address for associates |

### Accepted entity types

| Value | Description |
| --- | --- |
| `LLC` | Limited Liability Company |
| `CORPORATION` | Corporation |
| `PARTNERSHIP` | Partnership |
| `SOLE_PROPRIETOR` | Sole proprietor |
| `PUBLICLY_LISTED_COMPANY` | Publicly listed company |
| `TRUST` | Trust |
| `PRIVATE_FOUNDATION` | Private foundation |
| `CHARITY` | Charity |
| `NON_PROFIT_ORGANIZATION` | Non-profit organization |
| `PUBLIC_AGENCIES_OR_AUTHORITIES` | Public agencies or authorities |

### Parameter values

#### Business: Source of Funds (`businessProfile.sourceOfFunds`)

| Value | Description |
| --- | --- |
| `COMMERCIAL_ACTIVITIES` | Revenue from commercial activities |
| `SHAREHOLDER_CAPITAL` | Shareholder capital contributions |
| `VENTURE_CAPITAL` | Venture capital funding |
| `SALE_OF_ASSETS` | Proceeds from sale of assets |
| `CRYPTO_FUNDRAISING` | Crypto fundraising proceeds |
| `CRYPTO_TRADING_REVENUE` | Revenue from crypto trading |
| `CORPORATE_LOANS` | Corporate loans |
| `OTHER` | Other sources |

#### Business: Intended Use of Account (`businessProfile.intendedUseOfAccount` / `cdd.intendedUseOfAccount`)

| Value | Description |
| --- | --- |
| `SUPPLIER_VENDOR_PAYMENTS` | Supplier and vendor payments |
| `INTERCOMPANY_TRANSFERS` | Intercompany transfers |
| `PAYROLL` | Payroll |
| `CUSTOMER_PAYMENTS_RECEIVED` | Customer payments received |
| `CUSTOMER_PAYOUTS_REFUNDS_SETTLEMENTS` | Customer payouts, refunds, and settlements |
| `OPERATING_EXPENSES` | Operating expenses |
| `DIVIDEND_PROFIT_DISTRIBUTIONS` | Dividend and profit distributions |
| `LOAN_REPAYMENT_FINANCIAL_ACTIVITIES` | Loan repayment and financial activities |

#### Business: Monthly Expected Volume (`businessProfile.monthlyExpectedVolumes`)

| Value | Description |
| --- | --- |
| `FROM_0_TO_10K` | 0 to 10,000 USD equivalent |
| `FROM_10K_TO_50K` | 10,000 to 50,000 USD equivalent |
| `FROM_50K_TO_100K` | 50,000 to 100,000 USD equivalent |
| `FROM_100K_TO_1M` | 100,000 to 1,000,000 USD equivalent |
| `FROM_1M_TO_10M` | 1,000,000 to 10,000,000 USD equivalent |
| `ABOVE_10M` | Above 10,000,000 USD equivalent |

#### Individual: Intended Use of Account (`cdd.intendedUseOfAccount`)

| Value | Description |
| --- | --- |
| `TRANSFERS_OWN_WALLET` | Transfers to or from own wallet including bank accounts |
| `TRANSFERS_FAMILY_FRIENDS` | Transfers to or from family and friends |
| `INVESTMENTS` | Investments |
| `GOODS_SERVICES` | Purchases of goods and services |
| `DONATIONS` | Donations |

#### Individual: Source of Funds (`cdd.sourceOfFunds`)

| Value | Description |
| --- | --- |
| `SALARY` | Salary and employment income |
| `PENSION` | Pension and retirement income |
| `SAVINGS` | Savings and investments |
| `SELF_EMPLOYMENT` | Self employment and business income |
| `CRYPTO_TRADING` | Crypto trading |
| `GAMBLING` | Gambling and lottery winnings |
| `REAL_ESTATE` | Real estate sales |

#### Individual: Employment Status (`cdd.employmentStatus`)

| Value | Description |
| --- | --- |
| `SALARIED` | Salaried |
| `SELF_EMPLOYED` | Self employed and freelancer |
| `UNEMPLOYED` | Unemployed |
| `RETIRED` | Retired |

#### PEP Status (`cdd.pepStatus`)

| Value | Description |
| --- | --- |
| `NOT_PEP` | Not a PEP |
| `FORMER_PEP_2_YEARS` | Former or inactive PEP (within 2 years) |
| `FORMER_PEP_OLDER` | Former or inactive PEP (older than 2 years) |
| `DOMESTIC_PEP` | Domestic PEP |
| `FOREIGN_PEP` | Foreign PEP |
| `CLOSE_ASSOCIATES` | Close associates |
| `FAMILY_MEMBERS` | Family members |
| `STATE_OWNED` | State-owned entity (entity only) |

---

## Add documents to customers

:::info Customers API v2
The [new customer onboarding flow](../create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Make sure to study [Compliance Requirements](../../compliance-requirements/embedded-compliance-requirements-businesses) before submitting the corresponding documents.

## Add documents to a customer

Each request can upload multiple documents simultaneously.

:::warning When uploading customer documents:

* Reference the correct `customerReference`.
* Use `customerPersonReference` when the document belongs to a specific associate.
* If `customerPersonReference`is omitted or `null`, the document is attached at the company level for business customers.
* Encode files to Base64 before sending.
:::

To add documents to a customer profile, send the [`POST customers/{customerReference}/documents` ](../../../api-explorer/endpoints/upload-customer-documents) request with the `customerReference` in the path and the following request body:

<Tabs>
  <TabItem value="Company">
    ```json Example: upload multiple documents for a company and an associate
    [
        {
            "type": "COMPANY_DOC",
            "subType": "INCORPORATION_CERT",
            "name": "Company Structure.pdf",
            "description": "Document optional description",
            "countryCode": "GB",
            "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
            "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
        },
        {
            "customerPersonReference": "9b2c3d4e-567f-48f0-abc1-03a4e3df12ab",
            "type": "PASSPORT",
            "subType": "FRONT_SIDE",
            "name": "John Smith Passport.pdf",
            "description": "Document optional description",
            "countryCode": "GB",
            "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
            "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
        }
    ]
    ```

    | Parameter           | Required | Description                                                                                                                                                |
    | :------------------ | :-------: | :------------------------------------- |
    | `customerReference` | :white_check_mark:      | The unique identifier of the customer to whom the documents will be attached. Customer has to be in `INFO_REQUIRED` status (status after agreement consent) |

    | Attribute | Required | Description |
    | :--- | :---: | :--- |
    | `customerPersonReference` | :x: | Reference that links the document to a specific **associate** (for example, beneficial owner). If omitted or null, the document is attached at the company level. |
| `type` | :white_check_mark: | The document type, for example COMPANY\_DOC.See the full list of supported [COMPANY document type](../../compliance-requirements/embedded-compliance-requirements-businesses).When uploading documents for an **associate** (e.g. ) refer to the following [list for supported document types](../../compliance-requirements/compliance-requirements-for-individuals2). |
| `subType` | :x: | Additional specification of the document type, e.g. FRONT\_SIDE, BACK\_SIDE if applicable. See the full list of supported [document subType for COMPANY documents](../../compliance-requirements/embedded-compliance-requirements-businesses).When uploading documents for an **associate** (e.g. PASSPORT) refer to the following [list for supported document subTypes](../../compliance-requirements/compliance-requirements-for-individuals2). |
    | `name` | :white_check_mark: | Optional human-readable filename, for example, "John Smith Passport.pdf". |
    | `description` | :x: | Optional description for the provided document |
    | `countryCode` | :white_check_mark: | ISO 3166-1 alpha-2 country code associated with the document. |
    | `externalReference` | :white_check_mark: | The internal reference mapped to the document from your end. |
    | `content` | :white_check_mark: | Base64-encoded file content. |

  </TabItem>

  <TabItem value="Individual">
    ```json Example: upload multiple documents for an individual
    [
        {
            "type": "PASSPORT",
            "subType": "FRONT_SIDE",
            "name": "John Smith Passport.pdf",
            "description": "Document optional description",
            "countryCode": "GB",
            "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
            "content": "JVBERi0xLjUKJeLjz9MKMSAwIG9iago8PC9UeXBlIC9QYWdl..."
        }
    ]
    ```

    | Parameter           | Type     | Required | Description                                                                                                                                                |
    | :------------------ | :------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `customerReference` | `string` | Yes      | The unique identifier of the customer to whom the documents will be attached. Customer has to be in `INFO_REQUIRED` status (status after agreement consent) |

    | Attribute | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `type` | `string` | Yes | You must provide all three types of documents:ID (`PASSPORT`, `ID_CARD`, `DRIVER_LICENSE`, `RESIDENCE_PERMIT`)`SELFIE` (must be uploaded along with any ID)`PROOF_OF_RESIDENCE` (`UTILITY_BILL`)
            For the full list of supported document types, refer to the [Compliance Requirements for Individuals](../../compliance-requirements/compliance-requirements-for-individuals2). |
| `subType` | `string` | No | Additional specification of the document type, e.g. `FRONT_SIDE`, `BACK_SIDE` if applicable.
            [Full list of supported document subTypes](../../compliance-requirements/compliance-requirements-for-individuals2) |
| `name` | `string(128)` | Yes | Human-readable filename, for example, `"John Smith Passport.pdf"`. |
| `description` | `string(255)` | No | Optional description for the provided document |
| `countryCode` | `string(2)` | Yes | ISO 3166-1 alpha-2 country code associated with the document. |
| `externalReference` | `string(36)` | Yes | The external reference mapped to the document from your end. |
| `content` | `string` | Yes | Base64-encoded file content. |

  </TabItem>
</Tabs>

In the successful response, you receive unique references for tracking the status. That means the request has been accepted and the documents are queued for upload.

<Tabs>
  <TabItem value="Success">
    ```json Success
    {
      "reference": "d42e1c62-27b8-4b3b-b51e-eb10edeb1731",
      "externalReference": "2b8d8bde-eef5-408a-9228-96bef24865ad",
      "status": "INIT"
    }
    ```
  </TabItem>
  <TabItem value="Failure">
    ```json Failure
    {
      "code": "DOCUMENTS-4000",
      "status": "BAD_REQUEST",
      "message": "Invalid document content",
      "details": {
        "errors": {
          "content": [
            "Document file content is not valid base64"
          ]
        }
      }
    }
    ```
  </TabItem>
</Tabs>

:::tip
Onboarding procedures are completed automatically once you provide all the required documents and meet the customer compliance requirements.
:::

## Manage documents

:::info Tips

* **Check Document Status**.
  Retrieve the customer or associated person object to confirm document verification status.
* **Retain Document References**.
  Store the `reference` returned in the success response for future queries or audits.
* **Combine with KYC**.
  Document verification may be required before the customer status changes from `PENDING` to `VERIFIED`.

:::

### Search Documents

To search for specific documents, send the [`GET /platform/v1/customers/documents`](../../../api-explorer/endpoints/get-customer-documents) request with the optional query parameters:

* `customerReference`
* `externalReference`
* `name`
* `types`
* `subTypes`
* `statuses` (e.g., INIT, PENDING, APPROVED, DECLINED)

### Get document download URL

To get a Document Download link, send the [`GET /platform/v1/customers/documents/{documentReference}/url`](../../../api-explorer/endpoints/get-document-url) request with the `{documentReference}` specified in the query.

In the successful response, you receive a temporary URL for document download.

### Delete document

To remove a document from a customer's profile, send the [`DELETE /platform/v1/customers/documents/{documentReference}`](../../../api-explorer/endpoints/delete-document) request with the `{documentReference}` specified in the query.

In the successful response, you receive the status `204 No Content`, which means the document is deleted.

## Check monitoring status

You can monitor the customer's verification status via:

* **API**: Retrieve current customer's onboarding status by sending the [`GET /platform/v1/customers/{customerReference}`](../../../api-explorer/endpoints/get-customer-with-external-status) request.
* **Portal**: Track progress and statuses directly through the BVNK Portal.
* **Webhooks**: [Document verification status changes](../../../api-explorer/bvnk-webhooks/customer-document-status-change).

---

**What's next?**

After you create and onboard your customers, you are ready to send and receive payments.

- See the available [use cases](../find-your-usecase.mdx) to select the one that best suits your needs.
- [Create a wallet](../create-wallet.mdx) for yourself or your customers.
- If you are onboarding a Business customer, you also need to submit the [questionnaires](../onboard-epc) for them.

---

## Create business customers

This guide describes how to create and onboard your customers.

:::info Customers API v.2
This is a new customer onboarding flow, which is recommended for all new integrations.

If you already have an existing integration with [Customers API v.1](../create-embedded-partner-customer/creating-an-embedded-customer-company-api.mdx), you can continue using it. BVNK will continue to support this API v.1 going forward.
:::

The onboarding flow is asynchronous: after you create a customer, BVNK processes the application and notifies you via webhooks when action is required or when verification is complete.

You can customize the customer creation and onboarding according to your own platform flow. The modular approach allows you to call endpoints for adding documents or sharing data in any order.

The data and documents you must submit depend on your use case and on the BVNK entity (US or EU) your account is assigned to. See the [compliance requirements](../../compliance-requirements/embedded-compliance-requirements-businesses-2) for the full list.

When onboarding a customer, they pass through the following stages:

![](/img/bvnk/get-started/onboarding_flow.png)

| Status | Description |
| --- | --- |
|`INFO_REQUIRED`| The customer data is submitted partially. Provide other information or documents. |
|`PENDING`|The customer data is submitted and waiting for the BVNK review.|
|`VERIFIED`|Customer verification has been succesfully completed.|
|`ACTIONS_REQUIRED`|Additional actions are required from the partner/customer.|
|`REJECTED`|Customer checks failed. Customer onboarding is not possible.|
| `TERMINATED` | The customer is removed by BVNK or partner. |

## Prerequisites

Before you start, make sure you have:

- A BVNK account with [Embedded Partner](../../../get-started/delivery-models?delivery-model=custom-embedded) capabilities enabled.
- [API keys](../../../get-started/generate-api-keys) generated via the BVNK Portal.
- [Webhook endpoint](../../../get-started/create-webhook-listener) configured to receive status change events from BVNK.
- Familiarity with [BVNK's compliance requirements for business customers](../../compliance-requirements/embedded-compliance-requirements-businesses).

## Create business customers

Business customer creation and onboarding is only available for the [embedded delivery model](../../delivery-models?delivery-model=custom-embedded). This flow requires verification of the legal entity (KYB) and related individuals, including directors, UBOs, and authorised signatories (KYC). The specific data and document requirements depend on jurisdiction (US or EU) and onboarding model:

- **BVNK-Managed**: You submit structured data and raw identity documents (ID front/back, selfie, proof of address) via BVNK's Onboarding API. BVNK performs identity verification (ID&V) via partner services. Recommended when you don't have an existing KYC/KYB programme or want BVNK to handle the full verification lifecycle.
- **Partner-managed**: Available to regulated partners with an appropriate AML programme.. You perform ID&V using your own processes and pass verification metadata (document type, number, expiry, liveness timestamp, address verification type) along with a customer risk score and EDD attestation to BVNK. Note that some features of the BVNK-Managed model are not available for the Partner-managed model. To learn more, contact your BVNK account manager.

<!-- <Tabs queryString="embedded-onboarding">
<TabItem value="bvnk-managed" label="BVNK-Managed"> -->

:::warning Deprecated: pre-creation agreement sessions
The previous integration pattern required creating and signing an agreement session before creating a customer via [`POST /platform/v1/customers/agreement/sessions`](../signing-customer-agreements/). This flow still functions but is superseded by the post-creation agreement flow described below. New integrations should use the following flow.
:::

The typical BVNK-Managed flow for a business customer follows these steps:

:::tip
You can perform steps 3-6 in any order.
:::

1. Create a customer by sending the [`POST platform/v2/customers`](../../../api-explorer/endpoints/create-customer-v-2) request with the minimum required fields. In practice you should still send a complete `businessProfile` and jurisdiction-specific `associates` fields so onboarding is not stalled.

	```json
	{
		"useCase": "FIAT",
		"reference": "partner-ref-001",
        "company": {
            "name": "Acme Ltd",
            "entityType": "CORPORATION",
            "taxIdentification": {
                "number": "GB123456789",
                "taxResidenceCountryCode": "GB"
            },
            "registrationNumber": "12345678",
            "businessProfile": {
                "description": "Online retailer of consumer electronics",
                "naicsCode": "5411",
                "monthlyExpectedVolumes": "UNDER_100K",
                "website": "https://acme.test",
                "customerTypes": "Individuals",
                "prohibitedJurisdictionsExposure": false,
                "annualIncomingTransactionValue": "500000",
                "annualOutgoingTransactionValue": "250000",
                "jurisdictionalPortfolioDistribution": [
                    {
                        "country": "GB",
                        "percentage": 75
                    },
                    {
                        "country": "FR",
                        "percentage": 25
                    }
                ],
                "isRegulated": true,
                "regulatorInformation": {
                    "regulatorName": "Financial Conduct Authority",
                    "regulatorJurisdiction": "GB"
                },
                "isPubliclyListed": false,
                "publicInformation": {
                    "listedExchange": "LSE",
                    "tickerSymbol": "ACME"
                },
                "sourceOfFunds": "COMMERCIAL_ACTIVITIES",
                "intendedUseOfAccount": "SUPPLIER_VENDOR_PAYMENTS"
            },
            "address": {
                "addressLine1": "1 Main St",
                "addressLine2": "Suite 400",
                "city": "London",
                "postalCode": "E1 6AN",
                "countryCode": "GB"
            },
            "isOperationalAddressDifferent": true,
            "operationalAddress": {
                "addressLine1": "25 Commerce Way",
                "addressLine2": "Floor 3",
                "city": "London",
                "postalCode": "EC2A 4NE",
                "countryCode": "GB"
            },
            "incorporationDate": "2018-05-12",
            "businessOperationsStartDate": "2018-06-01",
            "associates": [
            {
                "person": {
                "firstName": "Jane",
                "lastName": "Smith",
                "dateOfBirth": "1985-09-23",
                "nationality": "GB",
                "secondNationality": "IE",
                "birthCountryCode": "GB",
                "address": {
                    "addressLine1": "12 Baker Street",
                    "addressLine2": "Apt 5B",
                    "city": "London",
                    "postalCode": "NW1 6XE",
                    "countryCode": "GB"
                },
                "contactInfo": {
                    "emailAddress": "jane.smith@acme.test",
                    "phoneNumber": "+442071234567"
                },
                "taxIdentification": {
                    "number": "AB123456C",
                    "taxResidenceCountryCode": "GB"
                },
                "position": "Managing Director"
                },
                "titles": [
                    "UBO",
                    "DIRECTOR",
                    "SIGNATORY"
                ],
                "ownership": {
                    "type": "DIRECT",
                    "percentage": "100"
                }
            }
        ]
    }
	}
	```

	The response includes the customer's `id` and initial `status` (for example `NOT_STARTED`). Save the returned associate, agreement, and customer IDs, and your external references for later steps.

2. Retrieve the customer's status and the list of documents required for compliance by sending the [`GET platform/v2/customers/{id}`](../../../api-explorer/endpoints/get-customer-v-2) request with the customer's ID you received in the response from step 1.

	In the response, you will receive the ID and the status of the customer.

	```json
	{
        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "reference": "partner-ref-001",
        "status": "PENDING",
        "type": "COMPANY",
        "model": "EMBEDDED_BVNK_MANAGED",
        "useCase": "FIAT",
        "name": "Acme Ltd",
        "createdAt": "2026-04-28T11:39:12.788Z",
        "updatedAt": "2026-04-28T11:39:12.788Z",
        "authenticatedLink": {
            "link": "https://onboarding.bvnk.com/link/eyJhbGciOi...",
            "expiresAt": "2026-04-28T12:39:12.788Z"
        },
        "requiredActions": [
            {
                "type": "DATA",
                "code": "PROOF_OF_DIRECTORSHIP",
                "category": "DOCUMENT_REQUIREMENTS",
                "description": "Proof of directorship/trustees dated within the past 6 months"
            },
            {
                "type": "DATA",
                "code": "CERTIFICATE_OF_INCORPORATION",
                "category": "DOCUMENT_REQUIREMENTS",
                "description": "Business Formation Document"
            },
            {
                "type": "DATA",
                "code": "PROOF_OF_OPERATIONAL_ADDRESS",
                "category": "DOCUMENT_REQUIREMENTS",
                "description": "Proof of Operational Address"
            },
            {
                "type": "DATA",
                "code": "CORPORATE_STRUCTURE",
                "category": "DOCUMENT_REQUIREMENTS",
                "description": "Capitalization Table / Ownership Structure"
            },
            {
                "type": "DATA",
                "code": "ARTICLE_OF_ASSOCIATION",
                "category": "DOCUMENT_REQUIREMENTS",
                "description": "Article of association"
            },
            {
                "type": "DATA",
                "code": "MEMORANDUM",
                "category": "DOCUMENT_REQUIREMENTS",
                "description": "Memorandum"
            },
            {
                "type": "DATA",
                "code": "REQUIRED_ALL_ASSOCIATES_VALID",
                "category": "ASSOCIATES",
                "description": "All associates must have valid status prior to submission."
            }
        ],
        "company": {
            "name": "Acme Ltd",
            "entityType": "CORPORATION",
            "registrationNumber": "12345678",
            "taxIdentification": {
                "number": "GB123456789",
                "taxResidenceCountryCode": "GB"
            },
            "incorporationDate": "2018-05-12",
            "businessOperationsStartDate": "2018-06-01",
            "address": {
                "addressLine1": "1 Main St",
                "addressLine2": "Suite 400",
                "city": "London",
                "postalCode": "E1 6AN",
                "countryCode": "GB"
            },
            "associates": [
                {
                    "person": {
                        "firstName": "Jane",
                        "lastName": "Smith",
                        "dateOfBirth": "1985-09-23",
                        "nationality": "GB",
                        "birthCountryCode": "GB"
                    },
                    "titles": [
                        "UBO",
                        "DIRECTOR",
                        "SIGNATORY"
                    ],
                    "ownership": {
                        "type": "DIRECT",
                        "percentage": "100"
                    }
                }
            ]
        }
    }
	```

3. Upload the required company documents by sending the [`POST platform/v2/customers/{customerId}/documents`](../../../api-explorer/endpoints/upload-customer-company-documents-v-2) request with the customer's ID you received in the response from step 1.

	Upload documents sequentially. You can add up to three documents in a batch. Add a one-second delay between uploads to stay within rate limits. For the list of the required documents, see [Business documents (KYB)](../../compliance-requirements/embedded-compliance-requirements-businesses-2#business-documents-kyb) in the Compliance requirements reference.

	:::tip
	For documents in unsupported languages, a professionally notarised English translation is permitted.
	:::

	In the response, you will see the documents accepted for processing.

    ```json
	{
        "id": "9b0c4f1d-7aa2-4c7e-8d55-f8b4a1d6c210",
        "customerId": "0a184641-30e2-4414-871f-3db1c683900e",
        "totalDocuments": 3,
        "successCount": 3,
        "failureCount": 0,
        "documents": [
            {
                "documentId": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21",
                "type": "CERTIFICATE_OF_INCORPORATION",
                "filename": "certificate.pdf",
                "description": "Certificate of Incorporation",
                "status": "STORED",
                "uploadedAt": "2026-04-22T10:58:35.056865Z"
            }
        ],
        "createdAt": "2026-04-22T10:58:35.056865Z"
    }
	```

4. Upload associate ID documents by sending the [`POST platform/v2/customers/{customerId}/associates/{associateId}/identification-documents`](../../../api-explorer/endpoints/upload-associate-identification-documents-v-2) request with the associate ID you received in the response from step 2.

    For the list of the required documents, see [Identity verification (associates)](../../compliance-requirements/embedded-compliance-requirements-businesses-2#identity-verification-associates) in the Compliance requirements reference.

	```json
	{
		"metadata": [
			{
				"type": "PASSPORT",
				"name": "passport.pdf",
				"countryCode": "GB"
			}
		]
	}
	```

	In the response, you will receive the associate ID and the number of documents accepted for processing.

	```json
	{
		"id": "4b0b8e2e-2f4e-4bfa-86d2-95aed0512c5f",
		"associateId": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240",
		"acceptedDocumentCount": 1,
		"createdAt": "2026-04-22T11:00:35.056865Z"
	}
	```

5. Retrieve assigned agreements by sending the [`GET platform/v2/customers/{customerId}/agreements`](../../../api-explorer/endpoints/list-customer-assigned-agreements-v-2) request with the customer ID you received in the response from step 1. You must share the agreements with your customers and request that they sign them.

	To fetch a specific assigned agreement by id, call [`GET platform/v2/customers/{customerId}/agreements/{assignedAgreementId}`](../../../api-explorer/endpoints/get-customer-assigned-agreement-v-2). To download the agreement document, call [`GET platform/v2/customers/{customerId}/agreements/{assignedAgreementId}/content`](../../../api-explorer/endpoints/get-customer-agreement-content-v-2) to receive a short-TTL presigned URL.

	The response is a paginated list of assigned agreements:

	```json
	{
		"content": [
			{
				"id": "06d119bc-64f6-46b2-aea2-3ff94c4c616f",
				"agreement": {
					"version": "1.0",
					"title": "Partner Platform Agreement (Non-US)",
					"locale": "en-GB"
				},
				"status": "PENDING",
				"createdAt": "2026-03-25T10:57:38.145505Z",
				"updatedAt": "2026-03-25T10:57:38.145505Z"
			}
		],
		"totalElements": 1,
		"totalPages": 1,
		"hasNext": false
	}
	```

6. Accept an assigned agreement for a specific customer by sending the [`POST platform/v2/customers/{customerId}/agreements/{assignedAgreementId}/actions`](../../../api-explorer/endpoints/respond-customer-assigned-agreement-v-2) request with the action.

    ```json
    {
        "type": "ACCEPT"
    }
    ```

    To accept or reject up several agreements in the single request, call the [POST `platform/v2/customers/{customerId}/agreements/actions`](../../../api-explorer/endpoints/bulk-respond-customer-assigned-agreements-v-2) endpoint with a similar payload.

    ```json
    {
        "actions": [
            {
                "assignedAgreementId": "06d119bc-64f6-46b2-aea2-3ff94c4c616f",
                "type": "ACCEPT"
            },
            {
                "assignedAgreementId": "6b4f0f2a-5c7d-4f1e-9c2a-1a9e2e1b3f48",
                "type": "ACCEPT"
            }
        ]
    }
    ```

7. Wait for the [webhook](#webhooks) or poll the status by sending the [`GET platform/v2/customers/{id}`](../../../api-explorer/endpoints/get-customer-v-2/) request. The response includes onboarding ID, status, timestamps, `associates` (including `requiredDocuments` and `validationErrors`), and `agreements`.
<!--
</TabItem>

<TabItem value="Partner-managed" label="Partner-managed">

The **Partner-managed onboarding** model offers a controlled alternative KYC intake path. Eligible partners act as the primary identity verification provider, transmitting pre-verified PII, CDD data, and verification metadata to BVNK via API.

<Tabs queryString="reliance-onboarding-variant">
<TabItem value="Individual onboarding">

    During the standard flow, customers are supposed to provide their documents, which BVNK later sends for verification to a designated entity.

    The new onboarding model changes this approach in the following way:

    * You conduct identity verification on your side in accordance with the agreed standards and provide the required verification outcomes to BVNK. No ID documents, selfies, or proofs of address are uploaded at this stage, but all submitted information is subject to validation.
    * You still have to provide customer data, such as name, date of birth, PEP status, and so on, via API.

    To onboard a customer within the Partner-managed model, do the following:

    1. Prepare and sign agreements with your customer as described in the [guide](/bvnk/get-started/create-embedded-partner-customer/signing-customer-agreements).

    2. Create an **Individual** customer by sending the [`POST /api/platform/v1/customers`](/bvnk/api-explorer/endpoints/create-customer) request with their personal and compliance data.

    ```json Example Request
    {
        "type": "INDIVIDUAL",
        "individual": {
            "description": "Tier 1 customer",
            "firstName": "John",
            "lastName": "Dole",
            "dateOfBirth": "1990-05-12",
            "nationality": "GB", // Required for EU
            "birthCountryCode": "GB", // Required for EU
            "emailAddress": "john.dole@example.com",
            "address": {
                "addressLine1": "123 Main St",
                "city": "New York",
                "postalCode": "10001",
                "stateCode": "NY",
                "countryCode": "US"
            },
            "taxIdentification": { // Required for US residents
                "number": "123-45-6789",
                "taxResidenceCountryCode": "US"
            },
            "cdd": {
                "employmentStatus": "SALARIED",
                "sourceOfFunds": "CRYPTO_TRADING",
                "pepStatus": "NOT_PEP",
                "intendedUseOfAccount": "INVESTMENTS",
                "expectedMonthlyVolume": { // Required for EU
                    "amount": "500.01",
                    "currency": "EUR"
                },
                "estimatedYearlyIncome": "INCOME_0_TO_50K", // Required for US residents
                "employmentIndustrySector": "AGRICULTURE_FORESTRY_FISHING_HUNTING" // Required for US residents
            },
            "reliance": {
                "identityDocumentMetadata": {
                    "type": "PASSPORT",
                    "subType": "FRONT_SIDE",
                    "number": "AB1234567",
                    "issueDate": "2020-12-31",
                    "expiryDate": "2030-12-31",
                    "issuingCountryCode": "GB",
                    "kycTimestamp": "2025-11-20T15:30:45.123Z"
                },
                "biometricLiveness": { // Required for EU
                    "livenessTimestamp": "2025-11-20T15:30:45.123Z"
                },
                "addressVerification": {
                    "type": "DOC"
                },
                "attestation": {
                    "riskScore": "LOW",
                    "eddCompleted": true
                }
            }
        },
        "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1"
    }
    ```

    For the detailed descriptions and examples of each field, see the [endpoint](/bvnk/api-explorer/endpoints/create-customer) in the API Reference and the [Create a customer via API](/bvnk/get-started/create-embedded-partner-customer/creating-an-embedded-customer-company-api) guide.

    Make sure to include the following parameters in the payload to submit metadata for the proofing documents you have already verified, including document ID, type, and timestamps.

    :::warning
    Data requirements differ for EU and US entities. Make sure to provide the correct data for the corresponding region.
    :::

    | Parameter | Description |
    | --------- | ----------- |
    | `identityDocumentMetadata` | Details of the ID document you verified (Type, Number, Expiry, Issuing Country).Not required for US residents when a Social Security number is provided. |
    | `identityDocumentMetadata.expiryDate`|Expiration date of the provided document. Mandatory for all document types, except `ID_CARD` and `OTHER`.|
    | `biometricLiveness` | **Mandatory for EU entities**. Timestamp for biometric or liveness checks performed on your side. |
    | `addressVerification` | The method you used to verify the residential address.Values:* DOC: verified by a document* NON_DOC: verified via a database or registry |
    | `riskScore` | Your internal risk rating for this customer per Personally Identifiable Information (PII).Allowed values:* LOW* MEDIUM* HIGH |
    | `eddCompleted` | Flag to indicate that you have already performed Enhanced Due Diligence (EDD).BVNK doesn't verify customer attestations within this flow, so make sure you have completed the EDD.Allowed values:* True* False |

    In the successful response, you receive the status `200 OK`, which means the customer is created. The customer status is set to `PENDING`, indicating that the required data has already been provided and that BVNK can run internal checks.

    :::warning
    Any attempt to follow the standard onboarding flow by sending the [`POST /platform/v1/customers/{customerReference}/documents`](/bvnk/api-explorer/endpoints/upload-customer-documents) request will be rejected.
    :::

    After you submit the customer's data, the API returns a status indicating the result of the onboarding request:

    | Status         | Description                                      | Action Required                                                                |
    | -------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
    | `VERIFIED`     | The customer application is approved.            | None. Onboarding is automatically finalised.                                   |
    | `PENDING`      | The customer application is under manual review. | Monitor the status via webhooks.                                               |
    | `EDD_REQUIRED` | BVNK requires further checks.                    | An internal case is raised for manual review. Monitor the status via webhooks. |

    You can monitor the customer's verification status via the following endpoints:

    * API: Retrieve current customer's onboarding status by sending the [`GET /platform/v1/customers/{customerReference}`](/bvnk/api-explorer/endpoints/get-customer-with-external-status) request.
    * Portal: Track progress and statuses directly through the BVNK Portal.
    * Webhooks: Set up webhooks to receive automated status change notifications.
</TabItem>
<TabItem value="Business onboarding">

    The **Partner-managed Onboarding** model for Businesses (KYB) uses a hybrid approach to maximize speed while maintaining compliance.

    * Associates (Directors/UBOs): You perform Identity Verification on your side and send verification metadata via API. You do not need to upload any ID or selfie documents.
    * The Entity (Company): You upload the required legal documents, for example, the Certificate of Incorporation, via the documents endpoint.
    * Risk: You attest to the risk scoring and screening results.

    To onboard a business customer within the Partner-managed model, do the following:

    1. Prepare and sign agreements with your customer as described in the [guide](/bvnk/get-started/create-embedded-partner-customer/signing-customer-agreements).

    2. Create a **Business** customer by sending the [`POST /platform/v1/customers`](/bvnk/api-explorer/endpoints/create-customer) request with `"type": "COMPANY"`.

        ```json Example Request
        {
            "type": "COMPANY",
            "company": {
                "name": "Acme Corp Ltd",
                "entityType": "LIMITED_LIABILITY_COMPANY",
                "registrationNumber": "12345678",
                "incorporationDate": "2015-06-20",
                "incorporationCountryCode": "GB",
                "taxResidenceCountryCode": "GB",
                "industryReference": "30ea5818-06d8-11ef-b6e1-027612b7f6b5", // UUID from Industry API
                "taxIdentification": {
                    "number": "12-3456789", // Mandatory for US (EIN)
                    "taxResidenceCountryCode": "US"
                },
                "address": {
                    "addressLine1": "456 Corporate Blvd",
                    "city": "London",
                    "postalCode": "EC1A 1BB",
                    "countryCode": "GB"
                },
                "cdd": {
                    "intendedUseOfAccount": "PAYROLL",
                    "pepStatus": "NOT_PEP",
                    "expectedMonthlyVolume": {
                        "amount": "50000.00",
                        "currency": "EUR"
                    }
                },
                "reliance": {
                    // NOTE: Incorporation, Address, and SoF are handled via /documents in Step 3.
                    "attestation": {
                        "riskScore": "LOW",
                        "eddCompleted": true
                    }
                },
                "associates": [
                    {
                        "titles": ["BUSINESS_OWNER", "DIRECTOR"],
                        "person": {
                            "firstName": "Jane",
                            "lastName": "Doe",
                            "dateOfBirth": "1985-03-15",
                            "nationality": "GB", // Mandatory for EU
                            "birthCountryCode": "GB", // Mandatory for EU
                            "emailAddress": "jane@acme.com",
                            "address": {
                                "addressLine1": "10 Downing St",
                                "city": "London",
                                "postalCode": "SW1A 2AA",
                                "countryCode": "GB"
                            },
                            "reliance": {
                                "identityDocumentMetadata": {
                                    "type": "PASSPORT",
                                    "number": "987654321",
                                    "expiryDate": "2031-01-01", // Optional for type: OTHER, ID_CARD
                                    "issueDate": "2021-01-01", // Optional
                                    "issuingCountryCode": "GB",
                                    "kycTimestamp": "2025-11-20T15:30:45.123Z"
                                },
                                "biometricLiveness": {
                                    "livenessTimestamp": "2025-11-20T15:30:45.123Z" // Mandatory for EU
                                },
                                "addressVerification": {
                                    "type": "DOC"
                                }
                            }
                        }
                    }
                ]
            },
            "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1"
        }
        ```

        For the detailed descriptions and examples of each field, see the [endpoint](/bvnk/api-explorer/endpoints/create-customer) in the API Reference.

        Crucial difference from the individual onboarding flow:

        * **Associates:** Do not trigger the document loop. Instead, include `reliance` metadata inside the `associates` block.
        * **Entity:** Include the `attestation` and `cdd` data, but exclude the company file proofs (Incorporation, Address, SoF) from the JSON. You will upload them in Step 3.

        :::warning
        Data requirements differ for EU and US entities. Make sure to provide the correct data for the corresponding region.
        :::

        | **Parameter** | **Description** |
        | ---------  | ----------- |
        |`company.taxIdentification.number`| Tax identification number of the entity:*US: EIN*EU: VAT number. |
        |`company.registrationNumber`| Registration number of the entity:*US: Optional*EU: Mandatory. |
        |`company.address.stateCode`| State code of the entity:*US: Mandatory*EU: Optional. |
        |`associates[].person.reliance.nationality`| Nationality of the associate:*US: Optional*EU: Mandatory ISO code. |
        |**Required to confirm you have screened the entity**.||
        | `company.reliance.riskScore`  | Your internal risk rating for this customer. Allowed values: `LOW`, `MEDIUM`, `HIGH` |
        | `company.reliance.eddCompleted`  | Flag to indicate that you have already performed Enhanced Due Diligence (EDD). Allowed values: `true`, `false` |
        |**Required to bypass Associate ID uploads**.||
        | `associates[].person.reliance.identityDocumentMetadata` | Details of the ID document you verified: `type`, `number`, `expiryDate`, `issuingCountryCode`, `kycTimestamp`. | Optional for US residents if SSN is provided. |
        |`associates[].person.reliance.biometricLiveness`| Timestamp for biometric or liveness checks performed on your side:*US: Optional*EU: Mandatory `livenessTimestamp`. |
        | `associates[].person.reliance.addressVerification` | The method you used to verify the residential address. Values: `DOC`, `NON_DOC` | |

    3. After creating the customer, upload entity documents by sending the [`POST /platform/v1/customers/{customerReference}/documents`](/bvnk/api-explorer/endpoints/upload-customer-documents) request.

        The customer's status changes to `INFO_REQUIRED` until the entity documents are received.

        :::warning
        Do **NOT** upload documents for the Associates (Directors/UBOs). Their verification was handled via metadata in Step 2.
        :::

        | Verification requirement | Document type to upload | Notes |
        | ------------------------ | ----------------------- | ----- |
        | **Certificate of Incorporation** | `COMPANY_DOC` > `INCORPORATION_CERT` | Mandatory for legal entity verification. **US entities only**.   |
        | **Registered Address Proof** | `COMPANY_DOC` > `PROOF_OF_ADDRESS` | Utility bill, Bank Statement, or Tax Document (dated < 3 months). **EU entities only**. |
        | **Source of Funds** | `COMPANY_DOC` > `OTHER` | Bank Statement or Financials showing the entity's funding source. |

        ```json Example Request: Upload the Certificate of Incorporation
        {
            "type": "COMPANY_DOC",
            "subType": "INCORPORATION_CERT",
            "name": "INC_CERT.pdf",
            "description": "Business Certificate of Incorporation",
            "countryCode": "US",
            "externalReference": "{{$randomUUID}}",
            "content": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoVGVzdGlu[...]"
        }
        ```

    Once the JSON is sent and the entity documents are uploaded, onboarding is completed.

    ---

    After you submit the customer's data and documents, the API returns a status indicating the result of the onboarding request:

    | Status         | Description                                      | Action Required                                                                |
    | -------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
    | `VERIFIED`     | The customer application is approved.            | None. Onboarding is automatically finalised.                                   |
    | `PENDING`      | The customer application is under manual review. | Monitor the status via webhooks.                                               |
    | `EDD_REQUIRED` | BVNK requires further checks.                    | An internal case is raised for manual review. Monitor the status via webhooks. |

    You can monitor the customer's verification status via the following endpoints:

    * API: Retrieve current customer's onboarding status by sending the [`GET /platform/v1/customers/{customerReference}`](/bvnk/api-explorer/endpoints/get-customer-with-external-status) request.
    * Portal: Track progress and statuses directly through the BVNK Portal.
    * Webhooks: Set up webhooks to receive automated status change notifications.
</TabItem>
</Tabs>

</TabItem>
</Tabs> -->

### Customer review

Onboarding completes automatically once all of the conditions are met:

- You uploaded company documents, and they are accepted for processing.
- You uploaded associate identity documents, and they are accepted for processing.
- All assigned agreements accepted.

There is no separate "complete" or "submit" API call. Once all conditions are met, BVNK triggers verification for all associates and the company entity. The customer transitions through processing states, and you receive the final outcome via webhook.

### Onboarding statuses

#### Customer status flow

<!-- #### Associate validation status

| Status | Description |
| --- | --- |
| `INVALID` | Outstanding requirements exist. Check `requiredDocuments` and `validationErrors`. |
| `VALID` | All requirements submitted. Verification in progress or complete. | -->

#### Agreement status

| Status | Description |
| --- | --- |
| `PENDING` | Agreement assigned to the customer and awaiting a response. |
| `ACCEPTED` | Customer accepted the agreement. |
| `REJECTED` | Customer rejected the agreement. |

#### Customer verification status

| Status | Description |
| --- | --- |
| `VERIFIED` | Customer verified and approved. Wallets and products can be provisioned. |
| `REJECTED` | Verification failed. The EPC cannot proceed. |
| `SUSPENDED` | Account suspended (post-onboarding). |

## Document rejection and resubmission

When a document is rejected, the status response includes rejection details:

```json
{
  "docSetType": "SELFIE",
  "types": ["SELFIE"],
  "status": "REJECTED",
  "rejectLabels": ["BAD_SELFIE"],
  "clientComment": "A new liveness check has been requested."
}
```

Handle rejections programmatically. Parse `rejectLabels` to determine whether to resubmit or surface a failure to your user. To resubmit, upload the corrected document to the same endpoint. The rejected document is replaced.

## Webhooks

Webhooks must be used as the primary mechanism for tracking status changes. Use polling only as a fallback.

To receive updates on each step of the onboarding process, configure your [webhook endpoint](../../../get-started/create-webhook-listener) in the BVNK Portal. BVNK sends notifications for key lifecycle events.

| Event URN | Trigger |
| --- | --- |
| [`bvnk:customers:status-change`](../../../api-explorer/bvnk-webhooks/customers-status-change/) | Customer's onboarding status changes. |
| [`bvnk:customers:agreements:status-change`](../../../api-explorer/bvnk-webhooks/agreement-status-change/) | Agreement is accepted or rejected by the customer. |
| [`bvnk:customers:associates:status-change`](../../../api-explorer/bvnk-webhooks/associate-status-change/) | Associate's onboarding validation state changes. |
| [`bvnk:customers:associates:documents:status-change`](../../../api-explorer/bvnk-webhooks/associate-documents-status-change/) | Status of one or more associate documents changes. |
| [`bvnk:customers:documents:status-change`](../../../api-explorer/bvnk-webhooks/company-documents-status-change/) | Status of one or more company-level documents changes. |

Use `bvnk:customers:status-change` as the primary driver for your onboarding flow. When you receive a status change, call the status endpoint to retrieve the current requirements.

## Error handling

| Scenario | Response status code | Resolution |
| --- | :---: | --- |
| Missing required field | `400` | Check the error message for the specific missing field. |
| Invalid industry / volume value | `400` | Use accepted enum values from the API definitions. |
| No associates provided | `400` | Include at least one associate with a valid title. |
| Associate missing required role | `400` | At least one associate must hold `BUSINESS_OWNER` or `DIRECTOR` title. |
| Documents not yet synced | `400: DOCUMENTS_NOT_READY` | Wait for all documents to reach `PENDING` status. |

---

## Create a customer

:::info Customers API v2
The [new customer onboarding flow](../create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

The following guide describes how you can create **company** or **individual** customer accounts on the BVNK platform.

**Partner** is a business that BVNK onboards that via a technical integration will embed some elements of our product into their platform.

**Customer** is both the partner's customer (business or individuals) and BVNK's customer. BVNK provides payment services to the customers.

Once a customer is created, we initiate verification. You can then retrieve the customer object or listen to webhooks to track the status change.

<!-- <Epc_state_diagram />

<Idempotency /> -->

## Prerequisites

* Collect and validate customer data (IDs, address proofs, and so on) before creating the customer. This is crucial for a smooth KYC/KYB flow.
* Remember to obtain the verified `reference` from the [signed agreement session](../signing-customer-agreements) and include it in the request payload as the `signedAgreementSessionReference` field. This ensures the agreements are correctly linked and recognized in your new customer creation and onboarding.
* Learn about required compliance documents for [company](../../compliance-requirements/embedded-compliance-requirements-businesses) and [individual customers](../../compliance-requirements/compliance-requirements-for-individuals2) and add them for your customer.

## Add a customer

This step allows the creation of a new customer on the BVNK platform to whom wallets can be assigned. For example, if your company is a financial institution that services businesses, you would first need to add the customer under the **My customer** section of the BVNK platform. This will facilitate your customer's execution of payments via BVNK through your platform.

To add a customer:

<Tabs queryString="type">
  <TabItem value="Via API" label="Via API" default>

    Select a type of customer you want to create:

    <Tabs>
      <TabItem value="Company">
        Use this endpoint to create a business or company customer. You can associate multiple beneficial owners, controlling persons, and signers (often referred to collectively as "associates").

        To create a customer type: Company, send the `POST /platform/v1/customers` request. For the detailed request body parameters, see the [Create customer](../../../api-explorer/endpoints/create-customer) endpoint.

        Upon a successful response, you receive a unique customer reference for tracking the verification status.

        <Tabs>
          <TabItem value="Success" label="Success">

            ```json Success
            {
              "reference": "b0ef182b-202d-4365-b69d-98dcb225fd62",
              "status": "INFO_REQUIRED",
              "infoRequired": {
                  "questionnaireCodes": ["financialServicesQuestionnaireFull"]
              }
            }
            ```

          </TabItem>
          <TabItem value="Failure" label="Failure">

            ```json Failure
            {
              "code": "ACCOUNTS-2000",
              "status": "BAD_REQUEST",
              "message": "Invalid request",
              "details": {
                "errors": {
                  "industryReference": [
                    "Industry with reference: 56e65ebc-06fa-11ef-bbf8-02d3d923cf2b does not exist"
                  ]
                }
              }
            }
            ```
          </TabItem>
        </Tabs>

        | Attribute | Type   | Description  |
        | --------- | ------ | -------------|
        | `reference` | string | A unique identifier for the customer. |
        | `status`    | string | The current status of the customer. Possible values include:• `INFO_REQUIRED` – customer information is needed for verification. Note that in this case, the code for a related questionnaire is sent. For more information, see [Retrieve Compliance Data](../onboard-epc) • `PENDING` – pending customer verification• `VERIFIED` – customer has been verified• `REJECTED` – verification has been unsuccessful. |
      </TabItem>

      <TabItem value="Individual" label="Individual">
        Use the following endpoint to create a customer type: "Individual".

        Prerequisites:

        * Ensure accurate personal data (name, DOB, nationality, address) is collected to facilitate a smooth KYC process.
        * Collect information about the customer before proceeding with the creation request.
        * Customer Due Diligence (CDD) data is required.

        To create an individual customer, send the `POST /platform/v1/customers` request. For the detailed request body parameters, see the [Create customer](../../../api-explorer/endpoints/create-customer) endpoint.

        In the successful response, you receive a unique customer `reference` for tracking the verification status.

        <Tabs>
          <TabItem value="Success" label="Success">

            ```json Success
            {
              "reference": "b0ef182b-202d-4365-b69d-98dcb225fd62",
              "status": "INFO_REQUIRED",
            }
            ```
          </TabItem>
          <TabItem value="Failure" label="Failure">
            ```json Failure
            {
              "code": "ACCOUNTS-2000",
                "status": "BAD_REQUEST",
                "message": "Invalid request",
                "details": {
                    "errors": {
                        "signedAgreementSessionReference": [
                            "Agreement session with reference: 814d949b-9a6d-49ea-92f5-23ee51b37e24 is already assigned to the customer"
                        ]
                    }
                }
            }
            ```
          </TabItem>
          </Tabs>

      </TabItem>
    </Tabs>

  </TabItem>
  <TabItem value="Portal">

  1. Log in to your account on the BVNK Portal.

    ![](/img/bvnk/get-started/portal-login.png)

    
  2. Go to **My customers** tab.

    ![](/img/bvnk/get-started/my-customers-tab.png)
  3. Click **Add New Customer**.

    ![](/img/bvnk/get-started/add-new-customer.png)

    Fill out the customer information form with the following details:

         * Business Name
         * Business Description
         * Business Industry
         * Country of Incorporation
         * Estimated Monthly Volume
         * Business Risk Score (Low, Medium, High)
         * Use Case

  4. Verify the entered information for accuracy.\
    Click **Continue** > **Confirm** to register the customer or **Cancel** to make changes.

    ![](/img/bvnk/get-started/customer-confirmation.png)

  ### Acquire agreement consent

  After submission, the customer status will change to "Agreements Pending". This means your customer must sign BVNK's Terms of Service.

  In the customer-side panel view, copy and share the agreements link with your customer.

  ![](/img/bvnk/get-started/agreements-link.png)

  To proceed, the customer must consent to BVNK's Terms of Service.

  ![](/img/bvnk/get-started/terms-consent.png)

  ### Verify submitted customer data

  Once consent is provided, the agreement status will automatically update to SIGNED, enabling the next step: customer verification.

  ![](/img/bvnk/get-started/verification-status.png)

  The verification process ensures compliance with BVNK's Due Diligence requirements and is essential for activating Embedded Wallets. The required information and documents for the Know Your Business (KYB) process are provided via a hosted experience accessible via the verification link.

  To start customer verification, in the customer-side panel view, copy the verification link to access BVNK's KYB/KYC process and share it with your customer.

  ![](/img/bvnk/get-started/verification-link.png)

  If additional data is required, the KYB/C verification link allows you, as a partner, to provide the necessary customer documents or information.

  Customer information includes, but is not limited to, the following:

  * Personal or business details: for example, name, email, and address.
  * Unique identifiers such as Social Security Number (SSN), Tax Identification Number (TIN), business registration number, and so on.
  * Supporting documents, such as proof of identity, proof of address, or business registration certificates.

  ### Complete verification

  BVNK performs Know Your Customer (KYC) and Know Your Business (KYB) checks to verify customer identity and legitimacy.

  Once the verification process is complete, the customer's status is updated in the BVNK's system. Approved customers can immediately access payment services and automatically have wallets assigned to them.

  ![](/img/bvnk/get-started/verification-complete.png)

  If the verification fails, customers may be asked to provide additional information or documentation.

  </TabItem>
</Tabs>

## Update customer details

To update the information of a specific customer, send the [`PUT /platform/v1/customers/{customerReference}`](../../../api-explorer/endpoints/update-customer) with the `{customerReference}` specified in the path.

In the request body, you can specify the following fields:

- `contactInfo`: Contact information (email and phone).
- `address`: Address details.
- `dateOfBirth`: Customer's date of birth.

```json
{
  "contactInfo": {
    "emailAddress": "customer@example.com",
    "phoneNumber": "+1234567890"
  },
  "address": {
    "addressLine1": "123 Main Street",
    "addressLine2": "Apartment 456",
    "postalCode": "NW1 4NP",
    "city": "London",
    "countryCode": "GB",
    "country": "Great Britain",
    "stateCode": "AL"
  },
  "dateOfBirth": "1990-01-15"
}
```

## Customer webhooks

To get notified when the status of the customer changes, listen to the following webhooks:

- [Customer's status changes to `INFO_REQUIRED`, `PENDING`, `VERIFIED`, or `REJECTED`](../../../api-explorer/bvnk-webhooks/customer-status-change).
- [Customer information is updated](../../../api-explorer/bvnk-webhooks/customer-update).

---
**What's next?**

* [Add compliance documents to a customer](../add-documents-to-customers)
* [Onboard a customer](../onboard-epc)
* [Retrieve information about a customer](../retrieve-embedded-partner-customer)

---

## Create a customer(Create-embedded-partner-customer)

Embedded Wallets provide partners with seamless payment and fund management capabilities directly within their platform while maintaining their branding.

This product is available to businesses and individual customers based in the US, UK, EEA, and other countries supported by BVNK outside of these regions.

To get started:

1. **Initiate the activation process**.\
   The partner representative must contact their BVNK Account Manager to initiate the activation process.
2. **Complete compliance procedures**.\
   Once compliance reviews are complete, the Embedded Wallets product will be enabled on the BVNK Portal and accessible via API. Following this, you can create customer accounts.
3. **Onboard your first customer**.

## API environments

You can use separate environments for development and live operations:

| Environment    | Location                                 |
| :------------- | :--------------------------------------- |
| **Production** | `https://api.bvnk.com/`         |
| **Sandbox**    | `https://api.sandbox.bvnk.com/` |

Use the sandbox environment to test your integration safely before going live.

---

## Manage customers

Use the following guide to view and track the customers you have created, including their current onboarding and verification status, and to manage their associates, documents, and agreements after onboarding.

:::info Customers API v.2
This is a new customer onboarding flow, which is recommended for all new integrations.

If you already have an existing integration with [Customers API v.1](../create-embedded-partner-customer/creating-an-embedded-customer-company-api.mdx), you can continue using it. BVNK will continue to support this API v.1 going forward.
:::

The endpoints on this page complement the [Create business customers](../create-customers-com/) flow. Use them to discover customers on your account, retrieve supporting data, and maintain an application after it has been submitted.

:::tip
All endpoints on this page operate on `platform/v2` resources and return UUIDs in the `id` field. If you only have a partner-supplied `reference`, use the [customers list](#get-customers-list) endpoint with the `reference` filter to resolve it to a customer `id` before calling the other endpoints.
:::

## Get customers list

To see all customers on your account, send the [`GET platform/v2/customers`](../../../api-explorer/endpoints/search-customers-v-2/) request. The endpoint supports filtering by name, lifecycle status, type, model, and your partner-supplied reference, and returns a paginated list.

In the response, you receive a paginated list of customer summaries. Use the returned `id` to call [`GET platform/v2/customers/{id}`](../../../api-explorer/endpoints/get-customer-v-2/) and retrieve detailed information on a specific customer, or to call any of the other endpoints on this page.

```json Example response
{
  "content": [
    {
      "id": "0a184641-30e2-4414-871f-3db1c683900e",
      "reference": "partner-ref-001",
      "status": "VERIFIED",
      "type": "COMPANY",
      "model": "EMBEDDED_BVNK_MANAGED",
      "name": "Krause Fintech GmbH",
      "createdAt": "2026-04-22T10:57:35.056865Z",
      "authenticatedLink": {
        "link": "https://onboarding.bvnk.com/link/eyJhbGciOi...",
        "expiresAt": "2026-04-22T11:57:35.056865Z"
      }
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20
  },
  "totalElements": 1,
  "totalPages": 1,
  "hasNext": false
}
```

:::tip
Persist the returned `id` alongside your own `reference` in your system. The `id` is the stable identifier used across every v2 endpoint. The `reference` is partner-supplied and useful for idempotent lookups from your side.
:::

## Manage associates

After creation, you can add, list, retrieve, and remove associates: directors, UBOs, signatories, and registered-business owners while the onboarding has not yet reached a terminal state.

:::warning You can only change associates before a customer moves to the `VERIFIED` status.
:::

### Add an associate

To add an associate to an existing customer, send the [`POST platform/v2/customers/{customerId}/associates`](../../../api-explorer/endpoints/create-customer-associate-v-2/) request. Use this endpoint when corporate structure changes during onboarding (for example, a new director joins or you need to register an indirect corporate UBO).

The request body is discriminated by `entity.type`:

- `PERSON` - a natural person such as a UBO, director, signatory, or account representative.
- `BUSINESS_REGISTRATION` - a registered-business owner holding shares in the customer.

<Tabs queryString="associate-type">
<TabItem value="person" label="Person associate">

```json Example request
{
  "types": ["UBO", "DIRECTOR"],
  "entity": {
    "type": "PERSON",
    "firstName": "Freya",
    "lastName": "Krause",
    "email": "freya.krause@krause-fintech.de",
    "phoneNumber": "+4915112345678",
    "dateOfBirth": "1982-03-24",
    "nationality": "DE",
    "birthCountryCode": "DE",
    "taxIdentificationNumber": "21/815/08150",
    "taxResidence": "DE",
    "position": "Geschaeftsfuehrer",
    "isPoliticallyExposedPerson": false,
    "percentageOfOwnership": "100",
    "ownershipType": "DIRECT",
    "controlOptions": {
      "canAppointDirectors": true,
      "hasSignificantControl": true,
      "controlsManagement": true,
      "controlsCorporateBody": true
    },
    "address": {
      "addressLine1": "Heidestrasse 19",
      "city": "Koeln",
      "postalCode": "51247",
      "countryCode": "DE"
    }
  }
}
```

</TabItem>
<TabItem value="business-registration" label="Business-registration associate">

```json Example request
{
  "types": ["UBO"],
  "entity": {
    "type": "BUSINESS_REGISTRATION",
    "entityName": "Krause Holdings Ltd",
    "registrationCountry": "GB",
    "registrationNumber": "12345678",
    "percentageOfOwnership": "75",
    "typeOfOwnership": "INDIRECT"
  }
}
```

</TabItem>
</Tabs>

In the response, you receive the new associate's `id`. Use this `id` to upload identification documents and submit questionnaires for the associate.

```json Example response
{
  "id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240"
}
```

Remember to send an `Idempotency-Key` header to safely retry failed requests without creating duplicate associates.

### List associates

To list every associate attached to a customer, send the [`GET platform/v2/customers/{customerId}/associates`](../../../api-explorer/endpoints/list-customer-associates-v-2/) request.

Use the returned list to reconcile the associates you created locally with what BVNK currently tracks for the customer and to fetch each associate's validation status.

```json Example response
{
  "content": [
    {
      "id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240",
      "types": ["UBO", "DIRECTOR"],
      "displayName": "Freya Krause",
      "validation": {
        "status": "COMPLETE",
        "issues": []
      },
      "createdAt": "2026-04-22T10:57:35.056865Z",
      "updatedAt": "2026-04-22T10:57:35.056865Z"
    },
    {
      "id": "3e8a1b4d-2c7f-4f1a-9d3e-5b2a1f6c9d20",
      "types": ["UBO"],
      "displayName": "Krause Holdings Ltd",
      "validation": {
        "status": "INCOMPLETE",
        "issues": [
          {
            "field": "entity.registrationNumber",
            "message": "Registration number is required."
          }
        ]
      },
      "createdAt": "2026-04-22T11:02:14.056865Z",
      "updatedAt": "2026-04-22T11:02:14.056865Z"
    }
  ],
  "pageable": {
    "pageNumber": 0,
    "pageSize": 20
  },
  "totalElements": 2,
  "totalPages": 1,
  "hasNext": false
}
```

:::tip
The list response returns only a compact summary for each associate (`displayName`, `validation`). To retrieve the full entity body (including identification documents, address, and control options), call [`GET /platform/v2/customers/{customerId}/associates/{associateId}`](../../../api-explorer/endpoints/get-customer-associate-v-2/).
:::

### Get an associate

To inspect a single associate, including the documents they have uploaded and any validation errors, send the [`GET platform/v2/customers/{customerId}/associates/{associateId}`](../../../api-explorer/endpoints/get-customer-associate-v-2/) request.

```json Example response
{
  "id": "07b099fa-e1ee-4ad4-9cc4-6f2513a5a240",
  "types": ["UBO", "DIRECTOR"],
  "entity": {
    "type": "PERSON",
    "firstName": "Freya",
    "lastName": "Krause",
    "email": "freya.krause@krause-fintech.de",
    "phoneNumber": "+4915112345678",
    "dateOfBirth": "1982-03-24",
    "nationality": "DE",
    "birthCountryCode": "DE",
    "taxIdentificationNumber": "21/815/08150",
    "taxResidence": "DE",
    "position": "Geschaeftsfuehrer",
    "isPoliticallyExposedPerson": false,
    "percentageOfOwnership": "100",
    "ownershipType": "DIRECT",
    "controlOptions": {
      "canAppointDirectors": true,
      "hasSignificantControl": true,
      "controlsManagement": true,
      "controlsCorporateBody": true
    },
    "address": {
      "addressLine1": "Heidestrasse 19",
      "city": "Koeln",
      "postalCode": "51247",
      "countryCode": "DE"
    },
    "identificationDocuments": [
      {
        "type": "PASSPORT",
        "country": "DE",
        "documentNumber": "C01X00T47",
        "issuedDate": "2021-01-15",
        "validUntil": "2031-01-14"
      }
    ],
    "identityVerification": {
      "link": "https://idv.bvnk.com/session/eyJhbGciOi...",
      "status": "COMPLETE"
    }
  },
  "validation": {
    "status": "COMPLETE",
    "issues": []
  },
  "createdAt": "2026-04-22T10:57:35.056865Z",
  "updatedAt": "2026-04-22T11:10:02.056865Z"
}
```

### Delete an associate

To remove an associate from an in-progress onboarding application, send the [`DELETE platform/v2/customers/{customerId}/associates/{associateId}`](../../../api-explorer/endpoints/delete-customer-associate-v-2/) request.

:::warning
This endpoint is only safe to call before the application transitions to a terminal state (for example, `VERIFIED`, `REJECTED`, or `TERMINATED`). Attempting to delete an associate from a finalised application will fail.
:::

A successful deletion returns `204 No Content`. The associate's uploaded documents are invalidated and must be re-uploaded against a new associate if the person needs to be re-added later.

## Manage customer documents

After you upload company documents during onboarding, use the endpoints below to review and download them, for example when reconciling compliance artefacts or responding to an audit.

### List customer documents

To retrieve every company-level document uploaded for a customer, send the [`GET platform/v2/customers/{customerId}/documents`](../../../api-explorer/endpoints/list-customer-documents-v-2/) request. The endpoint returns a paginated list with document metadata (type, filename, status, timestamps).

Use this endpoint to:

- Confirm that every required document is present before relying on the onboarding completion webhook.
- Surface upload history in your own admin UI.
- Identify documents that failed processing (`status: ERROR`) so you can resubmit corrected files via [`POST platform/v2/customers/{customerId}/documents`](../../../api-explorer/endpoints/upload-customer-company-documents-v-2/).

### Get a specific document

To retrieve metadata for a single document, send the [`GET platform/v2/customers/{customerId}/documents/{documentId}`](../../../api-explorer/endpoints/get-customer-document-v-2/) request.

```json Example response
{
  "id": "b8f8a6b5-8f44-4b7c-8d1e-4a6a5a9b4a21",
  "filename": "certificate.pdf",
  "type": "CERTIFICATE_OF_INCORPORATION",
  "checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "status": "COMPLETE",
  "createdAt": "2026-04-22T10:58:35.056865Z",
  "updatedAt": "2026-04-22T10:58:35.056865Z"
}
```

### Download a document

To download the binary content of a document, send the [`GET platform/v2/customers/{customerId}/documents/{documentId}/content`](../../../api-explorer/endpoints/download-customer-document-v-2/) request. The response is an `application/octet-stream` file attachment.

:::tip
Store the `documentId` returned during upload so you can later re-download the exact artefact that BVNK holds on record. This is typically required when satisfying external audits or responding to EDD questionnaires from downstream partners.
:::

## Manage agreements

BVNK provides the agreements your customers must sign and assigns them to each customer automatically during onboarding based on the customer's jurisdiction and account structure (for example, a US or Non-US Partner Platform Agreement). You do not author or upload these agreements yourself: BVNK hosts the canonical text, tracks version changes, and ensures the correct variant is served to each customer.

Use the following endpoints to enumerate, inspect, and retrieve the signed copies of the agreements BVNK has assigned.

### List customer agreements

To list every agreement assigned to a customer, send the [`GET platform/v2/customers/{customerId}/agreements`](../../../api-explorer/endpoints/list-customer-assigned-agreements-v-2/) request. The endpoint returns paginated results (maximum page size: `500`).

All returned agreements must reach `ACCEPTED` status before onboarding can complete. Use this endpoint to confirm which agreements are still `PENDING` and drive your UX to prompt the customer to accept them.

```json Example response item
{
  "id": "06d119bc-64f6-46b2-aea2-3ff94c4c616f",
  "agreement": {
    "version": "1.0",
    "title": "Partner Platform Agreement (Non-US)",
    "locale": "en-GB"
  },
  "status": "PENDING",
  "createdAt": "2026-03-25T10:57:38.145505Z",
  "updatedAt": "2026-03-25T10:57:38.145505Z"
}
```

To accept agreements, use the [`POST platform/v2/customers/{customerId}/agreements/{assignedAgreementId}/actions`](../../../api-explorer/endpoints/respond-customer-assigned-agreement-v-2/) or [bulk](../../../api-explorer/endpoints/bulk-respond-customer-assigned-agreements-v-2/) endpoints described in the [Create business customers](../create-customers-com/) guide.

### Download an agreement

To get a short-TTL presigned URL for the agreement PDF, send the [`GET platform/v2/customers/{customerId}/agreements/{assignedAgreementId}/content`](../../../api-explorer/endpoints/get-customer-agreement-content-v-2/) request.

In the response, you receive a download URL that expires at the `expiresAt` timestamp, along with the original filename.

```json Example response
{
  "downloadUrl": "https://files.bvnk.com/agreements/c83a528b-8c7a-4d95-9fbb-3fbe14332f7b.pdf?token=...",
  "expiresAt": "2026-04-22T11:05:35.056865Z",
  "filename": "partner-platform-agreement.pdf"
}
```

:::warning
Download links expire one minute after they are issued. Always generate a new link when you need to share the agreement with a customer instead of caching and reusing one from your database.
:::

Use this endpoint to surface the exact agreement text to the customer before they accept it, or to archive a copy of the signed terms in your own document store.

---

## Gather compliance data for onboarding

:::info Customers API v2
The [new customer onboarding flow](../create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

:::info Only required for the business customers onboarding

:::

To complete the onboarding of new customers, you must provide their details for the KYC/KYB checks. To collect the information, Questionnaires with industry-related questions are used.

The system determines which questionnaire each customer needs to complete. The necessary questionnaires are listed in the `infoRequired.questionnaires` field of the `GET /platform/v1/customers/{reference}` endpoint.

The high-level flow of the process is the following:

1. Partner fetches questionnaire schema.
2. Partner gathers and submits the customer's answers for verification.
3. BVNK validates whether all answers are provided:
   1. If YES: Customer transitions to the next onboarding state.
   2. If NO: BVNK specifies missing fields. Partner is requested to provide missing answers until all required details are submitted.

## Retrieve questionnaires

To retrieve all existing questionnaires, including sections, field types, and required inputs, send the [`GET /platform/v1/customers/questionnaire/definitions`](../../../api-explorer/endpoints/get-questionnaire-definitions) request.

To retrieve specific questionnaires, send the [`GET /platform/v1/customers/questionnaire/definitions`](../../../api-explorer/endpoints/get-questionnaire-definitions) request with industry `codes` specified in the path.

You can use the following industry-related `codes` to acquire a required questionnaire:

* Financial Services: `financialServicesQuestionnaireFull`
* Digital assets/crypto: `amlCryptoComplianceQuestionnaireFull`
* Gaming: `gamblingQuestionnaireFull`
* Fintech: `fintechsQuestionnaireFull`
* Other (unspecified): `otherQuestionnaireFull`

:::info
If you don't specify `codes`, all available questionnaires will be loaded.
:::

The response includes the required questions and types of answers that are expected to be provided. You can integrate the acquired questionnaire into your app or website front end.

<details>
<summary>Example response</summary>

```json
  [
    {
        "code": "amlCryptoComplianceQuestionnaireFull",
        "title": "Digital Assets (Crypto) Questionnaire",
        "description": "This questionnaire assesses AML/CFT and crypto compliance practices.",
        "sections": [
            {
                "code": "nature_of_business_section",
                "title": "Nature of Business",
                "items": [
                    {
                        "code": "products_services_offered",
                        "title": "What products or services does your company offer?",
                        "type": "textArea",
                        "required": true
                    },
                    {
                        "code": "clients_served",
                        "title": "What types of clients do you plan to service through BVNK?",
                        "type": "selectDropdown",
                        "required": true,
                        "options": [
                            {
                                "value": "individuals",
                                "title": "Individuals"
                            },
                            {
                                "value": "corporates",
                                "title": "Corporates"
                            },
                            {
                                "value": "both",
                                "title": "Both"
                            }
                        ]
                    },
                    {
                        "code": "exposure_prohibited_jurisdictions",
                        "title": "Exposure to prohibited jurisdictions?",
                        "type": "selectDropdown",
                        "required": true,
                        "options": [
                            {
                                "value": "yes",
                                "title": "Yes",
                                "score": 10
                            },
                            {
                                "value": "no",
                                "title": "No",
                                "score": 0
                            }
                        ]
                    }
                ]
            },
            {
                "code": "documentRequirementsGeneral",
                "title": "Document requirements",
                "items": [
                    {
                        "code": "certificateOfIncorpo",
                        "title": "Certificate of Incorporation",
                        "type": "fileAttachment"
                    },
                    {
                        "code": "amlPolicy",
                        "title": "AML Policy",
                        "type": "fileAttachment"
                    }
                ]
            },
            {
                "code": "amlCompliance",
                "title": "AML/CFT Compliance",
                "items": [
                    {
                        "code": "travelRule",
                        "title": "Is your company required to comply with the Travel Rule?",
                        "type": "selectDropdown",
                        "required": true,
                        "options": [
                            {
                                "value": "yes",
                                "title": "Yes"
                            },
                            {
                                "value": "no",
                                "title": "No"
                            }
                        ]
                    }
                ]
            }
        ]
    },
    {
        "code": "financialServicesQuestionnaireFull",
        "title": "Financial Services Questionnaire",
        "sections": [
            {
                "code": "nature_of_business_section",
                "title": "Nature of Business",
                "items": [
                    {
                        "code": "products_services_offered",
                        "title": "What products or services does your company offer?",
                        "type": "textArea",
                        "required": true
                    }
                ]
            },
            {
                "code": "clientClassification",
                "title": "Client Classification",
                "items": [
                    {
                        "code": "clientType",
                        "title": "Does your company service retail or professional clients?",
                        "type": "selectDropdown",
                        "required": true,
                        "options": [
                            {
                                "value": "retail",
                                "title": "Retail"
                            },
                            {
                                "value": "professional",
                                "title": "Professional"
                            },
                            {
                                "value": "both",
                                "title": "Both"
                            }
                        ]
                    }
                ]
            }
        ]
    }
  ]
  ```
</details>

## Submit questionnaire responses

After the customer answers all the questions, the questionnaire must be submitted for analysis and verification.

:::warning
Ensure that the customer provides the most comprehensive and complete answers to **all required** questions. Otherwise, the onboarding can be put on hold until BVNK receives the remaining details.
:::

To submit completed questionnaire responses for a specific customer, send the [`PUT /platform/v1/customers/{customerReference}/questionnaires`](../../../api-explorer/endpoints/submit-questionnaire-responses) request with `customerReference` specified in the path.

In the body, specify the following parameters:

```json Example request
[
    {
        "code": "amlCryptoComplianceQuestionnaireFull",
        "sections": [
            {
                "code": "nature_of_business_section",
                "items": [
                    {
                        "code": "products_services_offered",
                        "value": "embedded"
                    }
                ]
            }
        ]
    }
]
```

| Field | Description |
|-------|-------------|
| `code` | Industry-specific code of the questionnaire |
| `sections` | A list of questionnaires, each with its code and item-level answers |
| `sections.code` | Unique code of a section |
| `items.code` | Unique code of a question |
| `items.value` | Customer's answer in the form of string, dropdown value, or file reference ID |

In the successful response, you receive a message that the questionnaire has been submitted.

```json Example response
{
  "status": "success",
  "message": "Questionnaire submitted successfully."
}
```

## Search questionnaire submissions

To search for previously submitted questionnaire responses, send the [`GET /platform/v1/customers/questionnaires`](../../../api-explorer/endpoints/get-questionnaires) request with the following query parameters:

| Field | Description |
|-------|-------------|
| `customerReference` | Customer reference |
| `codes` | Questionnaire identifiers |
| `statuses` | Status filter (INIT, OK, NOK) |

```bash
GET /platform/v1/customers/questionnaires?customerReference=52ec68a9-1ff1-4b7c-a8b5-0630de484e42\&codes=amlCryptoComplianceQuestionnaireFull\&statuses=INIT,OK,NOK
```

In the successful response, you receive the submitted questionnaires for a specified customer based on the added filters

```json Example response
[
    {
        "customerReference": "52ec68a9-1ff1-4b7c-a8b5-0630de484e42",
        "questionnaireCode": "amlCryptoComplianceQuestionnaireFull",
        "status": "OK",
        "submittedDate": "2025-05-14T14:45:00Z",
        "sections": [
            {
                "code": "nature_of_business_section",
                "items": [
                    {
                        "code": "products_services_offered",
                        "value": "embedded"
                    }
                ]
            }
        ]
    }
]
```

---

## Onboard customers via your own KYC flow

:::info Customers API v2
The [new customer onboarding flow](../create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

The **Partner-managed onboarding** model offers a controlled alternative KYC intake path. Eligible partners act as the primary identity verification provider, transmitting pre-verified PII, CDD data, and verification metadata to BVNK via API.

<Tabs>
<TabItem value="Individual onboarding">

    During the standard flow, customers are supposed to provide their documents, which BVNK later sends for verification to a designated entity.

    The new onboarding model changes this approach in the following way:

    * You conduct identity verification on your side in accordance with the agreed standards and provide the required verification outcomes to BVNK. No ID documents, selfies, or proofs of address are uploaded at this stage, but all submitted information is subject to validation.
    * You still have to provide customer data, such as name, date of birth, PEP status, and so on, via API.

    To onboard a customer within the Partner-managed model, do the following:

    1. Prepare and sign agreements with your customer as described in the [guide](/bvnk/get-started/create-embedded-partner-customer/signing-customer-agreements).

    2. Create an **Individual** customer by sending the [`POST /api/platform/v1/customers`](/bvnk/api-explorer/endpoints/create-customer) request with their personal and compliance data.

    ```json Example Request
    {
        "type": "INDIVIDUAL",
        "individual": {
            "description": "Tier 1 customer",
            "firstName": "John",
            "lastName": "Dole",
            "dateOfBirth": "1990-05-12",
            "nationality": "GB", // Required for EU
            "birthCountryCode": "GB", // Required for EU
            "emailAddress": "john.dole@example.com",
            "address": {
                "addressLine1": "123 Main St",
                "city": "New York",
                "postalCode": "10001",
                "stateCode": "NY",
                "countryCode": "US"
            },
            "taxIdentification": { // Required for US residents
                "number": "123-45-6789",
                "taxResidenceCountryCode": "US"
            },
            "cdd": {
                "employmentStatus": "SALARIED",
                "sourceOfFunds": "CRYPTO_TRADING",
                "pepStatus": "NOT_PEP",
                "intendedUseOfAccount": "INVESTMENTS",
                "expectedMonthlyVolume": { // Required for EU
                    "amount": "500.01",
                    "currency": "EUR"
                },
                "estimatedYearlyIncome": "INCOME_0_TO_50K", // Required for US residents
                "employmentIndustrySector": "AGRICULTURE_FORESTRY_FISHING_HUNTING" // Required for US residents
            },
            "reliance": {
                "identityDocumentMetadata": {
                    "type": "PASSPORT",
                    "subType": "FRONT_SIDE",
                    "number": "AB1234567",
                    "issueDate": "2020-12-31",
                    "expiryDate": "2030-12-31",
                    "issuingCountryCode": "GB",
                    "kycTimestamp": "2025-11-20T15:30:45.123Z"
                },
                "biometricLiveness": { // Required for EU
                    "livenessTimestamp": "2025-11-20T15:30:45.123Z"
                },
                "addressVerification": {
                    "type": "DOC"
                },
                "attestation": {
                    "riskScore": "LOW",
                    "eddCompleted": true
                }
            }
        },
        "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1"
    }
    ```

    For the detailed descriptions and examples of each field, see the [endpoint](/bvnk/api-explorer/endpoints/create-customer) in the API Reference and the [Create a customer via API](/bvnk/get-started/create-embedded-partner-customer/creating-an-embedded-customer-company-api) guide.

    Make sure to include the following parameters in the payload to submit metadata for the proofing documents you have already verified, including document ID, type, and timestamps.

    :::warning
    Data requirements differ for EU and US entities. Make sure to provide the correct data for the corresponding region.
    :::

    | Parameter | Description |
    | --------- | ----------- |
    | `identityDocumentMetadata` | Details of the ID document you verified (Type, Number, Expiry, Issuing Country).Not required for US residents when a Social Security number is provided. |
    |`identityDocumentMetadata.expiryDate`|Expiration date of the provided document. Mandatory for all document types, except `ID_CARD` and `OTHER`.|
    | `biometricLiveness` | **Mandatory for EU entities**. Timestamp for biometric or liveness checks performed on your side. |
    | `addressVerification` | The method you used to verify the residential address.Values:* DOC: verified by a document* NON_DOC: verified via a database or registry |
    | `riskScore` | Your internal risk rating for this customer per Personally Identifiable Information (PII).Allowed values:* LOW* MEDIUM* HIGH |
    | `eddCompleted` | Flag to indicate that you have already performed Enhanced Due Diligence (EDD).BVNK doesn't verify customer attestations within this flow, so make sure you have completed the EDD.Allowed values:* True* False |

    In the successful response, you receive the status `200 OK`, which means the customer is created. The customer status is set to `PENDING`, indicating that the required data has already been provided and that BVNK can run internal checks.

    :::warning
        Any attempt to follow the standard onboarding flow by sending the [`POST /platform/v1/customers/{customerReference}/documents`](/bvnk/api-explorer/endpoints/upload-customer-documents) request will be rejected.
    :::

    After you submit the customer's data, the API returns a status indicating the result of the onboarding request:

    | Status         | Description                                      | Action Required                                                                |
    | -------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
    | `VERIFIED`     | The customer application is approved.            | None. Onboarding is automatically finalised.                                   |
    | `PENDING`      | The customer application is under manual review. | Monitor the status via webhooks.                                               |
    | `EDD_REQUIRED` | BVNK requires further checks.                    | An internal case is raised for manual review. Monitor the status via webhooks. |

    You can monitor the customer's verification status via the following endpoints:

    * API: Retrieve current customer's onboarding status by sending the [`GET /platform/v1/customers/{customerReference}`](/bvnk/api-explorer/endpoints/get-customer-with-external-status) request.
    * Portal: Track progress and statuses directly through the BVNK Portal.
    * Webhooks: Set up webhooks to receive automated status change notifications.
</TabItem>
<TabItem value="Business onboarding">

    <!-- :::warning This section is a work in progress.
    Please treat this text with caution—it's here to demonstrate a flow that's currently being developed. Endpoint and field names might change or be removed as things evolve.
    ::: -->

    The **Partner-managed Onboarding** model for Businesses (KYB) uses a hybrid approach to maximize speed while maintaining compliance.

    * Associates (Directors/UBOs): You perform Identity Verification on your side and send verification metadata via API. You do not need to upload any ID or selfie documents.
    * The Entity (Company): You upload the required legal documents, for example, the Certificate of Incorporation, via the documents endpoint.
    * Risk: You attest to the risk scoring and screening results.

    To onboard a business customer within the Partner-managed model, do the following:

    1. Prepare and sign agreements with your customer as described in the [guide](/bvnk/get-started/create-embedded-partner-customer/signing-customer-agreements).

    2. Create a **Business** customer by sending the [`POST /platform/v1/customers`](/bvnk/api-explorer/endpoints/create-customer) request with `"type": "COMPANY"`.

        ```json Example Request
        {
            "type": "COMPANY",
            "company": {
                "name": "Acme Corp Ltd",
                "entityType": "LIMITED_LIABILITY_COMPANY",
                "registrationNumber": "12345678",
                "incorporationDate": "2015-06-20",
                "incorporationCountryCode": "GB",
                "taxResidenceCountryCode": "GB",
                "industryReference": "30ea5818-06d8-11ef-b6e1-027612b7f6b5", // UUID from Industry API
                "taxIdentification": {
                    "number": "12-3456789", // Mandatory for US (EIN)
                    "taxResidenceCountryCode": "US"
                },
                "address": {
                    "addressLine1": "456 Corporate Blvd",
                    "city": "London",
                    "postalCode": "EC1A 1BB",
                    "countryCode": "GB"
                },
                "cdd": {
                    "intendedUseOfAccount": "PAYROLL",
                    "pepStatus": "NOT_PEP",
                    "expectedMonthlyVolume": {
                        "amount": "50000.00",
                        "currency": "EUR"
                    }
                },
                "reliance": {
                    // NOTE: Incorporation, Address, and SoF are handled via /documents in Step 3.
                    "attestation": {
                        "riskScore": "LOW",
                        "eddCompleted": true
                    }
                },
                "associates": [
                    {
                        "titles": ["BUSINESS_OWNER", "DIRECTOR"],
                        "person": {
                            "firstName": "Jane",
                            "lastName": "Doe",
                            "dateOfBirth": "1985-03-15",
                            "nationality": "GB", // Mandatory for EU
                            "birthCountryCode": "GB", // Mandatory for EU
                            "emailAddress": "jane@acme.com",
                            "address": {
                                "addressLine1": "10 Downing St",
                                "city": "London",
                                "postalCode": "SW1A 2AA",
                                "countryCode": "GB"
                            },
                            "reliance": {
                                "identityDocumentMetadata": {
                                    "type": "PASSPORT",
                                    "number": "987654321",
                                    "expiryDate": "2031-01-01", // Optional for type: OTHER, ID_CARD
                                    "issueDate": "2021-01-01", // Optional
                                    "issuingCountryCode": "GB",
                                    "kycTimestamp": "2025-11-20T15:30:45.123Z"
                                },
                                "biometricLiveness": {
                                    "livenessTimestamp": "2025-11-20T15:30:45.123Z" // Mandatory for EU
                                },
                                "addressVerification": {
                                    "type": "DOC"
                                }
                            }
                        }
                    }
                ]
            },
            "signedAgreementSessionReference": "78eedde1-2402-4a59-8bbd-ccecb6d612d1"
        }
        ```

        For the detailed descriptions and examples of each field, see the [endpoint](/bvnk/api-explorer/endpoints/create-customer) in the API Reference.

        Crucial difference from the individual onboarding flow:

        * **Associates:** Do not trigger the document loop. Instead, include `reliance` metadata inside the `associates` block.
        * **Entity:** Include the `attestation` and `cdd` data, but exclude the company file proofs (Incorporation, Address, SoF) from the JSON. You will upload them in Step 3.

        :::warning
        Data requirements differ for EU and US entities. Make sure to provide the correct data for the corresponding region.
        :::

        | **Parameter** | **Description** |
        | ---------  | ----------- |
        |`company.taxIdentification.number`| Tax identification number of the entity:*US: EIN*EU: VAT number. |
        |`company.registrationNumber`| Registration number of the entity:*US: Optional*EU: Mandatory. |
        |`company.address.stateCode`| State code of the entity:*US: Mandatory*EU: Optional. |
        |`associates[].person.reliance.nationality`| Nationality of the associate:*US: Optional*EU: Mandatory ISO code. |
        |**Required to confirm you have screened the entity**.||
        | `company.reliance.riskScore`  | Your internal risk rating for this customer. Allowed values: `LOW`, `MEDIUM`, `HIGH` |
        | `company.reliance.eddCompleted`  | Flag to indicate that you have already performed Enhanced Due Diligence (EDD). Allowed values: `true`, `false` |
        |**Required to bypass Associate ID uploads**.||
        | `associates[].person.reliance.identityDocumentMetadata` | Details of the ID document you verified: `type`, `number`, `expiryDate`, `issuingCountryCode`, `kycTimestamp`. | Optional for US residents if SSN is provided. |
        |`associates[].person.reliance.biometricLiveness`| Timestamp for biometric or liveness checks performed on your side:*US: Optional*EU: Mandatory `livenessTimestamp`. |
        | `associates[].person.reliance.addressVerification` | The method you used to verify the residential address. Values: `DOC`, `NON_DOC` | |

    3. After creating the customer, upload entity documents by sending the [`POST /platform/v1/customers/{customerReference}/documents`](/bvnk/api-explorer/endpoints/upload-customer-documents) request.

        The customer's status changes to `INFO_REQUIRED` until the entity documents are received.

        :::warning
        Do **NOT** upload documents for the Associates (Directors/UBOs). Their verification was handled via metadata in Step 2.
        :::

        | Verification requirement | Document type to upload | Notes |
        | ------------------------ | ----------------------- | ----- |
        | **Certificate of Incorporation** | `COMPANY_DOC` > `INCORPORATION_CERT` | Mandatory for legal entity verification. **US entities only**.   |
        | **Registered Address Proof** | `COMPANY_DOC` > `PROOF_OF_ADDRESS` | Utility bill, Bank Statement, or Tax Document (dated < 3 months). **EU entities only**. |
        | **Source of Funds** | `COMPANY_DOC` > `OTHER` | Bank Statement or Financials showing the entity's funding source. |

        ```json Example Request: Upload the Certificate of Incorporation
        {
            "type": "COMPANY_DOC",
            "subType": "INCORPORATION_CERT",
            "name": "INC_CERT.pdf",
            "description": "Business Certificate of Incorporation",
            "countryCode": "US",
            "externalReference": "{{$randomUUID}}",
            "content": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoVGVzdGlu[...]"
        }
        ```

    Once the JSON is sent and the entity documents are uploaded, onboarding is completed.

    ---

    After you submit the customer's data and documents, the API returns a status indicating the result of the onboarding request:

    | Status         | Description                                      | Action Required                                                                |
    | -------------- | ------------------------------------------------ | ------------------------------------------------------------------------------ |
    | `VERIFIED`     | The customer application is approved.            | None. Onboarding is automatically finalised.                                   |
    | `PENDING`      | The customer application is under manual review. | Monitor the status via webhooks.                                               |
    | `EDD_REQUIRED` | BVNK requires further checks.                    | An internal case is raised for manual review. Monitor the status via webhooks. |

    You can monitor the customer's verification status via the following endpoints:

    * API: Retrieve current customer's onboarding status by sending the [`GET /platform/v1/customers/{customerReference}`](/bvnk/api-explorer/endpoints/get-customer-with-external-status) request.
    * Portal: Track progress and statuses directly through the BVNK Portal.
    * Webhooks: Set up webhooks to receive automated status change notifications.
</TabItem>
</Tabs>

---

## Retrieve customer details

:::info Customers API v2
The [new customer onboarding flow](../create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

With these endpoints, you can retrieve information about a specific customer within the system: key customer data, including their profile, associated wallets, and other relevant details. You can list all customers or acquire details of a specific one.

***

## Retrieve all customers

To get a list of all your customers in the system, send the [`GET platform/v1/customers`](../../../api-explorer/endpoints/get-customer-with-external-status) request.

In the response, you will receive the complete list of customers with the details:

```json Response
{
    "content": [
        {
            "reference": "8a0e1da2-2af3-4b9e-a221-e74db4e01b06",
            "status": "VERIFIED",
            "type": "COMPANY",
            "model": "EMBEDDED",
            "name": "LB Ltd.",
            "description": "Embedded customer"
        },
        {
            "reference": "e38af699-5595-4ec4-a4d3-89b85e4fc906",
            "status": "PENDING",
            "type": "COMPANY",
            "model": "EMBEDDED",
            "name": "The Walt Disney company",
            "description": "Embedded customer two"
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 2,
        "sort": {
            "empty": true,
            "sorted": false,
            "unsorted": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": false,
    "totalPages": 42,
    "totalElements": 83,
    "first": true,
    "size": 2,
    "number": 0,
    "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
    },
    "numberOfElements": 2,
    "empty": false
}
```

***

## Retrieve customer's details

To get the detailed information of a specific customer, send the [`GET /platform/v1/customers/{customerReference}`](../../../api-explorer/endpoints/get-customer-with-external-status) with the `{customerReference}` specified in the path.

In the successful response, you receive detailed information on this customer:

```json Response
{
    "reference": "8a0e1da2-2af3-4b9e-a221-e74db4e01b06",
    "status": "PENDING",
    "type": "COMPANY",
    "company": {
        "name": "LB Ltd.",
        "description": "Embedded customer",
        "taxResidenceCountryCode": "US",
        "registrationNumber": "21-4532998",
        "address": {
            "addressLine1": "101 West Broadway",
            "addressLine2": "Suite 1975",
            "city": "San Diego",
            "postalCode": "92101",
            "countryCode": "US",
            "country": "United States"
        },
        "associates": [
            {
                "person": {
                    "reference": "911685b0-acaa-418d-bd91-ed80b96c62cf",
                    "firstName": "Sean",
                    "lastName": "Bond",
                    "dateOfBirth": "2001-01-31",
                    "address": {
                        "addressLine1": "101 West Broadway",
                        "addressLine2": "Suite 1975",
                        "city": "San Diego",
                        "postalCode": "92101",
                        "countryCode": "US",
                        "country": "United States"
                    }
                },
                "details": {
                    "birthCountryCode": "US",
                    "contactInfo": {
                        "emailAddress": "Sean.Bond@disney.com",
                        "phoneNumber": "+123456789"
                    },
                    "documentNumber": "123456789",
                    "documentInfo": {
                        "number": "123456789",
                        "type": "DRIVERS_LICENSE",
                        "issuingCountryCode": "US"
                    },
                    "taxIdentification": {
                        "number": "914764628",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "title": "CEO",
                "riskScore": "LOW",
                "controls": {
                    "hasOwnership": true,
                    "hasControl": true,
                    "isSigner": false
                },
                "verification": {
                    "url": "https://verify.com/2",
                    "status": "infoRequired"
                }
            },
            {
                "person": {
                    "reference": "c4cfa062-ea5f-49ca-96e0-8495e648520e",
                    "firstName": "Luke",
                    "lastName": "Dickens",
                    "dateOfBirth": "2001-01-31",
                    "address": {
                        "addressLine1": "101 West Broadway",
                        "addressLine2": "Suite 1975",
                        "city": "San Diego",
                        "postalCode": "92101",
                        "countryCode": "US",
                        "country": "United States"
                    }
                },
                "details": {
                    "birthCountryCode": "US",
                    "contactInfo": {
                        "emailAddress": "Luke.Dickens@disney.com",
                        "phoneNumber": "+123456789"
                    },
                    "documentNumber": "123456789",
                    "documentInfo": {
                        "number": "123456789",
                        "type": "DRIVERS_LICENSE",
                        "issuingCountryCode": "US"
                    },
                    "taxIdentification": {
                        "number": "914764628",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "title": "Representative",
                "riskScore": "LOW",
                "controls": {
                    "hasOwnership": false,
                    "hasControl": false,
                    "isSigner": true
                },
                "verification": {
                    "url": "https://verify.com/3",
                    "status": "infoRequired"
                }
            }
        ],
        "verification": {
            "url": "https://verify.com/1",
            "status": "infoRequired"
        }
    },
    "riskScore": "LOW"
}
```

***

## List required information

When receiving the response with the status `INFO_REQUIRED` from [`GET /platform/v1/customers/{customerReference}`](../../../api-explorer/endpoints/get-customer-with-external-status), you can request the complete list of missing [documents required](../add-documents-to-customers) to complete the customer onboarding. For that, send the [`GET /platform/v1/customers/{customerReference}/info-required` ](../../../api-explorer/endpoints/get-customer-info-required) request with the ID of your customer in the path.

The customer can be in the following statuses:

* `INFO_REQUIRED`: Additional documents or information are required to complete the customer onboarding.
* `REJECTED`: The customer application was rejected and the onboarding cannot proceed.
* `VERIFIED`: The customer application is approved and the onboarding is complete.

In this case, a similar corresponding response is shown:

```json
{
    "status": "VERIFIED"
}
```

For the status `INFO_REQUIRED`, you receive the following responses, depending on the customer type:

<Tabs>
  <TabItem value="Individual">
    In the response, you receive the [list of documents](../../compliance-requirements/embedded-compliance-requirements-businesses) to provide.

    ```json Example Response with the List of Required Documents
    {
        "status": "INFO_REQUIRED",
        "infoRequired": {
            "questionnaires": [],
            "documents": [
                {
                    "docSetType": "IDENTITY",
                    "types": [
                        "PASSPORT",
                        "DRIVERS",
                        "ID_CARD",
                        "RESIDENCE_PERMIT"
                    ]
                },
                {
                    "docSetType": "SELFIE",
                    "types": [
                        "SELFIE"
                    ]
                }
            ],
            "data": []
        },
        "verificationFailure": {
            "reasons": [
                {
                    "failureCode": "PROBLEMATIC_APPLICANT_DATA:fullName",
                    "description": "Name mismatch detected"
                }
            ]
        }
    }
    ```
    If the verification status is `INFO_REQUIRED` due to a failure, the `verificationFailure` object is populated with a list of specific reasons. Each reason includes a machine-readable `failureCode` for programmatic handling and a human-readable description explaining the mismatch or error.

    According to the earlier example, you must upload the following documents for your customer:

    * Any `IDENTITY`, for example, a passport or a residence permit.
    * `SELFIE`
  </TabItem>

  <TabItem value="Company">
    In the response, you receive the [list of documents](../../compliance-requirements/embedded-compliance-requirements-businesses) to provide.

    ```json
    {
        "status": "INFO_REQUIRED",
        "infoRequired": {
            "questionnaires": [
                "QuestionnaireFull"
            ]
        }
    }
    ```

    For example, the earlier response shows that you need to provide a questionnaire. To upload it, follow the [Gather Compliance Data for Onboarding](../onboard-epc) guides.

    After you pass the "questionnaire" stage, you could receive another response requiring you to provide the `associates` information.

    ```json
    {
        "status": "INFO_REQUIRED",
        "infoRequired": {
            "associates": [
                {
                    "roles": [
                        "BUSINESS_OWNER",
                        "DIRECTOR",
                        "ACCOUNT_REPRESENTATIVE"
                    ]
                }
            ]
        }
    }
    ```

    After you add the information, you get the following response:

    ```json
    {
      "status": "INFO_REQUIRED",
      "infoRequired": {
          "questionnaires": [
              "additionalCompanyDat"
          ],
          "associates": [
              {
                  "customerPersonReference": "6599f942-dd82-4c1c-a9f1-d5e0e40a4368",
                  "associateName": "Gabriel Syme",
                  "roles": [
                      "BUSINESS_OWNER",
                      "DIRECTOR",
                      "ACCOUNT_REPRESENTATIVE"
                  ],
                  "documents": [
                      {
                          "docSetType": "IDENTITY",
                          "types": [
                              "DRIVERS",
                              "ID_CARD",
                              "RESIDENCE_PERMIT",
                              "PASSPORT"
                          ]
                      },
                      {
                          "docSetType": "SELFIE",
                          "types": [
                              "SELFIE"
                          ]
                      },
                      {
                          "docSetType": "PROOF_OF_RESIDENCE",
                          "types": [
                              "UTILITY_BILL"
                          ]
                      }
                  ],
                  "data": [
                      "dateOfBirth",
                      "details.nationality",
                      "details.contactInfo.emailAddress",
                      "details.taxIdentification.number",
                      "details.taxIdentification.taxResidenceCountry"
                  ]
              }
          ]
      }
    }
    ```

    Here, the systems requests additional `data` and the complete set of documents to be uploaded. To provide it, follow the [Add Documents to customers](../add-documents-to-customers) guides to upload or re-upload the documents. If the documents still can't be accepted after re-upload, you can send the link from `verification.url` to your customers so that they can provide the correct materials.

    ```json
    "verification": {
        "status": "infoRequired",
        "url": "https://VERIFICATION_WEBSITE.com/C6PqOEXyQRFtSrDz"
    }
    ```

    Let's say, you've provided the needed information and documents, but the selfie was of poor quality. In this case, you receive the following response:

    ```json
    {
      "status": "INFO_REQUIRED",
      "infoRequired": {
          "questionnaires": [
              "additionalCompanyDat"
          ],
          "associates": [
              {
                  "customerPersonReference": "6599f942-dd82-4c1c-a9f1-d5e0e40a4368",
                  "associateName": "Gabriel Syme",
                  "roles": [
                      "BUSINESS_OWNER",
                      "DIRECTOR",
                      "ACCOUNT_REPRESENTATIVE"
                  ],
                  "documents": [
                      {
                          "docSetType": "SELFIE",
                          "types": [
                              "SELFIE"
                          ]
                      }
                  ]
              }
          ]
      }
    }
    ```
  </TabItem>
</Tabs>

After all the requirements are satisfied, the response may look like as follows:

```json
{
    "status": "INFO_REQUIRED",
    "infoRequired": {

    }
}
```

## Retrieve customer details by page and size

To get the detailed information of a specific customer, send the [`GET /platform/v1/customers?page={page}&size={size}`](../../../api-explorer/endpoints/get-customer-with-external-status) with the `{page}` and `{size}` specified in the path.

```json Request
curl --location 'https://api.sandbox.bvnk.com/platform/v1/customers?page=0&size=20' \
--header 'Authorization: Hawk id="vbfc61D890wg6LAAVbkR11qP9O6cXeMNmKWgcUNZaOHPiQeebp9cl6h02tWv84R8", ts="1728656129", nonce="nt0eD9", mac="gv77Nu/nVWEQo8sfp/leXrC8xVs6UlOG+AoxZlyltJw="'
```

In the successful response, you will receive the details of the customers:

```json Response
{
    "content": [
        {
            "reference": "61461ad5-0599-4a4a-8e4e-c2575605f5bb",
            "status": "PENDING",
            "type": "COMPANY",
            "name": "UK Ltd Version 2.0",
            "description": "Number 1 customer, be super nice."
        },
        {
            "reference": "60bf3fed-7e76-4cc8-9c1f-e0f19878e0c8",
            "status": "PENDING",
            "type": "COMPANY",
            "name": "UK Ltd Version 2.0",
            "description": "Number 1 customer, be super nice."
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 2,
        "sort": {
            "empty": true,
            "sorted": false,
            "unsorted": true
        },
        "offset": 0,
        "paged": true,
        "unpaged": false
    },
    "last": false,
    "totalPages": 5,
    "totalElements": 9,
    "first": true,
    "size": 2,
    "number": 0,
    "sort": {
        "empty": true,
        "sorted": false,
        "unsorted": true
    },
    "numberOfElements": 2,
    "empty": false
}
```

| Attribute          | Type    | Description                                                              |
| ------------------ | ------- | ------------------------------------------------------------------------ |
| `pageNumber`       | Integer | Current page number (e.g., 0 for the first page).                        |
| `pageSize`         | Integer | Number of records per page (e.g., 2).                                    |
| `sort.empty`       | Boolean | Whether the sort criteria is empty (true means no sorting).              |
| `sort.sorted`      | Boolean | Whether the results are sorted (false means no sorting).                 |
| `sort.unsorted`    | Boolean | Whether the results are unsorted (true means not sorted).                |
| `offset`           | Integer | Offset of the first record (e.g., 0, meaning no offset).                 |
| `paged`            | Boolean | Whether the results are paginated (true).                                |
| `unpaged`          | Boolean | Whether the results are not paginated (false).                           |
| `last`             | Boolean | Whether this is the last page of results (false means more pages exist). |
| `totalPages`       | Integer | Total number of pages (e.g., 10 pages).                                  |
| `totalElements`    | Integer | Total number of elements across all pages (e.g., 20 elements).           |
| `first`            | Boolean | Whether this is the first page (true).                                   |
| `size`             | Integer | Number of elements per page (e.g., 2).                                   |
| `number`           | Integer | The current page number (e.g., 0 for the first page).                    |
| `sort.empty`       | Boolean | Whether the sort criteria is empty (true).                               |
| `sort.sorted`      | Boolean | Whether the results are sorted (false).                                  |
| `sort.unsorted`    | Boolean | Whether the results are unsorted (true).                                 |
| `numberOfElements` | Integer | Number of elements in the current page (e.g., 2).                        |
| `empty`            | Boolean | Whether the page is empty (false means there are elements).              |

---

## Prepare customer agreements

:::info Customers API v2
The [new customer onboarding flow](../create-customers-com) is recommended for all new integrations.

If you already have an existing integration with Customers API v1, you can continue using it. BVNK will continue to support this API going forward.
:::

Before [creating customer accounts via API](../creating-an-embedded-customer-company-api), ensure your customers have accepted and signed BVNK's Terms and Conditions.

The agreements can be signed in the following ways:

* Via [HostedURL](#sign-agreements-via-hostedurl)
* Via [API](#sign-agreements-via-api)

## Sign agreements via HostedURL

:::info We recommend preparing the Agreement Page before you set up the signing procedure. The page's URL will later be used as `{redirect URL}`.
:::

To sign an agreement using a **HostedURL with a redirect**:

1. Send a [`POST /customers/agreement/sessions`](../../../api-explorer/endpoints/create-agreement-session) request with the following JSON payload to create a unique Hosted Agreement signing session.

   ```json Example Payload
   {
       "customerType": "INDIVIDUAL",
       "countryCode": "US",
       "useCase": "STABLECOIN_PAYOUTS"
   }
   ```

   The response from BVNK includes the agreement details:

   ```json Example Response
   {
    "reference": "79d697b7-489a-4a01-96a2-f7403e8c5735",
    "status": "PENDING",
    "expiresOn": "2025-12-12T14:15:10Z",
    "agreements": [...]"
   }
   ```

   The `reference` field is the unique customer agreement session identifier.
2. Construct the redirect link to BVNK's Agreement Page by adding `session={reference}` and `redirectUri={redirect URL}` as query parameters to the base URL.

   | Environment | Example of the constructed redirect link |
   | :---------- | :--------------------------------------- |
   | Sandbox     | [`https://signup.sandbox.bvnk.com/agreements?session={reference}&redirectUri=http://example.com/callback`](https://signup.sandbox.bvnk.com/agreements?session={reference}&redirectUri=http://example.com/callback) |
   | Production  | [`https://signup.bvnk.com/agreements?session={reference}&redirectUri=http://example.com/callback`](https://signup.bvnk.com/agreements?session={reference}&redirectUri=http://example.com/callback)                 |
3. Redirect your customer to the constructed BVNK Agreement Page.

### What happens next

* The user reviews the required agreements on the Agreement Page and can choose to **Submit** or **Cancel**.
* When the user clicks **Submit**, the session status updates to `SIGNED`, completing the signature process.
* The user is redirected via `302` to the provided `redirectUri`, with the session status (`SIGNED` or `DECLINED`) included as a query parameter.

Once the agreement status changes to `SIGNED`, send a [`POST /platform/v1/customers`](../../../api-explorer/endpoints/create-customer) request with the included `signedAgreementSessionReference` from the previous step to create the Embedded customer. For the detailed instructions, see [Create a customer via API](../creating-an-embedded-customer-company-api).

## Sign agreements via API

BVNK supports a direct API method for signing agreements, eliminating the need for user redirection.

To create an Agreement Session via API, send a [`POST /customers/agreement/sessions`](../../../api-explorer/endpoints/create-agreement-session) request with the following body parameters:

```json Example body parameters
{
    "countryCode": "DE",
    "customerType": "INDIVIDUAL",
    "useCase": "STABLECOIN_PAYOUTS"
}
```

| Parameter | Description | Required |
| :--- | :--- | :--- |
| `countryCode` | Country code of the customer's address in the ISO 3166-1 alpha-2 format, for example, `"US"`. | :white_check_mark: |
| `customerType` | Type of customer. Available options: - `INDIVIDUAL`: A natural person.- `COMPANY`: A legal entity. | :white_check_mark: |
| `useCase` | Type of product to which the customer agreement applies. Available options:- `STABLECOIN_PAYOUTS`: Enables sending stablecoin payments to customers' crypto wallets from fiat or crypto balances.- `EMBEDDED_STABLECOIN_WALLETS`: Allows partners to create and manage stablecoin wallets for their customers to facilitate crypto transactions.- `EMBEDDED_FIAT_ACCOUNTS`: Enables creating virtual accounts with unique vIBANs for customers to send, hold, and receive fiat funds. | :white_check_mark: |

The response includes the agreement session details.

```json Example Response
{
  "reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d",
  "status": "PENDING",
  "customerType": "INDIVIDUAL",
  "useCase": "STABLECOIN_PAYOUTS",
  "countryCode": "DE",
  "expiresOn": "2025-05-23T15:05:20.859141Z",
  "agreements": [ ... ]
}
```

| Parameter | Description |
| :--- | :--- |
| `reference` | Unique session identifier. |
| `status` | Session status. Available options:- `PENDING`: The session is pending and the agreements have not been signed yet.- `SIGNED`: The agreement has been signed by the customer.- `DECLINED`: The customer has declined the agreement. |
| `customerType` | Type of customer. Available options:- `INDIVIDUAL`: A natural person.- `COMPANY`: A legal entity. |
| `useCase` | Type of product to which the customer agreement applies. Available options:- `STABLECOIN_PAYOUTS`: Enables sending stablecoin payments to customers' crypto wallets from fiat or crypto balances.- `EMBEDDED_STABLECOIN_WALLETS`: Allows partners to create and manage stablecoin wallets for their customers to facilitate crypto transactions.- `EMBEDDED_FIAT_ACCOUNTS`: Enables creating virtual accounts with unique vIBANs for customers to send, hold, and receive fiat funds. |
| `countryCode` |Country code of the customer's address in the ISO 3166-1 alpha-2 format, for example, `"US"`. |
| `expiresOn` | Session expiration (ISO8601 timestamp). |
| `agreements` | List of agreements for review and acceptance. |

Each agreement includes:

* `name`: Agreement identifier.
* `displayName`: Public-facing title.
* `description`: Agreement details.
* `url`: URL for agreement document.
* `status`: Session status of the agreement signing.
* `privacyPolicyName`: Privacy policy title.
* `privacyPolicyDescription`: Privacy policy details.
* `privacyPolicyUrl`: URL to privacy policy.

## Update agreement session status

To update the agreement session status, follow these steps:

1. Send [`PUT /customers/agreement/sessions/{reference}`](../../../api-explorer/endpoints/update-agreement-session) request with the session reference obtained in the previous step.
2. In the request, include the following payload:
   * session status (`SIGNED` or `DECLINED`)
   * IP address

```json Example Request
{
    "status": "SIGNED",
    "ipAddress": "192.172.1.16"
}
```

The session status will update accordingly.

## Verify session status

To retrieve the session status, send the [`GET /customers/agreement/sessions/{reference}`](../../../api-explorer/endpoints/get-agreement-session-status) request with the session reference.

The response confirms the current session status (`SIGNED`, `PENDING`, or `DECLINED`).

```json Example Verified Response
{
  "reference": "5f74fee5-3e8e-4dcc-85cd-24b9205bb44d",
  "status": "SIGNED",
  ...
}
```

## Key considerations

* Store session references securely.
* Clearly inform your customers about the legally binding nature of agreements.
* Monitor and manage session expirations carefully.

:::important
The **Customers** section in Portal and API is not enabled by default when a sandbox account is created. Contact the Solutions team to configure this capability.
:::
---

**What's next?**

- [Create a customer](../creating-an-embedded-customer-company-api)

---

## Update customer details

With these endpoints, you can update information about a specific customer within the system: key customer data, including their profile, associated wallets, and other relevant details. You can update the customer's profile, address, and other relevant details.

***

## Update customer details

To update the detailed information of a specific customer, send the `PUT /platform/v1/customers/{customerReference}` with the `{customerReference}` specified in the path.

In the request body, you can update the following fields:

```json Request
{
    "name": "Updated Company Name",
    "description": "Updated description",
    "address": {
        "addressLine1": "Updated Address Line 1",
        "addressLine2": "Updated Address Line 2",
        "city": "Updated City",
        "postalCode": "Updated Postal Code",
        "countryCode": "US",
        "country": "United States"
    }
}
```

In the successful response, you receive the updated customer information:

```json Response
{
    "reference": "8a0e1da2-2af3-4b9e-a221-e74db4e01b06",
    "status": "PENDING",
    "type": "COMPANY",
    "company": {
        "name": "Updated Company Name",
        "description": "Updated description",
        "taxResidenceCountryCode": "US",
        "registrationNumber": "21-4532998",
        "address": {
            "addressLine1": "Updated Address Line 1",
            "addressLine2": "Updated Address Line 2",
            "city": "Updated City",
            "postalCode": "Updated Postal Code",
            "countryCode": "US",
            "country": "United States"
        },
        "associates": [
            {
                "person": {
                    "reference": "911685b0-acaa-418d-bd91-ed80b96c62cf",
                    "firstName": "Sean",
                    "lastName": "Bond",
                    "dateOfBirth": "2001-01-31",
                    "address": {
                        "addressLine1": "101 West Broadway",
                        "addressLine2": "Suite 1975",
                        "city": "San Diego",
                        "postalCode": "92101",
                        "countryCode": "US",
                        "country": "United States"
                    }
                },
                "details": {
                    "birthCountryCode": "US",
                    "contactInfo": {
                        "emailAddress": "Sean.Bond@disney.com",
                        "phoneNumber": "+123456789"
                    },
                    "documentNumber": "123456789",
                    "documentInfo": {
                        "number": "123456789",
                        "type": "DRIVERS_LICENSE",
                        "issuingCountryCode": "US"
                    },
                    "taxIdentification": {
                        "number": "914764628",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "title": "CEO",
                "riskScore": "LOW",
                "controls": {
                    "hasOwnership": true,
                    "hasControl": true,
                    "isSigner": false
                },
                "verification": {
                    "url": "https://verify.com/2",
                    "status": "infoRequired"
                }
            }
        ],
        "verification": {
            "url": "https://verify.com/1",
            "status": "infoRequired"
        }
    },
    "riskScore": "LOW"
}
```

| Attribute | Type | Description |
| :--- | :--- | :--- |
| name | String | Updated name of the company. |
| description | String | Updated description of the company. |
| address | Object | Updated address of the company. |
| address.addressLine1 | String | Updated primary address line. |
| address.addressLine2 | String | Updated secondary address line. |
| address.city | String | Updated city. |
| address.postalCode | String | Updated postal code. |
| address.countryCode | String | Updated country code. |
| address.country | String | Updated full country name. |

***

## Update customer status

To update the status of a specific customer, send the `PUT /platform/v1/customers/{customerReference}/status` with the `{customerReference}` specified in the path.

In the request body, you can update the status:

```json Request
{
    "status": "VERIFIED"
}
```

In the successful response, you receive the updated customer status:

```json Response
{
    "reference": "8a0e1da2-2af3-4b9e-a221-e74db4e01b06",
    "status": "VERIFIED",
    "type": "COMPANY",
    "company": {
        "name": "Updated Company Name",
        "description": "Updated description",
        "taxResidenceCountryCode": "US",
        "registrationNumber": "21-4532998",
        "address": {
            "addressLine1": "Updated Address Line 1",
            "addressLine2": "Updated Address Line 2",
            "city": "Updated City",
            "postalCode": "Updated Postal Code",
            "countryCode": "US",
            "country": "United States"
        },
        "associates": [
            {
                "person": {
                    "reference": "911685b0-acaa-418d-bd91-ed80b96c62cf",
                    "firstName": "Sean",
                    "lastName": "Bond",
                    "dateOfBirth": "2001-01-31",
                    "address": {
                        "addressLine1": "101 West Broadway",
                        "addressLine2": "Suite 1975",
                        "city": "San Diego",
                        "postalCode": "92101",
                        "countryCode": "US",
                        "country": "United States"
                    }
                },
                "details": {
                    "birthCountryCode": "US",
                    "contactInfo": {
                        "emailAddress": "Sean.Bond@disney.com",
                        "phoneNumber": "+123456789"
                    },
                    "documentNumber": "123456789",
                    "documentInfo": {
                        "number": "123456789",
                        "type": "DRIVERS_LICENSE",
                        "issuingCountryCode": "US"
                    },
                    "taxIdentification": {
                        "number": "914764628",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "title": "CEO",
                "riskScore": "LOW",
                "controls": {
                    "hasOwnership": true,
                    "hasControl": true,
                    "isSigner": false
                },
                "verification": {
                    "url": "https://verify.com/2",
                    "status": "infoRequired"
                }
            }
        ],
        "verification": {
            "url": "https://verify.com/1",
            "status": "infoRequired"
        }
    },
    "riskScore": "LOW"
}
```

| Attribute | Type | Description |
| :--- | :--- | :--- |
| status | String | Updated status of the customer (e.g., "VERIFIED"). Possible statuses could include PENDING, VERIFIED, REJECTED. |

***

## Update customer associates

To update the associates of a specific customer, send the `PUT /platform/v1/customers/{customerReference}/associates` with the `{customerReference}` specified in the path.

In the request body, you can update the associates:

```json Request
{
    "associates": [
        {
            "person": {
                "firstName": "Updated First Name",
                "lastName": "Updated Last Name",
                "dateOfBirth": "2001-01-31",
                "address": {
                    "addressLine1": "Updated Address Line 1",
                    "addressLine2": "Updated Address Line 2",
                    "city": "Updated City",
                    "postalCode": "Updated Postal Code",
                    "countryCode": "US",
                    "country": "United States"
                }
            },
            "details": {
                "birthCountryCode": "US",
                "contactInfo": {
                    "emailAddress": "updated.email@example.com",
                    "phoneNumber": "+123456789"
                },
                "documentNumber": "123456789",
                "documentInfo": {
                    "number": "123456789",
                    "type": "DRIVERS_LICENSE",
                    "issuingCountryCode": "US"
                },
                "taxIdentification": {
                    "number": "914764628",
                    "taxResidenceCountryCode": "US"
                }
            },
            "title": "Updated Title",
            "riskScore": "LOW",
            "controls": {
                "hasOwnership": true,
                "hasControl": true,
                "isSigner": false
            }
        }
    ]
}
```

In the successful response, you receive the updated customer associates:

```json Response
{
    "reference": "8a0e1da2-2af3-4b9e-a221-e74db4e01b06",
    "status": "VERIFIED",
    "type": "COMPANY",
    "company": {
        "name": "Updated Company Name",
        "description": "Updated description",
        "taxResidenceCountryCode": "US",
        "registrationNumber": "21-4532998",
        "address": {
            "addressLine1": "Updated Address Line 1",
            "addressLine2": "Updated Address Line 2",
            "city": "Updated City",
            "postalCode": "Updated Postal Code",
            "countryCode": "US",
            "country": "United States"
        },
        "associates": [
            {
                "person": {
                    "reference": "911685b0-acaa-418d-bd91-ed80b96c62cf",
                    "firstName": "Updated First Name",
                    "lastName": "Updated Last Name",
                    "dateOfBirth": "2001-01-31",
                    "address": {
                        "addressLine1": "Updated Address Line 1",
                        "addressLine2": "Updated Address Line 2",
                        "city": "Updated City",
                        "postalCode": "Updated Postal Code",
                        "countryCode": "US",
                        "country": "United States"
                    }
                },
                "details": {
                    "birthCountryCode": "US",
                    "contactInfo": {
                        "emailAddress": "updated.email@example.com",
                        "phoneNumber": "+123456789"
                    },
                    "documentNumber": "123456789",
                    "documentInfo": {
                        "number": "123456789",
                        "type": "DRIVERS_LICENSE",
                        "issuingCountryCode": "US"
                    },
                    "taxIdentification": {
                        "number": "914764628",
                        "taxResidenceCountryCode": "US"
                    }
                },
                "title": "Updated Title",
                "riskScore": "LOW",
                "controls": {
                    "hasOwnership": true,
                    "hasControl": true,
                    "isSigner": false
                },
                "verification": {
                    "url": "https://verify.com/2",
                    "status": "infoRequired"
                }
            }
        ],
        "verification": {
            "url": "https://verify.com/1",
            "status": "infoRequired"
        }
    },
    "riskScore": "LOW"
}
```

| Attribute | Type | Description |
| :--- | :--- | :--- |
| associates | Array | Updated list of associates for the company. |
| associates.person.firstName | String | Updated first name of the associate. |
| associates.person.lastName | String | Updated last name of the associate. |
| associates.person.dateOfBirth | String | Updated date of birth of the associate. |
| associates.person.address | Object | Updated address of the associate. |
| associates.details.contactInfo.emailAddress | String | Updated email address of the associate. |
| associates.details.contactInfo.phoneNumber | String | Updated phone number of the associate. |
| associates.title | String | Updated title of the associate. |
| associates.riskScore | String | Updated risk score of the associate. |
| associates.controls.hasOwnership | Boolean | Updated ownership status of the associate. |
| associates.controls.hasControl | Boolean | Updated control status of the associate. |
| associates.controls.isSigner | Boolean | Updated signer status of the associate. |

---

## Receive transactions report via webhook

## Generate account-level webhook and secret

Create a webhook as described in [Create webhook listener](../../get-started/create-webhook-listener). In the **Events** field, specify `bvnk:ledger:report:ready` to enable the receiving of reports.

![](/img/bvnk/get-started/add-webhook.png)

After creating the webhook, click it in the list to open the details and copy the **Public key** value. You will later need to use it as `secretKey` to verify the webhook and calculate the signature.

![](/img/bvnk/get-started/transaction-history-report.png)

## Generate transactions report

To generate a report, send the [`POST /ledger/v1/reports`](../../api-explorer/endpoints/wallet-transaction-report) request with the following payload:

```json Example Payload
{
    "format": "csv",
    "type": "TRANSACTION",
    "from": "2025-08-01T00:00:00",
    "to": "2025-09-29T23:59:59",
    "deliveryChannel": "EMAIL",
    "walletId": "a:25082029387281:8DBI2gV:1"
}
```

The example above triggers asynchronous transaction report generation for all of your wallets. Once the report is ready, it will be sent via webhook.

Other possible parameters are:

| Parameter | Required | Description |
|-----------|:----------:|-------------|
| `from` | :white_check_mark: | Export range from date in format 'YYYY-MM-dd'. |
| `to` | :white_check_mark: | Export range to date in format 'YYYY-MM-dd'. |
| `deliveryChannel` | :x: | Method of how the report will be received. Available options: "webhook", "email". Default, "email".In this scenario, provide `deliveryChannel=webhook`. |
| `format` | :x: | Format of the generated file report. Available options: "CSV", "JSON". Default, JSON. |
| `walletId` | :x: | Filter the transactions based on `walletId`. If omitted, all transactions will be included in the report. |
| `type` | :white_check_mark: | Type of the sent report. Use `TRANSACTION`for a transactions report. |

## Handle created transaction report

Webhooks for transaction reports are sent as an HTTP POST with `Content-Type: application/json` containing the following payload:

```json Example Webhook Payload
{
  "event": "bvnk:ledger:report:ready",
  "eventId": "01989e35-4435-7a98-978d-780c97566ac0",
  "timestamp": "2025-08-12T12:15:47.7656623082",
  "data": {
    "id": "b13ae8ee-3f1c-45c4-b99c-93d784abbe02",
    "type": "TRANSACTION",
    "status": "READY",
    "url": "https://reports.ws.com/transaction/b13bc8ee-3f1c-45c4-b99c-93d784abbe02_a0479821-71fd-45aa-8aa3-173cvcde4e1c.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA2P6R7NUDFAGFQNAX%2F20250812%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Expires=604800&X-Amz-Signature=bf045216e6dbe2b5e1ab2664affceb0c0371ee0ced"
  }
}
```

Verify that the event name is correct and then download the report. Note that the link to the report will remain active for the next 24 hours. After that, the report won't be accessible.

---

## Reconcile transactions

Reconciliation allows you to verify that your internal transaction records match BVNK's transaction data. By comparing your system's records with BVNK's transaction reports, you can identify discrepancies, ensure accounting accuracy, and maintain compliance with financial reporting requirements.

You can generate reconciliation reports manually on demand or automatically on a schedule. Reports are available in CSV, PDF, or JSON format and can be delivered via email or webhook. Use these reports to:
- Verify transaction amounts and balances.
- Identify missing or duplicate transactions.
- Reconcile fees and currency conversions.
- Prepare accounting records and financial statements.

## Prerequisites

To use the Reconciliation API, you need to have:
- BVNK account in the sandbox or production environment
- [API credentials](../../get-started/generate-api-keys): Hawk Auth ID and Secret Key
<!-- - Required permissions/roles: `ledger:read`, `ledger:write` -->

---

## Retrieve transaction history

Create reconciliation reports manually using the API or the Portal.

<Tabs groupId="report">
  <TabItem value="api" label="API">
    
    To generate transaction and balance reports via API, use the following endpoints:
    
    - [`POST /ledger/v1/reports`](../../api-explorer/endpoints/wallet-transaction-report): Recommended for reconciliation. Generates comprehensive transaction reports for specific wallets or all wallets. Supports CSV, PDF, and JSON formats, as well as webhook or email delivery.
    - [`GET /ledger/v1/transactions`](../../api-explorer/endpoints/wallet-list-transactions): Use for real-time transaction queries. Returns paginated results suitable for API integration, not bulk reconciliation.
    - [`GET /api/wallet/balances`](../../api-explorer/endpoints/wallet-balance-list): Use to retrieve balance snapshots for a specific date. Useful for balance reconciliation.
    - [`GET /api/v1/pay/summary`](../../api-explorer/endpoints/payment-list): Use for crypto payment history only. Limited to crypto transactions.
    - [`GET /api/v2/channel`](../../api-explorer/endpoints/channel-list): Use for channel payment history only. Limited to channel transactions.
    
    See the endpoints' documentation for more information.

  </TabItem>
  <TabItem value="portal" label="Portal">

    1. On the Portal, go to the **Transaction history** section and click **Export Transactions**.
    
        ![](/img/bvnk/recon/transaction-export.png)

    2. In the **Export wallet transactions** form, select **Once-off** to generate a one-time report.

    3. Configure the exported report:
        - **Report type**:
            - **Transactions**: Generates a report including all transactions in your account.

                

            - **Wallet balances**: Generates a report of wallet balances as of the selected date. Useful for checking balance snapshots.

                

        - **Period**:
            - **Last 30 days**: Includes transactions from the past 30 days counting backward from today.
            - **Previous calendar month**: Includes all transactions from the previous complete calendar month.
            - **Previous 3 calendar months**: Includes all transactions from the previous three complete calendar months.
            - **Custom**: Includes all transactions from a specific start and end date for the report period.
            - **Balance date**: Generates a wallet balance report for the selected date only. Applies exclusively to the 'Wallet balances' report type.

    4. Click **Send to email**. The CSV file will be sent to your email inbox.

    Also, you can generate a report for a specific wallet:

    1. Go to the **Wallets** section and click on the wallet you want to generate a report for.
    2. On the **Transaction history** tab, click **Export**.
    3. Configure the exported report:
        - **Report type**: Transactions or Wallet Balance.
        - **Period**: Same as above.
        - **Export format**: 
            - **Transaction CSV**: Exports transaction data in CSV format for import into accounting systems or spreadsheets.
            - **PDF Statement**: Generates a formatted PDF statement suitable for record-keeping or sharing.

        
    4. Click **Send to email**. The CSV file will be sent to your email inbox.

  </TabItem>
</Tabs>

## Schedule a recurring report

Schedule recurring reports for automated email delivery on a regular basis.

:::info
You can create only one recurring export per account.
:::

Scheduled reports are generated for the previous time period:

- **Daily**: Generated for the previous day. For example, a report scheduled for January 2nd contains data from January 1st.
- **Weekly**: Generated for the previous week. For example, a report scheduled for Wednesday contains data from the previous Tuesday to the current Wednesday.
- **Monthly**: Generated for the previous month. For example, a report scheduled for February 1st contains data from January.

:::warning Mind the data lag

Reports have a data lag due to processing time:
- **Production environment**: 1-hour lag. A report generated at 9:00 AM includes transactions up to 8:00 AM.
- **Sandbox environment**: 8-hour lag. A report generated at 9:00 AM includes transactions up to 1:00 AM.
:::

<Tabs groupId="report">
  <TabItem value="api" label="API">

  If you try to create a schedule when one already exists, you receive a `409 Conflict` error. Delete or update the existing export schedule first.

    To schedule a recurring report via API, use the following endpoints:

  - [`POST /ledger/v1/report-schedules`](../../api-explorer/endpoints/create-report-schedule): Schedules a recurring report for a specific wallet. Use the `id` of the report from the response to update or delete the schedule.
  - [`GET /ledger/v1/report-schedules/{scheduleId}`](../../api-explorer/endpoints/list-report-schedules): Retrieves a list of recurring report schedules created by the user.

  </TabItem>
  <TabItem value="portal" label="Portal">
    1. On the Portal, go to the **Transaction history** section and in the **Export wallet transactions** form, click **Recurring export**.

    2. Configure the exported report:
        - Recurrence:
            - **Daily**: a report will be generated daily.
            - **Weekly**: a report will be generated weekly. Here, select the day of the week when the report will be generated.
            - **Monthly**: a report will be generated monthly.
        - Send at:
            - Time: the time of day when the report will be generated.
            - Timezone: your timezone.

        
    3. Click **Create schedule**. The report will be generated and sent to your email on a regular basis.

    To modify an existing schedule, click the schedule in the list, then update its settings. To delete a schedule, click the schedule and select **Delete**.

  </TabItem>
</Tabs>

### Manage scheduled reports

To change an existing schedule, do the following:

<Tabs groupId="report">
  <TabItem value="api" label="API">
    Use the [`PUT /ledger/v1/report-schedules/{scheduleId}`](../../api-explorer/endpoints/update-report-schedule) endpoint to update the schedule parameters of a recurring report.
  </TabItem>
  <TabItem value="portal" label="Portal">
    1. Go to the **Transaction history** > **Export transactions** > **Recurring export**.
    
        
    2. Click the pencil icon next to the schedule and change the settings.
    3. Click **Update schedule**.

        
   
  </TabItem>
</Tabs>

To delete a schedule, do the following:

<Tabs groupId="report">
  <TabItem value="api" label="API">
    Use the [`DELETE /ledger/v1/report-schedules/{scheduleId}`](../../api-explorer/endpoints/delete-report-schedule) endpoint to delete a recurring report for a specific wallet.
  </TabItem>
  <TabItem value="portal" label="Portal">
       1. Go to the **Transaction history** > **Export transactions** > **Recurring export**.

            
    
       2. Click the trash bin icon next to the schedule.
  </TabItem>
</Tabs>

---

## Report data

The downloadable reports are created in the CSV, PDF, or JSON format. 

Use the report data to check that balances, amounts, and fees match between your system and BVNK.

You can import the data into accounting tools for further analysis or open it in any spreadsheet editor.

:::info Download link expiration
Report download links remain active for 24 hours after generation. After that, the report is no longer accessible. Download and save your reports promptly.
:::

In the report, you can find the following data:

| Field | Description |
|-------|-------------|
| `Account Name` | Name of the BVNK account associated with the transaction. |
| `Account Reference` | Unique reference identifier for the account. |
| `Date Created` | Timestamp when the transaction was created. |
| `Currency` | Currency code of the transaction. |
| `Transaction ID` | Unique identifier for the transaction. |
| `Transaction Type` | Type of transaction. Possible values:- `PAYOUT`- `PAYIN`- `FEE`- `internalTransfer`- `paymentOut`- `channelDeposit`- `reversal` |
| `Description` | Human-readable description of the transaction. |
| `Amount` | Transaction amount. |
| `Transaction Hash` | Blockchain transaction hash for crypto transactions. |
| `Transaction UUID` | Universally unique identifier for the transaction. |
| `Payment Type` | Type of payment: incoming (IN) or outgoing (OUT). |
| `Payment Status` | Current status of the payment. Possible values:- `PENDING`- `COMPLETE`- `CANCELLED`- `EXPIRED`- `UNDERPAID` |
| `Merchant Reference` | Reference identifier provided by the merchant. |
| `From Currency Code` | Source currency code for currency conversion transactions. |
| `To Currency Code` | Destination currency code for currency conversion transactions. |
| `Merchant ID` | Unique identifier for your BVNK account. In the Direct model, this matches the Account ID and identifies the account that uses BVNK services directly. |
| `Running Balance` | Cumulative balance after the transaction. |
| `Transaction Context` | Additional context or metadata for the transaction. |
| `Wallet Lsid` | Wallet ledger identifier. |
| `Wallet Id` | Unique identifier for the wallet. |
| `Wallet Description` | Human-readable description of the wallet. |
| `Required Amount` | Amount required for the transaction. |
| `Paid Actual Amount` | Actual amount that was paid. |
| `Paid Amount Currency` | Currency code of the paid amount. |
| `Transaction Amount` | Total transaction amount. |
| `Display Currency` | Currency code used for display purposes. |
| `Exchange Rate` | Exchange rate applied for currency conversion. |
| `Display Actual Amount` | Actual amount displayed in the display currency. |
| `Display Required Amount` | Required amount displayed in the display currency. |
| `Counterparty Details` | Information about the counterparty in the transaction. |
| `Contact Name` | Name of the contact associated with the transaction. |
| `Customer Id` | Unique identifier for the customer. In the Embedded model, this identifies your customers who use BVNK services via your account. |
| `Country Code` | ISO country code associated with the transaction. |

---

## Reconcile your records

After generating a report, compare it with your internal transaction records:

1. **Match transactions**: Use `Transaction ID`, `Transaction UUID`, or `Merchant Reference` to match BVNK transactions with your records.

2. **Verify amounts**: Compare `Amount`, `Transaction Amount`, and `Running Balance` fields with your records.

3. **Check statuses**: Verify that `Payment Status` matches your system's status. Investigate any `PENDING` or `UNDERPAID` transactions.

4. **Reconcile fees**: Compare fee amounts in your records with BVNK's fee calculations.

5. **Handle discrepancies**: If you find mismatches:
   - Verify the date range of your report
   - Check for transactions that may be in different statuses
   - Contact BVNK support if discrepancies persist

<!-- ---
Questions:

- What are possible values for Transaction Type?
- How is merchantID different from customerID?
- Is it correct: | `Transaction Context` | Additional context or metadata for the transaction. |
- How is walletLSID different from walletId?
- What is the required amount? -->

---

**See also**

To learn how to receive reconciliation reports via webhook delivery instead of email, see [Receive transactions report via webhook](../receive-transactions-report-via-webhook).

---

## Overview(Fiat)

This process allows for the ability for the `CUSTOMER ENABLED` wallet to complete payouts to other bank accounts using their virtual account.

It is possible to create both a payout to themselves (first party) or a payout to another bank account (third party).

When creating a Fiat Payout, the following information is necessary:

- **EUR (local payments)**: Bank account number (IBAN format)
- **GBP (local payments)**:
  - Option 1: Bank account number (IBAN format)
  - Option 2: Bank account number (UK account number format) and bank code (sort code)
- **USD (local payments)**: Bank account number (ABA format) and bank code (routing number)
- **SWIFT (international payments)**:
  - Bank account number (any format is accepted)
  - Bank code (BIC format)

Note that if an invalid Bank Account or Bank Code are provided the payment will be rejected with an error message returned.

## Understanding the workflow of fiat payouts

Fiat payouts progress through various statuses as part of the payout workflow.

The following diagram shows the possible transitions between states.

![](/img/bvnk/use-cases/fiat-flow.png)

| Status | Description |
| :----- | :---------- |
| `PENDING_APPROVAL` | Optional. This state is returned if payouts from the wallet require approvals. The payout will remain in this state until all approvals are received. After that, the **PROCESSING** webhook is emitted. Only relevant for **fiat transactions**. |
| `PROCESSING` | Payouts will remain in this state until a final response has been received from our processing partners. |
| `COMPLETED` | Once a payout has been successfully completed from the side of BVNK, the payout will transition to COMPLETED. Note that it is still possible for the funds to be rejected by the beneficiary bank. |
| `FAILED` | If for any reason our processing partners are unable to successfully complete the payout, the payout will transition to FAILED, and funds will remain in the merchant's wallet. |
| `CANCELLED` | Should the payment be cancelled, then the status will be transitioned to the CANCELLED state. This can occur in scenarios such as when a four-eyes approval is rejected or the request of a four-eyes approval times out. Funds will be returned to the merchants wallet. |
| `RETURNED` | Optional. Should the funds be returned after we have received a response from our processing partners, the payout will be marked as returned and the funds will be returned to the merchants wallet. |
| `ON_HOLD` | This status is shown when screening takes longer than anticipated. |

---

## Automate fiat-to-crypto transfers

## Create payment rule

To create a rule that links a fiat virtual account to a crypto blockchain address, send the [`POST /payment/v1/rules`](../../../api-explorer/endpoints/payment-rule-create) request with the following payload.

For the detailed description of the payload, refer to the [Create Payment Rule](../../../api-explorer/endpoints/payment-rule-create) API reference. Note the following important parameters:

* `trigger` specifies the originating event which triggers this automated action. For fiat-to-crypto on-ramping, use `payment:payin:fiat`.
* `customerIdentifier` is the unique identifier of the customer.

:::info Wallet validation
When you create a payment rule to automatically on-ramp funds to a blockchain address, BVNK validates the address format. This ensures that funds converted to crypto settle successfully.
:::

<Tabs>
<TabItem value="Company" label="Company">

```json Example request for Individual
{
    "reference": "REF558628",
    "trigger": "event:payment:payin",
    "walletId": "a:24145329329347:HsdJVhW:1",
    "fees": {
        "customerFee": {
            "amount": 0.5,
            "currency": "USD"
        }
    },
    "beneficiary": {
        "currency": "USDT",
        "entity": {
            "type": "COMPANY",
            "customerIdentifier": "9401203948572394595",
            "legalName": "3Com",
            "relationshipType": "SELF_OWNED",
            "registrationNumber": "ABC21D21FZC",
            "address": {
                "addressLine1": "Champs-Élysées 101",
                "addressLine2": "Apartment 3B",
                "city": "Paris",
                "region": "Île-de-France",
                "postCode": "75008",
                "country": "FR"
            }
        },
        "cryptoAddress": {
            "network": "ETHEREUM",
            "address": "0x12323542636474747",
            "tag": "332455"
        }
    }
}
```
</TabItem>
<TabItem value="Individual" label="Individual">
```json Example request for Company
{
    "reference": "REF7658628",
    "trigger": "event:payment:payin",
    "walletId": "a:25031045518203:IUMTTAY:1",
    "fees": {
        "customerFee": {
            "amount": 1,
            "currency": "USD"
        }
    },
    "paidCurrency": "ETH",
    "beneficiary": {
        "entity": {
            "type": "INDIVIDUAL",
            "customerIdentifier": "9401203948572394595",
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "1990-05-15",
            "relationshipType": "SELF_OWNED",
            "address": {
                "addressLine1": "1600 Amphitheatre Parkway",
                "addressLine2": "Building 43",
                "city": "Mountain View",
                "region": "California",
                "postCode": "94043",
                "country": "US"
            }
        },
        "cryptoAddress": {
            "network": "Ethereum",
            "address": "0xDDCD0Aa2C21d2d02ec0977565D037aBC67F7F151"
        }
    }
}
```
</TabItem>
</Tabs>

Upon successful linking of the fiat virtual account to the blockchain address, the API returns an HTTP `200 OK` status code along with a JSON object confirming the operation.

```json Example Response
{
    "id": "98c0bb03-567f-11f0-b26e-6b1848874a27",
    "reference": "REF558628",
    "trigger": "event:payment:payin",
    "status": "ACTIVE",
    "fees": {
        "customerFee": {
            "amount": 0.5,
            "currency": "USD"
        }
    },
    "originator": {
        "currency": "USD",
        "walletId": "acc:22041242429000:3MPpU:0"
    },
    "beneficiary": {
        "currency": "USDT",
        "entity": {
            "legalName": "3Com",
            "type": "COMPANY",
            "relationshipType": "SELF_OWNED",
            "registrationNumber": "ABC21D21FZC",
            "address": {
                "addressLine1": "Champs-Élysées 101",
                "addressLine2": "Apartment 3B",
                "city": "Paris",
                "region": "Île-de-France",
                "postCode": "75008",
                "country": "FR"
            }
        },
        "cryptoAddresses": {
            "network": "ETHEREUM",
            "addresses": [
                "0x12323542636474747"
            ],
            "tag": "332455"
        }
    },
    "metadata": {},
    "updatedAt": "2025-07-01T13:31:02.52.000000000Z",
    "createdAt": "2025-07-01T13:30:02.52.000000000Z"
}
```

Whenever funds land into your wallet (identified by the `walletId` in the response), the system automatically converts them to the specified crypto and sends them to the specified blockchain address (detailed in `cryptoAddresses.addresses`).

If the operation was not successful, the API returns an HTTP `400 BAD REQUEST` status code along with a JSON error code. See the [Errors](../../../api-explorer/api-overview/errors) reference for details.

```json Example of Failed Request
{
    "code": "bvnk:payment:rules:4002",
    "status": "BAD_REQUEST",
    "message": "Address validation error"
}
```

## Update payment rule

To change a previously created payment rule, send the [`PATCH payment/v1/rules/{id}`](../../../api-explorer/endpoints/payment-rule-update) request with the `id` received in the successful response earlier, here, `98c0bb03-567f-11f0-b26e-6b1848874a27`.

In the request body, specify only properties that you want to update. The omitted fields will remain unchanged, and sending a null for a nullable property will clear it.

<details>
    <summary>Click to expand the list of properties you can update</summary>

  * `beneficiary.cryptoAddress.address`
  * `beneficiary.cryptoAddress.network`
  * `beneficiary.cryptoAddress.tag`
  * `beneficiary.entity.address.addressLine1`
  * `beneficiary.entity.address.addressLine2`
  * `beneficiary.entity.address.city`
  * `beneficiary.entity.address.country`
  * `beneficiary.entity.address.postCode`
  * `beneficiary.entity.address.region`
  * `beneficiary.entity.customerIdentifier`
  * `beneficiary.entity.dateOfBirth (Individual)`
  * `beneficiary.entity.firstName (Individual)`
  * `beneficiary.entity.lastName (Individual)`
  * `beneficiary.entity.legalName (Company)`
  * `beneficiary.entity.registrationNumber (Company)`
  * `beneficiary.entity.relationshipType`
  * `beneficiary.entity.type`
  * `fees.customerFee.amount`
  * `fees.customerFee.currency`
  * `paidCurrency`

</details>

See the example payloads for different use cases:

<Tabs>
  <TabItem value="Update fees" label="Update fees">
    ```json Update Fees
    {
        "fees": {
            "customerFee": {
                "amount": 3.5,
                "currency": "USD"
            }
        }
    }
    ```
    </TabItem>
    <TabItem value="Change company name" label="Change company name">
    ```json
    {
        "beneficiary": {
            "entity": {
                "type": "COMPANY",
                "legalName": "APEX Ltd."
            }
        }
    }
    ```
    </TabItem>
    <TabItem value="Change crypto address" label="Change crypto address">
    ```json
    {
        "beneficiary": {
            "cryptoAddress": {
                "address": "0x742d35cc6634C0532925a3b844Bc9e7595f0bEA5",
                "network": "Ethereum"
            }
        }
    }
    ```
    </TabItem>
  </Tabs>

## Deactivate payment rule

<Tabs>
  <TabItem value="Activate" label="Activate rule">
    To activate a payment rule, send the [`POST /payment/v1/rules/{id}/action`](../../../api-explorer/endpoints/payment-rule-action) request with the `id` received in the successful response earlier, here, `98c0bb03-567f-11f0-b26e-6b1848874a27`.

    ```json Example request to activate a payment rule
    {
        "action": "ACTIVATE"
    }
    ```
  </TabItem>
  <TabItem value="Deactivate" label="Deactivate rule">
    To deactivate a payment rule, send the [`POST /payment/v1/rules/{id}/action`](../../../api-explorer/endpoints/payment-rule-action) request with the `id` received in the successful response earlier, here, `98c0bb03-567f-11f0-b26e-6b1848874a27`.

    ```json Example request to deactivate a payment rule
    {
        "action": "DEACTIVATE"
    }
    ```
  </TabItem>
</Tabs>

Only one rule can be active for the same wallet. You can deactivate a rule and create another one for that wallet. However, if you activate the first wallet again, it won't be applied.

## Payment webhooks

To receive notifications about operations, use the following webhooks:

* [Incoming fiat payment status change](../../../api-explorer/bvnk-webhooks/payment-payin-status-change)
* [Cryptocurrency payment status change](../../../api-explorer/bvnk-webhooks/crypto-status-change)

For more information about webhooks, refer to [Configure webhooks](../../get-started/create-webhook-listener.mdx).

---

## Convert funds (on-ramp)

An _on-ramp_ is the process of automatically converting value from fiat currency into crypto, offering customers greater financial flexibility by providing them direct access to crypto from fiat payments without multiple manual steps. 

Within BVNK, this is enabled through the _payment rules endpoint_, which allows you to define rules on a fiat virtual account. These rules automatically convert fiat funds deposited into the virtual account into crypto then transfers them to a designated blockchain address.

This solution is comparable to the [stablecoin payout flow](../stablecoin-payments-for-platforms/epc-stablecoin-overview.mdx). However, here, instead of the conversion and payout steps being distinct, sequential actions that you trigger, an on-ramp is set up as a one-time rule triggered by a system event (when fiat funds land in your virtual account).

---

## For who is this product intended?

This feature is designed for companies that operate mainly in fiat and want to continually convert funds to crypto and send them to a blockchain address all in one movement. Thus, decreasing effort and complexity of integration.

The product is best suited for:

- Payment Service Providers (PSPs)
- Employer of Record services
- Marketplaces
- Neobanks

---

## What is a standard use case for on-ramp payments?

Imagine a following scenario:

> You represent an Employer of Record service (let's name it Deal, Inc) and you want to offer your employees the ability to pay 50% of their salary into a stablecoin of their choice, which will be sent to their MetaMask wallet. Each time the salary gets paid, you will take 50% of that, convert it, and then send it to a blockchain address. 
>
>To achieve that with just one action, you will create an on-ramp rule for the customer's wallet. This rule will be triggered whenever funds are transferred into that wallet. After that, the funds will be automatically converted to a stablecoin and sent to the specified external blockchain address.

---

## How on-ramp works?

![On-ramp flow](/img/bvnk/use-cases/on-ramp-flow.png)

---

**Ready to start?** Once you have completed all prerequisites above, you can proceed with the integration. The next sections will guide you through:
- [Checklist for integration](../prepare-for-onramp-integration)
- [Automate fiat-to-crypto transfers](../automate-fiat-to-crypto-transfers)

---

## Prepare for integration

<Overview />

---

<SetupAndWallets />

---

<Customer />

---

## Fiat wallet setup

On-ramp conversions require a fiat wallet to receive incoming payments before converting to stablecoins. Request fiat wallet activation from your Account Manager—fiat wallets require verification before use.

Specify the currency (EUR, USD, GBP) and payment method (SEPA, SWIFT, ACH, Faster Payments) based on your customers' geography and preferences. Each wallet receives a virtual account with banking details your customers use for deposits.

After you have created the wallet, find its ID in the Wallet section on the Portal. You will later need it for creating payments.

![WalletId](/img/bvnk/use-cases/walletId.png)

---

## Customer fee wallet (optional)

If you plan to charge markup fees on your customers' transactions, designate a wallet to receive these fees. Customer fees are optional charges separate from transaction amounts and BVNK fees—they let you collect additional revenue from your customers. The fee wallet currency must match the currency of the fees you charge.

See [Charge customer fees](../../../get-started/charge-customer-fees) for implementation details.

---

<TestAndGoLive />

---

**What's next?**

Once you have completed all prerequisites above, you can proceed with [automating on-ramp payments](../automate-fiat-to-crypto-transfers).

---

## Approve and reject payouts

In case you want to integrate an additional layer of security to your payments, you can approve or reject payouts before they go out. For example, your customers may create a payout request, and your Ops team should verify and approve it. With the approval flows enabled, a payout will go to a pending state after the wallet details are provided. Then BVNK will wait for an Approve or a Reject call to proceed or cancel the payout. 

There are several ways of working with approvals:

- **Portal**: You can enable approval flows on the BVNK Portal and set the approval rules and limits.
- **API**: Use it to integrate the approval logic in your own system or interface. To enable payout approval flows for the API flow, contact your Solutions consultant.

<!-- If you don't know the wallet address, you can use our hosted payment page to collect the information; for this, in the create payout request, you will not specify the `payOutDetails` object. -->

<Tabs>
  <TabItem value="api" label="Via API">

  1. Create a payout request as described in the [Create a payout](../pay-out-to-your-users#create-a-payout) section.
  2. Once the payout is created, you will receive the `redirectUrl` in the response. Use it to redirect your customers to the Hosted payment page to collect the destination wallet details.
  
        ```json Response
        {
            "redirectUrl": "https://pay.sandbox.bvnk.com/payout/79e520a8-d4d8-4a3c-983b-dd1d98acbe95"
        }
        ```

        If the approval flows are enabled, once your customer submits the wallet details on the hosted payment page the Payout will go to a processing state. It will then need to be approved by your Operations team.

  3. To **approve** or **reject** the payment send the `POST /api/approval-workflow/v2/action` request using the `UUID` value that you received in the payment response from Step 1 as the `reference` 

        <Tabs>
        <TabItem value="approve" label="Approve">
            ```json
            {
                "action": "APPROVE",
                "reference": [
                    "79e520a8-d4d8-4a3c-983b-dd1d98acbe95"
                ]
            }
            ```
        </TabItem>
        <TabItem value="reject" label="Reject">
            ```json
            {
                "action": "REJECT",
                "reference": [
                    "79e520a8-d4d8-4a3c-983b-dd1d98acbe95"
                    ],
                "rejectionReason": "API reject"
            }
            ```

            If you decline the payout, specify the reason for the rejection using the `rejectionReason` attribute.
        </TabItem>
        </Tabs>
    
  </TabItem>
  <TabItem value="portal" label="Via Portal">
    To approve or reject a payout, do the following:
       1. On the BVNK Portal, go to **Approvals** > **Pending** tab.
       2. Find the required payout and click **Approve** or **Reject**. 
  </TabItem>
</Tabs>

---

## Refund Payments

In the case where a payment exception scenario has taken place, BVNK provides the option to automatically refund the cryptocurrency for merchants who do not want to hold these cryptocurrencies, due to any compliance issues, or for merchants that do not want to internally process any payments that have fallen outside of the agreed upon payment rules.

:::important
Auto Refund does not automatically return the funds to the sender's address.

Instead, it generates a payout and sends a URL via webhook. This URL should be forwarded to the end user, allowing them to provide their address and accept the refund.
:::

## How a refund works

Refunds function as an automatically generated payout request, which needs to be sent to the end user to complete. In this case, the user needs to enter their desired wallet address to which they want the funds sent and confirm the payout.

:::note
Contact your Merchant Support or Integration Manager to have the refund options enabled.
:::

## Refund exception scenarios

As stated on the previous pages, the three payment exception scenarios to consider are:

* Overpayments
* Underpayments
* Late payments

Each scenario handles the refund slightly differently, as explained below.

:::warning
If you use `walletID` in the request that produces the webhook, note that you will also receive this field in the webhook response. In this case, you can ignore merchantID, since merchantId will be discontinued soon.
:::

<Tabs>
<TabItem value="Overpayments">

When an overpayment has occurred, the status of the transaction is updated from `PROCESSING` to `COMPLETE`. This `COMPLETE` status should be seen as a standard successful payment on the merchant's side.

The original payment amount requested in the invoice is credited to the merchant's wallet as usual. Still, the additional amount of overpaid cryptocurrency is deposited into a holding account, ensuring no impact on the merchant's wallet balance.

This **additional** amount is then the total amount that will be returned to the sender as an automatically generated payout.

</TabItem>
<TabItem value="Underpayments">

When an underpayment has occurred, the status of the transaction is updated from `PROCESSING` to `UNDERPAID`. This `UNDERPAID` status should be marked as an unsuccessful payment on the merchant's side.

The entire payment amount is deposited into a holding account, ensuring it is not credited to the merchant's wallet.

The **full** payment amount of the underpayment is then the total amount that will be returned to the sender as an automatically generated payout.

</TabItem>
<TabItem value="Late payments">

In the rare occurrence that a late payment has occurred, the status of the transaction is updated from `PENDING` to `EXPIRED`. This `EXPIRED` status should be marked as an unsuccessful payment on the merchant's side.

The entire payment amount is deposited into a holding account, ensuring it is not credited to the merchant's wallet.

The **full** payment amount for the late payment is then the total amount that will be returned to the sender as an automatically generated payout.

</TabItem>
</Tabs>

## Refund flow

The ideal flow of an automatically generated refund is given as follows:

1. The merchant creates the payment request for an end user.
2. The merchant forwards the payment link returned from BVNK to the end user.
3. The end user completes the payment by sending funds to the given address.
4. The total funds amount is too low, too high, or received late, triggering the appropriate refund.
5. BVNK sends a webhook notification to the merchant, specifying the amount to refund and the URL where it can be claimed.
6. The merchant notifies the end user about the URL.
7. The end user navigates to the URL and enters their wallet address.
8. Once BVNK receives this address, the displayed amount of cryptocurrency is sent through, less the fees.
9. The merchant receives a relevant webhook that updates the success of the refund payout.
10. The process is complete.

## Expired refund

If the end user never entered their wallet address and confirms the refund within the expiry limit,

1. The refund will become `EXPIRED`. The default expiry limit for a refund is set to **three months**.
2. When the limit is reached, the total refund amount will be transferred from the held account to the merchant's MID wallet.
3. A further webhook is sent to the merchant to indicate that the refund has expired and the amounts have been credited to the appropriate wallet.

## Refund webhook

BVNK automatically initiates the refund process, which in effect acts as a payout transaction.

You will receive a `refundInitiated` event webhook. Pay attention to the following webhook fields:

| Webhook field                                         | Description                                                                             |
| :---------------------------------------------------- | :-------------------------------------------------------------------------------------- |
| `event: refundIntiated`                               | Event type indicating that the refund has been initiated.                               |
| `data.uuid: xxxxxx-xxxx-xxxx-xxxx-xxxxxxxx`           | UUID of the refund, different to the linked incoming payment.                           |
| `data.type: OUT`                                      | Type. For a refund, it is always set to `OUT`.                                          |
| `data.subType: merchantRefund`                        | Subtype indicating it is a Merchant refund.                                             |
| `data.status: PENDING`                                | Status of a refund. Possible options: `EXPIRED` or `COMPLETE`.                          |
| `data.redirectUrl: https://pay.bvnk.com/payout?uuid=` | URL to send to the end user, allowing them to enter their address and claim the refund. |

If the refund is not claimed and has expired, a `statusChanged` event webhook is sent to the merchant. The important fields in this webhook are the following:

| Webhook field                                 | Description                                                       |
| :-------------------------------------------- | :---------------------------------------------------------------- |
| `event: statusChanged`                        | Event type indicating that the refund has had its status changed. |
| `data.uuid: xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx` | Matching UUID of the refund.                                      |
| `data.subType: merchantRefund`                | Subtype indicating it is a Merchant refund.                       |
| `data.status: EXPIRED`                        | Final state of the expired payment.                               |

For more details, see the [Refund webhook](../../../api-explorer/bvnk-webhooks/crypto-refund-initiated/) reference.

---

## Collect via Channels

Use channels to add crypto payments to your checkout flow. In this guide, you'll use the BVNK-hosted page—though you can build your own UI using the API responses. Next, we'll outline the channels workflow so you understand how to implement it yourself if you decide not to use the hosted page.

When an end-user tops up with cryptocurrency for the first time, create a channel linked to their user ID in your system so you can display the correct address whenever they request sending funds.
## Create a channel
To create a channel, send the [`POST /api/v2/channel`](../../../api-explorer/endpoints/channel-create) request with the body parameters:

```json Example Payload
{
  "payCurrency": "ETH",
  "displayCurrency": "EUR",
  "walletId": "a:25022613287255:zmHs0pg:1",
  "reference": "customer1topup",
  "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
  "complianceDetails": {
    "requesterIpAddress": "77.71.188.87",
    "partyDetails": [
      {
        "type": "ORIGINATOR",
        "entityType": "INDIVIDUAL",
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1984-06-30",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "DE"
      }
    ]
  }
}
```

The details to be sent in this request are as follows:

| Parameter         | Description                                                                                    |
| :---------------- | :--------------------------------------------------------------------------------------------- |
| `payCurrency`     | Currency code that defines the cryptocurrency of the wallet.                                   |
| `displayCurrency` | Currency code that specifies the currency in which prices are displayed.                       |
| `walletId`        | Unique identifier of the wallet linked to the channel.                                         |
| `reference`       | Unique reference that will be displayed to the end user and serve as the title of the channel. |

After successfully submitting the request, you receive the following response:

```json
{
  "id": 65,
  "dateCreated": 1631619193321,
  "lastUpdated": 1631619193321,
  "walletId": "a:25022613287255:zmHs0pg:1",
  "walletCurrency": "EUR",
  "displayCurrency": "JPY",
  "payCurrency": "ETH",
  "address": "0xb4e8bb9918248007dc9d0dc12ae1142f0d62ef0e",
  "tag": null,
  "reference": "c1b933d5-3354-4f83-a05f-0b53f1be85f2",
  "status": "OPEN",
  "uuid": "9d1f67f2-a647-404b-9b02-247c77be81d0",
  "redirectUrl": "https://pay.sandbox.bvnk.com/channel?uuid=9d1f67f2-a647-404b-9b02-247c77be81d0",
  "uri": "ethereum:0xb4e8bb9918248007dc9d0dc12ae1142f0d62ef0e",
  "alternatives": null
}
```

Key takeaways include the following:

* `address` is the created channel that you can share with the end-user.
* `redirectUrl` is the URL to which you can redirect customers each time they log in to your platform and initiate a top-up request.

:::danger Avoid assigning the same channel to multiple end-users
You won't be able to determine which customer sent the funds. Unlike fiat transfers, blockchain transactions don't include customer references. Thus, providing each user with a unique channel ensures you can correctly match their top-ups to their account.
:::

:::tip

Instead of just showing customers the destination address, redirect them to the `redirectUrl` whenever they want to top up. On that page, they will be able to scan a QR code from their wallet. This will eliminate the chance of mistyped addresses. Customers will also be able to view the exact exchange rate for the transaction.
:::

---
<TravelRuleCompliance />
---

## Channel webhooks

To get notified when the status of the channel changes, listen to the following webhooks:

- [Channel transaction detected](../../../api-explorer/bvnk-webhooks/channel-transaction-detected)
- [Channel transaction confirmed](../../../api-explorer/bvnk-webhooks/channel-transaction-confirmed)
- [Channel transaction on hold](../../../api-explorer/bvnk-webhooks/channel-transaction-on-hold)

---

## Enable payouts for customers

The customer stablecoin payment flow enables Payment Service Providers (PSPs) to offer stablecoin payouts to their customers without requiring direct integration with cryptocurrency infrastructure. 

## For who is this product intended?

This solution is designed for: 

- **Payment Service Providers (PSPs) and Enterprises** that want to offer stablecoin payouts to their customers' end-users while only maintaining a pre-funded fiat balance. Partners can extend their services to include such payments without worrying about stablecoin or crypto complexity.

---

## What is a standard use case?

You represent a PSP (let's name it **PayCore**) and want to offer stablecoin payout services to your customers. BVNK handles the exchange and transfer of fiat to stablecoins and ensures that stablecoins are settled to the intended <Term popup="The entity that receives the transaction." reference="/terms/beneficiary">Beneficiary</Term>.

As the partner, after you have onboarded with BVNK, you will get access to a fiat wallet, to which you can deposit fiat funds. They will be used to facilitate the exchange and transfer of stablecoins to your customers. As the partner, you will need to onboard your customers to BVNK via the BVNK Portal or API. Once you have created your customer's account, and they have been successfully verified, you can start offering stablecoin payouts to your customers.

When your customer, a ride-sharing platform (let's name them **WeRideShare**), wants to offer stablecoin payouts to their drivers, the flow is as follows:

1. WeRideShare will already have an available balance with PayCore to facilitate fiat payouts to WeRideShare drivers.
2. PayCore uses its available liquidity to pre-fund a fiat balance with BVNK to enable stablecoin payouts to WeRideShare. WeRideShare does not need to have an account with BVNK. 
3. When WeRideShare requests a stablecoin payout to their drivers, PayCore initiates a payment request to BVNK via API.
4. BVNK debits funds from PayCore's pre-funded fiat balance and converts the required amount to payout to the WeRideShare driver in USDC.
5. During the payment flow, BVNK credits USDC to WeRideShare's embedded wallet and the USDC is immediately paid out to the external wallet address of the WeRideShare driver.

    The USDC wallet for WeRideShare is created automatically for the first payout and is completely separate from PayCore's wallet. For the following transactions, BVNK checks whether the customer's wallet already exists in the required currency and then re-uses it.

This model allows PayCore to offer stablecoin payouts as a product to WeRideShare, without WeRideShare having to manage stablecoin wallets or conversions directly. PayCore can offer this service using its existing funding infrastructure. It can have several customers and use their same pre-funded balance at BVNK to offer this service to all of them.

---

## Supported payment types

BVNK supports various payment combinations to meet different business needs:

- **Fiat to stablecoins**: Convert fiat currency to stablecoins and send to crypto wallets.
- **Crypto to crypto**: Convert from one stablecoin to another and pay out to wallets.

---

## How it works?

The customer stablecoin payment flow operates through a three-step process:

1. **Fund Conversion**: Funds are pulled from the partner's pre-funded wallet and converted to USDC or other supported stablecoins.
2. **Wallet Credit**: The converted stablecoin amount is credited to the customer's wallet.
3. **External Payout**: The stablecoin is immediately paid out to the external wallet address

This product allows PSPs and Large Enterprises to leverage their existing pre-funded fiat balances to provide stablecoin payment services to their customers. Customers won't need to maintain direct relationships with crypto providers.

![](/img/bvnk/use-cases/send-from-epc-wallet-flow.png)

---

**Ready to start?** Once you have completed all prerequisites above, you can proceed with the integration. The next sections will guide you through:
- [Checklist for integration](../prepare-for-epc-integration)
- [Sending stablecoin payments from your pre-funded wallet](./send-stabelcoin-via-customers-wallet.mdx)

---

## Exception scenarios

The final step is to build in handling for exceptions that may occur in the payment flow. The types of webhooks are covered on the Receive Payment Notifications page, but the following guides provide a more detailed explanation of the scenarios.

As cryptocurrency payments are push payments rather than pull ones, BVNK cannot control when and how much cryptocurrency BVNK will receive to complete the end-user's payment.

Generally, exception scenarios are caused by user error, hidden or unpredictable fee amounts from the sending exchange, or slow blockchain processing speeds.

There are three payment exception scenarios that need to be considered and handled by merchants:

If you want your customers to pay the exact amount.

<DocCardList />

---

## Receive stablecoin payments

Using BVNKs Receive products, you can collect crypto payments from your customers, allowing them to top up accounts or purchase goods and services from you whilst BVNK manages the conversion and settlement to your accounts.

BVNK stablecoin payments are perfect, when:

- You need to collect payments from your customers and you want stablecoins to be an option so that you can unlock additional markets and user segments.
- As a Neobank or PSP serving businesses and individuals you want to allow your customers to send stablecoins to top up their account.

BVNK supports various pay-in combinations to meet different business needs:

- **Crypto converted and received in fiat**: Accept stablecoin payments from customers and receive fiat currency in your account
- **Crypto converted and received in a different crypto**: Accept one type of stablecoin and receive a different crypto currency in your account
- **Crypto paid in the same currency**: Accept stablecoin payments and receive the same stablecoin type in your account

There are two methods to collect payments from your customers:

- [**Payment Links** / **Checkout**](./?payment-collection=payment-links): For every payment, BVNK generates a live quote to be accepted by the customer and a unique blockchain address for the payment to be made to.

    Best for gaming, trading, or e-commerce platforms where the customer needs to send the exact amount of cryptocurrency or stablecoins to purchase an item, given the market rate at that point.
- [**Channels**](./?payment-collection=channels). A channel is a unique, repeated-use blockchain address that can receive crypto or stablecoins at any time. The address never changes. BVNK converts any amount of crypto or stablecoin that the customer sends to that address at the spot rate at that time. Simply assign the channel to your customers, so they won't need to create a new payment link and different address for every top-up.

    Best for traditional banking and neobanks, where the customer can just send crypto at any time and it's going to convert into their account.

See the respective tabs for more details on the workflow.

:::info
Before you start
Make sure you've followed the [Getting Started guide](../../../get-started/get-started-w-bvnk), so that you have your account set up, API keys generated, and a wallet ID ready to be used.
:::

<Tabs queryString="payment-collection">
<TabItem value="payment-links" label="Payment Links">
For this method, you will use the BVNK-hosted payments page, as it is the fastest way to add crypto to your payment flows.

![](/img/bvnk/use-cases/currency_selection.gif)

Payments pass the following statuses throughout the workflow:

| Status     | Immutable? | Description |
|------------|:----------:|-------------|
| `PENDING`    | :x:         | Initial status of your payment. It will not transition out of this state until the payment expires or a transaction linked to this payment is detected on the blockchain. |
| `PROCESSING` | :x:         | Once your customer sends a payment, and BVNK can see the payment on the blockchain, the payment will transition to processing until funds are credited to your wallet. Payments may still expire when in this state if the customer has not sent enough gas or enough blockchain confirmations occur within the given expiry time. |
| `COMPLETE`   | :white_check_mark:        | Full amount has been received and credited to your wallet in the desired currency. |
| `UNDERPAID`  | :white_check_mark:        | Partial amount has been received and are credited to your wallet in the desired currency. However, the customer did not send enough funds to cover the original amount requested. |
| `EXPIRED`    | :white_check_mark:        | The payment expired before the customer sent funds. |

![](/img/bvnk/use-cases/get-payment-links-flow.png)

</TabItem>
<TabItem value="channels" label="Channels">

For this method you generate a dedicated channel address for an end-user and build a UI (using our hosted page) to collect cryptocurrency payments.

![](/img/bvnk/use-cases/2e792ce-EthChannel1.png)

After you've created a channel and your customer proceeds to send funds to it, the transactions pass through the following states:

| Status     | Immutable? | Description |
| :--------- | :---------: | :---------- |
| `DETECTED` | :x:         | A new crypto transaction has been detected at the channel address. In the Merchant's wallet, BVNK creates a Channel Payment transaction with the status of `DETECTED`. Once the on-chain transaction receives the required confirmations on the network, its status updates to `COMPLETE`. |
| `COMPLETE` | :white_check_mark:        | The crypto transaction received the required confirmations on the network. BVNK updates the Channel Payment status from `DETECTED` to `COMPLETE` and adds funds to your wallet in the desired currency. The payment is finalized, and the status will not change thereafter.                       |

![](/img/bvnk/use-cases/channel-workflow.png)

</TabItem>
</Tabs>

---

**Ready to start?** Once you have completed all prerequisites above, you can proceed with the integration. The next sections will guide you through:
- Collect [payments from your customers via Payment Links](../get-payment-overview?payment-collection=payment-links)
- Collect [payments from your customers via a BVNK-hosted page](../get-payment-overview?payment-collection=channels)
- Handling [exception scenarios](../exception-scenarios) for payments
- Integrate [automatic refunds](../auto-refund-payments) for payments

---

## Receive stablecoins via Payment Links

Use this method to add crypto payments to your checkout flow and collect payments from your customers. You have the option to build your own UI using the API response or redirect your user to a pre-built Hosted Payments Page.

> **Example use case**: this flow is useful for platforms that collect payments from their customers. For example, a trading platform wants to implement a deposit feature, allowing its customers to top up their accounts for futures trading. Customers would go to the cashier, select cryptocurrency as the payment method, and enter the amount they want to deposit. Then, they would be redirected to the Hosted Payments Page to select the cryptocurrency they want to use for the deposit. Here BVNK acts as the provider for cryptocurrency payments.
<!--
## How it works -->

BVNK generates a wallet address for your customer to send funds to. BVNK monitors the blockchain to detect incoming transactions to the wallet address. Once funds are received, BVNK converts the stablecoins and settles you in fiat, a different stablecoin or the same stablecoin depending on your preference.

## Collect payments

To accept stablecoin payments from your customers, do the following:

1. Send the [`POST /api/v1/pay/summary`](../../../api-explorer/endpoints/payment-create) request with a similar body. Remember to set the `type` parameter to `IN` to collect payments from your customers:

    ```json Request
    {
        "walletId": "a:25022613287255:zmHs0pg:1",
        // highlight-next-line
        "type": "IN",
        "amount": 10,
        "currency": "USD",
        "expiryMinutes": 30,
        "reference": "test_reference_in_Qa4wy9",
        "returnUrl": "https://your-url-here.com/status",
        "payInDetails": {
            "currency": "USDT"
        },
        "customerId": "ba388054-4512-441e-a9c4-cbe9b0fe0332",
        "complianceDetails": {
            "requesterIpAddress": "77.71.188.87",
            "partyDetails": [
                {
                    "type": "ORIGINATOR",
                    "entityType": "INDIVIDUAL",
                    "firstName": "John",
                    "lastName": "Doe",
                    "dateOfBirth": "1984-06-30",
                    "relationshipType": "THIRD_PARTY",
                    "countryCode": "DE"
                }
            ]
        }
    }
    ```

In the request, specify at least the following parameters:

| Parameter | Required | Description |
|-----------|:----------:|-------------|
| `walletId` | :white_check_mark: | Unique ID of the receiving wallet where you want the funds to settle in your BVNK account. |
| `reference` | :white_check_mark: | Reference relating to the payment that you and your customer will see. You can place any string here. |
| `amount` | :white_check_mark: | Amount required to complete the payment. Minimum deposit: €5. |
| `currency` | :white_check_mark: | Currency code you want to display the price in for the customer on the BVNK hosted page, or in your own UI. |
| `returnUrl` | :x: | URL that takes the customer back to your platform when they click a “back to merchant” button after initiating the pay-in on the BVNK hosted payments page. |
| `redirectUrl` | :x: | URL that redirects customers to the BVNK Hosted Payments Page where they can make the payment. You can create your own payment page using the endpoint's request and response fields. The minimum required set is: `displayCurrency`, `paidCurrency.amount` (to show how much they have to pay), `exchangeRate`, `address` (to which the customer has to pay). |
| `type` | :white_check_mark: | Transaction type. Use `IN` to collect payments from your customers. |
| `expiryMinutes` | :x: | Time limit granted to end-users for completing incoming payments. If the parameter is left blank in your request, BVNK will default it to 2880 minutes (48 hours). |
| `payInDetails.currency` | :x: | Currency for incoming payments.Set the value if you already know the currency your end-user uses for pay-ins, to skip the cryptocurrency selection screen.Leave the value blank to allow your customers to specify the desired currency. |
| `payInDetails.protocol` | :x: | Protocol is strictly required when supplying `payInDetails.currency`. For the complete list of supported protocols for each currency, refer to the [Currencies](../../../references/currencies) document. |

<!-- You can also include custom metadata in your payment request. This metadata will be associated with the transaction and will be included in webhook events related to it.

To add metadata, include a top-level JSON object with the key `metadata`. The value of this key is another JSON object containing your desired key-value pairs.

```json Metadata Example
{
    "metadata": {
        "orderId": "PO-2025-001",
        "internalUserId": "user-456",
        "reason": "Customer withdrawal"
    }
}
``` -->

You can specify the currencies that are available for your customers while making the payment with the `currencyOptions` parameter. This object is not mandatory; however, if provided, it restricts the currencies that can be used for the transaction. If `currencyOptions` is not specified, the customers can deposit funds in any of the 16 available currencies supported by the BVNK platform. For the complete list of supported currencies and protocols, refer to the [Supported Currencies API](https://api.bvnk.com/api/currency/crypto?max=100\&sort=rank\&order=asc\&allowDeposits=true).

The following example limits the list of available currencies to ETH and USDT.

```json
{
    "walletId": "a:25022613287255:zmHs0pg:1",
    "amount": 2.0,
    "currency": "ETH",
    ...
    "currencyOptions": [
    {
      "code": "ETH"
    },
    {
      "code": "USDT"
    }
  ]
}
```

Upon successfully submitting the request, you receive the following response:

<details>
<summary>Response</summary>
    ```json Response
    {
        "uuid": "3332388b-43cd-45a1-ad1b-7df5e5f4dc6e",
        "merchantDisplayName": "Euro Company",
        "walletId": "a:25022613287255:zmHs0pg:1",
        "dateCreated": 1728647621633,
        "expiryDate": 1728649421633,
        "quoteExpiryDate": 1728649422000,
        "acceptanceExpiryDate": 1728647652000,
        "quoteStatus": "ACCEPTED",
        "reference": "test_reference_in_Qa4wy9",
        "type": "IN",
        "subType": "merchantPayIn",
        "status": "PENDING",
        "displayCurrency": {
            "currency": "USD",
            "amount": 10,
            "actual": 0
        },
        "walletCurrency": {
            "currency": "EUR",
            "amount": 9.15,
            "actual": 0
        },
        "paidCurrency": {
            "currency": "USDT",
            "amount": 10.008422,
            "actual": 0
        },
        "feeCurrency": {
            "currency": "EUR",
            "amount": 0.09,
            "actual": 0
        },
        "networkFeeCurrency": null,
        "displayRate": {
            "base": "USDT",
            "counter": "USD",
            "rate": 0.999158508704
        },
        "exchangeRate": {
            "base": "USDT",
            "counter": "EUR",
            "rate": 0.91423
        },
        "address": {
            "address": "0x7b686317f8ed2c2bc3bbd060464f1939359a00e3",
            "tag": null,
            "network": "ETHEREUM",
            "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x7b686317f8ed2c2bc3bbd060464f1939359a00e3&uint256=10008422",
            "alternatives": [
                {
                    "address": "0xab12ec2f0e47c45ac8ff0c3914fb426d5ef9541a",
                    "tag": null,
                    "network": "BINANCE",
                    "uri": "0xab12ec2f0e47c45ac8ff0c3914fb426d5ef9541a",
                    "alternatives": []
                },
                {
                    "address": "0x3f2b71f5cbca1e4cda0948208f67706a1a519c8e",
                    "tag": null,
                    "network": "POLYGON",
                    "uri": "0x3f2b71f5cbca1e4cda0948208f67706a1a519c8e",
                    "alternatives": []
                },
                {
                    "address": "TYbVJodUGrkWJSWSVnHjXHU6g8RC7AvPE6",
                    "tag": null,
                    "network": "TRON",
                    "uri": "TYbVJodUGrkWJSWSVnHjXHU6g8RC7AvPE6",
                    "alternatives": []
                }
            ]
        },
        "returnUrl": "https://your-url-here.com/status",
        "redirectUrl": "https://pay.sandbox.bvnk.com/payin?uuid=3332388b-43cd-45a1-ad1b-7df5e5f4dc6e",
        "transactions": [],
        "refund": null,
        "refunds": [],
        "currencyOptions": [],
        "flow": "DEFAULT",
        "twoStep": false,
        "metadata": {
        "deviceType": "desktop",
        "sessionId": "abcdef123456",
        "userSegment": "premium",
        "campaignId": "promo-spring-2025"
        },
    "customerId": "ba388054-4512-441e-a9c4-cbe9b0fe0332"
    }
    ```
</details>

Here, take note of the `redirectURL` variable, which is used to direct customers to the Hosted Payments Page for digital asset selection.

---

<TravelRuleCompliance />

---
<!--## Get updates when a top-up is triggered

Use top-up webhooks to track incoming payment requests related to on-demand top-ups. These webhooks provide the status of the incoming payment request, from the time when BVNK received the request and the payment was authorized, up to when the funds were added to the balance account. These webhooks also inform you if the payment failed. -->
## Handle errors

If a customer uses an incorrect currency, BVNK can still process the payment. However, you have to show them a disclaimer forcing to use the correct currency, or the payment can be declined, or your funds could be lost.

---

## Late Payments

:::important
This type of payment is specific for Merchant Payment Services / Payment Links only.
:::

Late payments occur when cryptocurrency arrives after a payment has already expired or been marked as `COMPLETE` or `UNDERPAID`. This situation can arise if:

* The blockchain confirmation is delayed.
* The user sends funds late.
* They attempt to top up an already finalized payment.

## Why and when do payments expire?

We don't want to leave payments in the `PENDING` state indefinitely if a user never sends any funds. Therefore, each payment has an expiry window:

* If you specify `expiryMinutes` and the payment is still in a `PENDING` or `PROCESSING` state after that time, it will expire once that many minutes elapse without reaching a `COMPLETE` or `UNDERPAID` status.
* If you don't specify `expiryMinutes`in the payment request, your default expiration period, as configured in your merchant settings, will be used.
* The default expiry time of **60 minutes** will be used for payments, meaning the currencies exchange quote is locked for this period. So if the customer pays later, we won't guarantee that the exchange rate will be the same as the one when the payment was created.
  * That require an FX conversion between the currency that is being paid and the currency of your MID wallet, **and**
  * With no `expiryMinutes` specified, **and**
  * No default expiration setting configured.

>**Example**: the customer wants to pay 300 USDC from their ETH wallet. The current rate is 1 ETH = 1000 USDC, and it's locked for one hour. If the customer pays later, the rate might have changed, so the payment will be settled at the new rate. So the payment might be settled at 1 ETH = 1100 USDC, meaning the customer will receive 263.16 USDC instead of 300 USDC. And vice versa, if the rate is 1 ETH = 900 USDC, the customer will receive 333.33 USDC instead of 300 USDC.

For greater flexibility of **when** customers send their funds and **how much**, use [cryptocurrency top-ups](doc:adding-crypto-top-ups).

## How do I know the payment has expired?

Once a payment expires, you receive a `statusChanged` webhook with the status field showing `EXPIRED`.

## How do I know a payment is a late payment?

You will receive a `transactionLate` webhook, meaning funds have been received for a payment with the status of `expired`, `complete`, or `underpaid`. The `walletCurrency.actual` value is the credited amount in your wallet currency.

> 📘 Payment states
>
> In most cases, the payment's status remains `EXPIRED` status after funds have been received. If an additional payment is received for a `COMPLETE` or `UNDERPAID` payment this is still categorized as 'late' and the payments will remain in those states.

## Late payments exception flows

The summary of the flow for three different outcomes is given below:

| Configuration              | Balance impact | Status                      |
| -------------------------- | -----------------------------| --------------------------- |
| **Settle Merchant Wallet** | Received amount is credited to your MID wallet in your wallet currency. No further action required.For more information on a MID wallet, refer to the merchant setup guide.        | `EXPIRED`                   |
| **Handle Manually**        | Received amount is deposited into the merchant cryptocurrency wallet. This allows you to refund these funds to customers if you choose to do so.You can also convert this cryptocurrency amount into your MID wallet using a spot FX rate on the BVNK portal. | `EXPIRED`                   |
| [**Auto Refund**](../auto-refund-payments)            | Late payment amount is attributed to a new refund payout that will be auto-created for your MID wallet. | `EXPIRED``PENDING` (refund) |

![](/img/bvnk/use-cases/late-payments-flow.png)

:::note
To change your configuration or learn more, contact your Account or Integration Manager.
:::

## Late payments webhooks

To get notified when the status of the transaction changes, listen to the following webhooks:

- The transaction has been fully processed and settled: [Cryptocurrency transaction settled webhook](../../../api-explorer/bvnk-webhooks/crypto-transaction-settled/).
- Transaction is received after the payment has expired or been completed: [Cryptocurrency transaction late webhook](../../../api-explorer/bvnk-webhooks/crypto-transaction-late/).

---

## Overpayments

Overpayments occur when end-users send more cryptocurrency than intended. For example, they intend to send 0.01 ETH but send 0.1 ETH instead. In this case, the payment still transitions to a `COMPLETE` status.

To give greater flexibility to your customers on how much they send [crypto top-ups](doc:adding-crypto-top-ups) is recommended.

## How can I see the actual amount received?

To see the actual received amount, on the `transactionConfirmed` webhook, compare the fields:

* `paidCurrency.actual` indicates the amount you received.
* `paidCurrency.amount` indicates the original expected amount.

## Handle overpayments

To ensure the best customer experience when managing overpayments, it is advisable to adjust the final payment made by the end user to reflect the higher total amount received. This method eliminates the need to return minor excess amounts of cryptocurrency. Instead, the complete sum will be credited to the end user's account. There is the **Settle Merchant Wallet** setting, where the total sent amount is deposited into the MID wallet associated with the transaction.

The sent amount is indicated in the `.actual` field, which can then be referenced to update the end user's total payment amount in your system, in relation to the requested `.amount` field.

In certain circumstances, such as regulatory issues that may arise when receiving more crypto than requested, two alternative options can be used. These are **Handle Manually** and **Auto Refund**.

* **Handle manually**: will retain the excess fraction of the transaction in its original cryptocurrency and deposit it into an equivalent cryptocurrency wallet on your account. The original payment amount is sent to the MID-linked wallet. You can then use the payout functionality to manually return the excess amount to the end user if required.

    >**Example**: the customer must pay 300 USDC and deposits 500 USDC instead. You decide to handle the overpayment manually: settle 300 USDC to their fiat wallet, and keep the 200 USDC in their cryptocurrency wallet.

* [**Auto Refund**](../auto-refund-payments): will send the original payment amount to the MID-linked wallet. Any additional amount will be kept separately. An automatic payout request will be generated, resulting in a unique URL. This URL must be sent to the end user for final confirmation of the address where the excess funds should be sent.

    >**Example**: the customer must pay 300 USDC but deposits 500 USDC instead. You decide to settle 300 USDC to their fiat wallet and refund the rest. Any additional amount is kept separately. The payment refund request is generated and the link is automatically sent to a customer so they can claim the excessive funds. The link remains active for three months. If the customer doesn't claim the funds within this period, the funds are settled into the customer's account.

## Overpayment exception flows

The summary of the flow for three different outcomes is given below:

| Configuration              | Balance impact   | Status                      |
|----------------------------|------------------|-----------------------------|
| **Settle Merchant Wallet** | Full amount of the overpayment is credited to your MID wallet in your wallet currency. For more information on a MID wallet, refer to the merchant setup guide.           | `COMPLETE`                  |
| **Handle Manually**        | The original payment amount is credited to your MID wallet in the currency of your wallet. The excess amount of cryptocurrency received is credited to the cryptocurrency wallet in the currency of the payment.                                   | `COMPLETE`                  |
| [**Auto Refund**](../auto-refund-payments)            | Functions similarly to **Handle Manually**, except it is done automatically for you. The original payment amount is credited to your MID wallet in the currency of your wallet. The excess amount of cryptocurrency received will be attributed to a new refund payout that will be auto created. | `COMPLETE`, `PENDING` (refund) |

![](/img/bvnk/use-cases/overpayment-flow.png)

:::note
To change your configuration or learn more, contact your Account or Integration Manager.
:::

## Settlement webhook

To get notified when the transaction has been fully processed and settled, listen to the [Cryptocurrency transaction settled webhook](../../../api-explorer/bvnk-webhooks/crypto-transaction-settled/).

---

## Create payouts

There are two ways to create a payout:

* You already know the crypto address of the destination of the payout and can specify it on the API call.

    In this flow, we recommend using the [estimate endpoint](../pay-out-to-your-users?fast-crypto-payouts=api-payout&advanced-crypto-payouts=estimate#integrate-advanced-payout-capabilities) to get an estimated quote before creating the payout. This endpoint allows you to retrieve an indicative exchange rate. This is equivalent to the all-in exchange rate that you would receive if your payout had been received and processed at the moment you requested an indicative exchange rate.

* You don't know the crypto address of the destination of the payout, and will redirect the user to the hosted page using the provided redirect URL (much like the payments workflow). For the details, see the payment workflow guide.

This guide assumes you already have the recipient's address.

You can create a payout using the following methods:

- Fast:
  - [API](../pay-out-to-your-users?fast-crypto-payouts=api-payout&advanced-crypto-payouts=two-step-payout#create-a-payout): Send a request to the API and receive a response.
  <!-- - [Portal](../pay-out-to-your-users?fast-crypto-payouts=portal-payout&advanced-crypto-payouts=two-step-payout#create-a-payout). Go to the Portal, add the details, and create the payout. -->
- Advanced:
  - [Estimate and Create Payout](../pay-out-to-your-users?fast-crypto-payouts=api-payout&advanced-crypto-payouts=estimate#integrate-advanced-payout-capabilities). Use this flow to display the details of the payout to your customers before they confirm the payout.
  - [Two-step Payout](../pay-out-to-your-users?fast-crypto-payouts=api-payout&advanced-crypto-payouts=two-step-payout#integrate-advanced-payout-capabilities). Follow this method to make a payout in two steps:

    1. Create a payment with the quote generated.
    2. Have your customer accept the quote before executing the payout.
  - [Direct customer to payments](../pay-out-to-your-users/?advanced-crypto-payouts=direct-customer-to-payments#integrate-advanced-payout-capabilities): Integrate user payouts using BVNK-hosted payment pages or a custom user interface.

## Validate a crypto address

If you are integrated directly with the API, it's recommended to validate the crypto address before making a payout. This ensures all required data is present and improves the customer experience. For example, a `tag` is required for XRP payouts to exchanges to ensure funds are allocated correctly.

Note: If you use the hosted page, the address is validated when the user enters it before processing the payout.

To validate an address, send the [`PUT /api/v1/pay/validate`](../../../api-explorer/endpoints/payment-out-validate) request with the following body parameters:

```json
{
     "code": "crypto",
     "currency": "USDT",
     "address": "TFsmkjujT9omG5TFrEXYbDocTdjeeHgcrQ",
     "network": "TRON"
}
```

If the address is invalid, the payout request will fail and you will receive an error similar to the following:

```json
{
    "errorList": [
        {
            "parameter": "payOutInstruction",
            "code": "invalidPayout",
            "message": "Invalid Instruction for Payout"
        }
    ]
}
```

## Create a payout

To create a payout, send the [`POST /api/v1/pay/summary`](../../../api-explorer/endpoints/payment-create) request with similar body parameters:

```json
{
    "walletId": "a:25022613287255:zmHs0pg:1",
    "type": "OUT",
    "amount": 10,
    "currency": "USD",
    "expiryMinutes": 30,
    "reference": "SQeh6J",
    "returnUrl": "https://your-url-here.com/status",
    "payOutDetails": {
        "code": "crypto",
        "currency": "USDT",
        "network": "ETHEREUM",
        "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
        "tag": ""
    },
    "customerId": "9420b652-c6e9-4bfe-9425-fc069c6bb710",
    "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
            {
                "type": "BENEFICIARY",
                "entityType": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Mirra",
                "dateOfBirth": "1984-06-30",
                "relationshipType": "THIRD_PARTY",
                "countryCode": "DE"
            }
        ]
    }
}
```

Include at least the following parameters in your request:

| **Field** | **Description** |
| :-------- | :-------------- |
| `walletId` | Unique ID of your wallet used for the transaction. |
| `reference` | Your unique reference for the payout. |
| `amount` | Amount to pay in the display currency. For example, the funding wallet currency can be USD, and on the hosted payments page, you choose to display EUR. |
| `currency` | The payout currency that is displayed to your customers. This currency field may differ from the currency of the wallet from which funds will originate. |
| `type` | Set to `OUT` for payouts. |
| `customerId` | Unique identification of the party requesting the payment. If multiple payments for the same party are requested, the ID should remain consistent. |
| `complianceDetails.requesterIpAddress` | IP address of the requester. |
| `complianceDetails.partyDetails` | Compliance details of the party requesting the payment. |

For a complete list of updatable fields, refer to the endpoint description in the API reference.

Examples:

> - **Case 1**. Your wallet is in USD, and you are going to pay 10 USD, which will be converted to USDT at the current exchange rate. If the exchange rate is 1:0.99, the end user will receive 9.99USDT.
> - **Case 2**. If the displayed `currency` is the same as the funding wallet currency, for example, USDT, the <Term popup="The entity that receives the transaction." reference="/terms/beneficiary">Beneficiary</Term> receives the exact amount shown (10 USDT in the example).
    > - **Case 3**. If the displayed `currency` is the same as the `payOutDetails.currency` currency, for example, USDT in both fields, the <Term popup="The entity that receives the transaction." reference="/terms/beneficiary">Beneficiary</Term> receives the exact amount shown (10 USDT in the example). BVNK will debit your wallet with the calculated exchange amount.

In the successful response, the payout is created, and you receive transaction details:

```json Response
{
    "uuid": "b9bf94a8-2e2e-4d29-b8d1-5cdf658e6731",
    "merchantDisplayName": "LHV EUR Wallet",
    "walletId": "a:25022613287255:zmHs0pg:1",
    "dateCreated": 1741985003161,
    "expiryDate": 1741986803161,
    "quoteExpiryDate": 1741986803161,
    "acceptanceExpiryDate": 1741985033850,
    "quoteStatus": "ACCEPTED",
    "reference": "test_reference_out_SQeh6J",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PENDING",
    "displayCurrency": {
        "currency": "USD",
        "amount": 10,
        "actual": 0
    },
    "walletCurrency": {
        "currency": "EUR",
        "amount": 9.21,
        "actual": 9.21
    },
    "paidCurrency": {
        "currency": "USDT",
        "amount": 9.997368,
        "actual": 0
    },
    "feeCurrency": {
        "currency": "EUR",
        "amount": 0.09,
        "actual": 0
    },
    "networkFeeCurrency": {
        "currency": "EUR",
        "amount": 1,
        "actual": 0
    },
    "displayRate": {
        "base": "USDT",
        "counter": "USD",
        "rate": 1.000263269292
    },
    "exchangeRate": {
        "base": "EUR",
        "counter": "USDT",
        "rate": 1.085490537307
    },
    "address": {
        "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
        "tag": "",
        "network": "ETHEREUM",
        "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156&uint256=9997368",
        "alternatives": []
    },
    "returnUrl": "https://your-url-here.com/status",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout/b9bf94a8-2e2e-4d29-b8d1-5cdf658e6731",
    "transactions": [],
    "refund": null,
    "refunds": [],
    "currencyOptions": [],
    "flow": "DEFAULT"
}
```

If there are any errors, the payout won't be created, and you'll have to retry the request with the correct details.

Ensure you set a unique reference for each payout. Otherwise, you will receive an error similar to the following:

```json
{
    "errorList": [
        {
            "parameter": "reference",
            "code": "unique",
            "message": "Duplicate Reference"
        }
    ]
}
```

## Integrate advanced payout capabilities

  <Tabs queryString="advanced-crypto-payouts">
  <TabItem value="estimate" label="Estimate and Create Payout">
    The **Estimate** endpoint allows you to retrieve the latest exchange rates, fees and network costs for a crypto payout **without creating an actual payout request**. This feature enables you to display detailed cost information to your customers before any funds are transferred, thereby enhancing transparency and user trust.

    To generate an estimate, provide details such as the payout currencies, desired amount, and network information. You can choose to specify either:

    * The **amount you want to send** (`walletRequiredAmount`), or
    * The **amount the recipient should receive** (`paidRequiredAmount`).

    The system will calculate the corresponding value for the other.

    1. Create a payout quote by sending the [`POST /api/v1/pay/estimate`](../../../api-explorer/endpoints/pay-estimate) request with a similar payload:

        ```json Example Payload
        {
            "network": "ETHEREUM",
            "complianceDetails": {
            "requesterIpAddress": "172.16.254.1"
            },
            "walletId": "a:24072237783989:Unkx9kW:1",
            "walletCurrency": "USD",
            "paidRequiredAmount": 15,
            "paidCurrency": "USDT",
            "reference": "REF46730"
        }
        ```

        You can specify one of the following:

        * `walletRequiredAmount`: the amount to send in the wallet's currency, **OR**
        * `paidRequiredAmount`: the amount the recipient should receive.

        The system will calculate the corresponding value based on the latest rates and fees.

        If the request is successful, you'll receive a `200 OK` status with the estimated payout details.

        ```json Example Response
        {
            "externalId": "4f7768e5-cd82-42c4-80d6-18d84a5b3832",
            "accountId": "4ea1277f-29d7-11ed-84d9-0a878439b77f",
            "walletId": "0da83d78-5c84-475f-a657-9b8b329e9491",
            "customerReference": "REF46730",
            "walletCurrency": "USD",
            "walletRequiredAmount": 15.79,
            "paidCurrency": "USDT",
            "paidRequiredAmount": 15,
            "feeCurrency": "USD",
            "feePredictedAmount": 0.16,
            "networkFeeCurrency": "USD",
            "networkFeePredictedAmount": 1.62,
            "totalWalletAmount": 15.95,
            "exchangeRate": 0.949715,
            "customerId": "9e9bb7cb-f5d4-4f7b-bada-6ad156f3a8d8",
            "paymentExternalId": null,
            "network": "ETHEREUM"
        }
        ```

        The **exchange rate** is typically the most important piece of information that financial companies are after, as it directly affects the cost and value of transactions. Along with the source (`walletCurrency`) and destination (`paidCurrency`) currencies, this information helps you determine the exact conversion dynamics of the payout.

        | **Field**        | **Description**                                                        |
        | :--------------- | :--------------------------------------------------------------------- |
        | `walletCurrency` | The currency from which funds are debited (e.g., `USD`).               |
        | `paidCurrency`   | The currency in which the payout is made (e.g., `USDT`).               |
        | `exchangeRate`   | The exchange rate applied between `walletCurrency` and `paidCurrency`. |

        **Other Fields**

        | **Field**                   | **Description**   |
        | :-------------------------- | :-------------------- |
        | `externalId`                | Unique ID for the estimate request generated by the system.|
        | `accountId`                 | Internal account ID associated with the estimate.          |
        | `walletId`                  | ID of the originator's wallet used for this payout.        |
        | `customerReference`         | The reference provided in the request (`REF46730`).        |
        | `walletRequiredAmount`      | Calculated amount in the wallet currency required to fund the payout. |
        | `paidRequiredAmount`        | The amount the recipient will receive.                     |
        | `feeCurrency`               | Currency in which the transaction fee is calculated.       |
        | `feePredictedAmount`        | Estimated transaction fee in the `feeCurrency`.            |
        | `networkFeeCurrency`        | Currency for the blockchain network fee.                   |
        | `networkFeePredictedAmount` | Estimated blockchain network fee in `networkFeeCurrency`.  |
        | `totalWalletAmount`         | Total amount debited from the wallet, including fees and network costs.|
        | `customerId`                | Associated customer ID, if applicable.                     |
        | `paymentExternalId`         | External payment ID, if linked to an actual transaction (usually `null` for estimates). |
        | `network`                   | Blockchain network to process the payout. See [Supported Currencies](../../../references/currencies) for possible values. |

    2. To update the quote every 30 seconds, use the `externalId` value that you received on step 1 to send the [`PUT api/v1/pay/estimate/{externalId}/update`](../../../api-explorer/endpoints/pay-estimate-update) request.

        You can provide new values in the payload or leave it as is. For the complete list of fields that can be updated, see the endpoint description in the API reference.
        <Tabs>
        <TabItem value="paidRequiredAmount" label="Refresh the desired paid amount">
        ```json Refresh the desired paid amount
        {
            "paidRequiredAmount": 15,
            "reference": "REF46730-updated-1"
        }
        ```
        </TabItem>
        <TabItem value="walletRequiredAmount" label="Refresh the desired wallet amount">
        ```json Change required amount
        {
            "walletRequiredAmount": 15.79,
            "reference": "REF46730-updated-1"
        }
        ```
        </TabItem>
        </Tabs>
    3. When you are ready to make a payout, turn the quote into a pending payment by sending the [`POST /api/v1/pay/estimate/{externalId}/accept`](../../../api-explorer/endpoints/pay-estimate-accept) request with the following payload. Again, use the `externalId` received for the earlier quote.

        <Tabs queryString="entity-type">
        <TabItem value="individual" label="Individual">
            ```json Example Payload: Individual
            {
                "customerId": "9e9bb7cb-f5d4-4f7b-bada-6ad156f3a8d8",
                "payOutDetails": {
                    "currency": "USDT",
                    "address": "0xc32dEc8Ad273EDeEC81186CBCfce0732AD088fA9",
                    "tag": "",
                    "network": "ETHEREUM"
                },
                "complianceDetails": {
                    "requesterIpAddress": "172.16.254.1",
                    "partyDetails": [
                        {
                            "type": "BENEFICIARY",
                            "entityType": "INDIVIDUAL",
                            "relationshipType": "THIRD_PARTY",
                            "firstName": "John",
                            "lastName": "Doe",
                            "dateOfBirth": "1988-10-12",
                            "countryCode": "UK"
                        }
                    ]
                }
            }
            ```
            </TabItem>
            <TabItem value="company" label="Company">
            ```json Example Payload: Company
            {
                "customerId": "123",
                "payOutDetails": {
                    "currency": "USDT",
                    "address": "0xc32dEc8Ad273EDeEC81186CBCfce0732AD088fA9",
                    "tag": "",
                    "network": "ETHEREUM"
                },
                "complianceDetails": {
                    "requesterIpAddress": "172.16.254.2",
                    "partyDetails": [
                        {
                            "type": "BENEFICIARY",
                            "entityType": "COMPANY",
                            "relationshipType": "SELF_OWNED",
                            "legalName": "Nijke",
                            "registrationNumber": "268558392",
                            "countryCode": "GB",
                        }
                    ]
                }
            }
            ```
            </TabItem>
            </Tabs>

        Note that on this stage, the payment has not sent yet.
    4. Confirm the payout by sending the [`PUT /api/v1/pay/{uuid}/confirm/summary`](../../../api-explorer/endpoints/payment-confirm) request with the payment `uuid` received from [`POST /api/v1/pay/estimate/{externalId}/accept`](../../../api-explorer/endpoints/pay-estimate-accept).

  </TabItem>
  <TabItem value="two-step-payout" label="Two-step Payout">
    The two-step process allows you to initiate a crypto payout, which must be accepted in two stages. This approach provides an additional layer of security and control before the funds are moved.

    >**Example use case**: You can use this approach for an Employer of Records platform. For example, you create the payout in the background and send an email to the customer to notify them of the salary that will be paid soon. The customer isn't actually logged into the platform at the time. They receive an email saying something like, "You're going to get paid out 1000 USDT. Do you accept this? If you do, click the button here." The customer clicks **Accept** within a one hour timeframe, and gets paid out. If they miss it, the payment will expire.

    <!-- :::note
    Remember to use `"walletId": {{wallet_lsId}}` instead of the `merchantID` in the request.
    ::: -->

    To create a payout, do the following:

    1. Send the [`POST /api/v1/pay/summary`](../../../api-explorer/endpoints/payment-create) request, including a variable of `"twoStep": "true"`. To initiate a two-step payout, you will need to provide the `currency`, `amount`, `destination address`, and any additional necessary details to complete the payout. For complete information about this endpoint, see the endpoint description in the API reference.

        :::note
        At this step, the quote is locked in, meaning the crypto exchange rate (for example, USD to USDT) is fixed at the time of the request. It won't fluctuate while waiting for acceptance. The user must accept the payment and quote before processing.
        :::

        ```json Request
        {
            "walletId": "a:25022613287255:zmHs0pg:1",
            "type": "OUT",
            "amount": 10,
            "currency": "USD",
            "expiryMinutes": 30,
            "reference": "test_reference_out_rWoHOk",
            "returnUrl": "https://your-url-here.com/status",
            // highlight-next-line
            "twoStep": "true",
            "payOutDetails": {
                "code": "crypto",
                "currency": "USDT",
                "network": "ETHEREUM",
                "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
                "tag": null
            },
            "customerId": "aaa1940d-adea-42ec-a831-ccf4189560ab",
            "complianceDetails": {
                "requesterIpAddress": "77.71.188.87",
                "partyDetails": [
                    {
                        "type": "BENEFICIARY",
                        "entityType": "INDIVIDUAL",
                        "firstName": "John",
                        "lastName": "Doe",
                        "dateOfBirth": "1984-06-30",
                        "relationshipType": "THIRD_PARTY",
                        "countryCode": "DE"
                    }
                ]
            }
        }
        ```

        If the request is successful, you will get a `200 OK` message and the following response:

        <details>
        <summary>Response</summary>
        ```json Response
        {
            "uuid": "ffc83433-8f31-42ad-b510-e935da03952b",
            "merchantDisplayName": "Zapier Channel Webhook",
            "walletId": "a:25022613287255:zmHs0pg:1",
            "dateCreated": 1740399254636,
            "expiryDate": 1740401054636,
            "quoteExpiryDate": 1740401054636,
            "acceptanceExpiryDate": 1740399284690,
            // highlight-next-line
            "quoteStatus": "ACCEPTED",
            "reference": "test_reference_out_rWoHOk",
            "type": "OUT",
            "subType": "merchantPayOut",
            "status": "PENDING",
            "displayCurrency": {
                "currency": "USD",
                "amount": 10,
                "actual": 0
            },
            "walletCurrency": {
                "currency": "USD",
                "amount": 10,
                "actual": 10
            },
            "paidCurrency": {
                "currency": "USDT",
                "amount": 9.498955,
                "actual": 0
            },
            "feeCurrency": {
                "currency": "USD",
                "amount": 0.1,
                "actual": 0
            },
            "networkFeeCurrency": {
                "currency": "USD",
                "amount": 1.08,
                "actual": 0
            },
            "displayRate": {
                "base": "USDT",
                "counter": "USD",
                "rate": 1.052747381159
            },
            "exchangeRate": {
                "base": "USD",
                "counter": "USDT",
                "rate": 0.949895511494
            },
            "address": {
                "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
                "tag": null,
                "network": "ETHEREUM",
                "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156&uint256=9498955",
                "alternatives": []
            },
            "returnUrl": "https://your-url-here.com/status",
            "redirectUrl": "https://pay.sandbox.bvnk.com/payout/ffc83433-8f31-42ad-b510-e935da03952b",
            "transactions": [],
            "refund": null,
            "refunds": [],
            "currencyOptions": [],
            "flow": "DEFAULT",
            "twoStep": true
        }
        ```
        </details>

        Once the payout is created, the quote status automatically changes to `ACCEPTED`. The response also  shows `quoteExpiryDate` / `acceptanceExpiryDate` that caps how long the quote rate holds. Review the quote and confirm the payout to move the funds if all the details are correct.

        :::warning
        The quote is valid for one hour. To proceed, send the confirmation request within this period so BVNK can move the funds to the destination wallet. If you do not want to move the funds, you can do nothing, and the quote will expire automatically after one hour.
        :::

    2. To approve the payout, send the [`PUT /api/v1/pay/{{uuid}}/confirm/summary`](../../../api-explorer/endpoints/payment-confirm) request. No payload body is required for this request.

        ```json Request
        curl --location --request PUT 'https://api.sandbox.bvnk.com/api/v1/pay/ffc83433-8f31-42ad-b510-e935da03952b/confirm/summary' \
        --header 'Authorization: Hawk id="vbfc61D890wg6LAAVbkR11qP9O6cXeMNmKWgcUNZaOHPiQeebp9cl6h02tWv84R8", ts="1740399374", nonce="0ctn1z", mac="YuIfbHw8ZBYVBNh/FJCsW4S2qQUZ/9Hf+EBYMzSFg5Q="'
        ```

        If the request is successful, you will get a `200 OK` message and the following response:

        <details>
        <summary>Response</summary>
        ```json Response
        {
            "uuid": "ffc83433-8f31-42ad-b510-e935da03952b",
            "merchantDisplayName": "Zapier Channel Webhook",
            "walletId": "a:25022613287255:zmHs0pg:1",
            "dateCreated": 1740399255000,
            "expiryDate": 1740401055000,
            "quoteExpiryDate": 1740401055000,
            "acceptanceExpiryDate": 1740399285000,
            "quoteStatus": "ACCEPTED",
            "reference": "test_reference_out_rWoHOk",
            "type": "OUT",
            "subType": "merchantPayOut",
            "status": "PROCESSING",
            "displayCurrency": {
                "currency": "USD",
                "amount": 10,
                "actual": 0
            },
            "walletCurrency": {
                "currency": "USD",
                "amount": 10,
                "actual": 10
            },
            "paidCurrency": {
                "currency": "USDT",
                "amount": 9.498955,
                "actual": 0
            },
            "feeCurrency": {
                "currency": "USD",
                "amount": 0.1,
                "actual": 0
            },
            "networkFeeCurrency": {
                "currency": "USD",
                "amount": 1.08,
                "actual": 0
            },
            "displayRate": {
                "base": "USDT",
                "counter": "USD",
                "rate": 1.052747381159
            },
            "exchangeRate": {
                "base": "USD",
                "counter": "USDT",
                "rate": 0.949895511494
            },
            "address": {
                "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
                "tag": null,
                "network": "ETHEREUM",
                "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156&uint256=9498955",
                "alternatives": []
            },
            "returnUrl": "https://your-url-here.com/status",
            "redirectUrl": "https://pay.sandbox.bvnk.com/payout/ffc83433-8f31-42ad-b510-e935da03952b",
            "transactions": [],
            "refund": null,
            "refunds": [],
            "currencyOptions": null,
            "flow": null,
            "twoStep": true,
            "networkFeeBilledTo": "MERCHANT",
            "networkFeeRates": []
        }
        ```
        </details>

    To check the status of a payout, send the [`GET /api/v1/pay/{uuid}`](../../../api-explorer/endpoints/payment-read) request with the payout `uuid` received from the response of the previous request.

  </TabItem>
  <TabItem value="direct-customer-to-payments" label="Direct customer to payments">
    You can integrate user payouts using BVNK-hosted payment pages or a custom user interface.

    <Tabs>
    <TabItem value="hosted" label="Hosted payments page">

        This section explains how to redirect customers to the hosted payments page to complete a payout. Customers select their currency, enter their wallet address, and accept the final quote, so you do not need to build a full user interface.

        To integrate the hosted payments page, follow these steps:

        1. Send the [`POST /v1/pay/summary`](../../../api-explorer/endpoints/payment-create/) request to create a `PENDING` payout request with the specified amount, currency, and compliance details, and generate a quote template.

            ```json Example Request Payload
            {
                "walletId": "a:25041848230123:LWWoNSn:1",
                "type": "OUT",
                "amount": 10,
                "currency": "USD",
                "expiryMinutes": 30,
                "reference": "REF123456",
                "returnUrl": "https://your-url-here.com/status",
                "customerId": "9420b652-c6e9-4bfe-9425-fc069c6bb710",
                "complianceDetails": {
                    "requesterIpAddress": "77.71.188.87",
                    "partyDetails": [
                        {
                            "type": "BENEFICIARY",
                            "entityType": "INDIVIDUAL",
                            "firstName": "Paul",
                            "lastName": "Walker",
                            "dateOfBirth": "1988-12-20",
                            "relationshipType": "THIRD_PARTY",
                            "countryCode": "GB"
                        }
                    ]
                }
            }
            ```
            For the detailed description of each parameter, see the [Create a payout](pay-out-to-your-users.mdx#create-a-payout) guide.

            The response contains the details of the pending payout, including the unique identifier (`uuid`) and the `redirectUrl`.

            ```json Example Response (Excerpt)
            {
                "metadata": {},
                "uuid": "019bc68d-d0e9-7a3d-a8fd-72d9fdfa4e84",
                ...
                "status": "PENDING",
                ...
                "returnUrl": "https://your-url-here.com/status",
                "redirectUrl": "https://pay.sandbox.bvnk.com/payout/019bc68d-d0e9-7a3d-a8fd-72d9fdfa4e84",
                ...
            }
            ```

        2. Direct the user to the hosted page using the `redirectUrl` as soon as you receive the response.

            This link is time-sensitive and directs the customer to the BVNK-hosted payments page, where they complete the following steps:

                * Selects their preferred currency and protocol.
                * Enters their wallet address.
                * Views and accepts the final quote.

                

        3. After the payment is completed, redirect the user to your `returnUrl` provided in the initial response.

    </TabItem>
    <TabItem value="custom" label="Custom payout UI">

        This section outlines the API endpoints required to build a custom user interface for crypto payouts. This approach gives you full control over the user experience, including currency selection, wallet address collection, quote acceptance, and final confirmation within your application.

        To integrate a custom payment page, follow these steps:

        1. Send the [`POST /v1/pay/summary`](../../../api-explorer/endpoints/payment-create/) request to create the initial payment object and provide a list of available currencies and protocols that your customers can select.

            ```json Example Request
            {
            "walletId": "*{{partner_wallet_id}}*",
            "type": "OUT",
            "amount": 10,
            "currency": "USD",
            "expiryMinutes": 30,
            "reference": "REF123456",
            "returnUrl": "https://your-url-here.com/status",
            "customerId": "9420b652-c6e9-4bfe-9425-fc069c6bb710",
            "complianceDetails": {
                "requesterIpAddress": "55.55.55.55",
                "partyDetails": [
                    {
                        "type": "BENEFICIARY",
                        "entityType": "INDIVIDUAL",
                        "firstName": "Gabriel",
                        "lastName": "Brown",
                        "dateOfBirth": "1990-01-01",
                        "relationshipType": "THIRD_PARTY",
                        "countryCode": "GB"
                    }
                ]
            }
            }
            ```

            The new payment is created with a `PENDING` status, specified amount, currency, compliance details, and a `TEMPLATE` quote.

            The response includes the `uuid` for subsequent calls and the `currencyOptions` array:

            |Parameter|Description|
            |---------|-----------|
            |`uuid`|The payment ID used in subsequent requests.|
            |`currencyOptions`|List of objects showing available cryptocurrencies (`code`) and their compatible network protocols (`protocols`).|
            |`displayCurrency`|The target currency and amount. For example, 10 USD.|

        2. Prompt the user to select their preferred currency and protocol from `currencyOptions`, and send the [`PUT /v1/pay/{uuid}/update/summary`](../../../api-explorer/endpoints/payment-update/) request to update the quote.

            This request provides the final conversion rate, fees, and payout amount in the selected cryptocurrency. Use the `{uuid}` from the initial response.

            ```json Example Request
            {
                "payOutMethod": "crypto",
                "currency": "ETH"
            }
            ```

            :::info
            Although the example uses ETH, the active document's response shows USDT. You should use the user's selected currency/protocol.
            :::

            The quote status updates to `PENDING` and includes all final transaction details.

            The response provides updated quote details, including:

            |Parameter|Description|
            |---------|-----------|
            |`paidCurrency`|The final cryptocurrency, amount, and actual value the user will receive. For example, 9.985592 USDT.|
            |`feeCurrency`|Any fees applied to the transaction. For example, 0.02 USD.|
            |`exchangeRate`|The rate used for the conversion.|
            |`quoteExpiryDate`|The timestamp when the quote will expire and needs to be refreshed.|

        3. Collect the user's wallet address and call [`PUT /api/v1/pay/validate`](../../../api-explorer/endpoints/payment-out-validate/) to verify that it matches the selected currency and protocol.

            ```json Example Request
            {
                "code": "crypto",
                "currency": "USDT",
                "address": "TFsmkjujT9omG5TFrEXYbDocTdjeeHgcrQ",
                "network": "TRON"
            }
            ```

            :::warning
            If the API returns a successful response, proceed to the next step.

            If an error is returned, prompt the user to correct the address and try again.
            :::

        4. After the address is validated and the user confirms the quoted amount, display the final quoted amount and details of the payment.

            Then, send the [`POST api/v1/pay/{uuid}/accept/summary`](../../../api-explorer/endpoints/payment-confirm/) request to finalize the transaction. Use the `{uuid}` from the initial response.

            This request changes the transaction status from `PENDING` to `IN_PROGRESS` and initiates the crypto transfer.

        5. Monitor the transaction status using [webhooks](../../../api-explorer/bvnk-webhooks/crypto-status-change/) and redirect the user to your platform's status page (`returnUrl`) once the process is complete.

    </TabItem>
    </Tabs>
    </TabItem>
</Tabs>

---

<TravelRuleCompliance />

---

## Handle errors

If the wallet doesn't have enough funds to cover the payment amount, network and processing fees, the following error is returned. In this case, top up the wallet balance or contact the Solutions team.

```json Error Response: Insufficient Funds
{
    "requestId": "fd3b64b97db85a7ebab39d5a1fb20867",
    "errorList": [
        {
            "requestId": null,
            "code": "MER-PAY-2012",
            "parameter": "amount",
            "message": "insufficient funds"
        }
    ]
}
```

## Payout webhook

To receive notifications when the payout status changes, subscribe to the following webhooks:

- [Fiat payout webhook](../../../api-explorer/bvnk-webhooks/payment-payout-status-change-v-2/)
- [Crypto payout webhook](../../../api-explorer/bvnk-webhooks/crypto-status-change/)

---

## Send stablecoin payments

The following guide describes how you can integrate stablecoin payments into your platform via BVNK.

A stablecoin payment refers to sending stablecoins to an end-users' crypto wallet from your BVNK account.

<CoastDemoEmbed
  src="https://bvnk.coastdemo.com/share/69c2b8f7d77d8579ee7096b3"
  title="Stablecoin payouts demo"
  scale={0.82}
/>

## For who is this product intended?

This product is designed for Businesses that want to make payments to their customers in stablecoins and best suited for:

- Gaming Platform
- CFD / FX brokers
- Trading Platforms
- Neobanks
- Payment Service Providers (PSPs)

---

## What is a standard use case for stablecoin payments?

In general, you can imagine a following scenario:

> You represent a trading platform and your user has just made some money on selling their XAU/USD asset that was growing for some time. Or you are a gaming platform and your user has just made some money on selling their in-game items. In both cases, your user wants to withdraw their winnings from your platform to their own account.
>
>They go to your platform, click on a **Cash out** button, and are presented with alternative payout options. The user selects stablecoins and wants to cash out $5000, paid out in stablecoins, from their $10,000 balance available on your platform. By creating a payout request via BVNK your user can now receive stablecoins to their digital asset wallet.

BVNK supports multiple payout use cases, including but not limited to:

- As a Neobank or PSP serving businesses and individuals you would like to allow your customers to payout stablecoins from your platform to pay a supplier.
- You want to pay stablecoins as a salary to your employees and contractors.

---

## How stablecoin payments work?

When you initiate a stablecoin payment, BVNK handles the entire conversion and transfer process:

1. **Source Wallet**: You start with a fiat wallet containing your available balance.
2. **Conversion**: When you create a stablecoin payment, BVNK automatically converts your fiat currency to the requested stablecoin.
3. **Transfer**: The converted stablecoins are immediately sent to the <Term popup="The entity that receives the transaction.">Beneficiary</Term>'s crypto wallet address.
4. **Debit**: Your fiat wallet balance is debited for the equivalent amount.

This product allows you as a BVNK customer to only ever have to hold fiat balances. BVNK handles the conversion and payout of stablecoins on your behalf.

---

### Supported payment types

BVNK supports various payment combinations to meet different business needs:

- **Fiat to crypto**: Convert fiat currency to stablecoins and send to crypto wallets.
- **Crypto to crypto**: Send stablecoins directly from your crypto wallet and convert between different stablecoin types during payment.

---

## What it looks like?

The following diagrams shows the flow of a stablecoin pay out.

![](/img/bvnk/use-cases/stablecoin-payout-flow.svg)

Payments go through the following statuses in the workflow:

| Status       | Immutable? | Description |
| :----------- | :---------: | :------------------------------- |
| `PENDING`    | :x:         | The initial state of a payment. payments will remain in this state until a crypto address to send the payment to has been input, or the payment request is cancelled. |
| `PROCESSING` | :x:         | After a crypto address has been provided by the payer, payments transition into a processing state.                                                                |
| `COMPLETE`   | :white_check_mark:        | Once the transaction has been registered on the blockchain and has a hash, the payment will transition to complete.                                                |
| `CANCELLED`  | :white_check_mark:        | If the payment is cancelled or fails, the state will transition to cancelled and the funds will remain in the merchant account.                                    |
| `EXPIRED`    | :white_check_mark:        | The payment expired before the customer inserted the wallet details.                                                                                              |

:::warning
Once you finalize a payment, please ensure no more API calls will be made to duplicate the withdrawal—transactions on the blockchain are final and cannot be recalled.
:::

---

**Ready to start?** Once you have completed all prerequisites above, you can proceed with the integration. The next sections will guide you through:
- [Checklist for integration](../prepare-for-integration)
- [Making your first payment](../pay-out-to-your-users)
- Handling [approvals and rejections](../approve-reject-payouts) for payments

---

## Prepare for integration(Stablecoin-payments-for-platforms)

<Overview />

---

<SetupAndWallets />
---

<Customer />

---

## Wallet setup

Create a stablecoin wallet for each currency you plan to use—typically USDT or USDC. Each wallet generates blockchain addresses on supported networks: Ethereum (ERC-20), Tron (TRC-20), or Solana. You specify the network when creating payment channels, not when creating the wallet itself.

For payouts, fund your wallet before initiating transactions. BVNK debits the payout amount plus network fees from your wallet balance when processing the withdrawal. For pay-ins, share the generated deposit address with your payer; incoming funds credit to your wallet after blockchain confirmation.

After you have created the wallet, find its ID in the Wallet section on the Portal. You will later need it for creating payments.

![WalletId](/img/bvnk/use-cases/walletId.png)

See [Create a wallet](../../../get-started/create-wallet) for setup instructions and profile configuration.

---

<TestAndGoLive />

---

**What's next?**

Once you have completed all prerequisites above, you can proceed with [sending stablecoins via your customers' wallets](../send-stabelcoin-via-customers-wallet).

---

## Prepare for integration(3)

<Overview />

---

<SetupAndWallets />
---

<Customer />

---

## Wallet setup

Create a stablecoin wallet for each currency you plan to use—typically USDT or USDC. Each wallet generates blockchain addresses on supported networks: Ethereum (ERC-20), Tron (TRC-20), or Solana. You specify the network when creating payment channels, not when creating the wallet itself.

For payouts, fund your wallet before initiating transactions. BVNK debits the payout amount plus network fees from your wallet balance when processing the withdrawal. For pay-ins, share the generated deposit address with your payer; incoming funds credit to your wallet after blockchain confirmation.

After you have created the wallet, find its ID in the Wallet section on the Portal. You will later need it for creating payments.

![WalletId](/img/bvnk/use-cases/walletId.png)

See [Create a wallet](../../../get-started/create-wallet) for setup instructions and profile configuration.

---

<TestAndGoLive />

---

**What's next?**

Once you have completed all prerequisites above, you can proceed with [making your first payment](../pay-out-to-your-users).

---

## Provide additional party information

In traditional payment systems such as credit cards and bank transfers, collecting and sharing party information is standard practice. The **Travel Rule** now extends this requirement to crypto and stablecoin payments under the EU's MiCA regulation for crypto assets.

The Travel Rule increases regulatory clarity and data transparency for crypto, enabling businesses to operate in a more secure environment. As trust in crypto payments grows, we anticipate broader adoption by businesses, consumers, and financial institutions.

:::tip
- If you use an API integration to initiate payments, update your integration to include the required data. The affected endpoints are listed below.
- If you initiate payments only through the BVNK Portal, you will be prompted to provide the required data in the user interface as needed.
:::

## Affected API endpoints

If you use these endpoints, update your integration as shown in the examples below.

| Product | Used for | Production endpoint | Sandbox endpoint |
| :--- | :--- | :--- | :--- |
| Crypto payments via Payment Links | DepositsPayouts | https://api.bvnk.com/api/v1/pay/summary| https://api.sandbox.bvnk.com/api/v1/pay/summary |
| Crypto payments via Payment Channels | Deposits |https://api.bvnk.com/api/v2/channel| https://api.sandbox.bvnk.com/api/v2/channel |

## Supply the additional data

<Tabs>
  <TabItem value="individual-originator" label="Individual: Originator (Payin)">
    ```json
    {
      "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
      "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
          {
            "type": "ORIGINATOR",
            "entityType": "INDIVIDUAL",
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "1984-06-30",
            "relationshipType": "THIRD_PARTY",
            "countryCode": "DE"
          }
        ]
      }
    }
    ```
  </TabItem>
  <TabItem value="individual-beneficiary" label="Individual: Beneficiary (Payout)">
    ```json
    {
      "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
      "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
          {
            "type": "BENEFICIARY",
            "entityType": "INDIVIDUAL",
            "firstName": "John",
            "lastName": "Doe",
            "dateOfBirth": "1984-06-30",
            "relationshipType": "THIRD_PARTY",
            "countryCode": "DE"
          }
        ]
      }
    }
    ```
  </TabItem>
  <TabItem value="business-originator" label="Business: Originator (Payin)">
    ```json
    {
      "customerId": "b061943d-e29f-481e-abcb-5c937ee8234e",
      "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
          {
            "type": "ORIGINATOR",
            "entityType": "COMPANY",
            "legalName": "Fast Cars LTD",
            "registrationNumber": "ABC123",
            "relationshipType": "THIRD_PARTY",
            "countryCode": "DE"
          }
        ]
      }
    }
    ```
  </TabItem>
  <TabItem value="business-beneficiary" label="Business: Beneficiary (Payout)">
    ```json
    {
      "customerId": "b061943d-e29f-481e-abcb-5c937ee8234e",
      "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
          {
            "type": "BENEFICIARY",
            "entityType": "COMPANY",
            "legalName": "Acme Corporation Ltd",
            "registrationNumber": "268558392",
            "relationshipType": "THIRD_PARTY",
            "countryCode": "GB"
          }
        ]
      }
    }
    ```
  </TabItem>
</Tabs>

| Parameter | Required | Description |
| :--- | :---: | :--- |
| `customerId` | :white_check_mark: | Unique identifier for the party requesting the payment. If multiple payments for the same party are requested, the ID should remain consistent. |
| `complianceDetails` | :white_check_mark: | Information about the party requesting the deposit. |
| `complianceDetails.requesterIpAddress` | :white_check_mark: | IP-address of the party requesting the deposit.Required only if `countryCode` is not provided. |
| `complianceDetails.partyDetails` | :white_check_mark: | Additional information about the party requesting the payment. |
| `complianceDetails.partyDetails.type` | :white_check_mark: | Party to which the information belongs. Possible values:• `BENEFICIARY`: Party receiving the pay-out• `ORIGINATOR`: Party sending the deposit |
| `complianceDetails.partyDetails.entityType` | :white_check_mark: | Entity type. Possible values:• `INDIVIDUAL`: details about an individual.• `COMPANY`: details about a business. |
| `complianceDetails.partyDetails.firstName` | :white_check_mark: | First name of the party requesting the deposit.Required only if `"entityType": "INDIVIDUAL"`. |
| `complianceDetails.partyDetails.lastName` | :white_check_mark: | Last name of the party requesting the deposit.Required only if `"entityType": "INDIVIDUAL"`. |
| `complianceDetails.partyDetails.dateOfBirth` | :white_check_mark: | Date of birth of the party requesting the deposit. Format: `YYYY-MM-DD`. Example: `1984-06-30`.Required only if `"entityType": "INDIVIDUAL"`. |
| `complianceDetails.partyDetails.countryCode` | :white_check_mark: | ISO 3166-1-alpha-2 code of the country that the party resides in. Example: `DE`.Required only if `requesterIpAddress` is not provided. |
| `complianceDetails.partyDetails.regionCode` | :white_check_mark: | ISO 3166-2:UA code for Ukraine's regions, enabling geoscreening of restricted areas.Required only if `complianceDetails.partyDetails.countryCode` is `UA`. In this case, submissions with missing or invalid `regionCode` are rejected. For all other countries, the region code is ignored.For the complete list of codes, see [ISO\_3166-2:UA](https://www.iso.org/obp/ui/#iso:code:3166:UA). Example: `UA-46`. |
| `complianceDetails.partyDetails.legalName` | :white_check_mark: | Legal entity name of the company.Required only if `"entityType": "COMPANY"`. |
| `complianceDetails.partyDetails.registrationNumber` | :white_check_mark: | Company registration number.Required only if `"entityType": "COMPANY"`. |
| `complianceDetails.partyDetails.relationshipType` | :white_check_mark: | Relationship type between the sender and the recipient of the transaction. Possible values:• `SELF_OWNED`: The wallet within BVNK is registered under the same entity for both accounts involved in the transaction. Thus, the funds are moved between accounts owned by the same entity. For example, if the BVNK wallet is registered to *Fast Cars LTD* and funds are being transferred to another account owned by *Fast Cars LTD*.• `THIRD_PARTY`: The transaction involves accounts belonging to different entities. For example, *Fast Cars LTD* receives a payment from *James Smith*, or *Fast Cars LTD* pays their supplier *Tires Supplies Inc*. |

## Examples

### Deposits

<Tabs>
  <TabItem value="deposit-payment-link-individual" label="Payment Link: Individual">
    ```json
    {
        "walletId": "a:12345678987654:xyzW1qp:3",
        "type": "IN",
        "amount": 500,
        "currency": "USDT",
        "expiryMinutes": 1440,
        "reference": "1xCbGZ",
        "returnUrl": "https://your-url-here.com/status",
        "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
        "complianceDetails": {
            "requesterIpAddress": "77.71.188.87",
            "partyDetails": [
                {
                    "type": "ORIGINATOR",
                    "entityType": "INDIVIDUAL",
                    "firstName": "John",
                    "lastName": "Doe",
                    "dateOfBirth": "1984-06-30",
                    "relationshipType": "THIRD_PARTY",
                    "countryCode": "DE"
                }
            ]
        }
    }
    ```
  </TabItem>
  <TabItem value="deposit-payment-link-business" label="Payment Link: Business">
    ```json
    {
        "walletId": "a:25022613287255:zmHs0pg:1",
        "type": "IN",
        "amount": 1000,
        "currency": "USDT",
        "expiryMinutes": 1440,
        "reference": "corp_deposit_001",
        "returnUrl": "https://your-url-here.com/status",
        "customerId": "b061943d-e29f-481e-abcb-5c937ee8234e",
        "complianceDetails": {
            "requesterIpAddress": "77.71.188.87",
            "partyDetails": [
                {
                    "type": "ORIGINATOR",
                    "entityType": "COMPANY",
                    "legalName": "Fast Cars LTD",
                    "registrationNumber": "ABC123",
                    "relationshipType": "THIRD_PARTY",
                    "countryCode": "DE"
                }
            ]
        }
    }
    ```
  </TabItem>
  <TabItem value="deposit-payment-channel-individual" label="Payment Channel: Individual">
    ```json
    {
        "walletId": "a:25133784920155:xyR7klz:7",
        "payCurrency": "USDT",
        "displayCurrency": "USD",
        "reference": "PayRef-USDT-d063635e",
        "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
        "complianceDetails": {
            "requesterIpAddress": "77.71.188.87",
            "partyDetails": [
                {
                    "type": "ORIGINATOR",
                    "entityType": "INDIVIDUAL",
                    "firstName": "John",
                    "lastName": "Doe",
                    "dateOfBirth": "1984-06-30",
                    "relationshipType": "THIRD_PARTY",
                    "countryCode": "DE"
                }
            ]
        }
    }
    ```
  </TabItem>
  <TabItem value="deposit-payment-channel-business" label="Payment Channel: Business">
    ```json
    {
        "walletId": "a:25133784920155:xyR7klz:7",
        "payCurrency": "USDT",
        "displayCurrency": "USD",
        "reference": "PayRef-USDT-corp-001",
        "customerId": "b061943d-e29f-481e-abcb-5c937ee8234e",
        "complianceDetails": {
            "requesterIpAddress": "77.71.188.87",
            "partyDetails": [
                {
                    "type": "ORIGINATOR",
                    "entityType": "COMPANY",
                    "legalName": "Fast Cars LTD",
                    "registrationNumber": "ABC123",
                    "relationshipType": "THIRD_PARTY",
                    "countryCode": "DE"
                }
            ]
        }
    }
    ```
  </TabItem>
</Tabs>

### Payouts

<Tabs>
  <TabItem value="payout-payment-link-individual" label="Payment Link: Individual">
    ```json
    {
        "walletId": "a:25022613287255:zmHs0pg:4",
        "type": "OUT",
        "amount": 3,
        "currency": "EUR",
        "expiryMinutes": 30,
        "reference": "test_reference_out_xpO23C",
        "returnUrl": "https://www.your-url-here.com/status",
        "payOutDetails": {
            "code": "crypto",
            "currency": "ETH",
            "network": "ETHEREUM",
            "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
            "tag": ""
        },
        "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
        "complianceDetails": {
            "requesterIpAddress": "77.71.188.87",
            "partyDetails": [
                {
                    "type": "BENEFICIARY",
                    "entityType": "INDIVIDUAL",
                    "firstName": "John",
                    "lastName": "Doe",
                    "dateOfBirth": "1984-06-30",
                    "relationshipType": "THIRD_PARTY",
                    "countryCode": "DE"
                }
            ]
        }
    }
    ```
  </TabItem>
  <TabItem value="payout-payment-link-business" label="Payment Link: Business">
    ```json
    {
        "walletId": "a:25022613287255:zmHs0pg:5",
        "type": "OUT",
        "amount": 5000,
        "currency": "EUR",
        "expiryMinutes": 30,
        "reference": "corp_payout_001",
        "returnUrl": "https://www.your-url-here.com/status",
        "payOutDetails": {
            "code": "crypto",
            "currency": "USDT",
            "network": "ETHEREUM",
            "address": "0xc32dEc8Ad273EDeEC81186CBCfce0732AD088fA9",
            "tag": ""
        },
        "customerId": "b061943d-e29f-481e-abcb-5c937ee8234e",
        "complianceDetails": {
            "requesterIpAddress": "77.71.188.87",
            "partyDetails": [
                {
                    "type": "BENEFICIARY",
                    "entityType": "COMPANY",
                    "legalName": "Acme Corporation Ltd",
                    "registrationNumber": "268558392",
                    "relationshipType": "THIRD_PARTY",
                    "countryCode": "GB"
                }
            ]
        }
    }
    ```
  </TabItem>
</Tabs>

## Add parameters to existing payment channels

If you have existing payment channels without the required data, you can provide this information by sending a `PUT` request to the payment channel endpoint (`/api/v2/channel`).

```json
{
    "uuid": "7e5e126b-0217-45d4-b38f-5d6f30388257",
    "walletId": "a:25022613287255:zmHs0pg:6",
    "reference": "b5af590b-6033-4b15-874b-289f269b15f9",
    "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
    "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
            {
                "entityType": "INDIVIDUAL",
                "type": "ORIGINATOR",
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "1984-06-30",
                "relationshipType": "THIRD_PARTY",
                "countryCode": "DE"
            }
        ]
    }
}
```

| Parameter | Required | Description |
| :--- | :---: | :--- |
| `uuid` | :white_check_mark: | `UUID` associated with the payment channel. This would have been provided in the response when you originally created the payment channel. |
| `walletId` | :white_check_mark: | ID of the wallet associated with the payment channel. |
| `reference` | :white_check_mark: | `reference` associated with the payment channel. |
| `customerId` | :white_check_mark: | Uniquely identifying the party requesting the payment. If multiple payment channels for the same party are created, the ID should remain consistent across them. |
| `complianceDetails` | :white_check_mark: | Information about the party requesting the deposit. |
| `complianceDetails.requesterIpAddress` | :white_check_mark: | IP-address of the party requesting the deposit.Required only if `countryCode` is not provided. |
| `complianceDetails.partyDetails` | :white_check_mark: | Additional information about the party requesting the payment. |
| `complianceDetails.partyDetails.type` | :white_check_mark: | Party to which the information belongs. Possible values:• `BENEFICIARY`: Party receiving the pay-out• `ORIGINATOR`: Party sending the deposit |
| `complianceDetails.partyDetails.entityType` | :white_check_mark: | Entity type. Possible values:• `INDIVIDUAL`: details about an individual.• `COMPANY`: details about a business. |
| `complianceDetails.partyDetails.firstName` | :white_check_mark: | First name of the party requesting the deposit.Required only if `"entityType": "INDIVIDUAL"`. |

---

## Additional resources

- [The Travel Rule for Crypto EU](https://www.bvnk.com/blog/the-travel-rule-crypto-eu)
- [Travel Rule guidelines](https://help.bvnk.com/hc/en-us/articles/21253138692370-Travel-Rule-Guidelines)

---

## Send stablecoin payments via customer's wallet

When creating a payout, there are two possible flows:

* You already know the destination crypto address for the payout and can specify it in the API call.
* You don't know the destination crypto address for the payout, and will redirect the user to the BVNK hosted payments page to collect it.

## Create a payout

To send stablecoin payments via your customer's wallet, do the following:

1. Retrieve the customer reference from the [customer section on the BVNK Portal](../../../get-started/create-embedded-partner-customer/creating-an-embedded-customer-company-api?type=Portal#add-a-customer) or [API](../../../get-started/create-embedded-partner-customer/retrieve-embedded-partner-customer#retrieve-customers-details).

2. Send the [`POST /api/v1/pay/summary`](../../../api-explorer/endpoints/payment-create) request with the following body parameters. Make sure to set the `flow` parameter to `EMBEDDED_CRYPTO`:

    ```json Request
    {
      "walletId": "a:25022613287255:zmHs0pg:1",
      "amount": 1000,
      "currency": "USD",
      "reference": "REF777579",
      "type": "OUT",
      "returnUrl": "https://my-return-url.com",
      "customerId": "1289702",
      "flow": "EMBEDDED_CRYPTO",
      "payOutDetails": {
        "currency": "USDC",
        "code": "crypto",
        "address": "0xca3b0670d63f4faa1a876efce4c471fb41abf124",
        "network": "ETHEREUM"
      },
      "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
          {
            "type": "BENEFICIARY",
            "entityType": "INDIVIDUAL",
            "firstName": "John",
            "lastName": "Mirra",
            "dateOfBirth": "1984-06-30",
            "relationshipType": "THIRD_PARTY",
            "countryCode": "DE"
          }
        ]
      },
      "embeddedCustomerDetails": {
        "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731"
      }
    }
    ```

    For the detailed description of each parameter, see the [Create a payout](pay-out-to-your-users.mdx) guide. Note the specific fields required:

    | Parameter | Required | Description |
    |-----------|:----------:|-------------|
    | `flow` | :white_check_mark: | Flag indicating that payouts are done from your pre-funded partner wallet, converted to crypto at BVNK, then paid out as crypto via the customer.Possible values: `EMBEDDED_CRYPTO` |
    | `embeddedCustomerDetails` | :white_check_mark: | Unique customer reference to be sent in the request in the UUID format.This is a BVNK-generated `reference` that specifies the customer on behalf of which the payment should be initiated.  |
    |`walletId`|:white_check_mark:|Unique ID of your wallet used for the transaction.Here, specify the `walletID` of your pre-funded wallet.|

    <!-- you can find it on the Portal, in -->

The `EMBEDDED_CRYPTO` parameter instructs the system to route funds from the pre-funded wallet via the customer wallet to the external wallet address. All steps are automated and will be executed within seconds.

<details>
<summary>Example Response</summary>
```json
{
    "metadata": {},
    "uuid": "019a5483-dec7-723c-a1f7-24ed4c88e449",
    "merchantDisplayName": "USD Merchant",
    "merchantId": "19eda61c-aabc-4186-8ab1-46a3da181bb6",
    "dateCreated": 1762354519922,
    "expiryDate": 1762440919922,
    "quoteExpiryDate": 1762358120300,
    "acceptanceExpiryDate": 1762354550300,
    "quoteStatus": "ACCEPTED",
    "reference": "EmbeddedCrypto1",
    "type": "OUT",
    "subType": "merchantPayOut",
    "status": "PROCESSING",
    "displayCurrency": {
        "currency": "USD",
        "amount": 10,
        "actual": 0
    },
    "walletCurrency": {
        "currency": "USD",
        "amount": 10,
        "actual": 10
    },
    "paidCurrency": {
        "currency": "USDT",
        "amount": 9.982695,
        "actual": 0
    },
    "feeCurrency": {
        "currency": "USD",
        "amount": 0.02,
        "actual": 0
    },
    "networkFeeCurrency": {
        "currency": "USD",
        "amount": 1.5,
        "actual": 0
    },
    "displayRate": {
        "base": "USDT",
        "counter": "USD",
        "rate": 1.001733499821
    },
    "exchangeRate": {
        "base": "USD",
        "counter": "USDT",
        "rate": 0.998269532774
    },
    "address": {
        "address": "0xa7d78498F7010e8FFac098D0B3A208c46896e00D",
        "tag": null,
        "network": "ETHEREUM",
        "uri": "ethereum:0xdac17f958d2ee523a2206206994597c13d831ec7/transfer?address=0xa7d78498F7010e8FFac098D0B3A208c46896e00D&uint256=9982695",
        "alternatives": []
    },
    "returnUrl": "https://my-return-url.com",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout/019a5483-dec7-723c-a1f7-24ed4c88e449",
    "transactions": [],
    "refund": null,
    "refunds": [],
    "currencyOptions": [
        {
            "code": "EURC",
            "protocols": [
                "BASE"
            ]
        },
        {
            "code": "USDT",
            "protocols": [
                "SOL",
                "POLYGON",
                "TRC20",
                "ERC20",
                "BEP20"
            ]
        }
    ],
    "flow": "EMBEDDED_CRYPTO",
    "twoStep": false,
    "pegged": true,
    "customerId": "1289702",
    "embeddedCustomerDetails": {
        "reference": "bbd5fee0-a2e1-4986-ab26-93e6e59aa7cc",
        "externalReference": null
    }
}
```
</details>

## Payment webhook

To get notified when the status of the payment changes, listen to the [Cryptocurrency payment status change](../../../api-explorer/bvnk-webhooks/crypto-status-change) webhook.

---

## Track transactions

To configure Payout webhooks, go to the BVNK Portal and navigate to **Integrations** >  **Webhooks**. For the full guide, see [Create a Webhook Listener](../../../get-started/create-webhook-listener).

:::warning
If you use `walletID` in the payment request that produces the webhook, note that you will also receive this field in the webhook response. In this case, you can ignore `merchantID`, since it will be discontinued soon.
:::

In the payout workflow, you should expect to receive the following webhooks:

| Event                                       | Description                                                                      |
| ------------------------------------------- | -------------------------------------------------------------------------------- |
| [`statusChanged`](#payment-status-changed)  | Payout has transitioned to a new state.                                          |
| [`refundInitiated`](#refund-initiated)      | Refund process has begun for a cryptocurrency payment.                           |
| [`transactionOnHold`](#transaction-on-hold) | Payment has been sent to a high risk address and is held to be further analyzed. |

## Payment status changed

The `bvnk:payment:crypto:status-change` webhook is triggered when the status of the crypto transaction changes, for example, from `Processing` to `Complete` or `Expired`.

<Tabs>
  <TabItem value="processing" label="Status Change: Processing">

    ```json Status Change: Processing
    {
        "event": "bvnk:payment:crypto:status-change",
        "eventId": "019856c0-5fd6-79c4-8065-3fa5ea70aa3e",
        "timestamp": "2025-07-29T15:15:04.790711Z",
        "data": {
            "flow": null,
            "type": "OUT",
            "uuid": "96491bf1-5af6-4a42-9d35-6e623a9e3426",
            "pegged": false,
            "refund": null,
            "status": "PROCESSING",
            "address": {
                "tag": null,
                "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0xa59d9f28537a3A9EE18E76A9fCe8261B0CA33723&uint256=6E+6",
                "address": "0xa59d9f28537a3A9EE18E76A9fCe8261B0CA33723",
                "network": "ETHEREUM",
                "alternatives": []
            },
            "refunds": [],
            "subType": "merchantPayOut",
            "twoStep": true,
            "metadata": {},
            "reference": "REF65908",
            "returnUrl": "",
            "customerId": "839ef707-91bb-44f5-b762-94a91310aaaa",
            "expiryDate": 1753888503000,
            "merchantId": "e91a7928-7353-4ad4-93eb-32632f01b7b6",
            "dateCreated": 1753802103000,
            "displayRate": {
                "base": "USDC",
                "rate": 1,
                "counter": "USDC"
            },
            "feeCurrency": {
                "actual": 0,
                "amount": 1.729048,
                "currency": "USDC"
            },
            "quoteStatus": "ACCEPTED",
            "redirectUrl": "https://pay.bvnk.com/payout/96491bf1-5af6-4a42-9d35-6e623a9e3426",
            "exchangeRate": {
                "base": "USDC",
                "rate": 1,
                "counter": "USDC"
            },
            "paidCurrency": {
                "actual": 0,
                "amount": 6,
                "currency": "USDC"
            },
            "transactions": [],
            "walletCurrency": {
                "actual": 6,
                "amount": 6,
                "currency": "USDC"
            },
            "currencyOptions": null,
            "displayCurrency": {
                "actual": 0,
                "amount": 6,
                "currency": "USDC"
            },
            "quoteExpiryDate": 1753805701000,
            "networkFeeCurrency": {
                "actual": 0,
                "amount": 0,
                "currency": "USDC"
            },
            "merchantDisplayName": "USDC",
            "acceptanceExpiryDate": 1753802131000
        }
    }
    ```
  </TabItem>
  <TabItem value="complete" label="Status Change: Complete">
    ```json Status Change: Complete
    {
        "event": "bvnk:payment:crypto:status-change",
        "eventId": "01983c01-6077-7282-a6c8-9b837847ff70",
        "timestamp": "2025-07-24T10:36:19.959993400Z",
        "data": {
            "flow": null,
            "type": "OUT",
            "uuid": "3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
            "pegged": false,
            "refund": null,
            "status": "COMPLETE",
            "address": {
                "tag": null,
                "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723&uint256=5E+6",
                "address": "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723",
                "network": "ETHEREUM",
                "alternatives": []
            },
            "refunds": [],
            "subType": "merchantRefund",
            "twoStep": false,
            "metadata": {},
            "reference": "RefundWebhook-318302166",
            "returnUrl": "",
            "customerId": "487548579",
            "expiryDate": 1761237313000,
            "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
            "dateCreated": 1753353313000,
            "displayRate": {
                "base": "USDC",
                "rate": 1,
                "counter": "USDC"
            },
            "feeCurrency": {
                "actual": 5.003059,
                "amount": 5.003059,
                "currency": "USDC"
            },
            "quoteStatus": "ACCEPTED",
            "redirectUrl": "https://pay.bvnk.com/payout/3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
            "exchangeRate": {
                "base": "USDC",
                "rate": 1,
                "counter": "USDC"
            },
            "paidCurrency": {
                "actual": 5,
                "amount": 5,
                "currency": "USDC"
            },
            "transactions": [
                {
                    "hash": "0xd915f19f8505bc90199d88a5f04a412b12662d9ca10e14368d24d8b1e142028a",
                    "amount": 5,
                    "sources": [],
                    "isOnHold": false,
                    "network": "ETHEREUM",
                    "dateCreated": 1753353380000,
                    "displayRate": {
                        "base": "USDC",
                        "rate": 1,
                        "counter": "USDC"
                    },
                    "exchangeRate": {
                        "base": "USDC",
                        "rate": 1,
                        "counter": "USDC"
                    },
                    "dateConfirmed": 1753353380000,
                    "networkFeeAmount": 0,
                    "networkFeeCurrency": "USDC"
                }
            ],
            "walletCurrency": {
                "actual": 5,
                "amount": 5,
                "currency": "USDC"
            },
            "currencyOptions": null,
            "displayCurrency": {
                "actual": 5,
                "amount": 5,
                "currency": "USDC"
            },
            "quoteExpiryDate": 1761237313000,
            "networkFeeCurrency": {
                "actual": 0,
                "amount": 0,
                "currency": null
            },
            "merchantDisplayName": "Merch_arch",
            "acceptanceExpiryDate": 1753353343000
        }
    }
    ```
  </TabItem>
  <TabItem value="expired" label="Status Change: Expired">

    ```json Status Change: Expired
    {
        "event": "bvnk:payment:crypto:status-change",
        "eventId": "01983c00-5d18-7e5e-b85c-c51cf4d42105",
        "timestamp": "2025-07-24T10:35:13.560470800Z",
        "data": {
            "flow": null,
            "type": "OUT",
            "uuid": "3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
            "pegged": false,
            "refund": {
                "flow": null,
                "type": "IN",
                "uuid": "f7c7adca-7e3a-4fcc-9cb1-87e36668a8b2",
                "pegged": false,
                "refund": null,
                "status": "EXPIRED",
                "address": {
                    "tag": null,
                    "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x632cbf94b236419c63f23867a89f4beded3ee3da&uint256=2E+6",
                    "address": "0x632cbf94b236419c63f23867a89f4beded3ee3da",
                    "network": "ETHEREUM",
                    "alternatives": []
                },
                "refunds": [],
                "subType": "merchantPayIn",
                "twoStep": false,
                "metadata": {},
                "reference": "RefundWebhook",
                "returnUrl": "",
                "customerId": "234234234",
                "expiryDate": 1753350971000,
                "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
                "dateCreated": 1753350575000,
                "displayRate": {
                    "base": "USDC",
                    "rate": 1,
                    "counter": "USDC"
                },
                "feeCurrency": {
                    "actual": 0,
                    "amount": 0.014,
                    "currency": "USDC"
                },
                "quoteStatus": "ACCEPTED",
                "redirectUrl": "https://pay.bvnk.com/payin/f7c7adca-7e3a-4fcc-9cb1-87e36668a8b2",
                "exchangeRate": {
                    "base": "USDC",
                    "rate": 1,
                    "counter": "USDC"
                },
                "paidCurrency": {
                    "actual": 5,
                    "amount": 2,
                    "currency": "USDC"
                },
                "transactions": [
                    {
                        "hash": "0x8c29b2b0c6d841b550783c797d3b9668675c05fb17d56db1c9d2172db2536d0e",
                        "amount": 5,
                        "sources": [
                            "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723"
                        ],
                        "isOnHold": false,
                        "network": "ETHEREUM",
                        "dateCreated": 1753353196000,
                        "displayRate": {
                            "base": "USDC",
                            "rate": 1,
                            "counter": "USDC"
                        },
                        "exchangeRate": {
                            "base": "USDC",
                            "rate": 1,
                            "counter": "USDC"
                        },
                        "dateConfirmed": 1753353312000,
                        "networkFeeAmount": 0.00011,
                        "networkFeeCurrency": "USDC"
                    }
                ],
                "walletCurrency": {
                    "actual": 0,
                    "amount": 2,
                    "currency": "USDC"
                },
                "currencyOptions": null,
                "displayCurrency": {
                    "actual": 0,
                    "amount": 2,
                    "currency": "USDC"
                },
                "quoteExpiryDate": 1753350875000,
                "networkFeeCurrency": {
                    "actual": 0,
                    "amount": 0,
                    "currency": null
                },
                "merchantDisplayName": "Merch_arch",
                "acceptanceExpiryDate": 1753350605000
            },
            "status": "PROCESSING",
            "address": {
                "tag": null,
                "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723&uint256=5E+6",
                "address": "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723",
                "network": "ETHEREUM",
                "alternatives": []
            },
            "refunds": [],
            "subType": "merchantRefund",
            "twoStep": false,
            "metadata": {},
            "reference": "RefundWebhook-318302166",
            "returnUrl": "",
            "customerId": "234234234",
            "expiryDate": 1761237313318,
            "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
            "dateCreated": 1753353313000,
            "displayRate": {
                "base": "USDC",
                "rate": 1,
                "counter": "USDC"
            },
            "feeCurrency": {
                "actual": 5.003059,
                "amount": 5.003059,
                "currency": "USDC"
            },
            "quoteStatus": "ACCEPTED",
            "redirectUrl": "https://pay.bvnk.com/payout/3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
            "exchangeRate": {
                "base": "USDC",
                "rate": 1,
                "counter": "USDC"
            },
            "paidCurrency": {
                "actual": 0,
                "amount": 5,
                "currency": "USDC"
            },
            "transactions": [],
            "walletCurrency": {
                "actual": 5,
                "amount": 5,
                "currency": "USDC"
            },
            "currencyOptions": null,
            "displayCurrency": {
                "actual": 0,
                "amount": 5,
                "currency": "USDC"
            },
            "quoteExpiryDate": 1761237313318,
            "networkFeeCurrency": null,
            "merchantDisplayName": "Merch_arch",
            "acceptanceExpiryDate": 1753353343353
        }
    }
    ```
  </TabItem>
</Tabs>

## Refund initiated

The `bvnk:payment:crypto:refund-initiated` webhook notifies when a refund process has begun for a cryptocurrency payment. This can happen if your merchant settings are set to auto-refund under- and overpayments, or if a payment is made to an expired payment link.

<Tabs>
  <TabItem value="complete" label="Refund Initiated: Complete">

    ```json Refund Initiated: Complete
    {
        "event": "bvnk:payment:crypto:refund-initiated",
        "eventId": "01983bf0-c3eb-77b8-bda2-3a09d9bb1235",
        "timestamp": "2025-07-24T10:18:11.307235200Z",
        "data": {
            "flow": null,
            "type": "OUT",
            "uuid": "bf651b97-722f-400b-b96f-3e56fe182cfe",
            "pegged": false,
            "refund": {
                "flow": null,
                "type": "IN",
                "uuid": "ad5c2cfc-6ec3-4e51-96f1-03dfad8efc11",
                "pegged": false,
                "refund": null,
                "status": "COMPLETE",
                "address": {
                    "tag": null,
                    "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x27f9bfa4e6782671e9224c5debdf4350a28bc728&uint256=2E+6",
                    "address": "0x27f9bfa4e6782671e9224c5debdf4350a28bc728",
                    "network": "ETHEREUM",
                    "alternatives": []
                },
                "refunds": [],
                "subType": "merchantPayIn",
                "twoStep": false,
                "metadata": {},
                "reference": "RefundWebhook1",
                "returnUrl": "",
                "customerId": "234850085",
                "expiryDate": 1753352469000,
                "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
                "dateCreated": 1753352169000,
                "displayRate": {
                    "base": "USDC",
                    "rate": 1,
                    "counter": "USDC"
                },
                "feeCurrency": {
                    "actual": 0.014,
                    "amount": 0.014,
                    "currency": "USDC"
                },
                "quoteStatus": "ACCEPTED",
                "redirectUrl": "https://pay.bvnk.com/payin/ad5c2cfc-6ec3-4e51-96f1-03dfad8efc11",
                "exchangeRate": {
                    "base": "USDC",
                    "rate": 1,
                    "counter": "USDC"
                },
                "paidCurrency": {
                    "actual": 5,
                    "amount": 2,
                    "currency": "USDC"
                },
                "transactions": [
                    {
                        "hash": "0x7551bf6f17e2d354f21415bdc46234872d6cc9cce1f504259bb72326b9e53b34",
                        "amount": 5,
                        "sources": [
                            "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723"
                        ],
                        "isOnHold": false,
                        "network": "ETHEREUM",
                        "dateCreated": 1753352226000,
                        "displayRate": {
                            "base": "USDC",
                            "rate": 1,
                            "counter": "USDC"
                        },
                        "exchangeRate": {
                            "base": "USDC",
                            "rate": 1,
                            "counter": "USDC"
                        },
                        "dateConfirmed": 1753352291000,
                        "networkFeeAmount": 0.000148,
                        "networkFeeCurrency": "USDC"
                    }
                ],
                "walletCurrency": {
                    "actual": 2,
                    "amount": 2,
                    "currency": "USDC"
                },
                "currencyOptions": null,
                "displayCurrency": {
                    "actual": 2,
                    "amount": 2,
                    "currency": "USDC"
                },
                "quoteExpiryDate": 1753352469000,
                "networkFeeCurrency": {
                    "actual": 0,
                    "amount": 0,
                    "currency": null
                },
                "merchantDisplayName": "Merch_arch",
                "acceptanceExpiryDate": 1753352199000
            },
            "status": "PENDING",
            "address": null,
            "refunds": [],
            "subType": "merchantRefund",
            "twoStep": false,
            "metadata": {},
            "reference": "REFUND-RefundWebhook1-296593287",
            "returnUrl": "",
            "customerId": "487548579",
            "expiryDate": 1761236291296,
            "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
            "dateCreated": 1753352291000,
            "displayRate": null,
            "feeCurrency": {
                "actual": 5.003059,
                "amount": 5.003059,
                "currency": "USDC"
            },
            "quoteStatus": "TEMPLATE",
            "redirectUrl": "https://pay.bvnk.com/payout/bf651b97-722f-400b-b96f-3e56fe182cfe",
            "exchangeRate": null,
            "paidCurrency": {
                "actual": 0,
                "amount": 0,
                "currency": null
            },
            "transactions": [],
            "walletCurrency": {
                "actual": 0,
                "amount": 3,
                "currency": "USDC"
            },
            "currencyOptions": null,
            "displayCurrency": {
                "actual": 0,
                "amount": 3,
                "currency": "USDC"
            },
            "quoteExpiryDate": null,
            "networkFeeCurrency": null,
            "merchantDisplayName": "Merch_arch",
            "acceptanceExpiryDate": null
        }
    }
    ```
  </TabItem>
  <TabItem value="expired" label="Refund Initiated: Expired">

    ```json Refund Initiated: Expired
    {
        "event": "bvnk:payment:crypto:refund-initiated",
        "eventId": "01983c00-5c32-77c1-9cfe-984d7d2efa6a",
        "timestamp": "2025-07-24T10:35:13.330886600Z",
        "data": {
            "flow": null,
            "type": "OUT",
            "uuid": "3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
            "pegged": false,
            "refund": {
                "flow": null,
                "type": "IN",
                "uuid": "f7c7adca-7e3a-4fcc-9cb1-87e36668a8b2",
                "pegged": false,
                "refund": null,
                "status": "EXPIRED",
                "address": {
                    "tag": null,
                    "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x632cbf94b236419c63f23867a89f4beded3ee3da&uint256=2E+6",
                    "address": "0x632cbf94b236419c63f23867a89f4beded3ee3da",
                    "network": "ETHEREUM",
                    "alternatives": []
                },
                "refunds": [],
                "subType": "merchantPayIn",
                "twoStep": false,
                "metadata": {},
                "reference": "RefundWebhook",
                "returnUrl": "",
                "customerId": "487548579",
                "expiryDate": 1753350971000,
                "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
                "dateCreated": 1753350575000,
                "displayRate": {
                    "base": "USDC",
                    "rate": 1,
                    "counter": "USDC"
                },
                "feeCurrency": {
                    "actual": 0,
                    "amount": 0.014,
                    "currency": "USDC"
                },
                "quoteStatus": "ACCEPTED",
                "redirectUrl": "https://pay.bvnk.com/payin/f7c7adca-7e3a-4fcc-9cb1-87e36668a8b2",
                "exchangeRate": {
                    "base": "USDC",
                    "rate": 1,
                    "counter": "USDC"
                },
                "paidCurrency": {
                    "actual": 5,
                    "amount": 2,
                    "currency": "USDC"
                },
                "transactions": [
                    {
                        "hash": "0x8c29b2b0c6d841b550783c797d3b9668675c05fb17d56db1c9d2172db2536d0e",
                        "amount": 5,
                        "sources": [
                            "0xa59d9f28537a3a9ee18e76a9fce8261b0ca33723"
                        ],
                        "isOnHold": false,
                        "network": "ETHEREUM",
                        "dateCreated": 1753353196000,
                        "displayRate": {
                            "base": "USDC",
                            "rate": 1,
                            "counter": "USDC"
                        },
                        "exchangeRate": {
                            "base": "USDC",
                            "rate": 1,
                            "counter": "USDC"
                        },
                        "dateConfirmed": 1753353312000,
                        "networkFeeAmount": 0.00011,
                        "networkFeeCurrency": "USDC"
                    }
                ],
                "walletCurrency": {
                    "actual": 0,
                    "amount": 2,
                    "currency": "USDC"
                },
                "currencyOptions": null,
                "displayCurrency": {
                    "actual": 0,
                    "amount": 2,
                    "currency": "USDC"
                },
                "quoteExpiryDate": 1753350875000,
                "networkFeeCurrency": {
                    "actual": 0,
                    "amount": 0,
                    "currency": null
                },
                "merchantDisplayName": "Merch_arch",
                "acceptanceExpiryDate": 1753350605000
            },
            "status": "PENDING",
            "address": null,
            "refunds": [],
            "subType": "merchantRefund",
            "twoStep": false,
            "metadata": {},
            "reference": "RefundWebhook-318302166",
            "returnUrl": "",
            "customerId": "487548579",
            "expiryDate": 1761237313318,
            "merchantId": "a1050da2-b085-4a6c-a68b-8c2b1950615a",
            "dateCreated": 1753353313000,
            "displayRate": null,
            "feeCurrency": {
                "actual": 5.003059,
                "amount": 5.003059,
                "currency": "USDC"
            },
            "quoteStatus": "TEMPLATE",
            "redirectUrl": "https://pay.bvnk.com/payout/3b38d6e1-51b4-4c46-9ce5-1d17ac9f7449",
            "exchangeRate": null,
            "paidCurrency": {
                "actual": 0,
                "amount": 0,
                "currency": null
            },
            "transactions": [],
            "walletCurrency": {
                "actual": 0,
                "amount": 5,
                "currency": "USDC"
            },
            "currencyOptions": null,
            "displayCurrency": {
                "actual": 0,
                "amount": 5,
                "currency": "USDC"
            },
            "quoteExpiryDate": null,
            "networkFeeCurrency": null,
            "merchantDisplayName": "Merch_arch",
            "acceptanceExpiryDate": null
        }
    }
    ```

  </TabItem>
</Tabs>

## Transaction on hold

`bvnk:payment:crypto:transaction-on-hold`

```json
{
  "event": "bvnk:payment:crypto:transaction-on-hold",
  "eventId": "01998078-3e41-7a64-92f2-d3c6f3713e95",
  "timestamp": "2025-09-25T10:43:07.969870Z",
  "data": {
    "flow": null,
    "type": "OUT",
    "uuid": "01998078-0eda-7794-a3aa-97566f9c04e0",
    "pegged": false,
    "refund": null,
    "status": "PROCESSING",
    "address": {
      "tag": null,
      "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x52a2cf95A494Cc7A39D9Cfa6ceF8fB43D1E3993e&uint256=7107892",
      "address": "0x52a2cf95A494Cc7A39D9Cfa6ceF8fB43D1E3993e",
      "network": "ETHEREUM",
      "alternatives": []
    },
    "refunds": [],
    "subType": "merchantPayOut",
    "twoStep": false,
    "metadata": {},
    "walletId": "a:24072237783989:Unkx9kW:1",
    "reference": "dc6d9706-020c-4a83-87db-0fbca9f11afd",
    "returnUrl": "",
    "customerId": "0e493702-f408-4a56-b842-603ac9058253",
    "expiryDate": 1758883376000,
    "merchantId": "19eda61c-aabc-4186-8ab1-46a3da181bb6",
    "dateCreated": 1758796976000,
    "displayRate": {
      "base": "USDC",
      "rate": 1.001703458634,
      "counter": "USD"
    },
    "feeCurrency": {
      "actual": 0,
      "amount": 0.07,
      "currency": "USD"
    },
    "quoteStatus": "ACCEPTED",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payout/01998078-0eda-7794-a3aa-97566f9c04e0",
    "exchangeRate": {
      "base": "USD",
      "rate": 0.998299489847,
      "counter": "USDC"
    },
    "paidCurrency": {
      "actual": 0,
      "amount": 7.107892,
      "currency": "USDC"
    },
    "transactions": [
      {
        "hash": null,
        "amount": 7.107892,
        "sources": [],
        "isOnHold": true,
        "network": "ETHEREUM",
        "dateCreated": 1758796988000,
        "displayRate": {
          "base": "USDC",
          "rate": 1.001703458634,
          "counter": "USD"
        },
        "exchangeRate": {
          "base": "USD",
          "rate": 0.9982994898469539,
          "counter": "USDC"
        },
        "dateConfirmed": null,
        "networkFeeAmount": 0,
        "networkFeeCurrency": "USDC"
      }
    ],
    "walletCurrency": {
      "actual": 7.12,
      "amount": 7.12,
      "currency": "USD"
    },
    "currencyOptions": null,
    "displayCurrency": {
      "actual": 0,
      "amount": 7.12,
      "currency": "USD"
    },
    "quoteExpiryDate": 1758800577000,
    "networkFeeCurrency": {
      "actual": 0,
      "amount": 1.76,
      "currency": "USD"
    },
    "merchantDisplayName": "USD Merchant",
    "acceptanceExpiryDate": 1758797007000,
    "embeddedCustomerDetails": {
      "reference": null,
      "externalReference": "givanov-airbnb-custom-ref123"
    }
  }
}
```

## Webhook fields

| Field | Description |
|-------|-------------|
| `event` | Type of the event triggering the webhook. |
| `eventId` | Unique identifier for the event. |
| `timestamp` | Timestamp of when the event occurred. |
| `data.flow` | Flow type of the payment. |
| `data.type` | Type of the payment event. |
| `data.uuid` | Unique identifier for the payout transaction. |
| `data.pegged` | Whether the payment is pegged. |
| `data.refund` | Refund information for the payment. |
| `data.status` | Status of the payout. Possible values:• `PENDING`• `PROCESSING`• `PENDING_APPROVAL`• `ON_HOLD`• `COMPLETED`• `EXPIRED`• `CANCELLED`• `FAILED`• `RETURNED` |
| `data.address` | Payment address information. |
| `data.address.address` | The actual payment address. |
| `data.address.alternatives` | Alternative addresses for the payment. |
| `data.address.network` | Network of the payment address (e.g., ETHEREUM). |
| `data.address.protocol` | Protocol of the payment address (e.g., ERC20). |
| `data.address.tag` | Tag associated with the payment address. |
| `data.address.uri` | URI of the payment address. |
| `data.refunds` | List of refunds associated with the payment. |
| `data.subType` | Subtype of the payment (e.g., merchantPayOut, merchantRefund, merchantPayIn). |
| `data.twoStep` | Whether the payment requires a [two-step process](../pay-out-to-your-users?advanced-crypto-payouts=two-step-payout#integrate-advanced-payout-capabilities). |
| `data.metadata` | Additional metadata associated with the webhook event. |
| `data.reference` | Reference identifier for the payment. |
| `data.returnUrl` | URL to return to after payment completion. |
| `data.customerId` | Unique identifier of the customer. |
| `data.expiryDate` | Expiry date of the payment. |
| `data.merchantId` | Unique identifier of the merchant. |
| `data.dateCreated` | Timestamp when the payment was created. |
| `data.displayRate` | Display rate information for the payment. |
| `data.feeCurrency` | Fee currency information including amount and currency. |
| `data.quoteStatus` | Status of the quote (e.g., ACCEPTED, TEMPLATE). |
| `data.redirectUrl` | URL to redirect to for payment processing. |
| `data.exchangeRate` | Exchange rate information for the payment. |
| `data.paidCurrency` | Paid currency information including amount and currency. |
| `data.transactions` | Array of transaction details. |
| `data.transactions[].amount` | Amount of the transaction. |
| `data.transactions[].dateConfirmed` | Date when the transaction was confirmed. |
| `data.transactions[].dateCreated` | Date when the transaction was created. |
| `data.transactions[].displayRate` | Display rate for the transaction. |
| `data.transactions[].exchangeRate` | Exchange rate for the transaction. |
| `data.transactions[].hash` | Hash of the transaction. |
| `data.transactions[].isOnHold` | Whether the transaction is on hold. |
| `data.transactions[].networkFeeAmount` | Network fee amount for the transaction. |
| `data.transactions[].networkFeeCurrency` | Currency of the network fee. |
| `data.transactions[].protocol` | Protocol of the transaction (e.g., ERC20). |
| `data.transactions[].sources` | Source addresses for the transaction. |
| `data.walletCurrency` | Wallet currency information including amount and currency. |
| `data.currencyOptions` | Available currency options for the payment. |
| `data.displayCurrency` | Display currency information including amount and currency. |
| `data.quoteExpiryDate` | Expiry date of the quote. |
| `data.networkFeeCurrency` | Network fee currency information including amount and currency. |
| `data.merchantDisplayName` | Display name of the merchant. |
| `data.acceptanceExpiryDate` | Expiry date for payment acceptance. |
| `data.walletId` | Unique identifier of the wallet. |
| `data.embeddedCustomerDetails` | Embedded customer details including reference and external reference. |
| `data.id` | Unique identifier for the payout transaction. |
| `data.fees.customerFee.amount` | Amount of the customer fee. |
| `data.fees.customerFee.currency` | Currency code of the customer fee. |
| `data.fees.processingFee.amount` | Amount of the processing fee. |
| `data.fees.processingFee.currency` | Currency code of the processing fee. |
| `data.method` | Payment method used for the payout. Possible values:• `CRYPTO` (Only for crypto payouts. Not applicable to fiat)• `WALLET`• `CARD` (Only for crypto payouts. Not applicable to fiat)• `SEPA_CT`• `SEPA_INST`• `FASTER_PAYMENT`• `SWIFT`• `ACH`• `ACH_SAME_DAY`• `FEDWIRE`• `FEDNOW`• `RTP`• `BOOK`• `UNKNOWN` |
| `data.createdAt` | Timestamp when the payout was created. |
| `data.direction` | Direction of the payment: incoming (IN) or outgoing (OUT). |
| `data.updatedAt` | Timestamp when the payout was last updated. |
| `data.originator.amount` | Amount sent by the originator. |
| `data.originator.customerId` | Unique identifier of the customer. |
| `data.originator.currency` | Currency code of the originator amount. |
| `data.originator.entity.legalName` | Legal name of the sender entity. |
| `data.originator.entity.type` | Type of the sender entity. |
| `data.originator.walletId` | Wallet ID of the <Term popup="The entity that initiates the transaction. For example, a customer that wants to buy crypto with fiat currency." reference="../../../references/glossary#originator">Originator</Term>. |
| `data.beneficiary.amount` | Amount received by the <Term popup="The entity that receives the transaction.">Beneficiary</Term>. |
| `data.beneficiary.currency` | Currency code of the beneficiary amount. |
| `data.beneficiary.entity.address.addressLine1` | First line of the beneficiary's address. |
| `data.beneficiary.entity.address.addressLine2` | Second line of the <Term popup="The entity that receives the transaction.">Beneficiary</Term>'s address. |
| `data.beneficiary.entity.address.city` | City of the <Term popup="The entity that receives the transaction.">Beneficiary</Term>'s address. |
| `data.beneficiary.entity.address.country` | Country code of the <Term popup="The entity that receives the transaction.">Beneficiary</Term>'s address. |
| `data.beneficiary.entity.address.postCode` | Postal code of the beneficiary's address. |
| `data.beneficiary.entity.address.region` | Region/state of the beneficiary's address. |
| `data.beneficiary.entity.dateOfBirth` | Date of birth of the beneficiary. |
| `data.beneficiary.entity.firstName` | First name of the beneficiary for individuals. |
| `data.beneficiary.entity.lastName` | Last name of the beneficiary for individuals. |
| `data.beneficiary.entity.relationshipType` | Relationship type of the beneficiary. |
| `data.beneficiary.entity.type` | Type of the beneficiary entity. |
| `data.beneficiary.bankAccount.accountNumber` | Account number of the beneficiary. |
| `data.beneficiary.bankAccount.accountNumberFormat` | Format of the account number of the beneficiary. |
| `data.beneficiary.bankAccount.bank.address.addressLine1` | First line of the bank's address. |
| `data.beneficiary.bankAccount.bank.address.addressLine2` | Second line of the bank's address. |
| `data.beneficiary.bankAccount.bank.address.city` | City of the bank's address. |
| `data.beneficiary.bankAccount.bank.address.country` | Country code of the bank's address. |
| `data.beneficiary.bankAccount.bank.address.postCode` | Postal code of the bank's address. |
| `data.beneficiary.bankAccount.bank.address.region` | Region/state of the bank's address. |
| `data.beneficiary.bankAccount.bank.identificationCode` | Bank identification code (BIC/SWIFT). |
| `data.beneficiary.bankAccount.bank.nid` | National identifier of the beneficiary's bank. |
| `data.beneficiary.bankAccount.intermediaryBanks` | List of intermediary banks involved in the transaction. |
| `data.beneficiary.remittanceInformation` | Additional information for the payment. |
| `metadata` | Additional metadata associated with the webhook event. |

---

## Underpayments

Underpayments occur when end-users do not transfer enough cryptocurrency to fulfill their payment obligation.

This can occur if the end user is charged a network fee by their exchange platform that exceeds the amount they anticipated from their payment. Furthermore, the end user might unintentionally send less than intended (e.g. they mean to send 0.1 ETH but send 0.01 ETH instead). In this situation, the payment will still transition to the `UNDERPAID` status.

To give greater flexibility to your end-users on how much they send [crypto top-ups](doc:adding-crypto-top-ups) is recommended.

## How can I see the actual amount received?

To see the actual received amount, on the `transactionConfirmed` webhook, compare the fields:

* `paidCurrency.actual` indicates the amount you actually received.
* `paidCurrency.amount` indicates the original expected amount.

## Handle underpayments

To ensure the best customer experience when managing underpayments, it's advisable to adjust the end user's final payment to reflect the lower total amount received. This approach prevents the need to return the entire sum of crypto, which may be slightly less than expected due to fees or rounding errors, and instead, credits the revised amount to the end user's account.

The sent amount is indicated in the `.actual` fields referenced in the preceding section, which can then be utilized to modify the end user's total payment amount in your system, aligning with the `.amount` field.

There is the **Settle Merchant Wallet** setting, where the total sent amount will be deposited into the MID wallet that was linked to the transaction.

In certain circumstances, when it is essential that the full amount is received, and an underpayment does not fulfill this need,  two alternative options can be used:

* **Handle manually** will retain the payment in its originally sent cryptocurrency and deposit it into an equivalent cryptocurrency wallet on your account. No funds are sent to the MID-linked wallet. You can then use the payout functionality to manually return the excess amount to the end user if required, or manually convert to the MID-linked wallet at a new FX spot rate.
* [**Auto Refund**](../auto-refund-payments) will generate an automatic payout request for the full underpaid amount, keeping it separate from any account wallets and generating a URL. This URL must be sent to the end user for final confirmation of the address where the returned funds should be sent.

  >**Example**: the customer must pay 300 USDC but deposits 100 USDC instead. You decide to return 100 USDC stating that the amount is incorrect. The payment refund request is generated and the link is automatically sent to a customer so they can claim the funds. The link remains active for three months. If the customer doesn't claim the funds within this period, the funds are settled into the customer's account.

## Overpayment exception flows

The summary of the flow for three different outcomes is given below:

| Configuration              | Balance impact                                                                                                                                                                                                            | Status                         |
| :------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :----------------------------- |
| **Settle Merchant Wallet** | Received amount is credited to your MID wallet in your wallet currency. For more information on a MID wallet, refer to the merchant setup guide. | `UNDERPAID`                    |
| **Handle Manually**        | Received amount is deposited into the merchant cryptocurrency wallet.                                                                                                                                                     | `UNDERPAID`                    |
| [**Auto Refund**](../auto-refund-payments)  | Functions similarly to **Handle Manually**, except it is done automatically for you. The total amount of cryptocurrency received is attributed to a new refund payout that will be automatically created. | `UNDERPAID`, `PENDING`(refund) |

![](/img/bvnk/use-cases/underpayments-flow.png)

:::note
To change your configuration or learn more, contact your Account or Integration Manager.
:::

## Settlement webhook

To get notified when the transaction has been fully processed and settled, listen to the [Cryptocurrency transaction settled webhook](../../../api-explorer/bvnk-webhooks/crypto-transaction-settled/).

---

## Charge Customer Fees(Unprocessed)

As a partner, you can add a markup fee to your customers' transactions, enabling you to collect additional revenue from your Customers.

These customer fees are optional charges. They are separate from the transaction amount and transaction fees and are collected from the customer's wallet.

## Implement customer fees

To add a customer fee to a transaction, include the `customerFee` object in your API request:

```json Example Payload with Customer Fee
{
    "type": "OUT",
     "fees": {
        "customerFee": {
            "currency": "USD",
            "amount": 1
        }
    }
}
```

The example use case for charging the customer fees may look as follows:

1. Send the [`GET /api/wallet`](ref:walletlist) request to acquire the list of your existing wallets with details.

   In the response, find a wallet to which you plan to deposit fees and copy its `lsid` value.

   ```json Get wallets list 
   [
       {
           "id": 3683091,
           "description": "USDC Wallet",
           "currency": {
               "id": 1773,
               "code": "USDC",
               "fiat": true,
               "icon": null,
               "name": "Euro",
               "withdrawalParameters": [],
               "options": {},
               "withdrawalFee": 0.4,
               "depositFee": 0,
               "supportsDeposits": true,
               "supportsWithdrawals": true,
               "quantityPrecision": 2,
               "pricePrecision": 5,
               "protocols": []
           },
           "lsid": "a:25041552279666:vpH2wtz:1",
           "status": "ACTIVE"
       }
   ]
   ```

   The selected wallet's currency should match the currency of the fees you are charging.

   You may use both fiat and crypto wallets, configuring an existing wallet or creating a new one for fees.
2. Designate the selected wallet as the fee destination by sending the [`PUT /platform/v1/fees/customer-fee-wallets`](ref:setcustomerfeewallet) request. Include the following payload:
   ```json Example Request Payload
   {
       "destinationWalletId": "a:25041552279666:vpH2wtz:1",
       "currency": "USDC"
   }
   ```
   Here, "a:25041552279666:vpH2wtz:1" is `lsid` from step 1.
3. Check that your selected wallet can receive customer fees by sending the [`GET /platform/v1/fees/customer-fee-wallets`](https://docs.bvnk.com/api-explorer/getcustomerfeewallets#/) request.

   In the response, you receive the list of wallets that will be used for accepting customer fees. The wallet with the `lsid` specified earlier must be listed here.

   ```json Wallets to Accept Customer Fees
   {
       "content": [
           {
               "destinationWalletId": "a:25041552279666:vpH2wtz:1",
               "currency": "USDC"
           },
           {
               "destinationWalletId": "a:38472618394521:kLm9xRs:1",
               "currency": "USDC"
           }
       ],
       "pageable": {
           "pageNumber": 0,
           "pageSize": 20,
           "sort": [],
           "offset": 0,
           "paged": true,
           "unpaged": false
       },
       "first": true,
       "last": true,
       "size": 20,
       "number": 0,
       "sort": [],
       "numberOfElements": 2,
       "empty": false
   }
   ```

   Now, your wallet is configured for receiving customer fees.
4. To apply the fee, when creating [payment requests](ref:paymentcreate), include the customer fee information in the `fees` object:
   ```json Example Payload with Customer Fee for Crypto
   {
       "walletId": "a:25022613287255:zmHs0pg:1",
       "amount": 100,
       "currency": "USDC",
       "reference": "REF182597",
       "type": "OUT",
       "fees": {
           "customerFee": {
               "currency": "USDC",
               "amount": 1
           }
       }
   }
   ```
   ```json Example Payload with Customer Fee for Fiat
   {
   	"walletId": "a:24071743000626:go5SB1l:1",
       "amount": {
           "value": "100.00",
           "currency": "USD"
       },
   		"customerFee": {
           "value": "20.00",
           "currency": "USD"
       },
       "paymentReference": "Ref112455",
       "instruction": {
         "type": "FIAT",
         "paymentMethod": "ACH",
         "beneficiary": {
               "details": {
                   "beneficiaryType": "SELF_OWNED",
                   "transferDestination": "LOCAL",
                   "currency": "USD",
                   "businessDetails": {
                       "businessName": "Company ABC"
                   },
                   "address": {
                       "addressLine1": "Some address Line 1",
                       "addressLine2": "Some address Line 2",
                       "city": "Some city",
                       "region": "Some region",
                       "postCode": "ABCDEF",
                       "country": "US"
                   },
                   "bankDetails": {
                       "accountNumber": "2152209165",
                       "accountType": "CHECKING",
                       "code": "021214891"
                   }
               }
           }
       },
       "requestDetails": {
           "originator": {
               "ipAddress": "5.57.72.118"
           }
       },
       "metadata": {
           "someKey": "someValue",
           "someKey2": {
               "someKey3": "someValue3"
           }
       }
   }
   ```

When implemented correctly, the fee-charging process works as follows:

1. The system calculates the total transaction amount (payment amount + customer fee)
2. During payment processing, the customer fee is:
   * Deducted from the EPC's wallet.
   * Transferred to your designated fee wallet.
3. The full payment amount (excluding fees) is sent to the recipient

This approach ensures transparent fee management while maintaining accurate transaction accounting.

Here's an example of how the customer fee is calculated:

:::info 📘 Example calculation

When you receive the amount of $100 from customer Jane and charge a $0.50 EP customer fee, Jane must have a minimum balance of $100.75 in her wallet (transaction amount $100 + BVNK fee $0.25 + customer fee $0.50). After a successful transaction,

* Jane's initial wallet balance was $100.75. The current balance is now $0.
* Amount credited to your designated fee wallet is $0.50.
:::

## Important Considerations

* **Outgoing payments**: Currently, the customer fees are only supported for payment `type: OUT`.
  Make sure the EPC's wallet has enough funds to cover the customer fee. If fees like network or customer fees cannot be covered, the transaction is cancelled.
* **Fee Structure**: Customer fees are implemented as a flat fee, a fixed predetermined price, per transaction.
* **Optional**: You are not required to charge customer fees. Transactions can be processed without additional fees if desired.

## Error Handling

If the EPC's wallet does not have enough funds for the customer fee, you have two options:

* Return an "insufficient funds" error to the user. In this case, the transaction is cancelled.
* Reduce the transaction amount to accommodate the fee. This ensures the total (transaction amount plus fee) does not exceed the available balance.

---

## Accept Stablecoin Pay-in with 1:1 Peg

This feature is a part of Payment Links product and offers customers a 1:1 exchange rate for Stablecoin to USD incoming payments. The stablecoin amount is automatically adjusted to maintain parity with the display currency, ensuring customers receive the exact equivalent regardless of market fluctuations. Any necessary adjustments are handled as fees charged to a specified Partner wallet.

:::warning 🚧 If you're a Merchant

Contact your Account Manager to enable 1:1 stablecoin peg.
:::

To create a payment with a 1:1 peg, send the [`POST /v1/pay/summary`](../../../api-explorer/endpoints/payment-create) request with the following body parameters.

To add custom metadata, include a top-level JSON object with the key `metadata` to the request. The metadata will be associated with the payment and added to the webhook events related to this payment.

```json Example Request
{
  "walletId": "{{wallet_id}}",
  "type": "IN",
  "amount": 100,
  "currency": "USD",
  "expiryMinutes": 30,
  "embeddedPartnerWalletId": "a:25021382554759:6kmtunl:1",
  "reference": "EmbeddedPegTest3",
  "returnUrl": "https://your-url-here.com/status",
  "customerId": "ba388054-4512-441e-a9c4-cbe9b0fe033a",
  "complianceDetails": {
    "requesterIpAddress": "77.71.188.87",
    "partyDetails": [
      {
        "type": "ORIGINATOR",
        "entityType": "INDIVIDUAL",
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-10-25",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "UK"
      }
    ]
  }
}
```

```json Example Request with Metadata
{
  "walletId": "{{wallet_id}}",
  "type": "IN",
  "amount": 100,
  "currency": "USD",
  "expiryMinutes": 30,
  "embeddedPartnerWalletId": "a:25021382554759:6kmtunl:1",
  "reference": "EmbeddedPegTest3",
  "returnUrl": "https://your-url-here.com/status",
  "customerId": "ba388054-4512-441e-a9c4-cbe9b0fe033a",
  "complianceDetails": {
    "requesterIpAddress": "77.71.188.87",
    "partyDetails": [
      {
        "type": "ORIGINATOR",
        "entityType": "INDIVIDUAL",
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1990-10-25",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "UK"
      }
    ]
  },
  "metadata": {
    "orderId": "PO-2025-002",
    "internalUserId": "user-789",
    "serviceType": "premium"
  }
}
```

| Parameter                              | Type    | Required | Description                                                      |
| -------------------------------------- | ------- | -------- | ---------------------------------------------------------------- |
| `walletId`                             | string  | Yes      | The Wallet ID of your customer                                   |
| `type`                                 | string  | Yes      | "IN" for incoming payment. Currently, only pay-ins are supported |
| `amount`                               | long    | Yes      | The amount required to complete the payment                      |
| `currency`                             | string  | Yes      | Currency code displayed to the user (e.g., "USD")                |
| `expiryMinutes`                        | integer | No       | Optional time limit for payment. Defaults to 20 minutes          |
| `embeddedPartnerWalletId`              | string  | Yes      | Wallet LSID to account for peg adjustment fees                   |
| `reference`                            | string  | Yes      | A reference visible to the customer and merchant                 |
| `returnUrl`                            | string  | No       | URL for redirection after payment                                |
| `customerId`                           | string  | No       | The ID of your customer                                          |
| `complianceDetails`                    | object  | No       | Details required for compliance checks                           |
| `complianceDetails.requesterIpAddress` | string  | No       | IP address of the requester                                      |
| `complianceDetails.partyDetails`       | array   | No       | Parties involved in the transaction                              |
| `partyDetails[].type`                  | string  | No       | Type of party (e.g., "ORIGINATOR")                               |
| `partyDetails[].entityType`            | string  | No       | "INDIVIDUAL" or "COMPANY"                                        |
| `partyDetails[].firstName`             | string  | No       | First name                                                       |
| `partyDetails[].lastName`              | string  | No       | Last name                                                        |
| `partyDetails[].dateOfBirth`           | string  | No       | Format: `YYYY-MM-DD`                                             |
| `partyDetails[].relationshipType`      | string  | No       | "SELF" or "THIRD\_PARTY"                                         |
| `partyDetails[].countryCode`           | string  | No       | ISO 3166-1 alpha-2 code (e.g., "UK")                             |

After a 1:1 pegged payment has been received successfully, you'll receive a response similar to the following. Note the `pegStablecoinDetails` and `pegged` fields.

```json
{
  "source": "payment",
  "event": "statusChanged",
  "data": {
    "uuid": "1f718f59-4f44-420b-9211-a354f4f0d8ef",
    "merchantDisplayName": "ach test",
    "merchantId": "5c91a2c9-1cb7-4af7-a5d9-03f997c647e5",
    "dateCreated": 1748507102000,
    "expiryDate": 1748508902000,
    "quoteExpiryDate": 1748508902000,
    "acceptanceExpiryDate": 1748507231000,
    "quoteStatus": "ACCEPTED",
    "reference": "EmbeddedPegTest1",
    "type": "IN",
    "subType": "merchantPayIn",
    "status": "COMPLETE",
    "displayCurrency": {
      "currency": "USD",
      "amount": 100,
      "actual": 50
    },
    "walletCurrency": {
      "currency": "USD",
      "amount": 100,
      "actual": 50
    },
    "paidCurrency": {
      "currency": "USDC",
      "amount": 200,
      "actual": 100
    },
    "feeCurrency": {
      "currency": "USD",
      "amount": 1,
      "actual": 1
    },
    "networkFeeCurrency": {
      "currency": null,
      "amount": 0,
      "actual": 0
    },
    "displayRate": {
      "base": "USDC",
      "counter": "USD",
      "rate": 0.5
    },
    "exchangeRate": {
      "base": "USDC",
      "counter": "USD",
      "rate": 0.5
    },
    "address": {
      "address": "0x47f622a092d208a6ecb1432dd4a0696c557b2a53",
      "tag": null,
      "network": "ETHEREUM",
      "uri": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48/transfer?address=0x47f622a092d208a6ecb1432dd4a0696c557b2a53&uint256=2E+8",
      "alternatives": []
    },
    "returnUrl": "https://your-url-here.com/status",
    "redirectUrl": "https://pay.sandbox.bvnk.com/payin/1f718f59-4f44-420b-9211-a354f4f0d8ef",
    "transactions": [
      {
        "dateCreated": 1748507322000,
        "dateConfirmed": 1748507372000,
        "hash": "0xa8522a3bba06edf5de248082cbc65b03a10fda2b655bea5e0abd7e7dbb8512e9",
        "amount": 100,
        "networkFeeCurrency": "USDC",
        "networkFeeAmount": 0.000086,
        "sources": [
          "0xa7d78498f7010e8ffac098d0b3a208c46896e00d"
        ],
        "displayRate": {
          "base": "USDC",
          "counter": "USD",
          "rate": 0.5
        },
        "exchangeRate": {
          "base": "USDC",
          "counter": "USD",
          "rate": 0.5
        },
        "network": "ETHEREUM",
        "isOnHold": false
      }
    ],
    "refund": null,
    "refunds": [],
    "currencyOptions": null,
    "flow": null,
    "twoStep": false,
    "metadata": {},
    "customerId": "ba388054-4512-441e-a9c4-cbe9b0fe033a",
    "pegStablecoinDetails": {
      "paidCurrency": {
        "currency": "USDC",
        "amount": 100,
        "actual": 100
      },
      "pegRateAdjustmentFee": {
        "currency": "USD",
        "amount": -50,
        "actual": -50
      },
      "exchangeRate": {
        "base": "USDC",
        "counter": "USD",
        "rate": 1
      }
    },
    "pegged": true
  }
}
```

:::info 📘 Use the `redirectUrl` from the response

Use the `redirectUrl` from the response to redirect the customer to the payment page.
:::

---

## Provide party information for crypto payments

# Why should I supply additional information?

In established payment systems like credit card and bank transfers, collecting and sharing information about the parties involved in a transaction (such as names) is already standard practice. This same requirement is now being applied to crypto and stablecoin payments through the Travel Rule as part of the EU's MiCA regulation for crypto assets.

The Travel Rule brings greater regulatory clarity and data transparency to crypto, allowing businesses that use stablecoins and other cryptocurrencies to grow in a more secure environment. As crypto becomes a more trusted payment option, we expect more businesses, consumers, and financial institutions to embrace this rapidly expanding market.

More background on this can be found on [https://www.bvnk.com/blog/the-travel-rule-crypto-eu](https://www.bvnk.com/blog/the-travel-rule-crypto-eu)

# What should I do to comply?

:::info 📘 If you have an API integration

to initiate payments in and out, then you will need to update your integration to start including the additional data. Below is a list of the affected endpoints that will require the additional data.
:::

If you are initiating payments solely from within the BVNK Portal, you will be prompted to include the additional data where applicable within the UI.

# By when must the changes be implemented?

:::tip 👍 The changes must be implemented by December 30, 2024.
:::

## Affected API endpoints

If you are using these endpoints, please make sure to update the integration as per the examples below.

| Product | Used for | Endpoint |
| :------ | :------ | :------- |
| Crypto paymentsvia Payment Links | DepositsPayouts | * PROD: `https://api.bvnk.com/api/v1/pay/summary`* Sandbox: `https://api.sandbox.bvnk.com/api/v1/pay/summary` |
| Crypto paymentsvia Payment Channels | Deposits | * PROD: `https://api.bvnk.com/api/v2/channel`* SANDBOX: `https://api.sandbox.bvnk.com/api/v2/channel` |

## Supplying the additional data

```json Payment to an Individual
"customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
  "complianceDetails": {
    "requesterIpAddress": "77.71.188.87",
    "partyDetails": [
      {
        "type": "ORIGINATOR",
        "entityType": "INDIVIDUAL",
        "firstName": "John",
        "lastName": "Doe",
        "dateOfBirth": "1984-06-30",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "DE",
        "regionCode": "null"
      }
    ]
```

```json Payment to a Business
"customerId": "b061943d-e29f-481e-abcb-5c937ee8234e",
  "complianceDetails": {
    "requesterIpAddress": "77.71.188.87",
    "partyDetails": [
      {
        "type": "ORIGINATOR",
        "entityType": "COMPANY",
        "legalName": "Fast Cars LTD",
        "registrationNumber": "ABC123",
        "relationshipType": "THIRD_PARTY",
        "countryCode": "DE",
        "regionCode": "null"
      }
    ]
```

| Parameter | Type | Required | Description |
| :-------- | :--- | :------- | :---------- |
| `customerId` | String | Yes | Uniquely identifying the party requesting the payment. If multiple payments for same party are requested, the ID should remain consistent. |
| `complianceDetails` | Object | Yes | Will contain information about the party requesting the deposit. |
| `complianceDetails.requesterIpAddress` | String | Yes | The IP-address of the party requesting the deposit.Required only if `countryCode` is not provided. |
| `complianceDetails.partyDetails` | Array of Objects | Yes | Will contain additional information about the party requesting the payment. |
| `complianceDetails.partyDetails.type` | String | Yes | Specifies who the party information belongs to. Possible values:* `BENEFICIARY` = Party receiving the pay-out* `ORIGINATOR` = Party sending the deposit |
| `complianceDetails.partyDetails.entityType` | String | Yes | Specifies the entity type. Possible values:* `INDIVIDUAL` = details about an individual.* `COMPANY`= details about a business. |
| `complianceDetails.partyDetails.firstName` | String | Yes | The first name of the party requesting the deposit.Required only if `entityType` = `INDIVIDUAL`. |
| `complianceDetails.partyDetails.lastName` | String | Yes | The last name of the party requesting the deposit.Required only if `entityType` = `INDIVIDUAL`. |
| `complianceDetails.partyDetails.dateOfBirth` | String | Yes | The date of birth of the party requesting the deposit. Format: `YYYY-MM-DD`. Example: `1984-06-30`.Required only if `entityType` = `INDIVIDUAL`. |
| `complianceDetails.partyDetails.countryCode` | String | Yes | The ISO 3166-1-alpha-2 code of the country that the party resides in. Example: `DE`.Required only if `requesterIpAddress` is not provided. |
| `complianceDetails.partyDetails.regionCode` | String | Yes | ISO 3166-2:UA code for Ukraine's regions, enabling geoscreening of restricted areas.Required only if `complianceDetails.partyDetails.countryCode` is `UA`. In this case, submissions with missing or invalid `regionCode` are rejected. For all other countries, the region code is ignored.For the complete list of codes, see [ISO\_3166-2:UA](https://www.iso.org/obp/ui/#iso:code:3166:UA). Example: `UA-46`. |
| `complianceDetails.partyDetails.legalName` | String | Yes | The legal entity name of the company.Required only if `entityType` = `COMPANY`. |
| `complianceDetails.partyDetails.registrationNumber` | String | Yes | The company registration number.Required only if `entityType` = `COMPANY`. |
| `complianceDetails.partyDetails.relationshipType` | String | Yes | This field specifies the relationship type between the sender and the recipient of the transaction. Possible values:* `SELF_OWNED` = The wallet within BVNK is registered under the same entity for both accounts involved in the transaction. This indicates that funds are being moved between accounts owned by the same entity. For example, if the BVNK wallet is registered to *Fast Cars LTD* and funds are being transferred to another account owned by *Fast Cars LTD*.* `THIRD_PARTY` = The transaction involves accounts belonging to different entities. For example, *Fast Cars LTD* receives a payment from *James Smith*, or *Fast Cars LTD* pays their supplier *Tires Supplies Inc*. |

## Code examples of the additional data

```json DEPOSIT - Payment Link
{
    "merchantId": "86955f40-8f4e-464c-be2b-583635bf1c62",
    "type": "IN",
    "amount": 5,
    "currency": "USDT",
    "expiryMinutes": 1440,
    "reference": "test_reference_in_1xCbGZ",
    "returnUrl": "https://your-url-here.com/status",
    "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
    "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
            {
                "type": "ORIGINATOR",
                "entityType": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "1984-06-30",
                "relationshipType": "THIRD_PARTY",
              	"countryCode": "DE"
            }
        ]
    }
}
```

```json DEPOSIT - Payment Channel
{
    "merchantId": "7fa95319-b854-402c-bbfb-5d9dfe9122b4",
    "payCurrency": "USDT",
    "displayCurrency": "USD",
    "reference": "PayRef-USDT-d063635e",
    "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
    "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
            {
                "type": "ORIGINATOR",
                "entityType": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "1984-06-30",
                "relationshipType": "THIRD_PARTY"
            }
        ]
    }
}
```

```json PAYOUT - Payment Link
{
    "merchantId": "86955f40-8f4e-464c-be2b-583635bf1c62",
    "type": "OUT",
    "amount": 3,
    "currency": "EUR",
    "expiryMinutes": 30,
    "reference": "test_reference_out_xpO23C",
    "returnUrl": "https://www.your-url-here.com/status",
    "payOutDetails": {
        "code": "crypto",
        "currency": "ETH",
        "network": "ETHEREUM",
        "address": "0x02ae6765C6991813a3EAa86fe63ebBCA1c9EC156",
        "tag": ""
    },
    "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
    "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
            {
                "type": "BENEFICIARY",
                "entityType": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "1984-06-30",
                "relationshipType": "THIRD_PARTY",
                "countryCode": "DE"
            }
        ]
    }
}
```

## Updating old payment channels with the additional data

If you have payment channels that were previously created without the additional data, you will be able to supply this information by sending a `PUT` request to the payment channel endpoint (`/api/v2/channel`). Example below:

### Supplying the additional data for old payment channels

```json Request
{
    "uuid": "7e5e126b-0217-45d4-b38f-5d6f30388257",
    "merchantId": "86955f40-8f4e-464c-be2b-583635bf1c62",
    "reference": "b5af590b-6033-4b15-874b-289f269b15f9",
    "customerId": "d063635e-0f83-4e47-a1f3-fc9484df1509",
    "complianceDetails": {
        "requesterIpAddress": "77.71.188.87",
        "partyDetails": [
            {
                "entityType": "INDIVIDUAL",
                "type": "ORIGINATOR",
                "firstName": "John",
                "lastName": "Doe",
                "dateOfBirth": "1984-06-30",
                "relationshipType": "THIRD_PARTY",
                "countryCode": "DE"
            }
        ]
    }
}
```

| Parameter | Type | Required | Description |
| :-------- | :--- | :------- | :---------- |
| `uuid` | String | Yes | The `UUID` associated to this payment channel. This would have been provided in the response when you originally created the payment channel. |
| `merchantId` | String | Yes | The `merchantId` associated to this payment channel. |
| `reference` | String | Yes | The `reference` associated to this payment channel. |
| `customerId` | String | Yes | Uniquely identifying the party requesting the payment. If multiple payment channels for same party are created, the ID should remain consistent. |
| `complianceDetails` | Object | Yes | Will contain information about the party requesting the deposit. |
| `complianceDetails.requesterIpAddress` | String | Yes | The IP-address of the party requesting the deposit.Required only if `countryCode` is not provided. |
| `complianceDetails.partyDetails` | Object | Yes | Will contain additional information about the party requesting the payment. |
| `complianceDetails.partyDetails.type` | String | Yes | Specifies who the party information belongs to. Possible values:* `BENEFICIARY` = Party receiving the pay-out* `ORIGINATOR` = Party sending the deposit |
| `complianceDetails.partyDetails.entityType` | String | Yes | Specifies the entity type. Possible values:* `INDIVIDUAL` = details about an individual.* `COMPANY`= details about a business. |
| `complianceDetails.partyDetails.firstName` | String | Yes | The first name of the party requesting the deposit.Required only if `entityType` = `INDIVIDUAL`. |

---

## Third Party Providers (TPPs)

## PSD2: What it is and why it's important

The revised Payment Services Directive (PSD2) was enacted on 13 January 2018 across Europe and the UK. PSD2 introduced new rights for certain third-party providers (TPPs) to directly access payment service users' online payment accounts in certain circumstances and requires Account Servicing Payment Service Providers (ASPSPs), to permit access through a dedicated interface built on APIs.

## What will you be able to do?

To meet our PSD2 requirements, BVNK will allow Third-Party Providers (TPPs) certain access:

* Account Information Services (AIS): Account Information from BVNK accounts will be able to be shared with other financial institutions, upon the account owner's consent.\
  *E.g.: a budgeting application that consolidates account information from multiple banks and financial institutions will be able to import data from BVNK virtual accounts.*

[Read more on AIS on the Open Banking website.](https://standards.openbanking.org.uk/customer-experience-guidelines/introduction/customer-journey-consent/v3-1-5/)

* Payment Initiation Services (PIS): payments to other financial institutions will be able to be initiated directly from other bank accounts, with the owner's consent.\
  *E.g.: a payment of a credit card balance can be made from a mobile application and biometric authentication, with the money coming out of a BVNK virtual account.*

**[Read more on PIS on the Open Banking website.](https://standards.openbanking.org.uk/customer-experience-guidelines/payment-initiation-services/latest/)**

## Register your interest

If you are interested, please fill in [the form](https://docs.google.com/forms/d/e/1FAIpQLSfMS90jgvzC_zosrA-rMxVfWT4dYRavIsJv9blVr41yeZuD9A/viewform?embedded=true) below:

<iframe 
  src="https://docs.google.com/forms/d/e/1FAIpQLSfMS90jgvzC_zosrA-rMxVfWT4dYRavIsJv9blVr41yeZuD9A/viewform?embedded=true" 
  width="760" 
  height="675" 
  frameBorder="0" 
  marginHeight="0" 
  marginWidth="0"
  title="Register your interest in Account Information and Payment Initiation Services (AIS and PIS)"
  style={{ border: 'none', width: '100%', maxWidth: '760px' }}
>
  Loading…
</iframe>

---

## Receive fiat funds via SWIFT

<FundSwiftWallet />

---

## Receive fiat funds via SWIFT(Virtual-accounts)

To receive fiat funds in your BVNK virtual account, you can deposit EUR, GBP, or USD from a registered bank account. This guide explains how SWIFT wallets work and how to obtain the deposit details your senders need.

SWIFT wallets at BVNK are **pooled accounts**. Multiple customers share a consolidated SWIFT account, and BVNK uses the payment reference to allocate incoming funds to the correct wallet.

---

## How SWIFT pooled accounts work

When you receive a SWIFT pay-in:

1. The sender initiates a payment from their bank to the BVNK SWIFT account.
2. BVNK receives the payment and checks the payment reference field.
3. Based on the reference, BVNK assigns the payment to the correct wallet.

If the payment reference is missing or incorrect, BVNK cannot automatically match the payment. In this case, provide proof of payment, such as a bank statement or transfer confirmation, so BVNK can manually credit your wallet.

---

## Prerequisites

Before depositing funds, ensure you have:

- A fiat wallet with the SWIFT payment method enabled. See [Create a wallet](../../../get-started/create-wallet).
- A registered bank account on your BVNK Settings page (for Portal deposits).

---

## Get deposit details

Retrieve the deposit details to share with the sender.

<Tabs queryString="method">
  <TabItem value="api" label="API">

To get your wallet's deposit details via API, send the [`GET /ledger/v1/wallets/{id}`](../../../api-explorer/endpoints/ledger-wallet-read) request:

In the response, locate the `ledgers` array. For fiat wallets, extract the `accountNumber`, `code`, and `paymentReference` fields.

    ```json
    {
        "id": "a:24092328494070:G5i4XZ9:1",
        "accountReference": "3399c975-e1c1-4acf-9a90-6cfbdcdeaaea",
        "customerReference": "b94dcf2a-d377-469e-8846-e21f65b18a77",
        "name": "USD SWIFT Wallet",
        "status": "ACTIVE",
        "balance": {
            "value": 5000.00,
            "currencyCode": "USD"
        },
        "ledgers": [
            {
                "type": "FIAT",
                "accountHolderName": "System Pay Services (Malta) Limited",
                "accountNumber": "DE10601202004579784373",
                // highlight-start
                "code": "BBVAESMMXXX",
                "accountNumberFormat": "SWIFT",
                "paymentReference": "REF DZ0XJL4",
                // highlight-end
                "bank": {
                    "identificationCode": "BBVAESMMXXX",
                    "name": "Banco Bilbao Vizcaya Argentaria, S.A.",
                    "address": {
                        "addressLine1": "De San Nicolas 4",
                        "city": "Bilboa",
                        "postCode": "48005",
                        "country": "ES"
                    }
                }
            }
        ]
    }
    ```

  </TabItem>
  <TabItem value="portal" label="Portal">

To find your deposit details in the BVNK Portal, follow these steps:

    1. Go to Portal and navigate to the **Wallets** section.
    2. In the **Wallets** list, locate the fiat wallet you want to fund and select it.
    3. Click **Deposit**.

        ![](/img/bvnk/use-cases/deposit-fiat.png)

    4. Review the displayed account details:

       - Account holder name
       - Account number or IBAN
       - SWIFT/BIC code

        ![](/img/bvnk/use-cases/deposit-details.png)

  </TabItem>
</Tabs>

---

## Provide payment instructions to senders

Provide the following details to anyone sending funds to your SWIFT wallet:

| Parameter | API field name | Description |
| :---- | :---------- | :---------- |
| Account number | `accountNumber` | The IBAN or account number for the BVNK SWIFT account. |
| SWIFT/BIC code | `code` | The bank identifier code for the receiving bank. |
| Payment reference | `paymentReference` | Unique reference for your account. Use this as the payment reference when instructing senders. |

:::info
Instruct external senders to include the `paymentReference` when transferring funds to your BVNK SWIFT wallet. The sending bank must include this value in the payment instructions to link the payment to your account.

Ensure senders use the same `paymentReference` for all future transfers to your BVNK wallet.
:::

---

## What happens without a payment reference

If the sender omits the payment reference:

- BVNK cannot automatically assign the payment to your wallet.
- You must provide proof of payment (such as a bank statement or transfer confirmation) to BVNK support.
- After verification, BVNK manually credits the funds to your wallet.

This process may delay the availability of your funds.

---

## Test in sandbox

To simulate a SWIFT pay-in in the sandbox environment, send the [`POST /payment/v2/payins/simulation`](../../../api-explorer/endpoints/simulate-payin-v-2) request:

```json
{
    "id": "a:25112856360743:5paGBL3:1",
    "accountReference": "b94c42ec-f87f-4ecb-a0ce-01182fe59eb8",
    "customerReference": "ab3529ed-29c2-447b-947f-fd5b4eb83a37",
    "name": "EUR SWIFT",
    "status": "ACTIVE",
    "balance": {
        "value": 0.00,
        "currencyCode": "EUR"
    },
    "ledgers": [
        {
            "type": "FIAT",
            "accountHolderName": "System Pay Services (Malta) Limited",
            "accountNumber": "DE10601202004579784373",
            "code": "BBVAESMMXXX",
            "accountNumberFormat": "SWIFT",
            "paymentReference": "REF DZ0XJL4",
            "bank": {
                "identificationCode": "BBVAESMMXXX",
                "name": "Banco Bilbao Vizcaya Argentaria, S.A.",
                "address": {
                    "addressLine1": "De San Nicolas 4",
                    "city": "Bilboa",
                    "postCode": "48005",
                    "country": "ES"
                }
            }
        }
    ]
}
```

For more simulation options, see [Try fiat payments in simulator](../../../get-started/payment-sim).

---

**What's next?**

- [Send payments to customers](../initiate-payment-2)
- [Refund fiat pay-ins](../refund-payments)
- [Configure webhooks](../../../get-started/create-webhook-listener) to receive real-time notifications about incoming payments

---

## Send payments

To create a fiat payout for **local payment** rails, you must have the following:

* Recipient's account number.
* Recipient's bank account details:
  * For GBP payments: SCAN and IBAN
  * For EUR payments: IBAN
  * For USD payments: ABA routing number

If invalid bank details are provided, such as an incorrect bank code or account number, the payout request will be rejected with an error message returned.

To create a fiat payout for **international payments** via SWIFT, you must first acquire the following information:

* Payee's full name or company name and address.
* Bank Account Number (IBAN or other, depending on the currency)
* Name and address of the payee's bank
* Payee's SWIFT or Bank identifier Code (BIC) bank code.

## Create payout

To create a payout, send the [`POST /payment/v2/payouts`](../../../api-explorer/endpoints/payout-create-v-2) request with the payload:

<Tabs>
  <TabItem value="individual" label="Individual">
    ```json Payout Request Example for Individual
    {
        "walletId": "a:24092324785677:o6rhCEZ:1",
        "amount": 1000.5,
        "currency": "EUR",
        "method": "SEPA_CT",
        "reference": "PAYOUT-2025-001",
        "beneficiary": {
            "remittanceInformation": "Payment for services",
            "entity": {
                "type": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Dove",
                "dateOfBirth": "15-01-1990",
                "relationshipType": "SELF_OWNED",
                "address": {
                    "addressLine1": "123 Main St",
                    "city": "New York",
                    "region": "NY",
                    "postCode": "10001",
                    "country": "US"
                }
            },
            "bankAccount": {
                "accountNumber": "000123456789",
                "accountType": "CHECKING",
                "bank": {
                    "identificationCode": "CHASUS33",
                    "nid": "021000021",
                    "address": {
                        "addressLine1": "383 MADISON AVENUE",
                        "city": "New York",
                        "region": "NY",
                        "postCode": "10001",
                        "country": "US"
                    }
                }
            }
        },
        "fees": {
            "customerFee": {
                "amount": 5,
                "currency": "USD"
            }
        },
        "metadata": {
            "source": "api",
            "merchantId": "merchantOne"
        },
        "requestDetails": {
            "originator": {
                "ipAddress": "10.0.0.2"
            }
        }
    }
    ```
</TabItem>
<TabItem value="company" label="Company">
    ```json Payout Request Example for Company
    {
        "walletId": "a:24092324785677:o6rhCEZ:1",
        "amount": 5000,
        "currency": "EUR",
        "method": "SEPA_INST",
        "reference": "CORPORATE-PAYOUT-001",
        "beneficiary": {
            "remittanceInformation": "Invoice payment #INV-2024-001",
            "entity": {
                "type": "COMPANY",
                "legalName": "Acme Corporation Ltd",
                "relationshipType": "SELF_OWNED",
                "address": {
                    "addressLine1": "456 Business Park",
                    "addressLine2": "Suite 100",
                    "city": "Dublin",
                    "region": "Leinster",
                    "postCode": "D02 XY45",
                    "country": "IE"
                }
            },
            "bankAccount": {
                "accountNumber": "IE29 AIBK 9311 5212 3456 78",
                "accountType": "BUSINESS_CHECKING",
                "bank": {
                    "identificationCode": "AIBKIE2D",
                    "address": {
                        "addressLine1": "Allied Irish Bank",
                        "city": "Dublin",
                        "country": "IE"
                    }
                }
            }
        },
        "fees": {
            "customerFee": {
                "amount": 15,
                "currency": "EUR"
            }
        }
    }
    ```
</TabItem>
</Tabs>

Note the following fields:

| Parameter | Required | Description |
| :-------- | :-------: | :---------- |
| `reference` | :x: | Optional. The internal reference is shown in the CSV reports for custom use cases. Can be a UUID or any string to identify the payment.**The field is for information purposes only. It will be fully supported in future releases.** |
| `method` | :x: | Payment method. Mandatory for payouts in USD and optional for other currencies.We recommend leaving it blank, so that the fastest method is selected automatically.Depending on the specific wallet and currency, not all methods can be available for the transaction. Available options:* SEPA_INST (EUR)* SEPA_CT (EUR)* ACH (USD)* ACH_SAME_DAY (USD)* FASTER_PAYMENT (GBP)* SWIFT (USD, EUR, GBP)* FEDWIRE (USD)* BOOK (USD)* RTP (USD)* FEDNOW (USD) |
| `beneficiary.remittanceInformation` | :white_check_mark: | Payment reference that beneficiaries see in their bank statements when receiving the payment.Can contain only alphanumeric characters (a-z, A-Z, 0-9), whitespaces, or the `.,-` symbols.Other allowed characters vary depending on the used payment method or currency. |
| `beneficiary.address.code` | :white_check_mark: | Country code of the beneficiary's address. The beneficiary address must include at least this field. |
| `bankAccount.accountType` | :x: | Type of the account. Optional. Only for US banks. |
| `bankAccount.bank.identificationCode` | :white_check_mark: | Bank's identification number, for example, BIC for UK banks, SORT code, ABA routing number, and so on.Optional for local payouts in EUR. |
| `bankAccount.bank.nid` | :x: | National bank identification code: country-specific code assigned to a financial institution by its central bank or banking authority. In most cases, used for SWIFT payments to US accounts. |
| `requestDetails.originator.ipAddress` | :x: | IP address of the customer initiating the payout. Required when you [make a payment via a customer's wallet](../../stablecoin-payments-for-platforms/send-stabelcoin-via-customers-wallet). |

While EUR local transfers have fewer requirements, for USD payments and SWIFT transactions, it's advisable to provide comprehensive details to prevent potential rejection by the banking partner.

For the detailed description of all fields, see the [`POST /payment/v2/payouts`](../../../api-explorer/endpoints/payout-create-v-2) API reference.

In the successful response, you receive the standard payment details.

<Tabs>
  <TabItem value="individual" label="Individual">
    ```json Payout Response Example for Individual
    {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "method": "SEPA_CT",
        "reference": "PAYOUT-2025-001",
        "status": "PROCESSING",
        "type": "payment:payout:fiat",
        "direction": "OUT",
        "fees": {
            "customerFee": {
                "amount": 5,
                "currency": "EUR"
            },
            "processingFee": {
                "amount": 1,
                "currency": "EUR"
            }
        },
        "originator": {
            "amount": 1000.5,
            "currency": "EUR",
            "walletId": "a:24092324785677:o6rhCEZ:1"
        },
        "beneficiary": {
            "remittanceInformation": "Payment for services",
            "amount": 1000.5,
            "currency": "EUR",
            "entity": {
                "type": "INDIVIDUAL",
                "firstName": "John",
                "lastName": "Dove",
                "relationshipType": "BENEFICIARY"
            },
            "bankAccount": {
                "accountNumber": "000123456789",
                "bank": {
                    "identificationCode": "CHASUS33"
                }
            }
        },
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:35:00Z",
        "metadata": {
            "source": "api",
            "merchantId": "merchantOne"
        }
    }
    ```
</TabItem>
<TabItem value="company" label="Company">
    ```json Payout Response Example for Company
    {
        "id": "660f9511-f30c-52e5-b827-557766551111",
        "method": "SEPA_INST",
        "reference": "CORPORATE-PAYOUT-001",
        "status": "COMPLETED",
        "type": "payment:payout:fiat",
        "direction": "OUT",
        "fees": {
            "customerFee": {
                "amount": 15,
                "currency": "EUR"
            },
            "processingFee": {
                "amount": 1,
                "currency": "EUR"
            }
        },
        "originator": {
            "amount": 5000,
            "currency": "EUR",
            "walletId": "a:24092324785677:o6rhCEZ:1"
        },
        "beneficiary": {
            "remittanceInformation": "Invoice payment #INV-2024-001",
            "amount": 4985,
            "currency": "EUR",
            "entity": {
                "type": "COMPANY",
                "legalName": "Acme Corporation Ltd",
                "relationshipType": "BENEFICIARY"
            },
            "bankAccount": {
                "accountNumber": "IE29 AIBK 9311 5212 3456 78",
                "bank": {
                    "identificationCode": "AIBKIE2D"
                }
            }
        },
        "createdAt": "2024-01-15T09:00:00Z",
        "updatedAt": "2024-01-15T11:30:00Z"
    }
    ```
</TabItem>
</Tabs>

| Parameter           | Description                                                                                                         |
| :------------------ | :------------------------------------------------------------------------------------------------------------------ |
| `type`              | Type of the response.                                                                                               |
| `originator.amount` | Amount of funds sent to the beneficiary. For fiat transactions, it will always be the same as `beneficiary.amount`. |

In case of payment in Euro, the transaction is subject to **Verification of Payee (VoP)**.

## Request VoP

**VoP** is a SEPA (Single Euro Payments Area) service that verifies a beneficiary's name against their IBAN to prevent fraud and errors. Before a SEPA Credit Transfer (SCT) or SEPA Instant Transfer (SCT inst) is authorized, the originator's bank will check the provided name and IBAN with the beneficiary's bank and report the result (Match, Close match, or No match) back to the originator. This is a regulatory requirement under the Instant Payments Regulation to enhance security for euro transfers within the SEPA zone.

![VoP flow](/img/bvnk/use-cases/fiat-payout-2.png)

When performing VoP, the system may return one of the following results:

* **Successful verification**: The beneficiary's name matches. The payment proceeds automatically.
* **Partial match**: The provided name is similar to the one associated with the IBAN, but not an exact match. You may still send the payment **at your own risk**, but there is a chance it may not be processed successfully.
* **No match**: The beneficiary's name does not match at all. You may still attempt to send the payment, but the likelihood of rejection increases.
* **Failed verification** due to other reasons:
  * For instance, **technical** issues may arise if the verification service is unavailable.
  * Others, for example, if a beneficiary's bank decides not to conduct verification.

All results, except for the successful verification, indicate that if the beneficiary's name in the request doesn't match the name in the beneficiary's bank account, the bank will issue a warning about the inconsistency. In this case, the status 202 is returned.

<Tabs>
  <TabItem value="partial-match" label="Partial Match">
    ```json
    {
      "id": "UUID",
      "requiredAction": "CONFIRM_BENEFICIARY",
      "status": "PAYEE_VERIFICATION_REQUIRED",
      "verificationResult": {
        "matchStatus": "PARTIAL_MATCH",
        "actualName": "George D Collins", // Only present if status is Partial Match
        "providedName": "George Colline"
      }
    }
    ```
  </TabItem>

  <TabItem value="no-match" label="No Match">
    ```json
    {
      "id": "UUID",
      "requiredAction": "CONFIRM_BENEFICIARY",
      "status": "PAYEE_VERIFICATION_REQUIRED",
      "verificationResult": {
        "matchStatus": "NO_MATCH",
        "providedName": "Gerorge Colline"
      }
    }
    ```
  </TabItem>

  <TabItem value="technical-error" label="Technical Issue">
    ```json
    {
      "id": "UUID",
      "requiredAction": "CONFIRM_BENEFICIARY",
      "status": "PAYEE_VERIFICATION_REQUIRED",
      "verificationResult": {
        "matchStatus": "TECHNICAL_ERROR",
        "providedName": "Gerorge Colline"
      }
    }
    ```
  </TabItem>

  <TabItem value="not-possible" label="Not Possible">
    ```json
    {
      "id": "UUID",
      "requiredAction": "CONFIRM_BENEFICIARY",
      "status": "PAYEE_VERIFICATION_REQUIRED",
      "verificationResult": {
        "matchStatus": "NOT_POSSIBLE",
        "providedName": "Gerorge Colline"
      }
    }
    ```
  </TabItem>
</Tabs>

:::warning 🚧 Your transaction is not created yet.

Status 202 means that you must send another request to confirm the operation. See Send confirmation below.
:::

You can also test how verification works in the sandbox. For that, use the following test names and IBANs, when sending the payment request:

<Tabs>
  <TabItem value="full-match" label="Full match">
    * First Name: John Smith
    * Last Name: Doe
    * IBAN: MT45SYPL39480744067217548372015
    * BIC: SYPLMTM2XXX
  </TabItem>

  <TabItem value="partial-match" label="Partial Match">
    * First Name: John
    * Last Name: Doe
    * IBAN: MT45SYPL39480744067217548372015
    * BIC: SYPLMTM2XXX
  </TabItem>

  <TabItem value="no-match" label="No Match">
    * First Name: Jane
    * Last Name: Mary
    * IBAN: MT45SYPL39480744067217548372015
    * BIC: SYPLMTM2XXX
  </TabItem>
</Tabs>

There are two ways of verifying the beneficiary's name:

* As part of the Payout process: by calling another endpoint to confirm the payout operation. See [Confirm payout](#confirm-payout).
* As a separate two-step process, where you verify a beneficiary via a separate endpoint and then make the payout using the received `verificationId`. See [Integrate two-step verification](#integrate-two-step-verification).

### Confirm payout

You can use this method after making a payout in euros described earlier and receive a response with any of the following `status` values :

* `PARTIAL_MATCH`
* `NO_MATCH`
* `NOT_POSSIBLE`
* `TECHNICAL_ERROR`

The statuses indicate that the beneficiary's name doesn't match the one associated with the beneficiary's bank account or cannot be verified.

If you are aware of this inconsistency and would like to proceed with the payment anyway, send a [`POST /payment/v2/payouts/{id}/actions`](../../../api-explorer/endpoints/payout-confirm-beneficiary-v-2) request with `id` of the transaction received in the 202 response and the following body.

```json Example Payload
{
    "type": "CONFIRM_BENEFICIARY"
}
```

In the successful response, you receive the standard payout details, as shown earlier.

If the operation is not confirmed within five minutes, it expires.

If you provide the wrong transaction ID or send the confirmation request after its expiration, an error is returned. In this case, you will have to create a new payout.

### Integrate two-step verification

Alternatively, you can verify the beneficiary's name using the verification endpoint. Note that in case you follow this approach, step 1 of the following procedure must be completed before creating the payout.

To verify the beneficiary's name, do the following:

1. Send the [`POST /platform/v1/beneficiaries/verification`](../../../api-explorer/endpoints/verify-beneficiary) request.

   ```json Example Request
   {
     "accountNumber":  "GB29NWBK60161331926819",
     "bankCode": "NWBKGB2L",
     "firstName":  "John",
     "lastName": "Smith",
     "businessName":  "Acme Corporation Ltd",
     "currency": "GBP"
   }
   ```

   In the request body, provide the following fields:

   | Field | Description |
   | :---- | :---------- |
   | `accountNumber` | The beneficiary's bank account number. |
   | `bankCode` | The beneficiary's bank code. |
   | `firstName` | The beneficiary's first name. Only for `"type": "INDIVIDUAL"`. |
   | `lastName` | The beneficiary's last name. Only for `"type": "INDIVIDUAL"`. |
   | `businessName` | The beneficiary's business name. Only for `"type": "COMPANY"`. |
   | `currency` | The currency of the beneficiary's bank account. |

   In the successful response, you receive the name match status and validation period:

   ```json Example Response
   {
     "id" :  "550e8400-e29b-41d4-a716-446655440000",
     "matchStatus" : "MATCH",
     "providedName" :  "John Smith",
     "actualName": "J. Smith", // only present for partial match
     "validUntil" : "2025-01-15T14:30:00Z" // when the verification will expire
   }
   ```

   Note the following fields:

   | Field | Description |
   | :---- | :---------- |
   | `matchStatus` | Status of the name verification. The following name statuses are available:* `MATCH`* `PARTIAL_MATCH`* `NO_MATCH`* `NOT_REQUIRED`* `NOT_POSSIBLE`* `TECHNICAL_ERROR` |
   | `validUntil` | Time period during which the verification request is valid. By default, five minutes. |
2. Send the [`POST /payment/v2/payouts`](../../../api-explorer/endpoints/payout-create-v-2) request as described earlier. Remember to include the verification `Id`, acquired on step 1 in the response, as the `X-Verification-Id` header.

   If you provide a valid `verificationId` regardless of status, BVNK verifies that it exists in the records and is not expired, then executes the payment regardless of the `matchStatus` value.

   The following outcomes are possible:

   * If the verification session is still valid, the payout will be created, and there will be no need to verify the beneficiary.
   * If the verification session is expired or `verificationId` is not found within BVNK records, the payout will not be created, and you will receive a `400` error.

## Check payout status

To check the status of a payout, send the [`GET /payment/v2/payouts/{transactionReference}`](../../../api-explorer/endpoints/payout-get-v-2) request.

In the successful response, you receive the details on the transaction and its status.

```json Response
{
    "transactionReference": "123e4567-e89b-12d3-a456-426614174000",
    "paymentReference": "Payment for invoice #12345",
    "amount": {
        "value": 1000,
        "currency": "GBP"
    },
    "fee": {
        "value": 0.00,
        "currency": "GBP"
    },
    "walletId": "a:24071743003474:xE95Oq7:1",
    "status": "PROCESSING",
    "createdAt": "2024-09-26T14:30:00Z",
    "details": {
        "type": "FIAT",
        "beneficiary": {
            "entityType": "COMPANY",
            "businessDetails": {
                "businessName": "Doe Corp"
            },
            "address": {
                "addressLine1": "123 Main St",
                "addressLine2": "Apt 4B",
                "region": "London",
                "city": "London",
                "country": "GB",
                "postCode": "EC2R 8AH",
                "fullAddress": "123 Main St Suite 500"
            },
            "bankAccount": {
                "format": "IBAN",
                "bankName": "NatWest Bank",
                "accountNumber": "GB29NWBK60161331926819",
                "bankCode": "NWBKGB2L",
                "bankAddress": {
                    "addressLine1": "123 Main St",
                    "addressLine2": "Suite 500",
                    "region": "London",
                    "city": "London",
                    "country": "GB",
                    "postCode": "12345",
                    "fullAddress": "123 Main St Suite 500"
                }
            },
            "correspondentBic": "ABCDEF12"
        }
    },
    "metadata": {
        "field1": "field1 value",
        "field2": "field2 value"
    }
}
```

Also, you can listen to the following webhooks to get notified when the status of the payment changes:

* [Fiat payout status change](../../../api-explorer/bvnk-webhooks/payment-payout-status-change-v-2)
* [Fiat pay-in status change](../../../api-explorer/bvnk-webhooks/payment-payin-status-change-v-2)

---

## Prepare for integration(Virtual-accounts)

<SetupAndWallets />

---

## Customer creation

Before proceeding with the customer creation request, collect information about the customer.

To create an account for your customer, send the `POST /platform/v1/customers` request with the payload specific to the customer type.

Apart from the typical information, include the [industry reference](https://docs.bvnk.com/references/industry-references) number and the [expected monthly volumes](https://docs.bvnk.com/references/monthly-expected-volumes) into the request payload. Note that unlike Embedded Customer, **you don't need to provide agreements or upload documents** to verify the customer.

For the detailed description of the body parameters, see the [Create customer](../../../api-explorer/endpoints/create-customer) endpoint.

<Tabs>
<TabItem value="Company" label="Company">

    ```json
    {
        "type": "COMPANY",
        "company": {
            "name": "TechSolutions GmbH",
            "description": "Software development and IT consulting services",
            "taxResidenceCountryCode": "DE",
            "registrationNumber": "HRB 123456",
            "industryReference": "30fdc9e7-06d8-11ef-b6e1-027612b7f6b5",
            "monthlyExpectedVolumesReference": "ef77a16d-547e-11ef-8b9c-027612b7f6b5",
            "address": {
                "addressLine1": "Unter den Linden 77",
                "city": "Berlin",
                "postalCode": "10117",
                "countryCode": "DE"
            },
            "representative": {
                "firstName": "Hans",
                "lastName": "Mueller",
                "dateOfBirth": "1980-11-29",
                "birthCountryCode": "DE",
                "address": {
                    "address1": "1, Oxford Street",
                    "address2": "Apartment 9",
                    "postalCode": "NW1 4NP",
                    "city": "London",
                    "countryCode": "GB"
                }
            }
        }
    }
    ```
</TabItem>
<TabItem value="Individual" label="Individual">

    ```json
    {
        "type": "INDIVIDUAL",
        "individual": {
            "firstName": "Sophie",
            "lastName": "Weber",
            "dateOfBirth": "1985-08-15",
            "birthCountryCode": "DE",
            "documentNumber": "C01XY 123456",
            "address": {
                "addressLine1": "Friedrichstraße 123",
                "city": "Berlin",
                "postalCode": "10117",
                "countryCode": "DE"
            },
        }
    }
    ```

  </TabItem>
</Tabs>

In the successful response, you receive a unique customer reference for tracking the verification status.

<Tabs>
  <TabItem value="Success" label="Status: 200 - Success">

    ```json Success
    {
        "reference": "a7e21c62-27b8-4b3b-b51e-eb10edeb1731",
        "status": "PENDING"
    }
    ```
</TabItem>
<TabItem value="Failure" label="Status: 400 - Bad Request">

    ```json Failure
    {
        "code": "ACCOUNTS-2000",
        "status": "BAD_REQUEST",
        "message": "Invalid request",
        "details": {
            "documentLink": null,
            "errors": {
                "monthlyExpectedVolumesReference": [
                    "Monthly expected volumes with reference: a4318a0d-5316-11ef-9887-0289b1b0d83d does not exist"
                ],
                "industryReference": [
                    "Industry with reference: 56e65ebc-06fa-11ef-bbf8-02d3d923cf2b does not exist"
                ]
            }
        }
    }
    ```
</TabItem>
</Tabs>

| Attribute  |  Description |
|------------|--------------|
| `reference`  | A unique identifier for the customer. |
| `status`     | The current status of the customer.Possible values include:* `PENDING` - customer is pending verification* `VERIFIED` - customer has been verified* `REJECTED` - customer has been rejected during verification. |

---

<FiatWalletSetup />

---

<TestAndGoLive />

---

## Next steps

Once a virtual account is created, you can immediately:

- [Create internal transfers](../../create-internal-transfer)
- [Send payments](../initiate-payment-2) from the virtual account to your customers.
- [Receive payments](../fund-swift-wallet) from your customers into the virtual account.
- [Convert](../../on-off-ramp/on-ramp-overview/) from fiat into cryptocurrency.
- [Check your transactions](../../../reconciliation/reconcile-transactions) with reconciliation reports.
- [Track your transactions](../../../get-started/create-webhook-listener) with webhook notifications.

---

## Prepare for integration(4)

<SetupAndWallets />

---

<FiatWalletSetup />

---

<TestAndGoLive />

---

## Next steps

Once a virtual account is created, you can immediately:

- [Send payments](../send-payment-via-va) from the virtual account to your customers.
- [Receive payments](../fund-swift-wallet-via-va) from your customers into the virtual account.
- [Refund payments](../refund-payments-via-va) from the virtual account to your customers.
- [Check your transactions](../../../reconciliation/reconcile-transactions) with reconciliation reports.
- [Track your transactions](../../../get-started/create-webhook-listener) with webhook notifications.

---

## Refund payments(Virtual-accounts)

<RefundPayments />

---

## Refund payments(3)

The Refund API allows you to instantly refund any previous pay-in with a single click. It automatically creates the transaction without entering payout information.

## Prerequisites

To process a refund, the original pay-in transaction must have been made to a BVNK account. You can find the necessary transaction references in the webhook events from the initial pay-in or by sending the [`GET /ledger/v1/transactions`](../../../api-explorer/endpoints/wallet-transaction-report) request.

## Limitations and rules

* Refunds are returned via the original payment method. If that's not possible, the system will try to re-route funds via alternative means.
* If you need to return funds to a different beneficiary, you can make it as a [new Payout](initiate-payment-2.mdx).
* Refunds cannot exceed the original pay-in total amount.
* Refunds can be performed in two ways:
  * **Fully**: The entire amount is refunded in one transaction.\
    Note that only full refunds are supported for **Automated Clearing House** (ACH) transfers.
  * **Partially**: The portion of the amount is refunded in multiple transactions until reaching the original total.\
    For example, instead of making one payment of £150, you can make separate transactions of £50, £70, and £30. In this case, three requests must be sent to the same `/refund` endpoint.

:::info Standard payout fees

Standard payout fees can be applied to each transaction per your agreement with BVNK.
:::

## Estimate refund

You can check the estimated fee before initiating a refund to understand the costs.

To estimate the refund via API, do the following:

1. From the [Pay-in webhook](../../../api-explorer/bvnk-webhooks/payment-payin-status-change-v-2) that you configured earlier, get `{transactionReference}`, the unique transaction ID you received previously and want to refund.

   Alternatively, you can make a GET request to the [transactions](../../../api-explorer/endpoints/wallet-transaction-report) endpoint to get the transaction list and select the reference ID of the required one.

2. Send the [`POST payment/v1/payins/{transactionReference}/refund/estimate`](../../../api-explorer/endpoints/estimate-refund-fee) request. In the path, specify `{transactionReference}` acquired in the previous step and include the following parameters in the request:

   ```json
    {
        "value": "150",
        "currency": "EUR"
    }
   ```

   | Parameter  | Required | Description                                                   |
   | :--------- | :------: | :------------------------------------------------------------ |
   | `value`    | :white_check_mark:    | Amount to refund                                              |
   | `currency` | :white_check_mark:    | Currency of the refund pay-in. Possible values: GBP, USD, EUR |

When you receive the response, note the following:

* `fee` is a charge applied when processing refunds. When a refund is issued, both the refund amount and the associated fee are deducted from your wallet.
* `maxAvailableToRefund` indicates the remaining amount of the refund.

```json Example response
{
  "fee": {
    "value": 1.00,
    "currency": "EUR"
  },
  "maxAvailableToRefund": {
    "value": 150.00,
    "currency": "EUR"
  }
}
```

## Refund pay-in

To refund any pay-in to your customers via API, do the following:

1. Get `{transactionReference}`, as described [earlier](#estimate-refund).
2. Send a [`POST payment/v1/payins/{transactionReference}/refund`](../../../api-explorer/endpoints/refund-payin) request. to the endpoint. In the path, specify `{transactionReference}`, acquired in the previous step, and include the following parameters:

   | Parameter | Required | Description |
   | :-------- | :------: | :---------- |
   | `X-Idempotency-Key` | :white_check_mark: | Idempotency key in the UUID format used to guarantee that retrying the same request will not create duplicate refunds. |
   | `paymentReference` | :white_check_mark: | Additional information about the payment that can be sent to processing partners. Can be any text |
   | `amount` | :white_check_mark: | Amount to refund. Includes parameters:* `value`: amount of the refund.* `currency`: Currency of the refund pay-in. Possible values:  * GBP  * USD  * EUR |

    Once the refund is initiated, a new transaction item is generated in the portal's wallet. This new payout will adhere to the standard payout state machine process.

    <Tabs>
    <TabItem value="full-refund" label="Full refund">
        ```json Example request (full refund)
        {
            "paymentReference": "order123456",
            "amount": {
                "value": "150",
                "currency": "EUR"
            }
        }
        ```
    </TabItem>
    <TabItem value="partial-refund" label="Partial refund">

        ```json Example request (partial refund)
        {
            "paymentReference": "order123456",
            "amount": {
                "value": "50",
                "currency": "EUR"
            }
        }
        ```
    </TabItem>
    </Tabs>

    When you receive the response, note the following:

    * `fee` is a charge applied when processing refunds. When a refund is issued, both the refund amount and the associated fee are deducted from your wallet.
    * `transactionReference` indicates the unique ID of the refund transaction.

    ```json Example response
    {
    "transactionReference": "018e5e83-ac50-4df0-a7e4-c9f15d493f90",
    "fee": {
        "value": 1.00,
        "currency": "EUR"
    }
    }
    ```

3. If you have a [4-eyes Approval flow](https://help.bvnk.com/hc/en-us/articles/18632401764626-4-Eye-Approval-flows) configured, you may need to confirm the operation on the BVNK Portal. See Cancel refund for more information.

   If you don't have any approval flows configured, the refund will be approved automatically.

4. To check the status of the refund, send a `GET /payment/v1/payins/{transactionReference}/refund` request to the endpoint:

For more information on parameters, see [Check the Status of a Payout](../../bvnk/../../api-explorer/endpoints/payout-get-v-2).

## Approve or cancel refund

You can cancel or approve a refund if you have previously configured 4-eyes Approval and have access to the BVNK Portal.

To cancel a refund:

1. On the BVNK Portal, navigate to **Approvals** in the main menu and select the **Pending** tab.
2. Find the specific refund you wish to cancel.
3. Click **Reject** next to that refund.

If you want to approve the refund instead, or if the API endpoint requires confirmation, click **Approve** or the confirmation button.

:::info Once rejected, the refund operation cannot be reversed.

Ensure you have selected the correct transaction before proceeding.
:::

## Handle failed refunds

When a pay-in refund is attempted but cannot be completed, the API will respond with a `400 Bad Request` error. This error response will include a detailed message explaining the reason for the failure. If the refund for a pay-in isn't possible, consider making a [new Payout](initiate-payment-2.mdx).

---

## Send payments via Virtual Accounts

<InitiatePayment />

---

## Create internal transfers

<CreateInternalTransfers />

---

## Virtual accounts overview

This guide outlines how to use virtual accounts (VAs) to manage fiat and crypto payments through BVNK.

A **virtual account** is a BVNK-managed payment account that includes a virtual IBAN (vIBAN) and a wallet. It is used to send, hold, and receive funds in one place.

A **wallet** stores value and maintains balances in either fiat or crypto. You can connect various payment instruments, such as crypto addresses, to a wallet. If crypto is received through a channel linked to a fiat wallet, it is automatically converted and deposited as fiat. When a virtual account is linked to the wallet, you can withdraw funds through the VA. The wallet remains separate from the payment instruments, allowing flexible fund management.

---

## Supported virtual account types

BVNK offers several types of virtual accounts to address different payment requirements:

- **Named Accounts** are issued in the name of your business or your customers, enabling personalized payment routing. They are intended for domestic payments within the EEA and support **SEPA payments in EUR**.

- **Pulled accounts** are standard SWIFT accounts with vIBANs for cross-border payments. These accounts are issued under the BVNK-owned legal entity "System Payed Services Malta".

:::info
This product is also available to businesses in the UK and in supported countries outside the EEA. GBP accounts are limited to companies incorporated in the UK, the Isle of Man, Jersey, Gibraltar, or Guernsey.
:::
---

## For who is this product intended?

Virtual accounts are intended for regulated financial institutions and similar businesses that need to manage payments for themselves and their customers. BVNK streamlines this process and provides tools to efficiently manage funds between your business, your customers, and their end-customers.

The product supports two main models:

- **Virtual accounts** are created for direct BVNK customers, including but not limited to:

    - **Any business entity**: Such as fintech companies, gaming platforms, crypto businesses, and others
    - **Individuals**: In the embedded model, individual persons may also have virtual accounts

- **Customer virtual accounts** enable financial institutions and banks to create underlying virtual accounts for their own customers, such as:

    - **Regulated Financial Institutions**
    - **Banks**
    - **Payment Service Providers (PSPs)**
    - **Crypto and Trading Platforms**

<!-- The customer support team typically creates customer virtual accounts, but if a customer has the customer VA option enabled, they can create virtual accounts for their own customers. -->

<Tabs queryString="va">
  <TabItem value="VA" label="Virtual Accounts">

**Virtual accounts** allow you to create payment accounts for your business with unique identifiers, details, and vIBANs issued in your business name. These accounts function like traditional bank accounts for sending and receiving payments, but do not support credit facilities. Each vIBAN links directly to your payment account, enabling you to send and receive payments under your business name.

You can create both crypto and fiat wallets and transfer funds between them. Each crypto payment transaction generates a corresponding fiat transaction record for accounting and reconciliation.

Named virtual accounts support compliance, accounting, and tax reporting by providing clear transaction records that demonstrate you are moving your own funds. This structure allows you to separate different business operations or projects while maintaining full control over your funds.

**What is a standard use case for principal virtual accounts?**

> You operate a crypto trading platform that receives deposits in stablecoins. Your business needs to convert these stablecoin deposits to fiat currency and withdraw funds to your external bank account for operational expenses, supplier payments, or regulatory requirements.
>
> With a virtual account, you receive stablecoin deposits into your crypto wallet. You convert the stablecoins to euros through BVNK's trading functionality, which deposits the euros into your fiat wallet. The conversion creates both a crypto transaction record and a corresponding fiat transaction record for accounting purposes. You then withdraw the euro to your external bank account using the vIBAN associated with your virtual account.
>
> This workflow enables you to manage crypto-to-fiat conversions while maintaining clear transaction records for compliance and accounting. The named vIBAN ensures that all withdrawals are clearly attributed to your business, supporting audit trails and tax reporting.
  </TabItem>
  <TabItem value="cVA" label="Customer Virtual Accounts">

The **customer virtual accounts** product provides the infrastructure to create virtual accounts for your customers, simplifying payment tracking and management.

Financial institutions can use a **Principal Wallet** to store value, functioning like any other fiat wallet. With the Principal Wallet, institutions can:

    - Create underlying virtual accounts for their customers
    - Create wallets for their customers
    - Manage funds across the entire structure

To manage transactions for your customers and their clients (whether businesses or individuals), you assign each customer a virtual account with a unique name, details, and a vIBAN. These vIBANs link to your payment account, allowing you to send and receive payments on behalf of your customers under their names.

BVNK offers virtual accounts as an optional solution. You and your customers may use them, but they are not required. Other BVNK services, such as payments, crypto trading, or treasury management, are available without setting up or managing virtual accounts.

To qualify for customer virtual accounts, your business must:

  - Be a fully licensed financial services provider (e.g., UK FCA license, Canadian MSB, etc.).
  - Demonstrate a robust financial crime control framework (AML, risk policies, transaction monitoring, etc.).
  - Undergo compliance checks, including documentation review and interviews with the BVNK's compliance team.

**What is a standard use case for customer virtual accounts?**

VAs are designed for partners who need to segregate funds, simplify reconciliation, or embed financial services within their platforms.

Virtual accounts support a range of payment scenarios:

**For Crypto and Trading Platforms**:

> You represent a crypto trading platform and want to allow your customers to deposit fiat funds for crypto trading. Your platform receives deposits from hundreds of customers daily, and you need a robust payment reconciliation mechanism to match incoming payments to the correct customer accounts.
>
> With virtual accounts, each of your customers receives a unique named vIBAN. When a customer deposits $5,000 into their virtual account, you can immediately identify the customer who made the payment using the unique account details. The funds are deposited into your principal wallet, and you can automatically credit the customer's trading account balance. Your customers can also convert their fiat deposits to crypto, trade, and then withdraw crypto or convert back to fiat—all through their virtual account.
>
> This setup enables seamless fund segregation, accurate reconciliation, and a smooth user experience for both fiat and crypto operations.

**For Payment Service Providers and Financial Institutions**:

> You represent a Payment Service Provider serving multiple business customers. Your customers need to receive payments from their own clients and make payouts to suppliers, employees, or contractors. Each customer requires their own named IBAN to maintain clear payment separation and reconciliation.
>
> You create a virtual account for each of your customers, with a unique vIBAN issued in their business name. When **customer A** receives a €10,000 payment from their client, the funds are automatically routed to customer A's virtual account, and you can immediately identify and reconcile the payment. Customer A can then use those funds to make payouts to their suppliers or employees, all processed through their dedicated virtual account.
>
> This model allows you to process third-party payments on behalf of your customers while maintaining complete fund segregation, enabling accurate reconciliation, and providing your customers with professional payment infrastructure. The flow can optionally include stablecoin pre-funding for faster settlement and cross-border capabilities.

  </TabItem>
</Tabs>

**Additional use cases**:

Virtual accounts also support the following scenarios:

- **Neobanks**: Issue named IBANs to customers for personal or business banking services
- **Marketplaces**: Provide each merchant with a dedicated virtual account to receive payments from buyers
- **Employer of Record services**: Create virtual accounts for each client company to manage payroll and contractor payments
- **Treasury management**: Segregate funds across business units or projects using dedicated virtual accounts

---

<!-- Contact your Account Manager to initiate the virtual account approval process. After approval, BVNK's commercial team configures your VA product and maps your parameters to the appropriate banking partner. -->

## How to get started?

Virtual accounts require approval from BVNK's compliance team. To qualify, your business must:

- Be a fully licensed financial services provider (for example, UK FCA license, Canadian MSB).
- Demonstrate a robust financial crime control framework, including AML policies, risk management, and transaction monitoring.
- Complete compliance checks, including documentation review and interviews.

Your business must be approved for the customer virtual accounts solution before you can request or create virtual accounts.

To request virtual accounts, follow these steps:

1. **Contact BVNK** through your Account Manager or sales contact to express interest in the VA product.
2. **Submit required documentation**:

   - Proof of regulatory status, for example, FCA license, MSB registration
   - AML/CTF policies and procedures
   - Risk management framework
   - Details of your business model and use case

BVNK's compliance team reviews your documents and may request additional information. Enhanced Due Diligence (EDD) may be required, especially if your business operates in a higher-risk sector, such as gambling, gaming, or trading.

After BVNK's compliance team approves your application:

1. The **commercial team** or support success team creates the VA product configuration, specifying which currency virtual accounts you need and other parameters.
2. The **account activation** team maps your parameters to the appropriate banking partner.
3. A wallet is created in the admin panel, mapped to the banking partner.
4. Once the wallet is created, a virtual account (EUR VA or SWIFT account) is attached to it.

Once your business is enabled for VAs, you can create VAs for your underlying customers. To do so:

- **Collect KYC information** for your customer (the end user who will receive the VA).
- **Screen the customer** according to BVNK's requirements, including manual screening and risk checks.

After completing these steps, you can proceed to the configuration phase.

---

**Ready to start?** After completing the setup process with BVNK, select the model that fits your business needs and proceed with integration:

- [Virtual Account for your business](./prepare-for-va-integration.mdx)
- [Virtual Accounts for your customers](./prepare-for-customer-va-integration.mdx)

---

## Enable Express wallets for customers

Express Embedded offers a customizable user interface and backend APIs that add stablecoin wallet functionality to your platform. This allows you to provide stablecoin storage and management to your customers with minimal investment and development effort.

Embedded Express is intended for customers who need wallets and stored balances. It is best suited for stored-value scenarios where customers maintain balances over time. For one-time payments or payments not requiring a stored-value wallet (e.g., on-ramps or off-ramps to an external wallet or account), we recommend using our [Embedded Custom model](../../../get-started/delivery-models/?delivery-model=custom-embedded).

This product lets you use your existing pre-funded fiat balances to offer stablecoin storage services. Your customers do not need to interact with crypto providers or manage conversions.

All Embedded Express wallets include built-in capabilities:

- **Rewards**: All balances can earn rewards automatically.
- **Spending cards**: All your customers can be issued with a spending card.

These features are enabled by default and require no additional setup.

Express provides revenue streams for partners:

- **Reward income sharing**: As a partner, you can receive a share of the reward income generated by customer balances. You may choose to:
  - Pay all rewards to your customers.
  - Keep all rewards for your platform.
- **Card interchange income**: You can earn revenue from each card transaction made by your customers.
- **Wallet activity markups**: You can add markups to, and earn revenue on, wallet activity (payments, conversions, etc.) by your customers as they use their stablecoin wallets.

Contact your Account Manager to discuss available revenue streams, fees, and revenue-sharing options with Embedded Express.

## For who is this product intended?

This product is designed for any BVNK partner looking to provide stablecoin wallets and associated services to their customers, for example:

- **Payment Service Providers (PSPs)** looking to offer stablecoin storage to customers with pre-funded fiat balances
- **Platforms and marketplaces** needing to convert and store customer funds in stablecoins
- **Neobanks and financial services** aiming to provide stablecoin wallet functionality to users

---

## What is a standard use case?

> You represent a platform (for example, **RentPlatform**) and one of your customers has $100,000 in their account. You want to offer this customer a branded stablecoin wallet to store and manage their funds.
>
> After your platform onboards with BVNK, you gain access to a fiat wallet for depositing funds. When the customer opts for the stablecoin wallet, you convert funds from the fiat wallet to stablecoins and store them in the customer's wallet. The customer can then view their balance, make transactions, and manage their spending card through BVNK's wallet interface, which is branded with RentPlatform's colors and logos.

---

## Supported payment types

BVNK supports multiple conversion options to address different business needs:

- **Fiat to stablecoins**: Convert fiat currency to stablecoins and store them in customer wallets.
- **Crypto to crypto**: Convert from one stablecoin to another within customer wallets.

---

## How does it work?

The Embedded Express model automates the interface shown to a customer: onboarding, registration, login. Your platform needs to call a single API endpoint any time your customer wants to access the platform, regardless of their status: new or existing. BVNK will determine the appropriate action and return the relevant link.

To enable Express capabilities for your customers, follow these steps:

- [**Choose onboarding method**](#choose-onboarding-method): Enable your customers to be onboarded by BVNK, either through Express UI or by passing KYC documentation directly.
- [**Get Express session link**](#get-express-session-link): Enable your customers to access their stablecoin wallet by providing a redirect URL.
- [**Fund wallets**](#fund-wallets): Let your customers fund their wallet by on-ramping from fiat held in their account on your platform.

### Choose onboarding method

When onboarding a new customer, you can choose to apply the Express onboarding process or your own onboarding flow.

- **Express onboarding**: Direct new customers to the Express UI where they will be onboarded by BVNK. This option is recommended if you want to launch quickly or do not manage customer onboarding, such as if your business is unregulated or does not hold a license.
- **Your own onboarding flow**: Continue using your existing onboarding process and endpoints for embedded customers. You only need to [implement the existing APIs](../../../get-started/create-embedded-partner-customer/onboard-epc/). This option is recommended if you are licensed business and maintain your own KYC data.

:::warning
For your own onboarding flow, you must implement the [hosted agreements page](../../../get-started/create-embedded-partner-customer/signing-customer-agreements/#sign-agreements-via-hostedurl).
:::

The system manages different customer scenarios:

| If your customer is                     | Then, you will receive                                                         |
| --------------------------------------- | ------------------------------------------------------------------------------ |
| **new**                                 | an onboarding link.                                                 |
| **existing and has never used Express** | an Express registration link                                                   |
| **existing Express customer**           | a login link to the Express app                                                |
| **has an active session token**         | a redirect link so that customer can access the wallet interface without login |

See below for usage of the get session link endpoint—the same endpoint used for onboarding.

<!-- WHAT HAPPENS WHEN YOU HAVE THE ONBOARDING LINK? -->

### Get Express session link

To get a wallet session URL for your customer, send the [`POST /platform/v1/express-sessions`](../../../api-explorer/endpoints/create-express-session) request with the following body parameters:

<Tabs>
  <TabItem value="existing" label="Existing embedded customer">

For customers who already exist in your system, use their customer reference:

    ```json
    {
        "customerReference": "22c8168d-f735-43f8-9a3b-a1578efeb86c",
        // optional
        "theme": {
            "logo": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697",
            "primary": "#121212",
            "accent": "#DEF832",
            "background": "#382457"
        }
    }
    ```

  </TabItem>
  <TabItem value="new" label="New embedded customer">

For new customers, provide their details:

    ```json
    {
        "type": "INDIVIDUAL",
        "countryCode": "GB",
        "externalCustomerId": "22c8168d-f735-43f8-9a3b-a1578efeb86n",
        // optional
        "theme": {
            "logo": "https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697",
            "primary": "#121212",
            "secondary": "#382457",
            "accent": "#DEF832"
        }
    }
    ```

  </TabItem>
</Tabs>

The `theme` parameter is optional and lets you customize the Express interface to align with your brand.

| Parameter    | Description                                                                                         |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `logo`       | URL to your company logo. For example, https://ok14static.oktacdn.com/fs/bco/1/fs0waisynotIeKa80697 |
| `primary`    | Primary brand color as the hex code. For example, #121212                                           |
| `accent`     | Accent color as the hex code. For example, #DEF832                                                  |
| `background` | Background color as the hex code. For example, #382457                                              |
| `secondary`  | Secondary color as the hex code. For example, #382457                                               |

Express uses these colors to generate a palette that reflects your brand and displays your logo throughout the interface.

In the response, you receive the `walletSessionUrl`.

```json
{
    "walletSessionUrl": "https://wallet.staging.bvnk.com/welcome?sessionId=f5b2d8cd-887d-421c-ae00-9d3f82b5a45f"
}
```
### Fund wallets

See [Store funds in your wallet](./store-funds.mdx) for more information on how to fund your customers' wallets.

### User experience

Share the `walletSessionUrl` with your customer using a web view, redirect, or other integration method.

After authentication, customers access their wallet home screen, where they can:

- View their balance
- See transaction history
- View on-ramp payments from your platform
- View outbound payments
- Manage their spending card

---

**Ready to start?** After completing the prerequisites above, you can proceed with the integration. The following sections will guide you through:

- [Fund wallets](./store-funds.mdx): Let the end user fund their wallet by on-ramping from fiat held in their account on your platform

---

## Fund Express wallets

This guide explains how to debit funds from your fiat account and credit them to your customer's stablecoin account. To complete the conversion, you will need the recipient's stablecoin wallet ID, which you can obtain using the get wallets endpoint.

The Embedded Express product follows a straightforward process:

1. **Get wallet ID**: Retrieve the customer's stablecoin wallet ID using the get wallets endpoint.
2. **Create quote**: Generate a conversion quote from your fiat wallet to the customer's stablecoin wallet.
3. **Accept quote**: Accept the quote to execute the conversion. This action debits your fiat account and credits the customer's stablecoin wallet.

Once complete, the converted stablecoins are stored in the customer's wallet and available for future transactions.

## Prerequisites

Before initiating the transfer, ensure you have the following:

- A fiat wallet with a sufficient balance
- The `customerReference` for the end user whose stablecoin wallet you intend to credit
- API credentials with merchant-level permissions

You do not need to create a wallet for Express customers. USDC wallets are automatically created when customers log into the Express app for the first time.

## Get wallets

To obtain the wallet ID for the end user's stablecoin account, use the [`GET /ledger/v1/wallets`](../../../api-explorer/endpoints/ledger-wallet-list) endpoint.

Filter wallets by `customerReference` to locate a specific customer's wallets and by `currencyCode` to find wallets in a particular currency, such as `USDC` or `USDT`.

```cUrl Request
GET /ledger/v1/wallets?customerReference=33e85982-e22b-4e8b-9057-445cf000bea9&currencyCode=USDC
```

The response provides a list of wallets and their details:

```json Response
{
  "content": [
    {
      "id": "a:24092328494070:G5i4XZ9:1",
      "accountReference": "4488d086-f2c2-5bdf-0b01-7dgcedfbfbb0",
      "customerReference": "33e85982-e22b-4e8b-9057-445cf000bea9",
      "name": "USDC Crypto Wallet",
      "status": "ACTIVE",
      "balance": {
        "value": 250.00,
        "currencyCode": "USDC"
      },
      "ledgers": [
        {
          "type": "CRYPTO",
          "address": "0x1234567890abcdef1234567890abcdef12345678",
          "network": "ETHEREUM"
        }
      ],
      "capabilities": "SAFEGUARDED"
    }
  ],
  ...
}
```

Find the `id` field in the response. This is the wallet ID required for the transfer.

## Fund wallet

1. Create a quote by sending the [`POST /api/v1/quote`](../../../api-explorer/endpoints/quote-create) request.

    ```json
    {
        "from": "ETH",
        "to": "USDC",
        "fromWalletLsid": "a:26012726855253:zMpcRHg:1",
        "useMaximum": false,
        "useMinimum": false,
        "reference": "REF6435921392",
        "toWalletLsid": "a:26012659807080:SsaiV4j:1",
        "amountIn": "0.004",
        "payInMethod": "wallet",
        "payOutMethod": "wallet"
    }
    ```

    For detailed request parameters, refer to the [Create Quote](../../../api-explorer/endpoints/quote-create) endpoint documentation.

    You will receive a response with the quote price, applicable fees, and the quote UUID.

    ```json Example Response
    {
      ...
      "quoteUuid": "019bfe65-92d8-7738-b855-1734474b279f",
      "price": "0.004",
      "fees": "0.0004",
      "quoteStatus": "PENDING",
      "paymentStatus": "PENDING"
      ...
    }
    ```

    :::note
    Many customers prefer a one-step flow rather than creating a quote and then accepting it separately. If you want to explore auto-accepting quotes via the quote endpoint, contact BVNK support or check the [Create Quote](../../../api-explorer/endpoints/quote-create) endpoint documentation for available options.
    :::

2. Accept the quote by sending the [`PUT /api/v1/quote/{uuid}`](../../../api-explorer/endpoints/quote-accept) request with the quote UUID received in the previous response.

    ```curl Example Request
    curl -X PUT https://api.staging.bvnk.com/api/v1/quote/accept/019bfe65-92d8-7738-b855-1734474b279f
    ```

    :::warning
    You may choose whether or not to display the rate to your customers, but you must **not** present it as a guaranteed rate. The rate must be shown as indicative only, reflecting the nature of the service BVNK provides to that user.
    :::

After you accept the quote, the stablecoins are credited to the user's wallet immediately.

## Get wallet balance

For the best user experience, we recommend implementing functionality to retrieve wallet balances. Integrate the [Get Wallet](../../../api-explorer/endpoints/wallet-read) or [List Wallet Balances](../../../api-explorer/endpoints/wallet-balance-list) endpoints to display real-time balances to users on your platform.

This allows users to:
- View the current balances of their wallets (including available and pending amounts).
- Confirm that funds have arrived before starting transfers or conversions.
- Track their assets across multiple currencies or wallets.
- Increase trust and transparency in your application.

## Receive notifications

Use the [Webhooks](../../../get-started/create-webhook-listener) feature to receive notifications about wallet balance changes.

When the wallet balance changes, you will receive a webhook notification with the following details:

- The wallet ID
- The new balance
- The currency
- The timestamp
- The transaction ID

---

## Tutorial Intro


Let's discover **Docusaurus in less than 5 minutes**.

## Getting Started

Get started by **creating a new site**.

Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**.

### What you'll need

- [Node.js](https://nodejs.org/en/download/) version 18.0 or above:
  - When installing Node.js, you are recommended to check all checkboxes related to dependencies.

## Generate a new site

Generate a new Docusaurus site using the **classic template**.

The classic template will automatically be added to your project after you run the command:

```bash
npm init docusaurus@latest my-website classic
```

You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor.

The command also installs all necessary dependencies you need to run Docusaurus.

## Start your site

Run the development server:

```bash
cd my-website
npm run start
```

The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there.

The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/.

Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes.

---

## Beneficiary

### Term explanation

The entity that receives the transaction.

---

## Originator

### Term explanation

The entity that initiates the transaction. For example, a customer that wants to buy crypto with fiat currency.