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

# 添加收款人

> 为商户注册新的收款人。提供从模板接口获取的支付方式字段，成功后返回收款人 ID。

添加新的收款人，以便之后在出金或全球支付订单中引用。调用此接口之前，请先使用目标 `paymentId` 调用 `GET /v2/payments/templates` 获取所需的字段结构，并据此填写 `fieldJson` 对象。在同一商户 ID 和 `paymentId` 下，每个唯一的收款账户只能有一条有效状态的记录 —— 尝试注册重复账户时，将返回 `status: 3` 响应，其中 `sameAccountNumberId` 指向已存在的记录。

## 接口地址

```text theme={null}
POST https://api.velafi.com/v2/payments
```

> [!NOTE]
>
> 在沙盒环境中测试时，请使用 `https://api-test.velafi.com/v2/payments`。

## 请求头

| 请求头 | 值 |
| - | - |
| `X-BH-TOKEN` | 通过 `GET /v2/token/generate` 获取的 token |
| `Content-Type` | `application/json` |

## 请求体参数

**merchantId** `integer`

要在其下注册收款人的商户数字 ID。省略时使用你的默认商户。

**paymentId** `integer` *required*

支付方式的数字 ID。决定 `fieldJson` 中需要哪些字段。

**country** `string` *required*

收款人所在国家的全称（例如 `"Mexico"`、`"Argentina"`、`"Brazil"`）。

**fiat** `string` *required*

该收款人的 ISO 4217 法币代码（例如 `"MXN"`、`"ARS"`、`"BRL"`、`"USD"`）。

**realName** `string` *required*

账户持有人的法定真实姓名。

**fieldJson** `object` *required*

用于填充支付方式模板的键值对。通过调用 `GET /v2/payments/templates?paymentId={paymentId}` 获取确切的必填键。若字段的 `indexCode` 非空，则以其作为键；否则使用 `title` 字符串。各已启用付款方式的键见[获取支付模板](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md)页面的“各支付方式的收款人字段”一节。

**remark** `string`

关于该收款人的可选自由文本备注（例如 `"Preferred supplier account"`）。

## 响应字段

**code** `integer`

响应状态码。`200` 表示成功。

**msg** `string`

可读的响应信息。

**data** `object`

结果数据对象。

**data 字段**

**data.id** `integer`

新创建的用户支付方式（收款人）ID。在出金订单中将此值用作 `userPaymentId`。

**data.status** `integer`

认证状态：`1` = 有效，`2` = 认证中（异步验证进行中），`3` = 认证失败。

**data.failReason** `string`

当 `status` 为 `3` 时，说明认证失败的原因。成功时为空字符串。

**data.sameAccountNumberId** `integer`

当 `status` 因账户重复而为 `3` 时，该字段包含具有相同账号的已有有效收款人的 `id`。

## 示例

> [tab] 墨西哥 SPEI – Finco Pay (105)
>
> ```bash theme={null}
> curl -X POST "https://api.velafi.com/v2/payments" \
>   -H "X-BH-TOKEN: YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "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": "Preferred beneficiary"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 456,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 456
>   }
> }
> ```

> [tab] 阿根廷 CVU/CBU (63)
>
> ```bash theme={null}
> curl -X POST "https://api.velafi.com/v2/payments" \
>   -H "X-BH-TOKEN: YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "merchantId": 123,
>     "paymentId": 63,
>     "country": "Argentina",
>     "fiat": "ARS",
>     "realName": "John Doe",
>     "fieldJson": {
>       "CVU/CBU Number": "0000000000000000000002",
>       "CUIT": "20000000001"
>     },
>     "remark": "Preferred beneficiary"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 789,
>     "status": 2,
>     "failReason": "",
>     "sameAccountNumberId": 789
>   }
> }
> ```
>
> > [!NOTE]
> >
> > `status: 2` 表示 VelaFi 正在异步验证该账户。请轮询 `GET /v2/payments`，检查其何时变为 `status: 1`。

> [tab] 巴西 Pix – Genial (90)
>
> ```bash theme={null}
> curl -X POST "https://api.velafi.com/v2/payments" \
>   -H "X-BH-TOKEN: YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "merchantId": 15123,
>     "paymentId": 90,
>     "country": "Brazil",
>     "fiat": "BRL",
>     "realName": "Tom",
>     "fieldJson": {
>       "Pix Type": "EMAIL",
>       "Pix Key": "tom@example.com"
>     },
>     "remark": "Preferred beneficiary"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 1001,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 1001
>   }
> }
> ```

> [tab] 哥伦比亚 Automatic ACH (68)
>
> ```bash theme={null}
> curl -X POST "https://api.velafi.com/v2/payments" \
>   -H "X-BH-TOKEN: YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "merchantId": 15123,
>     "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": "Preferred beneficiary"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 1002,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 1002
>   }
> }
> ```

> [tab] Wire CPN (120)
>
> ```bash theme={null}
> curl -X POST "https://api.velafi.com/v2/payments" \
>   -H "X-BH-TOKEN: YOUR_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "merchantId": 15123,
>     "paymentId": 120,
>     "country": "United States",
>     "fiat": "USD",
>     "realName": "Tom",
>     "fieldJson": {
>       "beneficiaryName": "Tom",
>       "country": "US",
>       "stateProvince": "US-AK",
>       "city": "Alaska",
>       "street": "789 Example Street",
>       "postalCode": "10001",
>       "dateOfBirth": "1990-01-01",
>       "idNumber": "123456",
>       "idExpirationDate": "2099-01-01",
>       "useCase": "B2B",
>       "reasonForPayment": "PMT001",
>       "bankName": "Bank of Nowhere",
>       "bankCountry": "US",
>       "swiftCode": "NACKUSAK001",
>       "accountNumber": "123456"
>     },
>     "remark": "Preferred beneficiary"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 1003,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 1003
>   }
> }
> ```

> [tab] 重复账户（错误）
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 0,
>     "status": 3,
>     "failReason": "account already exists",
>     "sameAccountNumberId": 100
>   }
> }
> ```
>
> > [!WARNING]
> >
> > 当 `status` 为 `3` 且 `failReason` 为 `"account already exists"` 时，请将 `sameAccountNumberId` 的值用作 `userPaymentId` —— 它指向该账号已存在的有效收款人记录。


## Related topics

- [管理收款人](https://docs.velafi.com/cn/docs/guides/managing-beneficiaries.md)
- [获取支付方式模板](https://docs.velafi.com/cn/api-reference/beneficiary/get-payment-templates.md)
- [出金（加密货币兑法币）](https://docs.velafi.com/cn/docs/guides/off-ramp.md)
- [删除收款人](https://docs.velafi.com/cn/api-reference/beneficiary/delete-beneficiary.md)
- [全球支付（法币兑法币）](https://docs.velafi.com/cn/docs/guides/global-payments.md)


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