Create a Merchant

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

X-BH-TOKEN: <your-token>
Content-Type: application/json

Request Parameters

string

required

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

string

required

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

string

required

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

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.

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.

string

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

string

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

string

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

string

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

Example Request

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"
  }'

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

number

Response code. 200 indicates success.

string

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

object

Show data fields

number

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

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.

Example Response

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

Redirect Mode
Embedded (iframe) 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.

window.location.href = data.kycLink;

Embed the kycLink URL in an <iframe> within your application for a seamless, in-app experience.

<iframe
  src="https://www.velafi.com/verify?velafi_token=abc123"
  width="100%"
  height="700"
  title="Identity Verification"
/>

Only use Mintlify-compatible components in MDX pages. The iframe snippet above is for your application’s frontend code, not for this documentation page.

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:

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

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.

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.

Get Started

Core Concepts

Guides

Reference

Create a Merchant

Why Merchants Are Required