激活企业商户账户

POST

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

使用此端点为企业（BUSINESS 类型）商户开通一个或多个法币支付通道。该流程与个人开通流程类似，但企业账户通常需要较少的个人字段，并且根据支付服务商的不同，可能需要提供公司注册数据和 UBO（最终受益所有人）信息。

所有请求都必须包含 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

显示 data 字段

string

已开通的法币。

number

通道状态：0 = 已初始化（当同时返回 verifyLink 时，需要进行额外的企业验证；见下文），1 = 处理中（通道正在开通或审核中），2 = 已激活，3 = 失败（参见 failReason），4 = 未完成（需要执行进一步步骤，例如在 verifyLink 中完成）。请轮询查询商户账户列表，直到 status 为 2。

string

企业需要打开以继续操作的 URL。当需要额外的企业验证时，会随 status: 0 一起返回；对于 USD/EUR Lead Bank 通道，企业需通过该链接完成所需的合规协议。

string

开通失败的原因说明（如适用）。

企业激活的工作方式

企业激活会走以下两种路径之一。响应会告诉您实际走的是哪一种。 额外的企业验证（status: 0 并返回 verifyLink）。 对于企业商户，MXN（CLABE - FINCO PAY、CLABE - TESORED）、COP（COP Account）、ARS（CVU - Momentum、QR Argentina）、BRL（BANCO GENIAL）和 PEN（PEN Account）的本地通道通常需要针对该通道完成一次额外的 KYB 验证。响应会返回 status: 0 和 verifyLink。请引导企业访问该链接完成验证。VelaFi 审核通过后，通道会自动开通，您无需再次调用此端点。在这条路径上，请求中的 fieldList 不会被使用。 直接激活。 如果 VelaFi 为您的账户开启了直接激活，通道将根据您的请求直接开通，fieldList 必须包含该通道的必填字段。缺少字段或字段无效会导致请求被拒绝。

Trench	必填 `fieldList` 字段
`CLABE - FINCO PAY`	`alias`（最多 40 个字符）
`CLABE - TESORED`	`alias`（最多 64 个字符）
`COP Account`	`alias`（最多 64 个字符）
`CVU - Momentum`	`cuit`、`name`；`alias` 为可选
`QR Argentina`	`cuit`（最多 40 个字符）
`PEN Account`	`customerIdentificationType`、`customerIdentification`、`customerName`、`customerEmail`、`customerPhone`（仅限数字，最多 9 位）
`BANCO GENIAL`	无

各币种示例

MXN
ARS
COP / BRL / PEN
BRL Woovi（企业）
USD/EUR

MXN — 通过 Finco Pay 的 SPEI（trench: "CLABE - FINCO PAY"）

Request body

{
  "merchantId": "100001",
  "fiat": "MXN",
  "trench": "CLABE - FINCO PAY"
}

MXN — 通过 Tesored 的 SPEI（trench: "CLABE - TESORED"）

Request body

{
  "merchantId": "100001",
  "fiat": "MXN",
  "trench": "CLABE - TESORED"
}

ARS — 通过 Momentum 的 CVU（trench: "CVU - Momentum"）

Request body

{
  "merchantId": "100001",
  "fiat": "ARS",
  "trench": "CVU - Momentum"
}

ARS — QR 3.0 转账（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"
}

BRL — 通过 Genial 的 Pix（trench: "BANCO GENIAL"）

Request body

{
  "merchantId": "100001",
  "fiat": "BRL",
  "trench": "BANCO GENIAL"
}

PEN — 银行转账（trench: "PEN Account"）

Request body

{
  "merchantId": "100001",
  "fiat": "PEN",
  "trench": "PEN Account"
}

BRL — 通过 Woovi 的 Pix — 需要提供完整的公司信息和 UBO 信息。

Request body

{
  "merchantId": "100001",
  "fiat": "BRL",
  "trench": "Pix - Woovi",
  "fieldList": {
    "companyInfo": {
      "companyName": "AURORA SANDBOX TECNOLOGIA LTDA.",
      "companyDescription": "Fintech platform",
      "countryStateOfIncorporation": "BR-SP",
      "website": "aurora.com.br",
      "socialMedia": "@aurora",
      "street1": "Avenida Paulista, 1000",
      "city": "São Paulo",
      "countryStateCode": "BR-SP",
      "postcode": "01310-100",
      "reasonForAccountOpening": "ecommerce_retail_payments",
      "sourceOfFunds": "sales_of_goods_and_services",
      "numberOfEmployees": "11-50",
      "estimatedAnnualRevenueUsd": "1m_to_10m",
      "estimatedMonthlyVolumeUsd": 10000,
      "companyRegistrationNumber": "00000000000001",
      "taxIdentificationNumberTin": "00000000000002",
      "taxIdentificationDocumentUrl": "1172300499489225472/5c2d8e4a-1b7f-4a39-8e60-2f9d3c7b1a45.pdf",
      "certificateOfIncorporationDocumentUrl": "1172300499489225472/9e4a7b2c-3d1f-4c68-a5b0-8f2e6d1c9b37.pdf"
    },
    "companyUbosInfo": [
      {
        "personType": "CEO",
        "firstName": "Maria",
        "lastName": "Silva",
        "email": "maria@example.com",
        "phone": "+5511999990000",
        "percentageOfOwnership": 0.51,
        "nationality": "BR",
        "taxIdentificationNumber": "000000000000000000",
        "dateOfBirth": "1985-03-20",
        "street1": "Rua Augusta, 500",
        "city": "São Paulo",
        "countryStateCode": "BR-SP",
        "postcode": "01305-000",
        "idType": "1",
        "govIdCountryAbbr": "BR",
        "govIdFrontUrl": "1172300499489225472/f97d9f9b-641a-4245-8d99-aa4788015e38.jpg"
      }
    ]
  }
}

USD/EUR — Lead Bank（trench: "Lead Bank"）

Request body

{
  "merchantId": "100001",
  "fiat": "EUR",
  "trench": "Lead Bank",
  "callbackUri": "https://your-app.com/agreement-callback",
  "fieldList": {
    "email": "admin@company.com",
    "companyName": "CAPITAL SA COCOS"
  }
}

多币种 — Circle Payment Network（trench: "Circle Payment Network"）支持：USD、HKD、EUR、SGD、NGN。仅支持付款。

Request body

{
  "merchantId": "100001",
  "fiat": "USD",
  "trench": "Circle Payment Network"
}

响应示例

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "MXN",
    "status": 0,
    "verifyLink": "https://verify-sandbox.aiprise.com/?business_onboarding_session_id=xxx",
    "failReason": ""
  }
}

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "USD",
    "status": 4,
    "verifyLink": "https://www.velafi.com/business/channel/verify?token=12ceff08",
    "failReason": ""
  }
}

企业 BRL Woovi 开通需要完整的 companyInfo，以及 companyUbosInfo 中 1 到 50 个条目。文档字段（certificateOfIncorporationDocumentUrl、taxIdentificationDocumentUrl 以及每个 UBO 的 govIdFrontUrl）必须是上传文件返回的 fileUrl 值。公开 URL 将被拒绝。缺失或无效的字段会导致开通立即失败。

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

概览

账户

配置

商户

加密钱包

收款人

报价

订单

Webhooks

激活企业商户账户

端点

核心请求字段

响应字段

企业激活的工作方式

各币种示例

响应示例

​端点

​核心请求字段

​响应字段

​企业激活的工作方式

​各币种示例

​响应示例

端点

核心请求字段

响应字段

企业激活的工作方式

各币种示例

响应示例