激活商户账户

激活商户的法币支付账户后，即可接入受支持国家/地区的本地银行渠道。激活后，商户将获得一个专属虚拟账户——例如阿根廷的 CVU/CUIT 号码——并可立即通过电汇或本地支付通道收发资金。VelaFi 会自动对账入账存款，并将其记入商户的账户余额。个人和企业账户类型均受支持，因此您可以在同一集成中为终端用户和企业客户激活账户。

支持的币种

币种	国家/地区	支付方式示例
`MXN`	墨西哥	SPEI via Finco Pay、SPEI via Tesored
`ARS`	阿根廷	CBU/CVU (Momentum)、3.0 Transfer (QR)
`BRL`	巴西	Pix (Genial)、Pix - Woovi (Avenia)
`COP`	哥伦比亚	PSE、ACH、Bre-B
`PEN`	秘鲁	银行转账
`USD`	美国 / 全球	ACH、Wire、SEPA (Lead Bank)；Wire、SEPA、FEDWIRE (CPN)
`EUR`	欧洲	SEPA (Lead Bank)、SEPA (CPN)

通过 Lead Bank 激活 EUR 账户后，同一账户也将支持 USD 交易。

端点

个人和企业激活均使用同一端点：

POST https://api.velafi.com/v2/merchant/accounts

请求头

X-BH-TOKEN: <your-token>
Content-Type: application/json

为个人商户激活

当商户的 merchantType 为 INDIVIDUAL 时，请使用此方式。

核心请求参数

string

必填

创建商户时返回的商户 ID。

string

必填

要激活的法币。可接受的值：MXN、ARS、BRL、COP、PEN、USD、EUR。

string

必填

该币种使用的支付渠道（服务商）。可用的 trench 值取决于所选的 fiat。完整列表请参见下方示例。

object

所选 trench 需要的其他渠道特定字段。必填字段因币种和服务商而异——请参见下方示例。

string

可选。对于通过 Lead Bank 开立的 USD/EUR 账户，用户接受账户协议后将被重定向到的 URL。如果省略，将使用 VelaFi 默认的重定向 URL。

请求示例（个人）

墨西哥 MXN — SPEI (Finco Pay)

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

墨西哥 MXN — SPEI (Tesored)

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

阿根廷 ARS — CBU/CVU (Momentum)

{
  "merchantId": "100001",
  "fiat": "ARS",
  "trench": "CVU - Momentum",
  "fieldList": {
    "email": "user@example.com",
    "cuit": "30000000001",
    "name": "COCOS CAPITAL SA",
    "alias": "my.alias"
  }
}

阿根廷 ARS — 3.0 Transfer (QR)

{
  "merchantId": "100001",
  "fiat": "ARS",
  "trench": "QR Argentina",
  "fieldList": {
    "cuit": "123456789"
  }
}

巴西 BRL — Pix (Genial)

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

哥伦比亚 COP — PSE/ACH/Bre-B

{
  "merchantId": "100001",
  "fiat": "COP",
  "trench": "COP Account",
  "fieldList": {
    "alias": "my.alias"
  }
}

秘鲁 PEN — 银行转账

{
  "merchantId": "100001",
  "fiat": "PEN",
  "trench": "PEN Account",
  "fieldList": {
    "customerIdentificationType": "00",
    "customerIdentification": "12345678",
    "customerName": "Tom",
    "lastName": "Garcia",
    "customerEmail": "tom@example.com",
    "customerPhone": "975728895"
  }
}

EUR/USD — Lead Bank

{
  "merchantId": "100001",
  "fiat": "EUR",
  "trench": "Lead Bank",
  "callbackUri": "https://yourapp.com/account/verified",
  "fieldList": {
    "email": "user@example.com",
    "firstName": "Maria",
    "lastName": "Lopez"
  }
}

巴西 BRL — 个人 Pix (Woovi)： 首先调用获取 Woovi 活体检测 URL，并让商户完成活体检测。然后使用 trench: "Pix - Woovi" 和 personalInfo 对象调用此端点（参见激活个人账户）。如果活体检测未完成，请求将失败并返回错误码 -5059。

为企业商户激活

当商户的 merchantType 为 BUSINESS 时，请使用此方式。端点和核心参数完全相同；但对于需要详细公司信息和 UBO（最终受益所有人）信息的渠道，fieldList 结构有所不同。如果您的账户未使用依赖模式 (Reliance Mode)，为企业商户激活 CLABE - FINCO PAY、CLABE - TESORED、CVU - Momentum、QR Argentina、COP Account、BANCO GENIAL 或 PEN Account 时，将返回 status: 0 和一个用于额外企业验证的 verifyLink，而不是直接开通渠道。参见激活企业账户。

