商户
激活个人商户账户
为个人商户激活法币支付渠道，通过本地支付服务商支持 MXN、ARS、COP、BRL、PEN、USD 和 EUR。
POST
/
v2
/
merchant
/
accounts
激活个人商户账户
curl --request POST \
--url https://api-test.velafi.com/v2/merchant/accounts \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": "<string>",
"fiat": "<string>",
"trench": "<string>",
"callbackUri": "<string>",
"fieldList": {}
}
'import requests
url = "https://api-test.velafi.com/v2/merchant/accounts"
payload = {
"merchantId": "<string>",
"fiat": "<string>",
"trench": "<string>",
"callbackUri": "<string>",
"fieldList": {}
}
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({
merchantId: '<string>',
fiat: '<string>',
trench: '<string>',
callbackUri: '<string>',
fieldList: {}
})
};
fetch('https://api-test.velafi.com/v2/merchant/accounts', 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/merchant/accounts")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": \"<string>\",\n \"fiat\": \"<string>\",\n \"trench\": \"<string>\",\n \"callbackUri\": \"<string>\",\n \"fieldList\": {}\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"fiat": "<string>",
"status": 123,
"verifyLink": "<string>",
"failReason": "<string>"
}
}使用此端点为个人商户激活一个或多个法币支付渠道。激活后，商户将获得专属的银行账户信息（例如墨西哥的 CLABE、阿根廷的 CVU），并可接收入账电汇，VelaFi 会自动将其对账并计入商户余额。每种币种与支付服务商的组合都需要单独发送激活请求。
当服务商拒绝注册（
所有请求都必须包含
X-BH-TOKEN 请求头和 Content-Type: application/json。端点
POST https://api.velafi.com/v2/merchant/accounts
核心请求字段
string
必填
要激活的商户 ID。
string
必填
目标法币。支持的值：
MXN、ARS、COP、BRL、PEN、EUR、USD。string
必填
支付服务商或账户类型标识符。必须是所选
fiat 支持的值之一（参见下方示例）。string
商户接受合规协议后显示的重定向 URL。用于 Lead Bank 渠道；如果省略，将使用 VelaFi 默认的重定向 URL。
object
渠道特定字段。内容因
fiat 和 trench 而异。请参阅下方各币种示例。响应字段
number
HTTP 风格的响应码。
200 表示成功。string
可读的状态消息，例如
SUCCESS。object
各币种示例
- MXN
- ARS
- COP
- BRL
- PEN
- USD/EUR
MXN — 通过 Finco Pay 的 SPEI（MXN — 通过 Tesored 的 SPEI（
trench: "CLABE - FINCO PAY"）cURL
curl -X POST https://api.velafi.com/v2/merchant/accounts \
-H "X-BH-TOKEN: YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"merchantId": "100001",
"fiat": "MXN",
"trench": "CLABE - FINCO PAY",
"fieldList": { "alias": "arturo_alias" }
}'
trench: "CLABE - TESORED"）Request body
{
"merchantId": "100001",
"fiat": "MXN",
"trench": "CLABE - TESORED",
"fieldList": { "alias": "arturo_alias" }
}
ARS — 通过 Momentum 的 CVU（ARS — QR 3.0 转账（
trench: "CVU - Momentum"）Request body
{
"merchantId": "100001",
"fiat": "ARS",
"trench": "CVU - Momentum",
"fieldList": {
"email": "arturo@example.com",
"cuit": "30000000001",
"name": "COCOS CAPITAL SA",
"alias": "soc.te"
}
}
trench: "QR Argentina"）Request body
{
"merchantId": "100001",
"fiat": "ARS",
"trench": "QR Argentina",
"fieldList": { "cuit": "123456789" }
}
COP — PSE / ACH / Bre-B（
trench: "COP Account"）Request body
{
"merchantId": "100001",
"fiat": "COP",
"trench": "COP Account",
"fieldList": { "alias": "soc.te" }
}
BRL — 通过 Genial 的 Pix（BRL — 通过 Woovi 的 Pix（
trench: "BANCO GENIAL"）Request body
{
"merchantId": "100001",
"fiat": "BRL",
"trench": "BANCO GENIAL"
}
trench: "Pix - Woovi"）— 需要完整的个人信息并完成活体检测请按以下顺序操作：- 调用获取 Woovi 活体检测 URL，并让商户在返回的
livenessUrl完成活体检测。 - 发送下方的激活请求。如果活体检测尚未完成，请求将失败并返回错误码
-5059。 - 响应返回
status: 1（处理中）。轮询获取商户账户列表，直到渠道status变为2。
govIdFrontUrl 和 govIdBackUrl 均为必填，且必须是上传文件返回的 fileUrl 值。公共 URL 将被拒绝。taxIdentificationNumber 只能包含字母和数字。dateOfBirth 使用 yyyy-MM-dd 格式，且本人必须年满 18 岁。idType 为 1（身份证）、2（驾驶证）或 3（护照）。countryStateCode 由两位字母国家代码、连字符和州代码组成，例如 BR-SP。Request body
{
"merchantId": "100001",
"fiat": "BRL",
"trench": "Pix - Woovi",
"fieldList": {
"personalInfo": {
"firstName": "MARIA",
"lastName": "EXEMPLO",
"email": "maria@example.com",
"taxIdentificationNumber": "00000000001",
"nationality": "BR",
"dateOfBirth": "1990-01-01",
"street1": "Rua das Flores 123",
"city": "São Paulo",
"countryStateCode": "BR-SP",
"postcode": "01310-100",
"idType": "1",
"govIdCountryAbbr": "BR",
"govIdFrontUrl": "1172300499489225472/f97d9f9b-641a-4245-8d99-aa4788015e38.png",
"govIdBackUrl": "1172300499489225472/0b6e2c1d-7a3f-4e58-9c21-5d8f4a6b3e90.png"
}
}
}
PEN — 银行转账（
trench: "PEN Account"）Request body
{
"merchantId": "100001",
"fiat": "PEN",
"trench": "PEN Account",
"fieldList": {
"customerIdentificationType": "00",
"customerIdentification": "12345678",
"customerName": "Tom",
"lastName": "Garcia",
"customerEmail": "tom@example.com",
"customerPhone": "975728895"
}
}
USD/EUR — Lead Bank（多币种 — Circle Payment Network（
trench: "Lead Bank"）Request body
{
"merchantId": "100001",
"fiat": "EUR",
"trench": "Lead Bank",
"callbackUri": "https://your-app.com/agreement-callback",
"fieldList": {
"email": "arturo@example.com",
"firstName": "Arturo",
"lastName": "Garcia"
}
}
trench: "Circle Payment Network"）支持：USD、HKD、EUR、SGD、NGN。仅支持付款。Request body
{
"merchantId": "100001",
"fiat": "USD",
"trench": "Circle Payment Network",
"fieldList": {
"accountName": "Tom",
"nationality": "HK",
"idNumber": "123456",
"countryStateCode": "HK-HK",
"city": "Hong Kong",
"street": "789 Finance Street",
"postalCode": "123456",
"dateOfBirth": "1990-01-01",
"phoneNumber": "123456"
}
}
激活结果
首次激活返回的状态
大多数本地通道会返回status: 1（处理中），并在服务商完成开户后变为 2（已激活）。您可以稍后通过获取商户账户列表查看通道状态。
| Trench | 返回的状态 | 含义 |
|---|---|---|
CLABE - FINCO PAY、CLABE - TESORED（MXN） | 1 | 处理中，账户正在开通。 |
CVU - Momentum、QR Argentina（ARS） | 1 | 处理中 |
COP Account（COP） | 1 | 处理中 |
BANCO GENIAL（BRL） | 1 | 处理中 |
Pix - Woovi（BRL，由 Avenia 提供） | 1 | 处理中。仅在商户完成活体检测后返回。 |
PEN Account（PEN） | 2 | 立即激活 |
Circle Payment Network | 2 | 立即激活 |
Lead Bank（USD/EUR） | 4 | 未完成。请引导商户访问 verifyLink 签署协议并完成验证。 |
Lead Bank：重复调用
如果商户已有 Lead Bank 验证，而您再次为 Lead Bank 调用此端点：| 情况 | 返回的状态 |
|---|---|
| 验证尚未完成且仍可继续 | 4，并返回新的 verifyLink |
| 验证未被拒绝且无需重新进行 | 3，failReason 为 Kyc is on processing or completed |
返回错误而非状态的情况
以下情况会返回错误码，而不是status：
| 错误码 | 情况 |
|---|---|
-5074 | 该商户的此通道已激活。 |
-5062 | 此通道的激活已在处理中。 |
-5076 | 此通道已关闭。 |
-5078 | 此通道已被禁用。 |
-5079 | 商户没有此通道的激活权限。 |
-5073 | 商户未通过 KYC。 |
-5077 | 商户已被禁用。 |
-4010 | 缺少必填的 fieldList 字段或字段无效。 |
-5059 | 服务商无法为商户注册（msg：Merchant registration failure.）。对于 Pix - Woovi，同一错误码表示活体检测尚未完成（msg：Please first pass the Liveness authentication）。 |
-5066 | 仅限 Pix - Woovi：账户已在审核中。 |
-5067 | 仅限 Pix - Woovi：账户已激活。 |
-5059）时，该通道会被记录为失败（3），您可以通过获取商户账户列表查看。
响应示例
{
"code": 200,
"msg": "SUCCESS",
"data": {
"fiat": "MXN",
"status": 1,
"failReason": ""
}
}
{
"code": 200,
"msg": "SUCCESS",
"data": {
"fiat": "PEN",
"status": 2,
"failReason": ""
}
}
{
"code": 200,
"msg": "SUCCESS",
"data": {
"fiat": "EUR",
"status": 4,
"verifyLink": "https://www.velafi.com/business/channel/verify?token=12ceff08",
"failReason": ""
}
}
对于 BRL Woovi，商户必须在您调用此端点之前完成 Woovi 活体检测（参见获取 Woovi 活体检测 URL）。否则请求将失败并返回错误码
-5059。对于 USD/EUR Lead Bank，响应会返回 status: 4 和 verifyLink。请引导商户访问该链接以完成剩余步骤。⌘I
激活个人商户账户
curl --request POST \
--url https://api-test.velafi.com/v2/merchant/accounts \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": "<string>",
"fiat": "<string>",
"trench": "<string>",
"callbackUri": "<string>",
"fieldList": {}
}
'import requests
url = "https://api-test.velafi.com/v2/merchant/accounts"
payload = {
"merchantId": "<string>",
"fiat": "<string>",
"trench": "<string>",
"callbackUri": "<string>",
"fieldList": {}
}
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({
merchantId: '<string>',
fiat: '<string>',
trench: '<string>',
callbackUri: '<string>',
fieldList: {}
})
};
fetch('https://api-test.velafi.com/v2/merchant/accounts', 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/merchant/accounts")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": \"<string>\",\n \"fiat\": \"<string>\",\n \"trench\": \"<string>\",\n \"callbackUri\": \"<string>\",\n \"fieldList\": {}\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"fiat": "<string>",
"status": 123,
"verifyLink": "<string>",
"failReason": "<string>"
}
}