> ## 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.

# 管理收款人

> 通过 VelaFi API 获取模板、添加收款人并进行管理，为出金和全球支付保存付款目的地。

**收款人**是已保存的付款目的地——银行账户、移动钱包或支付标识符——您的商户在出金或全球法币兑法币支付操作中会向其发送资金。添加收款人包括两个步骤：首先，获取您要使用的支付方式的字段模板；然后，提交填写完整的模板以注册该目的地。保存后，收款人可重复用于多次付款，无需每次重新输入账户详情。

***

## 第 1 步：获取支付方式模板

在添加收款人之前，请获取所选支付方式的模板。模板会准确告诉您该支付方式需要填写哪些字段。

**端点**

```
GET https://api.velafi.com/v2/payments/templates
```

**请求头**

```http theme={null}
X-BH-TOKEN: <your-token>
```

### 请求参数

**paymentId** `number` *required*

支付方式的数字 ID。每种支付方式（例如墨西哥的 SPEI、阿根廷的 CVU、SEPA、WIRE/ACH）都有自己的 ID。常用 ID 请参见下表。

### 常用支付方式 ID

| 支付 ID | 名称 | 类型 | 国家 / 网络 |
| - | - | - | - |
| `105` | SPEI (Finco Pay) | 自动 | 墨西哥 |
| `72` | SPEI (Tesored) | 自动 | 墨西哥 |
| `63`（沙盒环境：`18`） | CBU/CVU (Momentum) | 自动 | 阿根廷 |
| `137` | 3.0 Transfer (QR) | 自动 | 阿根廷 |
| `90` | Pix (Genial) | 自动 | 巴西 |
| `92` | Pix - Woovi (Avenia) | 自动 | 巴西 |
| `68` | Automatic ACH | 自动 | 哥伦比亚 |
| `69` | Bre-B | 自动 | 哥伦比亚 |
| `95` | Bank Transfer | 自动 | 秘鲁 |
| `81`（沙盒环境：`532`） | ACH Reference (Lead Bank) | 自动 | 美国 |
| `83`（沙盒环境：`534`） | FedWire Reference (Lead Bank) | 自动 | 美国 |
| `85` | SEPA (Bridge) | 自动 | 欧洲 |
| `120` | Wire (CPN) | 自动 | 全球 |
| `124` | SEPA (CPN) | 自动 | 全球 |
| `127` | FEDWIRE (CPN) | 自动 | 美国 |

### 模板响应示例

> [tab] 墨西哥 — SPEI (Finco Pay)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=105
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "Account Type": "",
>     "Account Number": "",
>     "Beneficiary Name": "",
>     "Bank Code": ""
>   }
> }
> ```
>
> `Account Type`：`clabe`（虚拟账户）或 `debit`（银行卡账户）。
> `Bank Code`：仅当 `Account Type` 为 `debit` 时必填。

> [tab] 阿根廷 — CVU/CBU (Momentum)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=63
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "CVU/CBU Number": "",
>     "cuit": "",
>     "Bank name": ""
>   }
> }
> ```

> [tab] SEPA (Bridge)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=85
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "Bank Name": "",
>     "Account Owner Name": "",
>     "Account Owner Type": "",
>     "Bank Country/Region": "",
>     "Account Number": "",
>     "Bic": "",
>     "firstName": "",
>     "lastName": "",
>     "businessName": ""
>   }
> }
> ```
>
> `Account Owner Type`：`Business` 或 `Individual`。
> 如果为 `Business`：`businessName` 为必填项。
> 如果为 `Individual`：`firstName` 和 `lastName` 为必填项。
> `Bank Country/Region`：ISO 3166-1 alpha-2 国家代码。

> [tab] WIRE / ACH (Lead Bank)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=81
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "Bank Name": "",
>     "Account Owner Name": "",
>     "Account Owner Type": "",
>     "Bank Country/Region": "",
>     "Account Number": "",
>     "Routing Number": "",
>     "Street Line1": "",
>     "Street Line2": "",
>     "City": "",
>     "State": "",
>     "Postal Code": "",
>     "firstName": "",
>     "lastName": "",
>     "businessName": ""
>   }
> }
> ```
>
> `Account Owner Type`：`Business` 或 `Individual`。
> `Bank Country/Region`：ISO 3166-1 alpha-2。
> `State`：ISO 3166-2 州/省代码。

***

## 第 2 步：添加收款人

获取目标支付方式的模板后，填写字段并提交 `POST` 请求，在某个商户下注册该收款人。

**端点**

```
POST https://api.velafi.com/v2/payments
```

**请求头**

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

### 请求参数

**merchantId** `number` *required*

此收款人所属商户的 ID。

**paymentId** `number` *required*

支付方式的 ID。必须与系统中已有的支付方式 ID 相匹配。

**country** `string` *required*

收款人所在国家的完整名称（例如 `Mexico`、`Argentina`、`Brazil`）。

**fiat** `string` *required*

此收款人的法币（例如 `MXN`、`ARS`、`USD`、`EUR`）。

**fieldJson** `object` *required*

以键值对象形式填写的支付模板字段。键和值的格式必须与 `GET /v2/payments/templates` 返回的模板相匹配。

**realName** `string`

账户持有人的真实姓名。可选，但建议填写以便留存合规记录。

**remark** `string`

附加到此收款人记录的可选自由文本备注。

### 请求示例