请求示例（企业）

墨西哥 MXN — SPEI (Finco Pay)

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

阿根廷 ARS — CBU/CVU (Momentum)

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

巴西 BRL — Pix (Woovi) — 完整企业示例

{
  "merchantId": "100001",
  "fiat": "BRL",
  "trench": "Pix - Woovi",
  "fieldList": {
    "companyInfo": {
      "companyName": "AURORA SANDBOX TECNOLOGIA LTDA.",
      "companyDescription": "Fintech payments provider",
      "countryStateOfIncorporation": "BR-SP",
      "website": "aurora.com.br",
      "socialMedia": "@auroratech",
      "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": 50000,
      "companyRegistrationNumber": "00000000000001",
      "taxIdentificationNumberTin": "00000000000002",
      "taxIdentificationDocumentUrl": "1172300499489225472/5c2d8e4a-1b7f-4a39-8e60-2f9d3c7b1a45.pdf",
              "certificateOfIncorporationDocumentUrl": "1172300499489225472/9e4a7b2c-3d1f-4c68-a5b0-8f2e6d1c9b37.pdf"
    },
    "companyUbosInfo": [
      {
        "personType": "CEO",
        "firstName": "Ana",
        "lastName": "Souza",
        "email": "ana@example.com",
        "phone": "+5511999999999",
        "percentageOfOwnership": 1,
        "nationality": "BR",
        "taxIdentificationNumber": "000000000000000000",
        "dateOfBirth": "1985-03-22",
        "street1": "Rua das Flores, 42",
        "city": "São Paulo",
        "countryStateCode": "BR-SP",
        "postcode": "01310-100",
        "idType": "3",
        "govIdCountryAbbr": "BR",
        "govIdFrontUrl": "1172300499489225472/f97d9f9b-641a-4245-8d99-aa4788015e38.jpg"
      }
    ]
  }
}

EUR/USD — Lead Bank（企业）

{
  "merchantId": "100001",
  "fiat": "EUR",
  "trench": "Lead Bank",
  "callbackUri": "https://yourapp.com/account/verified",
  "fieldList": {
    "email": "finance@acme.com",
    "companyName": "Acme Payments Ltd"
  }
}

响应

响应字段

number

响应码。200 表示请求已被接受。

string

人类可读的结果消息，例如 SUCCESS。

object

显示 data 字段

string

已激活的币种。

number

渠道状态：0 = 已初始化（附带 verifyLink 时，需要进行额外的企业验证），1 = 待处理，2 = 已激活，3 = 失败（参见 failReason），4 = 不完整（例如仍需完成 verifyLink 中步骤的 Lead Bank 账户）。请轮询列出商户账户，直到 status 为 2。

string

商户必须打开以继续激活的链接。对于 USD/EUR Lead Bank 账户，该链接指向账户协议；对于需要额外企业验证的企业商户，该链接会随 status: 0 一起返回。

string

失败原因描述。成功时为空。

MXN / ARS / COP / BRL / PEN
USD / EUR

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "MXN",
    "status": 1,
    "failReason": ""
  }
}

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

资金如何对账

商户账户激活后，商户将获得专属的银行信息——例如墨西哥的 CLABE 号码或阿根廷的 CVU/CUIT。商户可以指示其付款方向这些账户信息发起电汇。VelaFi 会自动识别入账转账并与商户余额进行对账，将资金记入账户，您无需进行任何人工操作。

部分币种和 trench 配置需要提供额外文件（例如巴西 Pix - Woovi 需要身份证件，企业账户需要公司注册证书）。在开始激活之前，请联系 contact@velafi.com 获取各国家/地区及账户类型的完整文件要求清单。

快速入门

核心概念

指南

参考

激活商户账户

支持的币种

端点

为个人商户激活

核心请求参数

请求示例（个人）

为企业商户激活

请求示例（企业）

响应

响应字段

资金如何对账

​支持的币种

​端点

​为个人商户激活

​核心请求参数

​请求示例（个人）

​为企业商户激活

​请求示例（企业）

​响应

​响应字段

​资金如何对账

支持的币种

端点

为个人商户激活

核心请求参数

请求示例（个人）

为企业商户激活

请求示例（企业）

响应

响应字段

资金如何对账