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

# Listar beneficiarios

> Obtén una lista paginada de los beneficiarios registrados, con filtros opcionales por país, estado, moneda fiat e ID de comercio para encontrar un registro específico.

Usa este endpoint para listar todos los beneficiarios registrados en tu cuenta. Filtra los resultados por país, moneda fiat, estado de autenticación o ID de comercio para encontrar rápidamente un beneficiario específico antes de crear una orden de off-ramp. Los resultados están paginados: usa `currentPage` y `pageSize` para navegar por conjuntos de resultados grandes. El campo `status` de cada registro indica si VelaFi validó la cuenta (`1`), si todavía la está verificando (`2`) o si la verificación falló (`3`).

## Endpoint

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

> [!NOTE]
>
> Usa `https://api-test.velafi.com/v2/payments` para pruebas en el sandbox.

## Parámetros de consulta

**country** `string`

Nombre completo del país para filtrar los resultados (p. ej., `"Mexico"`, `"Brazil"`).

**status** `integer`

Filtra por estado de autenticación: `0` = todos (valor por defecto), `1` = válido, `2` = en autenticación, `3` = autenticación fallida.

**fiat** `string`

Código de moneda fiat ISO 4217 para filtrar los resultados (p. ej., `"MXN"`, `"BRL"`).

**merchantId** `integer`

ID numérico del comercio para filtrar los resultados a un comercio específico.

**currentPage** `integer`

Número de página que quieres obtener. El valor por defecto es `1`.

**pageSize** `integer`

Número de registros por página. El valor por defecto es `10`.

## Campos de la respuesta

**code** `integer`

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

**msg** `string`

Mensaje legible de la respuesta.

**data** `object`

Conjunto de resultados paginado.

**Campos de data**

**data.currentPage** `integer`

Número de la página devuelta.

**data.size** `integer`

Número de registros por página.

**data.total** `integer`

Número total de registros de beneficiarios que coinciden, en todas las páginas.

**data.record** `array`

Arreglo de objetos de beneficiario.

**Campos de cada elemento de record**

**id** `integer`

ID único del método de pago del usuario (beneficiario). Envíalo como `userPaymentId` al crear órdenes de off-ramp.

**merchantId** `integer`

ID del comercio al que pertenece este beneficiario.

**country** `string`

Nombre completo del país del beneficiario.

**fiat** `string`

Código de la moneda fiat asociada a este beneficiario.

**paymentId** `integer`

ID de configuración del método de pago.

**paymentMethodName** `string`

Nombre visible del método de pago (p. ej., `"CHATS"`, `"SPEI"`).

**realName** `string`

Nombre legal del titular de la cuenta.

**status** `integer`

Estado de autenticación: `1` = válido, `2` = en autenticación, `3` = fallido.

**hasRefundAccount** `integer`

`1` si este beneficiario está designado como cuenta de reembolso; `0` en caso contrario.

**fieldList** `object`

Mapa clave-valor de los campos de pago guardados para este beneficiario.

**remark** `string`

Nota de texto libre opcional sobre este beneficiario.

**createTime** `integer`

Marca de tiempo Unix (milisegundos) en que se creó el beneficiario.

## Ejemplo

```bash theme={null}
curl -X GET "https://api.velafi.com/v2/payments?country=Mexico&status=1&currentPage=1&pageSize=10" \
  -H "X-BH-TOKEN: YOUR_TOKEN"
```

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "record": [
      {
        "id": 228,
        "merchantId": 67,
        "country": "Hong Kong",
        "fiat": "USD",
        "paymentId": 123,
        "paymentMethodName": "CHATS (CPN)",
        "realName": "test",
        "remark": "11",
        "createTime": 0,
        "fieldList": {
          "Account Owner Type": "Business",
          "Account Number": "000000000",
          "Bank Name": "Citibank, N.A., Hong Kong Branch",
          "Bank Country/Region": "HK",
          "Bank Identifier": "CITIHKHX",
          "Remarks": "111",
          "Street": "1 EXAMPLE STREET",
          "City": "Hong Kong",
          "State": "HK-HK",
          "Country/Region": "HK",
          "Postal Code": "00000"
        },
        "status": 1,
        "hasRefundAccount": 0
      }
    ],
    "size": 10,
    "currentPage": 1,
    "total": 1
  }
}
```


## Related topics

- [Listar métodos de pago compatibles](https://docs.velafi.com/es/api-reference/beneficiary/get-supported-payment-methods.md)
- [Administrar beneficiarios](https://docs.velafi.com/es/docs/guides/managing-beneficiaries.md)
- [Listar comercios](https://docs.velafi.com/es/api-reference/merchant/get-a-list-of-merchants.md)
- [Listar webhooks](https://docs.velafi.com/es/api-reference/webhooks/get-webhook-endpoints.md)
- [Listar países](https://docs.velafi.com/es/api-reference/basic-configuration/get-list-of-countries.md)


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