> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# Buscar pagos

> Lista los pagos de la cuenta creados en una ventana de hasta 1 día, con filtros y paginación por cursor.

Esta solicitud lista los pagos de la cuenta enviada en el header `X-Account-Code`. Úsala para sincronizar pagos con un data warehouse o para construir un panel de administración. Para consultar un solo pago, usa [Obtener pago por ID](https://docs.y.uno/es/reference/payments/retrieve-payment-by-id-v2.md) u [Obtener pago por ID de orden del comercio](https://docs.y.uno/es/reference/payments/retrieve-payment-by-merchant-order-id.md).

## Ventana de creación

`created_at_from` y `created_at_to` son fechas y horas obligatorias en formato RFC 3339 con desplazamiento de zona horaria, por ejemplo `2026-11-03T00:00:00Z` o `2026-11-03T00:00:00-03:00`. `created_at_from` es inclusiva y `created_at_to` es exclusiva, así que dos ventanas consecutivas que comparten un límite no se superponen. `created_at_to` debe ser posterior a `created_at_from`, y la ventana entre ambas es de hasta 1 día (24 horas). Una ventana más amplia responde `400 DATE_RANGE_TOO_WIDE`. Para cubrir un período más largo, envía una solicitud por cada ventana de 24 horas, por ejemplo días UTC consecutivos.

## Filtros

Todos los filtros son opcionales y se combinan con AND:

| Parámetro | Coincide con |
| - | - |
| `updated_at_from`, `updated_at_to` | Pagos cuya última actualización está dentro de este rango (`updated_at_from` inclusiva, `updated_at_to` exclusiva) |
| `status` | Cualquiera de los estados enviados, separados por coma (`status=SUCCEEDED,DECLINED`) o repitiendo el parámetro (`status=SUCCEEDED&status=DECLINED`) |
| `customer_id` | Pagos de este cliente (UUID) |
| `country` | Pagos de este país (ISO 3166-1 alpha-2, por ejemplo `US`) |
| `currency` | Pagos en esta moneda (ISO 4217, por ejemplo `USD`) |
| `merchant_order_id` | Pagos con este ID de orden del comercio |

Envía cada parámetro una sola vez, salvo `status`. Un parámetro que no aparece en esta página, o un filtro con un valor inválido, responde `400 INVALID_PARAMETERS`.

## Paginación

Las filas se ordenan por `created_at` ascendente. `limit` define el tamaño de la página, de 1 a 100, y por defecto es 50.

La respuesta es un objeto con tres campos:

| Campo | Descripción |
| - | - |
| `payments` | Las filas de la página |
| `next_cursor` | Cursor de la página siguiente, o `null` en la última página |
| `has_more` | `true` cuando existe otra página, `false` en la última página |

Para leer la página siguiente, envía `cursor` con el valor de `next_cursor` sin modificar, junto con el mismo `X-Account-Code` y los mismos filtros de la solicitud que lo devolvió. Sigue paginando hasta que `has_more` sea `false`. Un cursor modificado, o enviado con otra cuenta u otros filtros, responde `400 INVALID_CURSOR`. La paginación solo avanza.

## Filas

Cada fila es un resumen del pago: `id`, `account_id`, `merchant_order_id`, `description`, `country`, `status`, `sub_status`, `amount.value`, `amount.currency`, `payment_method.type`, `customer_payer.id`, `created_at` y `updated_at`.

> [!NOTE]
>
> Las filas no incluyen el arreglo `transactions`. Obtén el pago por su `id` para recibir el objeto de pago completo.

## Errores

Los errores usan el envoltorio con `code` y `messages`.

| Estado | Código | Causa |
| - | - | - |
| 400 | `INVALID_PARAMETERS` | Falta un parámetro obligatorio, un parámetro no está soportado o se envía más de una vez, o un valor es inválido: una fecha que no está en RFC 3339 con desplazamiento de zona horaria, `created_at_to` que no es posterior a `created_at_from`, un `status` desconocido, un `customer_id` o `X-Account-Code` que no es un UUID, o un `limit` fuera del rango de 1 a 100 |
| 400 | `DATE_RANGE_TOO_WIDE` | La ventana entre `created_at_from` y `created_at_to` es mayor a 1 día (24 horas) |
| 400 | `INVALID_CURSOR` | El cursor fue modificado, o se envió con una cuenta o filtros distintos a los de la solicitud que lo devolvió |
| 400 | `INVALID_ACCOUNT_ID` | `X-Account-Code` no es una cuenta de tu organización |


## OpenAPI

````yaml openapi/es/payments/search-payments.json GET /payments/search
openapi: 3.1.0
info:
  title: payment-api-search-payments
  version: 1.0.0
servers:
  - url: https://api-sandbox.y.uno/v1
    description: Sandbox
  - url: https://api.y.uno/v1
    description: Production (US)
security:
  - sec0: []
    sec1: []
paths:
  /payments/search:
    get:
      summary: Buscar pagos
      description: >-
        Lista los pagos de la cuenta enviada en `X-Account-Code` que se crearon
        dentro de una ventana de `created_at` de hasta 1 día, con filtros
        opcionales y paginación por cursor. Las filas se ordenan por
        `created_at` ascendente.
      operationId: search-payments
      parameters:
        - name: X-Account-Code
          in: header
          description: La cuenta cuyos pagos se listan.
          required: true
          schema:
            type: string
            format: uuid
        - name: created_at_from
          in: query
          description: >-
            Inicio de la ventana de creación, inclusivo (RFC 3339 con
            desplazamiento de zona horaria, por ejemplo `2026-11-03T00:00:00Z`).
            La ventana entre `created_at_from` y `created_at_to` es de hasta 1
            día (24 horas).
          required: true
          schema:
            type: string
            format: date-time
        - name: created_at_to
          in: query
          description: >-
            Fin de la ventana de creación, exclusivo (RFC 3339 con
            desplazamiento de zona horaria). Debe ser posterior a
            `created_at_from` y como máximo 1 día (24 horas) después.
          required: true
          schema:
            type: string
            format: date-time
        - name: updated_at_from
          in: query
          description: >-
            Solo pagos cuya última actualización es igual o posterior a esta
            fecha y hora (RFC 3339 con desplazamiento de zona horaria).
          schema:
            type: string
            format: date-time
        - name: updated_at_to
          in: query
          description: >-
            Solo pagos cuya última actualización es anterior a esta fecha y
            hora, exclusiva (RFC 3339 con desplazamiento de zona horaria). Debe
            ser posterior a `updated_at_from` cuando se envían ambas.
          schema:
            type: string
            format: date-time
        - name: status
          in: query
          description: >-
            Estados de pago a buscar. Envía una lista separada por coma
            (`status=SUCCEEDED,DECLINED`) o repite el parámetro
            (`status=SUCCEEDED&status=DECLINED`).
          schema:
            type: array
            items:
              type: string
              enum:
                - CREATED
                - READY_TO_PAY
                - PENDING
                - SUCCEEDED
                - VERIFIED
                - DECLINED
                - REJECTED
                - ERROR
                - EXPIRED
                - CANCELED
                - REFUNDED
                - IN_DISPUTE
                - CHARGEBACK
          style: form
          explode: true
        - name: customer_id
          in: query
          description: Solo pagos de este cliente.
          schema:
            type: string
            format: uuid
        - name: country
          in: query
          description: Solo pagos de este país (ISO 3166-1 alpha-2).
          schema:
            type: string
            pattern: ^[A-Z]{2}$
        - name: currency
          in: query
          description: Solo pagos en esta moneda (ISO 4217).
          schema:
            type: string
            pattern: ^[A-Z]{3}$
        - name: merchant_order_id
          in: query
          description: Solo pagos con este ID de orden del comercio.
          schema:
            type: string
        - name: limit
          in: query
          description: Cantidad de pagos por página, de 1 a 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          description: >-
            El `next_cursor` de la página anterior, sin modificar. Envíalo con
            el mismo `X-Account-Code` y los mismos filtros de la solicitud que
            lo devolvió.
          schema:
            type: string
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSearchResult'
              examples:
                Page with more results:
                  value:
                    payments:
                      - id: e3f397ed-b7d0-4816-ab75-8457b0a30ec1
                        account_id: 493e9374-510a-4201-9e09-de669d75f256
                        merchant_order_id: '0000022'
                        description: Test payment
                        country: US
                        status: SUCCEEDED
                        sub_status: APPROVED
                        amount:
                          value: 100
                          currency: USD
                        payment_method:
                          type: CARD
                        customer_payer:
                          id: cfae0941-7234-427a-a739-ef4fce966c79
                        created_at: '2026-11-03T10:24:58.900553Z'
                        updated_at: '2026-11-03T10:25:13.447662Z'
                    next_cursor: c2FtcGxlLWN1cnNvcg.c2FtcGxlLXNpZ25hdHVyZQ
                    has_more: true
                Last page:
                  value:
                    payments: []
                    next_cursor: null
                    has_more: false
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                INVALID_PARAMETERS:
                  value:
                    code: INVALID_PARAMETERS
                    messages:
                      - The query parameter 'created_at_from' is required.
                DATE_RANGE_TOO_WIDE:
                  value:
                    code: DATE_RANGE_TOO_WIDE
                    messages:
                      - >-
                        The range between 'created_at_from' and 'created_at_to'
                        must be at most 1 day.
                INVALID_CURSOR:
                  value:
                    code: INVALID_CURSOR
                    messages:
                      - >-
                        The query parameter 'cursor' is invalid or does not
                        match the filters of this search.
                INVALID_ACCOUNT_ID:
                  value:
                    code: INVALID_ACCOUNT_ID
                    messages:
                      - Account id is invalid
      deprecated: false
components:
  schemas:
    PaymentSearchResult:
      type: object
      required:
        - payments
        - next_cursor
        - has_more
      properties:
        payments:
          type: array
          description: Los pagos de la página, ordenados por `created_at` ascendente.
          items:
            $ref: '#/components/schemas/PaymentSummary'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Cursor opaco de la página siguiente. Envíalo como `cursor` junto con
            los mismos filtros. `null` en la última página.
        has_more:
          type: boolean
          description: >-
            `true` cuando existe otra página después de esta, `false` en la
            última página.
    Error:
      type: object
      properties:
        code:
          type: string
        messages:
          type: array
          items:
            type: string
    PaymentSummary:
      type: object
      description: >-
        Fila resumida del pago. No incluye el arreglo `transactions`: obtén el
        pago por `id` para recibir el objeto completo.
      properties:
        id:
          type: string
          format: uuid
          description: El identificador único del pago.
        account_id:
          type: string
          format: uuid
          description: El identificador único de la cuenta a la que pertenece el pago.
        merchant_order_id:
          type:
            - string
            - 'null'
          description: El identificador único de la orden del cliente.
        description:
          type:
            - string
            - 'null'
          description: La descripción del pago.
        country:
          type:
            - string
            - 'null'
          description: El país del pago (ISO 3166-1 alpha-2).
        status:
          type:
            - string
            - 'null'
          description: >-
            El estado del pago. Consulta [Estado del
            pago](/es/reference/payments/status-and-response-codes/payment).
        sub_status:
          type:
            - string
            - 'null'
          description: El subestado del pago.
        amount:
          type: object
          properties:
            value:
              type:
                - number
                - 'null'
              description: El monto del pago.
            currency:
              type:
                - string
                - 'null'
              description: La moneda del pago (ISO 4217).
        payment_method:
          type: object
          properties:
            type:
              type:
                - string
                - 'null'
              description: El tipo de método de pago, por ejemplo `CARD` o `PIX`.
        customer_payer:
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
              description: El identificador único del cliente, cuando el pago tiene uno.
        created_at:
          type: string
          format: date-time
          description: Fecha y hora de creación del pago (ISO 8601).
        updated_at:
          type: string
          format: date-time
          description: Fecha y hora de la última actualización del pago (ISO 8601).
  securitySchemes:
    sec0:
      type: apiKey
      in: header
      name: public-api-key
      x-default: <Your public-api-key>
    sec1:
      type: apiKey
      in: header
      name: private-secret-key
      x-default: <Your private-secret-key>

````

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