---
title: "List payments"
method: GET
path: "/v1/payments"
tags: ["Payments"]
---

# List payments

`GET /v1/payments`

Retrieve a paginated list of payments with optional filters.

## Query parameters

- `status` 'NEW' | 'PENDING_METHOD_SELECTION' | 'PROCESSING' | 'CONFIRMED' | 'PAID' | 'CANCELLED' | 'EXPIRED' | 'REFUNDED' | 'PARTIAL_REFUND' | 'CHARGEBACK' | 'MED_FROZEN' — Possible payment statuses.
- `method` 'PIX' | 'CARD' | 'BOLETO' — Available public payment methods.
- `startDate` string, date-time
- `endDate` string, date-time
- `minAmount` number
- `maxAmount` number
- `page` integer
- `limit` integer

## Response `200`

Payments listed.

- object
  - `payments` Payment[]
    - `id` string, uuid
    - `txId` string — YuvexPay transaction ID.
    - `amount` number — Merchant-requested base amount, in BRL. This is the seller's intended receivable.
    - `feeAmount` number — YuvexPay platform fee, in BRL. When `feePassedToPayer` is true, this equals `payerFeeAmount` and is charged on top of `amount`. When false, this is deducted from `amount` to produce `netAmount`.
    - `netAmount` number — Merchant's net receivable, in BRL. Equals `amount` when `feePassedToPayer` is true; equals `amount - feeAmount` otherwise.
    - `feePassedToPayer` boolean — Resolved decision (after applying the per-payment override, company default, and sub-R$1 forced passthrough) on whether the fee was added on top for the payer.
    - `payerFeeAmount` number, nullable — Fee amount added to the payer's total charge. Null when `feePassedToPayer` is false. When true, payer-charged total = `amount + payerFeeAmount`.
    - `status` 'NEW' | 'PENDING_METHOD_SELECTION' | 'PROCESSING' | 'CONFIRMED' | 'PAID' | 'CANCELLED' | 'EXPIRED' | 'REFUNDED' | 'PARTIAL_REFUND' | 'CHARGEBACK' | 'MED_FROZEN' — Possible payment statuses.
    - `paymentMethod` 'PIX' | 'CARD' | 'BOLETO' — Available public payment methods.
    - `currency` 'BRL' — Supported currencies.
    - `description` string
    - `metadata` object
    - `expiresAt` string, date-time
    - `createdAt` string, date-time
    - `methodData` object — Payment method-specific data (QR code for PIX, barcode for boleto, etc.).
      - `type` 'PIX' | 'CARD' | 'BOLETO' — Available public payment methods.
    - `paidAt` string, date-time, nullable — Timestamp when the payment was confirmed paid. Null until paid.
    - `payer` object, nullable — Payer (debtor) identity captured from the PIX network once the charge is paid. Provider-agnostic. Null for historical records or open-payer charges where no payer data was captured.
      - `name` string, nullable — Payer full name.
      - `document` string, nullable — Payer CPF or CNPJ, as digits. Some PIX participants report the document masked (for example `***405566**`); when that is all the network gave us, the masked string is what this field carries — a full document wins whenever one is on file. `null` when no document of either kind was captured, which for an open-payer charge is common. Match on `*` before parsing the value as a CPF or CNPJ.
      - `documentType` 'CPF' | 'CNPJ' | 'null', nullable — Payer document type. `null` when the network did not say which kind of document it reported, which is the usual case alongside a masked `document`.
      - `institutionName` string, nullable — Payer bank/institution name.
      - `institutionIspb` string, nullable — Payer bank ISPB (Banco Central participant identifier).
  - `pagination` Pagination
    - `page` integer
    - `limit` integer
    - `total` integer
    - `totalPages` integer

## Other responses

- `401` — Missing or invalid authentication token.
- `429` — Rate limit exceeded.

## Changes

- **2026-08-27** `9d4ba1cc037c` — 1 warning
  - added the new `undefined` enum value to the `payments/items/payer/documentType` response property for the response status `200`
- **2026-06-07** `bb5bf9a20957` — 2 info
  - added the optional property `payments/items/paidAt` to the response with the `200` status
  - added the optional property `payments/items/payer` to the response with the `200` status
- **2026-05-10** `c1963c0f2a87` — 2 info
  - added the optional property `payments/items/feePassedToPayer` to the response with the `200` status
  - added the optional property `payments/items/payerFeeAmount` to the response with the `200` status
- **2026-05-03** `a382df24e843` — 1 warning
  - deleted the `query` request parameter `externalId`
- **2026-04-14** `74ad5da44cf9` — 1 breaking, 1 warning, 4 info
  - removed the enum value `CRYPTO_LTC` from the `query` request parameter `method`
  - removed the optional property `pagination/hasMore` from the response with the `200` status
  - added the optional property `pagination/totalPages` to the response with the `200` status
  - removed the `CRYPTO_LTC` enum value from the `payments/items/methodData/type` response property for the response status `200`
  - …2 more

[Full history](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/changes/v1/payments/get.md)

---

[API](https://skmtc.dev/yuvexpay/apis/yuvexpay-api.md) · [All operations](https://skmtc.dev/yuvexpay/apis/yuvexpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yuvexpay/yuvexpay-api/revisions/746526879975/schema)