Administrar beneficiarios

Un beneficiario es un destino de pago guardado (una cuenta bancaria, una billetera móvil o un identificador de pago) al que tu comercio envía fondos durante operaciones de off-ramp o de pagos globales de fiat a fiat. Agregar un beneficiario tiene dos pasos: primero, obtén la plantilla de campos del método de pago que quieres usar; luego, envía la plantilla completada para registrar el destino. Una vez guardado, el beneficiario se puede reutilizar en pagos repetidos sin volver a capturar los datos de la cuenta cada vez.

Paso 1: Obtener las plantillas de métodos de pago

Antes de agregar un beneficiario, obtén la plantilla del método de pago que elegiste. La plantilla te indica exactamente qué campos debes llenar para ese método de pago. Endpoint

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

Headers

X-BH-TOKEN: <your-token>

Parámetros de la solicitud

number

requerido

El ID numérico del método de pago. Cada método de pago (por ejemplo, SPEI para México, CVU para Argentina, SEPA, WIRE/ACH) tiene su propio ID. Consulta la tabla siguiente para ver los IDs más comunes.

IDs de métodos de pago comunes

ID de pago	Nombre	Tipo	País / Red
`105`	SPEI (Finco Pay)	Automático	México
`72`	SPEI (Tesored)	Automático	México
`63` (Sandbox: `18`)	CBU/CVU (Momentum)	Automático	Argentina
`137`	3.0 Transfer (QR)	Automático	Argentina
`90`	Pix (Genial)	Automático	Brasil
`92`	Pix - Woovi (Avenia)	Automático	Brasil
`68`	Automatic ACH	Automático	Colombia
`69`	Bre-B	Automático	Colombia
`95`	Bank Transfer	Automático	Perú
`81` (Sandbox: `532`)	ACH Reference (Lead Bank)	Automático	EE. UU.
`83` (Sandbox: `534`)	FedWire Reference (Lead Bank)	Automático	EE. UU.
`85`	SEPA (Bridge)	Automático	Europa
`120`	Wire (CPN)	Automático	Global
`124`	SEPA (CPN)	Automático	Global
`127`	FEDWIRE (CPN)	Automático	EE. UU.

Ejemplos de respuestas de plantilla

México — SPEI (Finco Pay)
Argentina — 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 (cuenta virtual) o debit (cuenta de tarjeta). Bank Code: obligatorio solo cuando Account Type es 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 o Individual. Si es Business: businessName es obligatorio. Si es Individual: firstName y lastName son obligatorios. Bank Country/Region: código de país ISO 3166-1 alfa-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 o Individual. Bank Country/Region: ISO 3166-1 alfa-2. State: código de estado/provincia ISO 3166-2.

Paso 2: Agregar un beneficiario

Una vez que tengas la plantilla del método de pago de destino, llena los campos y envía una solicitud POST para registrar el beneficiario bajo un comercio. Endpoint

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

Headers

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

Parámetros de la solicitud

number

requerido

El ID del comercio al que pertenece este beneficiario.

number

requerido

El ID del método de pago. Debe coincidir con un ID de método de pago existente en el sistema.

string

requerido

El nombre completo del país del beneficiario (por ejemplo, Mexico, Argentina, Brazil).

string

requerido

La moneda fiat de este beneficiario (por ejemplo, MXN, ARS, USD, EUR).

object

requerido

Los campos de la plantilla de pago completados, como un objeto clave-valor. Las claves y los formatos de los valores deben coincidir con la plantilla que devuelve GET /v2/payments/templates.

string

El nombre real del titular de la cuenta. Opcional, pero recomendado para los registros de cumplimiento.

string

Una nota opcional de texto libre para adjuntar a este registro de beneficiario.

Ejemplos de solicitudes

México 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"
}

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

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

Valores aceptados de Pix Type: CPF (11 dígitos), CNPJ (14 dígitos), EMAIL, PHONE (10-11 dígitos), RANDOM_KEY (con -).

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

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

Campos de la respuesta

number

Código de respuesta. 200 indica que la solicitud se procesó.

string

Mensaje de resultado legible.

object

Mostrar campos de data

number

El ID de pago de usuario asignado a este beneficiario. Usa este ID para referenciar al beneficiario en las solicitudes de pago.

number

Estado de validación del beneficiario:

1 — Válido y listo para recibir pagos.
2 — En autenticación (verificación en curso).
3 — La autenticación falló.

string

Descripción del fallo cuando status es 3. Vacío si la operación es exitosa.

number

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. Usa este ID para los pagos en lugar de crear un registro nuevo.

Éxito
Cuenta duplicada

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

Usa sameAccountNumberId (100 en este ejemplo) como el ID del beneficiario para tu pago: la cuenta ya existe como un registro válido.

Gestionar beneficiarios

Después de crear beneficiarios, puedes gestionarlos con operaciones adicionales de la API:

Obtener beneficiario

Consulta los detalles de un beneficiario guardado mediante su ID de pago de usuario.

Eliminar beneficiario

Elimina un beneficiario que ya no necesitas.

Configurar cuenta de reembolso

Designa a un beneficiario como el destino predeterminado de reembolsos de un comercio.

Obtener plantillas de pago

Referencia completa de todas las plantillas de métodos de pago y los requisitos de sus campos.

Bajo el mismo Merchant ID y paymentId, el mismo número de cuenta receptora solo puede tener un registro en estado valid a la vez. Si intentas agregar un duplicado, la API devuelve status: 3 con un sameAccountNumberId que apunta al registro válido existente.

Primeros pasos

Conceptos clave

Guías

Referencia

Administrar beneficiarios

Paso 1: Obtener las plantillas de métodos de pago

Parámetros de la solicitud

IDs de métodos de pago comunes

Ejemplos de respuestas de plantilla

Paso 2: Agregar un beneficiario

Parámetros de la solicitud

Ejemplos de solicitudes

Campos de la respuesta

Gestionar beneficiarios

Obtener beneficiario

Eliminar beneficiario

Configurar cuenta de reembolso

Obtener plantillas de pago

​Paso 1: Obtener las plantillas de métodos de pago

​Parámetros de la solicitud

​IDs de métodos de pago comunes

​Ejemplos de respuestas de plantilla

​Paso 2: Agregar un beneficiario

​Parámetros de la solicitud

​Ejemplos de solicitudes

​Campos de la respuesta

​Gestionar beneficiarios

Obtener beneficiario

Eliminar beneficiario

Configurar cuenta de reembolso

Obtener plantillas de pago

Paso 1: Obtener las plantillas de métodos de pago

Parámetros de la solicitud

IDs de métodos de pago comunes

Ejemplos de respuestas de plantilla

Paso 2: Agregar un beneficiario

Parámetros de la solicitud

Ejemplos de solicitudes

Campos de la respuesta

Gestionar beneficiarios