Beneficiarios
Agregar un beneficiario
Registra un nuevo beneficiario de pago para un comercio. Proporciona los campos del método de pago obtenidos del endpoint de plantillas y recibe un ID de beneficiario si la operación es exitosa.
POST
/
v2
/
payments
Agregar un beneficiario
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
}
}Agrega un nuevo beneficiario para poder referenciarlo después en órdenes de off-ramp o de pagos globales. Antes de llamar a este endpoint, obtén la estructura de campos requerida llamando a
GET /v2/payments/templates con el paymentId de destino y completa el objeto fieldJson en consecuencia. Bajo el mismo ID de comercio y paymentId, cada cuenta receptora única solo puede tener un estado válido: si intentas registrar una cuenta duplicada, se devuelve una respuesta con status: 3 y sameAccountNumberId apuntando al registro existente.
Endpoint
POST https://api.velafi.com/v2/payments
Usa
https://api-test.velafi.com/v2/payments para pruebas en sandbox.Headers de la solicitud
| Header | Valor |
|---|---|
X-BH-TOKEN | Tu token de GET /v2/token/generate |
Content-Type | application/json |
Parámetros del cuerpo de la solicitud
integer
El ID numérico del comercio bajo el cual se registrará el beneficiario. Omítelo para usar tu comercio predeterminado.
integer
requerido
El ID numérico del método de pago. Determina qué campos son obligatorios en
fieldJson.string
requerido
Nombre completo del país del beneficiario (por ejemplo,
"Mexico", "Argentina", "Brazil").string
requerido
Código de moneda fiat ISO 4217 para este beneficiario (por ejemplo,
"MXN", "ARS", "BRL", "USD").string
requerido
El nombre legal real del titular de la cuenta.
object
requerido
Pares clave-valor que completan la plantilla del método de pago. Obtén las claves exactas requeridas llamando a
GET /v2/payments/templates?paymentId={paymentId}. Usa el indexCode del campo como clave cuando no esté vacío; de lo contrario, usa la cadena title. Consulta Campos del beneficiario por método de pago para ver las claves de cada método de pago habilitado.string
Nota opcional de texto libre sobre este beneficiario (por ejemplo,
"Preferred supplier account").Campos de la respuesta
integer
Código de estado de la respuesta.
200 indica éxito.string
Mensaje de respuesta legible.
object
Objeto con los datos del resultado.
Mostrar campos de data
Mostrar campos de data
integer
El ID del método de pago de usuario (beneficiario) recién creado. Usa este valor como
userPaymentId en las órdenes de off-ramp.integer
Estado de autenticación:
1 = válido, 2 = autenticando (verificación asíncrona en curso), 3 = autenticación fallida.string
Explicación de por qué falló la autenticación cuando
status es 3. Cadena vacía en caso de éxito.integer
Cuando
status es 3 por una cuenta duplicada, este campo contiene el id del beneficiario válido existente con el mismo número de cuenta.Ejemplos
- México SPEI – Finco Pay (105)
- Argentina CVU/CBU (63)
- Brasil Pix – Genial (90)
- Colombia ACH automático (68)
- Wire CPN (120)
- Cuenta duplicada (error)
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 significa que VelaFi está verificando la cuenta de forma asíncrona. Consulta periódicamente GET /v2/payments para saber cuándo llega a 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
}
}
Cuando
status es 3 y failReason es "account already exists", usa el valor de sameAccountNumberId como tu userPaymentId: apunta al registro de beneficiario válido existente para ese número de cuenta.⌘I
Agregar un beneficiario
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
}
}