商户
创建商户
在 VelaFi 合规框架下注册新的个人或企业商户，并获取唯一的 KYC/KYB 验证链接。
POST
/
v2
/
merchants
创建商户
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>"
}
}使用此端点创建新的商户实体，并启动 KYC（个人）或 KYB（企业）验证流程。提交必填字段后，VelaFi 会分配一个唯一的商户 ID，并返回一个托管验证链接，您的终端用户必须通过该链接完成验证。对于已存在但尚未验证的商户，您也可以仅提交其
merchantId 和 callbackUrl 来重新生成验证链接。
所有请求都必须包含
X-BH-TOKEN 请求头（携带通过 GET /v2/token/generate 获取的业务令牌）以及 Content-Type: application/json。端点
POST https://api.velafi.com/v2/merchants
请求参数 — 新商户（KYC/KYB）
string
必填
商户的唯一显示名称。
string
必填
商户账户的唯一电子邮件地址。
string
必填
商户实体类型。可选值：
INDIVIDUAL、BUSINESS。string
必填
KYC/KYB 验证完成后 VelaFi 回调的 URL。
string
KYC/KYB 界面的语言。可选值：
en（默认）、es、pt、zh。string
KYC 验证流程，仅适用于
INDIVIDUAL 商户。可选值：PROFESSIONALS（默认）、CONSUMERS。string
附加到商户记录的自由文本备注。
string
必填
商户的行业类别。可选值：
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
当
industryType 为 other 时必填。描述商户的具体行业。请求参数 — 未验证商户（重新生成链接）
当商户已存在但尚未完成验证时，使用此方式。number
必填
现有商户的 ID。
string
必填
KYC/KYB 验证完成后 VelaFi 回调的 URL。
string
KYC/KYB 界面的语言。可选值：
en（默认）、es、pt、zh。响应字段
number
HTTP 风格的响应码。
200 表示成功。string
可读的状态消息，例如
SUCCESS。示例
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"
}
}
收到
kycLink 后，请立即引导终端用户访问该 URL。链接会过期，且验证开始后无法重复使用。⌘I
创建商户
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>"
}
}