> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a Merchant

> Register an individual or business merchant, initiate KYC/KYB verification, and receive a Merchant ID to use in all subsequent API calls.

Every entity that sends or receives money through VelaFi must be registered as a **merchant** and pass identity verification. VelaFi uses this process to comply with Know Your Customer (KYC) and Know Your Business (KYB) regulations. Once verification is complete, the platform assigns a unique **Merchant ID (MID)** to the entity. You must include this MID in every subsequent API call related to transactions, account management, and settlements.

## Why Merchants Are Required

VelaFi operates within a regulated financial ecosystem. Each merchant record ties a real-world individual or business to their on-ramp, off-ramp, and global payment activity. The compliance review ensures that all parties meet anti-money-laundering (AML) and counter-financing-of-terrorism (CFT) standards before any funds move.

***

## Create a Merchant

Send a `POST` request to `/v2/merchants` to register a new individual or business merchant and kick off the verification flow.

**Endpoint**

```
POST https://api.velafi.com/v2/merchants
```

**Headers**

```http theme={null}
X-BH-TOKEN: <your-token>
Content-Type: application/json
```

### Request Parameters

**merchantName** `string` *required*

The merchant's full name or business name. Must be unique across your account.

**email** `string` *required*

The merchant's email address. Must be unique across your account.

**merchantType** `string` *required*

The type of merchant entity. Accepted values: `INDIVIDUAL`, `BUSINESS`.

**callbackUrl** `string` *required*

The URL that VelaFi calls after the KYC/KYB process is completed (success or failure). VelaFi sends a POST notification to this URL.

**industryType** `string`

The merchant's industry sector. **Required when `merchantType` is `BUSINESS`.** Accepted values: `payment_psp`, `fintech`, `lending`, `fx_or_otc`, `e-commerce`, `gaming_or_entertainment`, `crypto_or_web3`, `supply_chain`, `import_or_export`, `payroll_or_hr`, `media_or_advertising`, `remittance_or_money_transfer`, `treasury_or_asset_management`, `wholesale_or_b2b_marketplace`, `logistics_and_courier`, `digital_content_or_streaming`, `travel_or_booking`, `online_marketplace`, `investment_and_crowdfunding`, `real_estate_and_proptech`, `accounting_or_billing`, `freelancer_platform`, `saas_or_api`, `online_education`, `outsourcing_agency`, `other`.

**flow** `string`

KYC flow for `INDIVIDUAL` merchants only. Accepted values: `PROFESSIONALS` (default), `CONSUMERS`.

**languageCode** `string`

The language for the KYC/KYB verification interface. Accepted values: `en` (default), `es`, `pt`, `zh`.

**remark** `string`

An optional free-text note to attach to this merchant record.

**industryTypeRemark** `string`

Required when `industryType` is set to `other`. Provide a short description of the merchant's actual industry.

### Example Request

```bash cURL theme={null}
curl -X POST https://api.velafi.com/v2/merchants \
  -H "X-BH-TOKEN: <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantName": "Acme Payments Ltd",
    "email": "payments@acme.com",
    "merchantType": "BUSINESS",
    "callbackUrl": "https://acme.com/webhooks/kyc",
    "languageCode": "en",
    "industryType": "fintech",
    "remark": "Primary merchant account"
  }'
```

```json Request Body theme={null}
{
  "merchantName": "Acme Payments Ltd",
  "email": "payments@acme.com",
  "merchantType": "BUSINESS",
  "callbackUrl": "https://acme.com/webhooks/kyc",
  "languageCode": "en",
  "industryType": "fintech",
  "remark": "Primary merchant account"
}
```

### Response Fields

**code** `number`

Response code. `200` indicates success.

**msg** `string`

Human-readable result message, e.g. `SUCCESS`.

**data** `object`

**data fields**

**merchantId** `number`

The unique Merchant ID (MID) assigned to this merchant. Store this value — you need it for all subsequent API calls.

**kycLink** `string`

The URL that leads to VelaFi's secure KYC/KYB verification page. Redirect your user to this URL or embed it in an iframe.

```json Example Response theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "merchantId": 100001,
    "kycLink": "https://www.velafi.com/verify?velafi_token=abc123"
  }
}
```

***

## Complete KYC/KYB Verification

After a successful `POST /v2/merchants` call, direct your user to the `kycLink` URL to complete identity verification. You have two integration options:

> [tab] Redirect Mode
>
> Redirect the user's browser directly to the `kycLink` URL. This is the simplest integration — the user completes verification on VelaFi's hosted page and is returned to your `callbackUrl` when finished.
>
> ```javascript theme={null}
> window.location.href = data.kycLink;
> ```

> [tab] Embedded (iframe) Mode
>
> Embed the `kycLink` URL in an `<iframe>` within your application for a seamless, in-app experience.
>
> ```html theme={null}
> <iframe
>   src="https://www.velafi.com/verify?velafi_token=abc123"
>   width="100%"
>   height="700"
>   title="Identity Verification"
> />
> ```
>
> > [!NOTE]
> >
> > Only use Mintlify-compatible components in MDX pages. The iframe snippet above is for your application's frontend code, not for this documentation page.

> [!WARNING]
>
> The `kycLink` URL may expire after a short period depending on session and configuration settings. Ensure your user accesses it promptly after the API call.

***

## Re-request the KYC Link for an Unverified Merchant

If a merchant did not complete verification during the initial session — for example, if the link expired or the user closed the browser — you can request a new `kycLink` without creating a duplicate merchant record. Pass the existing `merchantId` instead of the full merchant details:

```json theme={null}
{
  "merchantId": 100001,
  "callbackUrl": "https://acme.com/webhooks/kyc",
  "languageCode": "en"
}
```

The response contains a fresh `kycLink` that you can redirect the user to again.

***

## Merchant Management Modes

> [accordion] Multi-Merchant Management
>
> Once your primary merchant account has passed KYB verification, you can create and manage **sub-merchants** — either individuals or businesses — under your account. This enables hierarchical merchant management with role-based access control and per-merchant configuration.
>
> Common use cases include:
>
> * **Aggregators** managing payments on behalf of multiple clients
> * **Platforms** offering payment infrastructure to their own merchants
> * **Marketplace operators** handling compliance and settlements at the merchant level
>
> Each sub-merchant goes through its own KYC/KYB flow and receives its own MID.

> [accordion] Reliance Mode (Licensed Financial Institutions)
>
> If your organisation is a licensed financial institution, you can apply to enable **Reliance Mode**. In this mode:
>
> * You take responsibility for merchant onboarding, ongoing review, and compliance monitoring.
> * VelaFi does **not** intervene in your merchant onboarding workflow.
> * VelaFi continues to provide the technical infrastructure, settlement rails, and regulatory support.
>
> Reliance Mode requires an additional compliance review by the VelaFi Compliance Team. [Learn more about the Reliance Mode application process](https://velafi.notion.site/Reliance-Model-Onboarding-Guide-With-TruBit-2944850302de80619bb8daa72f3a8841).


## Related topics

- [Create a Merchant](https://docs.velafi.com/api-reference/merchant/create-merchant.md)
- [Create an Account](https://docs.velafi.com/docs/guides/creating-account.md)
- [Introduction](https://docs.velafi.com/docs/introduction.md)
- [Changelog](https://docs.velafi.com/docs/changelog.md)
- [VelaFi API Docs](https://docs.velafi.com/index.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.