Comercios
Crear un comercio
Registra un nuevo comercio, persona física o empresa, dentro del marco de cumplimiento de VelaFi y recibe un enlace único de verificación KYC/KYB.
POST
/
v2
/
merchants
Crear un comercio
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>"
}
}Usa este endpoint para crear una nueva entidad de comercio e iniciar el proceso de verificación KYC (persona física) o KYB (empresa). Una vez que envías los campos obligatorios, VelaFi asigna un Merchant ID único y devuelve un enlace de verificación alojado que tu usuario final debe completar. También puedes volver a generar un enlace de verificación para un comercio existente pero no verificado enviando solo su
merchantId y su callbackUrl.
Todas las solicitudes deben incluir el header
X-BH-TOKEN con un token de negocio obtenido de GET /v2/token/generate y Content-Type: application/json.Endpoint
POST https://api.velafi.com/v2/merchants
Parámetros de la solicitud: comercio nuevo (KYC/KYB)
string
requerido
Nombre para mostrar único del comercio.
string
requerido
Dirección de correo electrónico única de la cuenta del comercio.
string
requerido
Tipo de entidad del comercio. Valores aceptados:
INDIVIDUAL, BUSINESS.string
requerido
URL a la que VelaFi llama cuando se completa la verificación KYC/KYB.
string
Idioma de la interfaz de KYC/KYB. Valores aceptados:
en (predeterminado), es, pt, zh.string
Flujo de verificación KYC, solo para comercios
INDIVIDUAL. Valores aceptados: PROFESSIONALS (predeterminado), CONSUMERS.string
Nota de texto libre que se adjunta al registro del comercio.
string
requerido
La categoría de industria del comercio. Valores aceptados:
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
Obligatorio cuando
industryType es other. Describe la industria específica del comercio.Parámetros de la solicitud: comercio no verificado (volver a generar el enlace)
Usa esta variante cuando el comercio ya existe pero todavía no ha completado la verificación.number
requerido
El ID del comercio existente.
string
requerido
URL a la que VelaFi llama cuando se completa la verificación KYC/KYB.
string
Idioma de la interfaz de KYC/KYB. Valores aceptados:
en (predeterminado), es, pt, zh.Campos de la respuesta
number
Código de respuesta de estilo HTTP.
200 indica éxito.string
Mensaje de estado legible, por ejemplo
SUCCESS.object
Ejemplos
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"
}
}
Dirige a tu usuario final a la URL de
kycLink en cuanto la recibas. Los enlaces vencen y no se pueden reutilizar una vez que comienza la verificación.⌘I
Crear un comercio
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>"
}
}