---
title: "Create merchant ID"
method: POST
path: "/api/v1/merchant"
tags: ["Merchant IDs"]
---

# Create merchant ID

`POST /api/v1/merchant`

## Request

- Base URL: `https://api.sandbox.bvnk.com`
- URL: `https://api.sandbox.bvnk.com/api/v1/merchant`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/docs/api/v1/merchant/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Request body

- object
  - `displayName` string, required: The name of the merchant that will be displayed on the payments page.
  - `webhookUrl` string: The URL that will recieve the webhooks.
  - `wallet` object, required
    - `id` string: The ID of the wallet to link to the merchant ID.

## Response `200`

OK

- MerchantDto
  - `id` integer: The ID of the Merchant ID.
  - `merchantId` string: The Merchant ID as a UUID.
  - `displayName` string: The name of the merchant displayed on the payments page.
  - `secret` string: The secret key used to validate webhooks.
  - `webhookUrl` string: The webhooks URL that webhoosk are sent to.
  - `autoConvertInvalidPayments` boolean: Is set to auto convert invalid payments.
  - `defaultExpiryMinutes` integer: The default number of minutes before a payment expires for this Merchant ID.
  - `webhookVersion` integer: The version of webhooks sent.
  - `wallet` WalletDto
    - `address` string: The crypto wallet address
    - `alternatives` unknown[]: The array of alternative protocol addresses.
      - unknown
    - `approxAvailable` string: The approximate amount availible in the wallet.
    - `approxBalance` string: The balance amount availible of the wallet.
    - `available` number, float
    - `balance` number, float: The balance of the wallet.
    - `convertedAvailable` number, float: The availible converted amount
    - `currency` CurrencyDto
      - `code` string: The currency code.
      - `depositFee` number: The % fee to deposit the currency.
      - `fiat` boolean: Is a fiat currency.
      - `icon` string: The icon of the currency.
      - `id` integer: The ID of the currency.
      - `name` string: The currency name.
      - `options` CurrencyOptions: The currency options.
        - `transaction` string: View onchain transactions.
        - `explorer` string: The explorer to view crypto network
        - `address` string: View wallet address
        - `confirmations` integer: Number of confirmations needed.
      - `pricePrecision` integer: The precision of decimal points for the currency.
      - `protocols` CurrencyProtocol[]: The alternative protocols array.
        - `code` string: The code of the currency.
        - `network` string: The network of the currency.
      - `quantityPrecision` integer: The precision of decimal points for the currency displayed.
      - `supportsDeposits` boolean: Is deposits for this currency supported.
      - `supportsWithdrawals` boolean: Is withdrawals for this currency supported
      - `withdrawalFee` number: The % fee to withdraw this currency.
      - `withdrawalParameters` ExternalCurrencyWithdrawalParameter[]: The withdrawal parameter object.
        - `id` integer: The ID of the external currency.
        - `code` string: The code of the external currency.
        - `name` string: The name of the external currency.
    - `custodianWallet` boolean: Is a custodian wallet.
    - `depositFee` number, float: The fee to deposit funds in wallet.
    - `description` string: The description of the wallet.
    - `id` integer: The wallet ID.
    - `isEmoney` boolean: Is E Money Wallet
    - `lookup` string: Is a lookup.
    - `network` string: The network of the wallet. We recommend using the `network` parameter instead of `protocol`.
    - `protocol` string: The protocol of the wallet.
    - `supportsDeposits` boolean: Is able to support deposits.
    - `supportsThirdParty` boolean: Is a third party wallet.
    - `supportsWithdrawals` boolean: Is able to support withdrawals.
    - `withdrawalFee` number, float: The fee to withdraw funds from wallet.
    - `supportsInternalBvnkNetworkTransfers` boolean: Supports internal BVNK network transfers.
    - `partner` string: Partner information.
    - `supportedTransferDestinations` string[]: List of supported transfer destinations.
    - `approxConvertedAvailable` string: The approximate converted available amount as a string.
    - `lsid` string: The wallet LSID (Local Session ID).
    - `status` 'ACTIVE' | 'INACTIVE' | 'TERMINATED': The status of the wallet.
  - `emailRecipients` string: The recipients of event emails.

## Other responses

- `400`: Bad Request

## Changes

- **2026-06-16** `97d6c0d2fe2e`: 2 info
  - the endpoint scheme security `ApiKeyAuth` was added to the API
  - the endpoint scheme security `Hawk` was removed from the API

[Operation history](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/changes/api/v1/merchant/post.md)

---

[API](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints.md) - [All operations](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/bvnk/apis/bvnk-api-endpoints/revisions/c386d436bf2c?raw)