> ## Documentation Index
> Fetch the complete documentation index at: https://docs.velafi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 激活商户账户

> 为商户激活法币支付渠道，以支持 MXN、ARS、BRL、COP、PEN、USD 和 EUR 的本地银行存款和提现。

激活商户的法币支付账户后，即可接入受支持国家/地区的本地银行渠道。激活后，商户将获得一个专属虚拟账户——例如阿根廷的 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) |

> [!NOTE]
>
> 通过 Lead Bank 激活 `EUR` 账户后，同一账户也将支持 `USD` 交易。

***

## 端点

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

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

**请求头**

```http theme={null}
X-BH-TOKEN: <your-token>
Content-Type: application/json
```

***

## 为个人商户激活

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

### 核心请求参数

**merchantId** `string` *required*

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

**fiat** `string` *required*

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

**trench** `string` *required*

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

**fieldList** `object`

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

**callbackUri** `string`

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

### 请求示例（个人）

> [accordion] 墨西哥 MXN — SPEI (Finco Pay)
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "MXN",
>   "trench": "CLABE - FINCO PAY",
>   "fieldList": {
>     "alias": "my_alias"
>   }
> }
> ```

> [accordion] 墨西哥 MXN — SPEI (Tesored)
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "MXN",
>   "trench": "CLABE - TESORED",
>   "fieldList": {
>     "alias": "my_alias"
>   }
> }
> ```

> [accordion] 阿根廷 ARS — CBU/CVU (Momentum)
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "ARS",
>   "trench": "CVU - Momentum",
>   "fieldList": {
>     "email": "user@example.com",
>     "cuit": "30000000001",
>     "name": "EXAMPLE COMPANY SA",
>     "alias": "my.alias"
>   }
> }
> ```

> [accordion] 阿根廷 ARS — 3.0 Transfer (QR)
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "ARS",
>   "trench": "QR Argentina",
>   "fieldList": {
>     "cuit": "123456789"
>   }
> }
> ```

> [accordion] 巴西 BRL — Pix (Genial)
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "BRL",
>   "trench": "BANCO GENIAL"
> }
> ```

> [accordion] 哥伦比亚 COP — PSE/ACH/Bre-B
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "COP",
>   "trench": "COP Account",
>   "fieldList": {
>     "alias": "my.alias"
>   }
> }
> ```

> [accordion] 秘鲁 PEN — 银行转账
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "PEN",
>   "trench": "PEN Account",
>   "fieldList": {
>     "customerIdentificationType": "00",
>     "customerIdentification": "12345678",
>     "customerName": "Tom",
>     "lastName": "Garcia",
>     "customerEmail": "tom@example.com",
>     "customerPhone": "975728895"
>   }
> }
> ```

> [accordion] EUR/USD — Lead Bank
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "EUR",
>   "trench": "Lead Bank",
>   "callbackUri": "https://yourapp.com/account/verified",
>   "fieldList": {
>     "email": "user@example.com",
>     "firstName": "Maria",
>     "lastName": "Lopez"
>   }
> }
> ```

> [!NOTE]
>
> **巴西 BRL — 个人 Pix (Woovi)：** 首先调用[获取 Woovi 活体检测 URL](https://docs.velafi.com/cn/api-reference/merchant/get-woovi-liveness-url.md)，并让商户完成活体检测。然后使用 `trench: "Pix - Woovi"` 和 `personalInfo` 对象调用此端点（参见[激活个人账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-individual.md)）。如果活体检测未完成，请求将失败并返回错误码 `-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`，而不是直接开通渠道。参见[激活企业账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-business.md)。

### 请求示例（企业）

> [accordion] 墨西哥 MXN — SPEI (Finco Pay)
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "MXN",
>   "trench": "CLABE - FINCO PAY"
> }
> ```

> [accordion] 阿根廷 ARS — CBU/CVU (Momentum)
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "ARS",
>   "trench": "CVU - Momentum"
> }
> ```

> [accordion] 巴西 BRL — Pix (Woovi) — 完整企业示例
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "BRL",
>   "trench": "Pix - Woovi",
>   "fieldList": {
>     "companyInfo": {
>       "companyName": "EXEMPLO TECNOLOGIA LTDA.",
>       "companyDescription": "Fintech payments provider",
>       "countryStateOfIncorporation": "BR-SP",
>       "website": "example.com.br",
>       "socialMedia": "@example",
>       "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": "100001/00000000-0000-0000-0000-000000000002.pdf",
>               "certificateOfIncorporationDocumentUrl": "100001/00000000-0000-0000-0000-000000000003.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": "100001/00000000-0000-0000-0000-000000000001.jpg"
>       }
>     ]
>   }
> }
> ```

> [accordion] EUR/USD — Lead Bank（企业）
>
> ```json theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "EUR",
>   "trench": "Lead Bank",
>   "callbackUri": "https://yourapp.com/account/verified",
>   "fieldList": {
>     "email": "finance@acme.com",
>     "companyName": "Acme Payments Ltd"
>   }
> }
> ```

***

## 响应

### 响应字段

**code** `number`

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

**msg** `string`

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

**data** `object`

**data 字段**

**fiat** `string`

已激活的币种。

**status** `number`

渠道状态：`0` = 已初始化（附带 `verifyLink` 时，需要进行额外的企业验证），`1` = 待处理，`2` = 已激活，`3` = 失败（参见 `failReason`），`4` = 不完整（例如仍需完成 `verifyLink` 中步骤的 Lead Bank 账户）。请轮询[列出商户账户](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-of-merchant-accounts.md)，直到 `status` 为 `2`。

**verifyLink** `string`

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

**failReason** `string`

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

> [tab] MXN / ARS / COP / BRL / PEN
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "fiat": "MXN",
>     "status": 1,
>     "failReason": ""
>   }
> }
> ```

> [tab] USD / EUR
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "fiat": "USD",
>     "status": 4,
>     "verifyLink": "https://www.velafi.com/business/channel/verify?token=12ceff08f9621808b5a573972cdfb10f",
>     "failReason": ""
>   }
> }
> ```

***

## 资金如何对账

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

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


## Related topics

- [更新日志](https://docs.velafi.com/cn/docs/changelog.md)
- [商户](https://docs.velafi.com/cn/docs/merchants.md)
- [激活个人商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-individual.md)
- [激活企业商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-business.md)
- [获取商户账户列表](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-of-merchant-accounts.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.