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

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

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

```text theme={null}
POST https://api.velafi.com/v2/payments
```

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

**merchantId** `integer`

El ID numérico del comercio bajo el cual se registrará el beneficiario. Omítelo para usar tu comercio predeterminado.

**paymentId** `integer` *required*

El ID numérico del método de pago. Determina qué campos son obligatorios en `fieldJson`.

**country** `string` *required*

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

**fiat** `string` *required*

Código de moneda fiat ISO 4217 para este beneficiario (por ejemplo, `"MXN"`, `"ARS"`, `"BRL"`, `"USD"`).

**realName** `string` *required*

El nombre legal real del titular de la cuenta.

**fieldJson** `object` *required*

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](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md#beneficiary-fields-by-payment-method) para ver las claves de cada método de pago habilitado.

**remark** `string`

Nota opcional de texto libre sobre este beneficiario (por ejemplo, `"Preferred supplier account"`).

## Campos de la respuesta

**code** `integer`

Código de estado de la respuesta. `200` indica éxito.

**msg** `string`

Mensaje de respuesta legible.

**data** `object`

Objeto con los datos del resultado.

**campos de data**

**data.id** `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.

**data.status** `integer`

Estado de autenticación: `1` = válido, `2` = autenticando (verificación asíncrona en curso), `3` = autenticación fallida.

**data.failReason** `string`

Explicación de por qué falló la autenticación cuando `status` es `3`. Cadena vacía en caso de éxito.

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

> [tab] México SPEI – Finco Pay (105)
>
> ```bash theme={null}
> 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"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 456,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 456
>   }
> }
> ```

> [tab] Argentina CVU/CBU (63)
>
> ```bash theme={null}
> 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"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 789,
>     "status": 2,
>     "failReason": "",
>     "sameAccountNumberId": 789
>   }
> }
> ```
>
> > [!NOTE]
> >
> > `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`.

> [tab] Brasil Pix – Genial (90)
>
> ```bash theme={null}
> 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"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 1001,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 1001
>   }
> }
> ```

> [tab] Colombia ACH automático (68)
>
> ```bash theme={null}
> 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"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 1002,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 1002
>   }
> }
> ```

> [tab] Wire CPN (120)
>
> ```bash theme={null}
> 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"
>   }'
> ```
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 1003,
>     "status": 1,
>     "failReason": "",
>     "sameAccountNumberId": 1003
>   }
> }
> ```

> [tab] Cuenta duplicada (error)
>
> ```json theme={null}
> {
>   "code": 200,
>   "msg": "SUCCESS",
>   "data": {
>     "id": 0,
>     "status": 3,
>     "failReason": "account already exists",
>     "sameAccountNumberId": 100
>   }
> }
> ```
>
> > [!WARNING]
> >
> > 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.


## Related topics

- [Administrar beneficiarios](https://docs.velafi.com/es/docs/guides/managing-beneficiaries.md)
- [Obtener plantillas de métodos de pago](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md)
- [Eliminar un beneficiario](https://docs.velafi.com/es/api-reference/beneficiary/delete-beneficiary.md)
- [Agregar una dirección a la lista blanca](https://docs.velafi.com/es/api-reference/crypto-wallet/add-whitelist-address.md)
- [Listar beneficiarios](https://docs.velafi.com/es/api-reference/beneficiary/get-beneficiary.md)


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