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

# Search Payments

> Lists the account's payments created in a window of at most 1 day, with filters and cursor pagination.

This request lists the payments of the account sent in the `X-Account-Code` header. Use it to sync payments to a data warehouse or to build an admin panel. To look up a single payment, use [Retrieve Payment by ID](https://docs.y.uno/reference/payments/retrieve-payment-by-id-v2.md) or [Retrieve Payment by Merchant Order ID](https://docs.y.uno/reference/payments/retrieve-payment-by-merchant-order-id.md) instead.

## Creation window

`created_at_from` and `created_at_to` are required date-times in RFC 3339 format with a timezone offset, for example `2026-11-03T00:00:00Z` or `2026-11-03T00:00:00-03:00`. `created_at_from` is inclusive and `created_at_to` is exclusive, so consecutive windows that share a boundary do not overlap. `created_at_to` must be after `created_at_from`, and the window between them is at most 1 day (24 hours). A wider window answers `400 DATE_RANGE_TOO_WIDE`. To cover a longer period, send one request per 24-hour window, for example consecutive UTC days.

## Filters

All filters are optional and combine with AND:

| Parameter | Matches |
| - | - |
| `updated_at_from`, `updated_at_to` | Payments last updated inside this range (`updated_at_from` inclusive, `updated_at_to` exclusive) |
| `status` | Any of the statuses sent, comma-separated (`status=SUCCEEDED,DECLINED`) or repeated (`status=SUCCEEDED&status=DECLINED`) |
| `customer_id` | Payments of this customer (UUID) |
| `country` | Payments of this country (ISO 3166-1 alpha-2, for example `US`) |
| `currency` | Payments in this currency (ISO 4217, for example `USD`) |
| `merchant_order_id` | Payments with this merchant order ID |

Send each parameter once, except `status`. A parameter that is not listed on this page, or a filter with an invalid value, answers `400 INVALID_PARAMETERS`.

## Pagination

Rows are ordered by `created_at` ascending. `limit` sets the page size, from 1 to 100, and defaults to 50.

The response is an object with three fields:

| Field | Description |
| - | - |
| `payments` | The rows of the page |
| `next_cursor` | Cursor for the next page, or `null` on the last page |
| `has_more` | `true` when another page exists, `false` on the last page |

To read the next page, send `cursor` with the `next_cursor` value unchanged, and the same `X-Account-Code` and filters as the request that returned it. Keep paging until `has_more` is `false`. A modified cursor, or one sent with a different account or different filters, answers `400 INVALID_CURSOR`. Pagination moves forward only.

## Rows

Each row is a summary of the payment: `id`, `account_id`, `merchant_order_id`, `description`, `country`, `status`, `sub_status`, `amount.value`, `amount.currency`, `payment_method.type`, `customer_payer.id`, `created_at` and `updated_at`.

> [!NOTE]
>
> Rows carry no `transactions` array. Retrieve a payment by its `id` to get the full payment object.

## Errors

Errors use the `code` and `messages` envelope.

| Status | Code | Cause |
| - | - | - |
| 400 | `INVALID_PARAMETERS` | A required parameter is missing, a parameter is not supported or is sent more than once, or a value is invalid: a date that is not RFC 3339 with a timezone offset, `created_at_to` not after `created_at_from`, an unknown `status`, a `customer_id` or `X-Account-Code` that is not a UUID, or a `limit` outside 1 to 100 |
| 400 | `DATE_RANGE_TOO_WIDE` | The window between `created_at_from` and `created_at_to` is longer than 1 day (24 hours) |
| 400 | `INVALID_CURSOR` | The cursor was modified, or was sent with an account or filters different from the request that returned it |
| 400 | `INVALID_ACCOUNT_ID` | `X-Account-Code` is not an account of your organization |


## OpenAPI

````yaml openapi/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: Search Payments
      description: >-
        Lists the payments of the account sent in `X-Account-Code` that were
        created inside a `created_at` window of at most 1 day, with optional
        filters and cursor pagination. Rows are ordered by `created_at`
        ascending.
      operationId: search-payments
      parameters:
        - name: X-Account-Code
          in: header
          description: The account whose payments are listed.
          required: true
          schema:
            type: string
            format: uuid
        - name: created_at_from
          in: query
          description: >-
            Start of the creation window, inclusive (RFC 3339 with a timezone
            offset, for example `2026-11-03T00:00:00Z`). The window between
            `created_at_from` and `created_at_to` is at most 1 day (24 hours).
          required: true
          schema:
            type: string
            format: date-time
        - name: created_at_to
          in: query
          description: >-
            End of the creation window, exclusive (RFC 3339 with a timezone
            offset). Must be after `created_at_from` and at most 1 day (24
            hours) after it.
          required: true
          schema:
            type: string
            format: date-time
        - name: updated_at_from
          in: query
          description: >-
            Only payments last updated at or after this date and time (RFC 3339
            with a timezone offset).
          schema:
            type: string
            format: date-time
        - name: updated_at_to
          in: query
          description: >-
            Only payments last updated before this date and time, exclusive (RFC
            3339 with a timezone offset). Must be after `updated_at_from` when
            both are sent.
          schema:
            type: string
            format: date-time
        - name: status
          in: query
          description: >-
            Payment statuses to match. Send a comma-separated list
            (`status=SUCCEEDED,DECLINED`) or repeat the parameter
            (`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: Only payments of this customer.
          schema:
            type: string
            format: uuid
        - name: country
          in: query
          description: Only payments of this country (ISO 3166-1 alpha-2).
          schema:
            type: string
            pattern: ^[A-Z]{2}$
        - name: currency
          in: query
          description: Only payments in this currency (ISO 4217).
          schema:
            type: string
            pattern: ^[A-Z]{3}$
        - name: merchant_order_id
          in: query
          description: Only payments with this merchant order ID.
          schema:
            type: string
        - name: limit
          in: query
          description: Number of payments per page, from 1 to 100.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 50
        - name: cursor
          in: query
          description: >-
            The `next_cursor` of the previous page, unchanged. Send it with the
            same `X-Account-Code` and filters as the request that returned it.
          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: The payments of the page, ordered by `created_at` ascending.
          items:
            $ref: '#/components/schemas/PaymentSummary'
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Opaque cursor for the next page. Send it as `cursor` together with
            the same filters. `null` on the last page.
        has_more:
          type: boolean
          description: >-
            `true` when another page exists after this one, `false` on the last
            page.
    Error:
      type: object
      properties:
        code:
          type: string
        messages:
          type: array
          items:
            type: string
    PaymentSummary:
      type: object
      description: >-
        Summarized payment row. It carries no `transactions` array: retrieve the
        payment by `id` for the full object.
      properties:
        id:
          type: string
          format: uuid
          description: The unique identifier of the payment.
        account_id:
          type: string
          format: uuid
          description: The unique identifier of the account that owns the payment.
        merchant_order_id:
          type:
            - string
            - 'null'
          description: The unique identifier of the customer's order.
        description:
          type:
            - string
            - 'null'
          description: The description of the payment.
        country:
          type:
            - string
            - 'null'
          description: The country of the payment (ISO 3166-1 alpha-2).
        status:
          type:
            - string
            - 'null'
          description: >-
            The status of the payment. See [Payment
            status](/reference/payments/status-and-response-codes/payment).
        sub_status:
          type:
            - string
            - 'null'
          description: The sub status of the payment.
        amount:
          type: object
          properties:
            value:
              type:
                - number
                - 'null'
              description: The amount of the payment.
            currency:
              type:
                - string
                - 'null'
              description: The currency of the payment (ISO 4217).
        payment_method:
          type: object
          properties:
            type:
              type:
                - string
                - 'null'
              description: The payment method type, for example `CARD` or `PIX`.
        customer_payer:
          type: object
          properties:
            id:
              type:
                - string
                - 'null'
              description: The unique identifier of the customer, when the payment has one.
        created_at:
          type: string
          format: date-time
          description: Payment creation date and time (ISO 8601).
        updated_at:
          type: string
          format: date-time
          description: Last update date and time of the payment (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.