> [accordion] 墨西哥 MXN — SPEI (Finco Pay)
>
> ```json theme={null}
> {
>   "merchantId": 123,
>   "paymentId": 105,
>   "country": "Mexico",
>   "fiat": "MXN",
>   "realName": "John Doe",
>   "fieldJson": {
>     "Account Type": "clabe",
>     "Account Number": "123456789012345678",
>     "Beneficiary Name": "John Doe",
>     "Bank Code": ""
>   },
>   "remark": "Primary MXN beneficiary"
> }
> ```

> [accordion] 阿根廷 ARS — CVU/CBU (Momentum)
>
> ```json theme={null}
> {
>   "merchantId": 123,
>   "paymentId": 63,
>   "country": "Argentina",
>   "fiat": "ARS",
>   "realName": "John Doe",
>   "fieldJson": {
>     "CVU/CBU Number": "0000000000000000000002",
>     "CUIT": "20000000001"
>   },
>   "remark": "Primary ARS beneficiary"
> }
> ```

> [accordion] 巴西 BRL — Pix (Genial)
>
> ```json theme={null}
> {
>   "merchantId": 123,
>   "paymentId": 90,
>   "country": "Brazil",
>   "fiat": "BRL",
>   "realName": "Tom",
>   "fieldJson": {
>     "Pix Type": "EMAIL",
>     "Pix Key": "tom@example.com"
>   },
>   "remark": "Primary BRL beneficiary"
> }
> ```
>
> `Pix Type` 可接受的值：`CPF`（11 位数字）、`CNPJ`（14 位数字）、`EMAIL`、`PHONE`（10-11 位数字）、`RANDOM_KEY`（含 `-`）。

> [accordion] 哥伦比亚 COP — Automatic ACH
>
> ```json theme={null}
> {
>   "merchantId": 123,
>   "paymentId": 68,
>   "country": "Colombia",
>   "fiat": "COP",
>   "realName": "Tom",
>   "fieldJson": {
>     "Account Type": "cc",
>     "Full Name": "Tom",
>     "ID Document Type": "cc",
>     "ID Document Number": "123456789",
>     "Bank Code": "1007",
>     "Bank Account Number": "9876543210"
>   },
>   "remark": "Primary COP beneficiary"
> }
> ```

> [accordion] 全球 USD — Wire (CPN)
>
> ```json theme={null}
> {
>   "merchantId": 123,
>   "paymentId": 120,
>   "country": "United States",
>   "fiat": "USD",
>   "realName": "Tom",
>   "fieldJson": {
>     "beneficiaryName": "Tom",
>     "country": "US",
>     "stateProvince": "US-AK",
>     "city": "Alaska",
>     "street": "789 Main Street",
>     "postalCode": "10001",
>     "dateOfBirth": "1990-01-01",
>     "idNumber": "123456",
>     "idExpirationDate": "2099-01-01",
>     "useCase": "B2B",
>     "reasonForPayment": "PMT001",
>     "bankName": "Bank of Example",
>     "bankCountry": "US",
>     "swiftCode": "EXAMPLUSXXX",
>     "accountNumber": "123456"
>   },
>   "remark": "USD wire beneficiary"
> }
> ```

### 响应字段

**code** `number`

响应码。`200` 表示请求已处理。

**msg** `string`

人类可读的结果消息。

**data** `object`

**data 字段**

**id** `number`

分配给此收款人的用户支付 ID。在付款请求中使用此 ID 引用该收款人。

**status** `number`

收款人的验证状态：

* `1` — 有效，可以接收付款。
* `2` — 认证中（验证进行中）。
* `3` — 认证失败。

**failReason** `string`

当 `status` 为 `3` 时的失败描述。成功时为空。

**sameAccountNumberId** `number`

当 `status` 因账户重复而为 `3` 时，此字段包含具有相同账号的现有有效收款人的 `id`。付款时请使用此 ID，而不是创建新记录。

> [tab] 成功
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 456,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 456
>   }
> }
> ```

> [tab] 账户重复
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 0,
>     "status": 3,
>     "failReason": "account already exists",
>     "sameAccountNumberId": 100
>   }
> }
> ```
>
> 请使用 `sameAccountNumberId`（本例中为 `100`）作为付款的收款人 ID——该账户已作为有效记录存在。

***

## 管理收款人

创建收款人后，您可以通过其他 API 操作对其进行管理：

> [card] [获取收款人](https://docs.velafi.com/cn/api-reference/beneficiary/get-beneficiary.md)
>
> 通过用户支付 ID 获取已保存收款人的详情。

> [card] [删除收款人](https://docs.velafi.com/cn/api-reference/beneficiary/delete-beneficiary.md)
>
> 删除不再需要的收款人。

> [card] [设置退款账户](https://docs.velafi.com/cn/api-reference/beneficiary/set-refund-account.md)
>
> 将某个收款人指定为商户的默认退款目的地。

> [card] [获取支付模板](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md)
>
> 所有支付方式模板及字段要求的完整参考。

> [!NOTE]
>
> 在同一商户 ID 和 `paymentId` 下，同一收款账号同一时间只能有一条处于 `valid` 状态的记录。如果您尝试添加重复记录，API 将返回 `status: 3`，并附带指向现有有效记录的 `sameAccountNumberId`。


## Related topics

- [API 概览](https://docs.velafi.com/cn/api-reference/overview.md)
- [添加收款人](https://docs.velafi.com/cn/api-reference/beneficiary/add-beneficiary.md)
- [删除收款人](https://docs.velafi.com/cn/api-reference/beneficiary/delete-beneficiary.md)
- [获取收款人列表](https://docs.velafi.com/cn/api-reference/beneficiary/get-beneficiary.md)
- [设置退款账户](https://docs.velafi.com/cn/api-reference/beneficiary/set-refund-account.md)


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