> ## 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、COP、BRL、PEN、USD 和 EUR。

使用此端点为个人商户激活一个或多个法币支付渠道。激活后，商户将获得专属的银行账户信息（例如墨西哥的 CLABE、阿根廷的 CVU），并可接收入账电汇，VelaFi 会自动将其对账并计入商户余额。每种币种与支付服务商的组合都需要单独发送激活请求。

> [!NOTE]
>
> 所有请求都必须包含 `X-BH-TOKEN` 请求头和 `Content-Type: application/json`。

## 端点

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

## 核心请求字段

**merchantId** `string` *required*

要激活的商户 ID。

**fiat** `string` *required*

目标法币。支持的值：`MXN`、`ARS`、`COP`、`BRL`、`PEN`、`EUR`、`USD`。

**trench** `string` *required*

支付服务商或账户类型标识符。必须是所选 `fiat` 支持的值之一（参见下方示例）。

**callbackUri** `string`

商户接受合规协议后显示的重定向 URL。用于 Lead Bank 渠道；如果省略，将使用 VelaFi 默认的重定向 URL。

**fieldList** `object`

渠道特定字段。内容因 `fiat` 和 `trench` 而异。请参阅下方各币种示例。

## 响应字段

**code** `number`

HTTP 风格的响应码。`200` 表示成功。

**msg** `string`

可读的状态消息，例如 `SUCCESS`。

**data** `object`

**data 字段**

**fiat** `string`

已激活的法币。

**status** `number`

通道状态：`0` = 已初始化，`1` = 处理中，`2` = 已激活，`3` = 失败（参见 `failReason`），`4` = 未完成（商户需在 `verifyLink` 中完成某个步骤）。返回哪个值取决于通道，请参见下方的“激活结果”一节。

**verifyLink** `string`

对于需要额外签署协议步骤的 USD/EUR 渠道，此 URL 会将商户重定向至协议页面。

**failReason** `string`

激活失败的原因（如适用）。

## 各币种示例

> [tab] MXN
>
> **MXN — 通过 Finco Pay 的 SPEI**（`trench: "CLABE - FINCO PAY"`）
>
> ```bash cURL theme={null}
> 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" }
>   }'
> ```
>
> **MXN — 通过 Tesored 的 SPEI**（`trench: "CLABE - TESORED"`）
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "MXN",
>   "trench": "CLABE - TESORED",
>   "fieldList": { "alias": "arturo_alias" }
> }
> ```

> [tab] ARS
>
> **ARS — 通过 Momentum 的 CVU**（`trench: "CVU - Momentum"`）
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "ARS",
>   "trench": "CVU - Momentum",
>   "fieldList": {
>     "email": "arturo@example.com",
>     "cuit": "30000000001",
>     "name": "EXAMPLE COMPANY SA",
>     "alias": "example.alias"
>   }
> }
> ```
>
> **ARS — QR 3.0 转账**（`trench: "QR Argentina"`）
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "ARS",
>   "trench": "QR Argentina",
>   "fieldList": { "cuit": "123456789" }
> }
> ```

> [tab] COP
>
> **COP — PSE / ACH / Bre-B**（`trench: "COP Account"`）
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "COP",
>   "trench": "COP Account",
>   "fieldList": { "alias": "example.alias" }
> }
> ```

> [tab] BRL
>
> **BRL — 通过 Genial 的 Pix**（`trench: "BANCO GENIAL"`）
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "BRL",
>   "trench": "BANCO GENIAL"
> }
> ```
>
> **BRL — 通过 Woovi 的 Pix**（`trench: "Pix - Woovi"`）— 需要完整的个人信息并完成活体检测
>
> 请按以下顺序操作：
>
> 1. 调用[获取 Woovi 活体检测 URL](https://docs.velafi.com/cn/api-reference/merchant/get-woovi-liveness-url.md)，并让商户在返回的 `livenessUrl` 完成活体检测。
> 2. 发送下方的激活请求。如果活体检测尚未完成，请求将失败并返回错误码 `-5059`。
> 3. 响应返回 `status: 1`（处理中）。轮询[获取商户账户列表](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-of-merchant-accounts.md)，直到渠道 `status` 变为 `2`。
>
> 字段规则：`govIdFrontUrl` 和 `govIdBackUrl` 均为必填，且必须是[上传文件](https://docs.velafi.com/cn/api-reference/basic-configuration/upload-file.md)返回的 `fileUrl` 值。公共 URL 将被拒绝。`taxIdentificationNumber` 只能包含字母和数字。`dateOfBirth` 使用 `yyyy-MM-dd` 格式，且本人必须年满 18 岁。`idType` 为 `1`（身份证）、`2`（驾驶证）或 `3`（护照）。`countryStateCode` 由两位字母国家代码、连字符和州代码组成，例如 `BR-SP`。
>
> ```json Request body theme={null}
> {
>   "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": "100001/00000000-0000-0000-0000-000000000001.png",
>       "govIdBackUrl": "100001/00000000-0000-0000-0000-000000000004.png"
>     }
>   }
> }
> ```

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

> [tab] USD/EUR
>
> **USD/EUR — Lead Bank**（`trench: "Lead Bank"`）
>
> ```json Request body theme={null}
> {
>   "merchantId": "100001",
>   "fiat": "EUR",
>   "trench": "Lead Bank",
>   "callbackUri": "https://your-app.com/agreement-callback",
>   "fieldList": {
>     "email": "arturo@example.com",
>     "firstName": "Arturo",
>     "lastName": "Garcia"
>   }
> }
> ```
>
> **多币种 — Circle Payment Network**（`trench: "Circle Payment Network"`）
>
> 支持：USD、HKD、EUR、SGD、NGN。仅支持付款。
>
> ```json Request body theme={null}
> {
>   "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`（已激活）。您可以稍后通过[获取商户账户列表](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-of-merchant-accounts.md)查看通道状态。

| 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`），您可以通过[获取商户账户列表](https://docs.velafi.com/cn/api-reference/merchant/get-a-list-of-merchant-accounts.md)查看。

## 响应示例

```json MXN / ARS / COP / BRL (pending) theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "MXN",
    "status": 1,
    "failReason": ""
  }
}
```

```json PEN / Circle Payment Network (active) theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "PEN",
    "status": 2,
    "failReason": ""
  }
}
```

```json USD / EUR (agreement required) theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "fiat": "EUR",
    "status": 4,
    "verifyLink": "https://www.velafi.com/business/channel/verify?token=12ceff08",
    "failReason": ""
  }
}
```

> [!WARNING]
>
> 对于 BRL Woovi，商户必须在您调用此端点**之前**完成 Woovi 活体检测（参见[获取 Woovi 活体检测 URL](https://docs.velafi.com/cn/api-reference/merchant/get-woovi-liveness-url.md)）。否则请求将失败并返回错误码 `-5059`。对于 USD/EUR Lead Bank，响应会返回 `status: 4` 和 `verifyLink`。请引导商户访问该链接以完成剩余步骤。


## Related topics

- [激活商户账户](https://docs.velafi.com/cn/docs/guides/activating-merchant-account.md)
- [更新日志](https://docs.velafi.com/cn/docs/changelog.md)
- [激活企业商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-business.md)
- [获取 Woovi 活体检测 URL](https://docs.velafi.com/cn/api-reference/merchant/get-woovi-liveness-url.md)
- [商户](https://docs.velafi.com/cn/docs/merchants.md)


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