管理收款人

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

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

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

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

请求头

X-BH-TOKEN: <your-token>

请求参数

number

必填

支付方式的数字 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)	自动	美国

模板响应示例

墨西哥 — SPEI (Finco Pay)
阿根廷 — CVU/CBU (Momentum)
SEPA (Bridge)
WIRE / ACH (Lead Bank)

GET /v2/payments/templates?paymentId=105

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "Account Type": "",
    "Account Number": "",
    "Beneficiary Name": "",
    "Bank Code": ""
  }
}

Account Type：clabe（虚拟账户）或 debit（银行卡账户）。 Bank Code：仅当 Account Type 为 debit 时必填。

GET /v2/payments/templates?paymentId=63

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "CVU/CBU Number": "",
    "cuit": "",
    "Bank name": ""
  }
}

GET /v2/payments/templates?paymentId=85

{
  "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 国家代码。

GET /v2/payments/templates?paymentId=81

{
  "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

请求头

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

请求参数

number

必填

此收款人所属商户的 ID。

number

必填

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

string

必填

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

string

必填

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

object

必填

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

string

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

string

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

请求示例

墨西哥 MXN — SPEI (Finco Pay)

{
  "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"
}

阿根廷 ARS — CVU/CBU (Momentum)

{
  "merchantId": 123,
  "paymentId": 63,
  "country": "Argentina",
  "fiat": "ARS",
  "realName": "John Doe",
  "fieldJson": {
    "CVU/CBU Number": "0000000000000000000002",
    "CUIT": "20000000001"
  },
  "remark": "Primary ARS beneficiary"
}

巴西 BRL — Pix (Genial)

{
  "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（含 -）。

哥伦比亚 COP — Automatic ACH

{
  "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"
}

全球 USD — Wire (CPN)

{
  "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"
}

响应字段

number

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

string

人类可读的结果消息。

object

显示 data 字段

number

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

number

收款人的验证状态：

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

string

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

number

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

成功
账户重复

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "id": 456,
    "status": 1,
    "failReason": "",
    "sameAccountNumberId": 456
  }
}

{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "id": 0,
    "status": 3,
    "failReason": "account already exists",
    "sameAccountNumberId": 100
  }
}

请使用 sameAccountNumberId（本例中为 100）作为付款的收款人 ID——该账户已作为有效记录存在。

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

获取收款人

通过用户支付 ID 获取已保存收款人的详情。

删除收款人

删除不再需要的收款人。

设置退款账户

将某个收款人指定为商户的默认退款目的地。

获取支付模板

所有支付方式模板及字段要求的完整参考。

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

快速入门

核心概念

指南

参考

管理收款人

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

请求参数

常用支付方式 ID

模板响应示例

第 2 步：添加收款人

请求参数

请求示例

响应字段