Merchants
Create a Merchant
Register a new individual or business merchant under VelaFi’s compliance framework and receive a unique KYC/KYB verification link.
POST
/
v2
/
merchants
Create a Merchant
curl --request POST \
--url https://api-test.velafi.com/v2/merchants \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantName": "<string>",
"email": "<string>",
"merchantType": "<string>",
"callbackUrl": "<string>",
"languageCode": "<string>",
"flow": "<string>",
"remark": "<string>",
"industryType": "<string>",
"industryTypeRemark": "<string>",
"merchantId": 123
}
'import requests
url = "https://api-test.velafi.com/v2/merchants"
payload = {
"merchantName": "<string>",
"email": "<string>",
"merchantType": "<string>",
"callbackUrl": "<string>",
"languageCode": "<string>",
"flow": "<string>",
"remark": "<string>",
"industryType": "<string>",
"industryTypeRemark": "<string>",
"merchantId": 123
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchantName: '<string>',
email: '<string>',
merchantType: '<string>',
callbackUrl: '<string>',
languageCode: '<string>',
flow: '<string>',
remark: '<string>',
industryType: '<string>',
industryTypeRemark: '<string>',
merchantId: 123
})
};
fetch('https://api-test.velafi.com/v2/merchants', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/merchants")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantName\": \"<string>\",\n \"email\": \"<string>\",\n \"merchantType\": \"<string>\",\n \"callbackUrl\": \"<string>\",\n \"languageCode\": \"<string>\",\n \"flow\": \"<string>\",\n \"remark\": \"<string>\",\n \"industryType\": \"<string>\",\n \"industryTypeRemark\": \"<string>\",\n \"merchantId\": 123\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"merchantId": 123,
"kycLink": "<string>"
}
}Use this endpoint to create a new merchant entity and initiate the KYC (individual) or KYB (business) verification process. Once you submit the required fields, VelaFi assigns a unique Merchant ID and returns a hosted verification link your end user must complete. You can also re-generate a verification link for an existing but unverified merchant by submitting only their
merchantId and callbackUrl.
All requests must include the
X-BH-TOKEN header with a business token from GET /v2/token/generate and Content-Type: application/json.Endpoint
POST https://api.velafi.com/v2/merchants
Request Parameters — New Merchant (KYC/KYB)
string
required
Unique display name for the merchant.
string
required
Unique email address for the merchant account.
string
required
Type of merchant entity. Accepted values:
INDIVIDUAL, BUSINESS.string
required
URL that VelaFi calls after KYC/KYB verification completes.
string
Language for the KYC/KYB interface. Accepted values:
en (default), es, pt, zh.string
KYC verification flow for
INDIVIDUAL merchants only. Accepted values: PROFESSIONALS (default), CONSUMERS.string
Free-text note to attach to the merchant record.
string
required
The merchant’s industry category. 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, otherstring
Required when
industryType is other. Describe the merchant’s specific industry.Request Parameters — Unverified Merchant (Re-generate Link)
Use this variant when the merchant already exists but has not yet completed verification.number
required
The existing merchant’s ID.
string
required
URL that VelaFi calls after KYC/KYB verification completes.
string
Language for the KYC/KYB interface. Accepted values:
en (default), es, pt, zh.Response Fields
number
HTTP-style response code.
200 indicates success.string
Human-readable status message, e.g.
SUCCESS.object
Examples
curl -X POST https://api.velafi.com/v2/merchants \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"merchantName": "Tom",
"email": "tom@example.com",
"merchantType": "INDIVIDUAL",
"callbackUrl": "https://your-app.com/kyc-callback",
"languageCode": "en",
"flow": "PROFESSIONALS",
"industryType": "fintech"
}'
curl -X POST https://api.velafi.com/v2/merchants \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"merchantId": 100001,
"callbackUrl": "https://your-app.com/kyc-callback",
"languageCode": "en"
}'
{
"code": 200,
"msg": "SUCCESS",
"data": {
"merchantId": 100001,
"kycLink": "https://www.velafi.com/verify?velafi_token=abc123"
}
}
{
"code": 200,
"msg": "SUCCESS",
"data": {
"merchantId": 100001,
"kycLink": "https://www.velafi.com/verify?velafi_token=xyz789"
}
}
Direct your end user to the
kycLink URL as soon as you receive it. Links expire and cannot be reused once verification begins.Was this page helpful?
⌘I
Create a Merchant
curl --request POST \
--url https://api-test.velafi.com/v2/merchants \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantName": "<string>",
"email": "<string>",
"merchantType": "<string>",
"callbackUrl": "<string>",
"languageCode": "<string>",
"flow": "<string>",
"remark": "<string>",
"industryType": "<string>",
"industryTypeRemark": "<string>",
"merchantId": 123
}
'import requests
url = "https://api-test.velafi.com/v2/merchants"
payload = {
"merchantName": "<string>",
"email": "<string>",
"merchantType": "<string>",
"callbackUrl": "<string>",
"languageCode": "<string>",
"flow": "<string>",
"remark": "<string>",
"industryType": "<string>",
"industryTypeRemark": "<string>",
"merchantId": 123
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchantName: '<string>',
email: '<string>',
merchantType: '<string>',
callbackUrl: '<string>',
languageCode: '<string>',
flow: '<string>',
remark: '<string>',
industryType: '<string>',
industryTypeRemark: '<string>',
merchantId: 123
})
};
fetch('https://api-test.velafi.com/v2/merchants', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/merchants")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantName\": \"<string>\",\n \"email\": \"<string>\",\n \"merchantType\": \"<string>\",\n \"callbackUrl\": \"<string>\",\n \"languageCode\": \"<string>\",\n \"flow\": \"<string>\",\n \"remark\": \"<string>\",\n \"industryType\": \"<string>\",\n \"industryTypeRemark\": \"<string>\",\n \"merchantId\": 123\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"merchantId": 123,
"kycLink": "<string>"
}
}