收款人
添加收款人
为商户注册新的收款人。提供从模板接口获取的支付方式字段，成功后返回收款人 ID。
POST
/
v2
/
payments
添加收款人
curl --request POST \
--url https://api-test.velafi.com/v2/payments \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": 123,
"paymentId": 123,
"country": "<string>",
"fiat": "<string>",
"realName": "<string>",
"fieldJson": {},
"remark": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/payments"
payload = {
"merchantId": 123,
"paymentId": 123,
"country": "<string>",
"fiat": "<string>",
"realName": "<string>",
"fieldJson": {},
"remark": "<string>"
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchantId: 123,
paymentId: 123,
country: '<string>',
fiat: '<string>',
realName: '<string>',
fieldJson: {},
remark: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/payments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/payments")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": 123,\n \"paymentId\": 123,\n \"country\": \"<string>\",\n \"fiat\": \"<string>\",\n \"realName\": \"<string>\",\n \"fieldJson\": {},\n \"remark\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"data.id": 123,
"data.status": 123,
"data.failReason": "<string>",
"data.sameAccountNumberId": 123
}
}添加新的收款人，以便之后在出金或全球支付订单中引用。调用此接口之前，请先使用目标
paymentId 调用 GET /v2/payments/templates 获取所需的字段结构，并据此填写 fieldJson 对象。在同一商户 ID 和 paymentId 下，每个唯一的收款账户只能有一条有效状态的记录 —— 尝试注册重复账户时，将返回 status: 3 响应，其中 sameAccountNumberId 指向已存在的记录。
接口地址
POST https://api.velafi.com/v2/payments
在沙盒环境中测试时，请使用
https://api-test.velafi.com/v2/payments。请求头
| 请求头 | 值 |
|---|---|
X-BH-TOKEN | 通过 GET /v2/token/generate 获取的 token |
Content-Type | application/json |
请求体参数
integer
要在其下注册收款人的商户数字 ID。省略时使用你的默认商户。
integer
必填
支付方式的数字 ID。决定
fieldJson 中需要哪些字段。string
必填
收款人所在国家的全称（例如
"Mexico"、"Argentina"、"Brazil"）。string
必填
该收款人的 ISO 4217 法币代码（例如
"MXN"、"ARS"、"BRL"、"USD"）。string
必填
账户持有人的法定真实姓名。
object
必填
用于填充支付方式模板的键值对。通过调用
GET /v2/payments/templates?paymentId={paymentId} 获取确切的必填键。若字段的 indexCode 非空，则以其作为键；否则使用 title 字符串。各已启用付款方式的键见获取支付模板页面的“各支付方式的收款人字段”一节。string
关于该收款人的可选自由文本备注（例如
"Preferred supplier account"）。响应字段
integer
响应状态码。
200 表示成功。string
可读的响应信息。
object
示例
- 墨西哥 SPEI – Finco Pay (105)
- 阿根廷 CVU/CBU (63)
- 巴西 Pix – Genial (90)
- 哥伦比亚 Automatic ACH (68)
- Wire CPN (120)
- 重复账户（错误）
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"
}'
{
"code": 200,
"msg": "SUCCESS",
"data": {
"id": 456,
"status": 1,
"failReason": "",
"sameAccountNumberId": 456
}
}
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"
}'
{
"code": 200,
"msg": "SUCCESS",
"data": {
"id": 789,
"status": 2,
"failReason": "",
"sameAccountNumberId": 789
}
}
status: 2 表示 VelaFi 正在异步验证该账户。请轮询 GET /v2/payments，检查其何时变为 status: 1。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"
}'
{
"code": 200,
"msg": "SUCCESS",
"data": {
"id": 1001,
"status": 1,
"failReason": "",
"sameAccountNumberId": 1001
}
}
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"
}'
{
"code": 200,
"msg": "SUCCESS",
"data": {
"id": 1002,
"status": 1,
"failReason": "",
"sameAccountNumberId": 1002
}
}
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"
}'
{
"code": 200,
"msg": "SUCCESS",
"data": {
"id": 1003,
"status": 1,
"failReason": "",
"sameAccountNumberId": 1003
}
}
{
"code": 200,
"msg": "SUCCESS",
"data": {
"id": 0,
"status": 3,
"failReason": "account already exists",
"sameAccountNumberId": 100
}
}
当
status 为 3 且 failReason 为 "account already exists" 时，请将 sameAccountNumberId 的值用作 userPaymentId —— 它指向该账号已存在的有效收款人记录。⌘I
添加收款人
curl --request POST \
--url https://api-test.velafi.com/v2/payments \
--header 'Content-Type: application/json' \
--header 'X-BH-TOKEN: <api-key>' \
--data '
{
"merchantId": 123,
"paymentId": 123,
"country": "<string>",
"fiat": "<string>",
"realName": "<string>",
"fieldJson": {},
"remark": "<string>"
}
'import requests
url = "https://api-test.velafi.com/v2/payments"
payload = {
"merchantId": 123,
"paymentId": 123,
"country": "<string>",
"fiat": "<string>",
"realName": "<string>",
"fieldJson": {},
"remark": "<string>"
}
headers = {
"X-BH-TOKEN": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-BH-TOKEN': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
merchantId: 123,
paymentId: 123,
country: '<string>',
fiat: '<string>',
realName: '<string>',
fieldJson: {},
remark: '<string>'
})
};
fetch('https://api-test.velafi.com/v2/payments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));HttpResponse<String> response = Unirest.post("https://api-test.velafi.com/v2/payments")
.header("X-BH-TOKEN", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"merchantId\": 123,\n \"paymentId\": 123,\n \"country\": \"<string>\",\n \"fiat\": \"<string>\",\n \"realName\": \"<string>\",\n \"fieldJson\": {},\n \"remark\": \"<string>\"\n}")
.asString();{
"code": 123,
"msg": "<string>",
"data": {
"data.id": 123,
"data.status": 123,
"data.failReason": "<string>",
"data.sameAccountNumberId": 123
}
}