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

# Administrar beneficiarios

> Guarda destinos de pago para off-ramp y pagos globales: obtén plantillas, agrega beneficiarios y gestiónalos con la API de VelaFi.

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**

```http theme={null}
X-BH-TOKEN: <your-token>
```

### Parámetros de la solicitud

**paymentId** `number` *required*

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

> [tab] México — SPEI (Finco Pay)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=105
> ```
>
> ```json theme={null}
> {
>   "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`.

> [tab] Argentina — CVU/CBU (Momentum)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=63
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "CVU/CBU Number": "",
>     "cuit": "",
>     "Bank name": ""
>   }
> }
> ```

> [tab] SEPA (Bridge)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=85
> ```
>
> ```json theme={null}
> {
>   "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.

> [tab] WIRE / ACH (Lead Bank)
>
> ```bash theme={null}
> GET /v2/payments/templates?paymentId=81
> ```
>
> ```json theme={null}
> {
>   "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**

```http theme={null}
X-BH-TOKEN: <your-token>
Content-Type: application/json
```

### Parámetros de la solicitud

**merchantId** `number` *required*

El ID del comercio al que pertenece este beneficiario.

**paymentId** `number` *required*

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

**country** `string` *required*

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

**fiat** `string` *required*

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

**fieldJson** `object` *required*

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

**realName** `string`

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

**remark** `string`

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

### Ejemplos de solicitudes

> [accordion] México MXN — SPEI (Finco Pay)
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [accordion] Argentina ARS — CVU/CBU (Momentum)
>
> ```json theme={null}
> {
>   "merchantId": 123,
>   "paymentId": 63,
>   "country": "Argentina",
>   "fiat": "ARS",
>   "realName": "John Doe",
>   "fieldJson": {
>     "CVU/CBU Number": "0000000000000000000002",
>     "CUIT": "20000000001"
>   },
>   "remark": "Primary ARS beneficiary"
> }
> ```

> [accordion] Brasil BRL — Pix (Genial)
>
> ```json theme={null}
> {
>   "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 `-`).

> [accordion] Colombia COP — Automatic ACH
>
> ```json theme={null}
> {
>   "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"
> }
> ```

> [accordion] Global USD — Wire (CPN)
>
> ```json theme={null}
> {
>   "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

**code** `number`

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

**msg** `string`

Mensaje de resultado legible.

**data** `object`

**campos de data**

**id** `number`

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

**status** `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ó.

**failReason** `string`

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

**sameAccountNumberId** `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.

> [tab] Éxito
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 456,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 456
>   }
> }
> ```

> [tab] Cuenta duplicada
>
> ```json theme={null}
> {
>   "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:

> [card] [Obtener beneficiario](https://docs.velafi.com/es/api-reference/beneficiary/get-beneficiary.md)
>
> Consulta los detalles de un beneficiario guardado mediante su ID de pago de usuario.

> [card] [Eliminar beneficiario](https://docs.velafi.com/es/api-reference/beneficiary/delete-beneficiary.md)
>
> Elimina un beneficiario que ya no necesitas.

> [card] [Configurar cuenta de reembolso](https://docs.velafi.com/es/api-reference/beneficiary/set-refund-account.md)
>
> Designa a un beneficiario como el destino predeterminado de reembolsos de un comercio.

> [card] [Obtener plantillas de pago](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md)
>
> Referencia completa de todas las plantillas de métodos de pago y los requisitos de sus campos.

> [!NOTE]
>
> 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.


## Related topics

- [Listar beneficiarios](https://docs.velafi.com/es/api-reference/beneficiary/get-beneficiary.md)
- [Agregar un beneficiario](https://docs.velafi.com/es/api-reference/beneficiary/add-beneficiary.md)
- [Eliminar un beneficiario](https://docs.velafi.com/es/api-reference/beneficiary/delete-beneficiary.md)
- [On-ramp (fiat a cripto)](https://docs.velafi.com/es/docs/guides/on-ramp.md)
- [Off-ramp (cripto a fiat)](https://docs.velafi.com/es/docs/guides/off-ramp.md)


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