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

# List Payments

`GET /api/v2/payments`

List all payments with pagination, filtering, and sorting options.

Payments can be filtered by invoice IDs, statuses, date ranges, or search terms.

## Query parameters

- `invoice_id` string[], nullable — Filter by invoice IDs. Default is None.
- `statuses` PaymentStatusEnum[], nullable — Filter by payment statuses. Default is None.
- `search_term` string, nullable — Search term to filter payments. Default is None.
- `from_date` string, date-time, nullable — Filter payments from this date. Default is None.
- `to_date` string, date-time, nullable — Filter payments up to this date. Default is None.
- `page` integer — Page number, defaults to 1.
- `limit` integer — Size of a page, defaults to 10. Maximum is 100.
- `sort_field` string, nullable — Field to sort by, e.g., 'amount', 'scheduled_on'
- `sort_direction` string, nullable — Sorting direction ('asc' or 'desc')

## Response `200`

Successful Response

- ListResourcePaymentResponse
  - `data` PaymentResponse[]
    - `id` string, uuid — Unique identifier (UUID) of the payment
    - `amount` string — Payment amount
    - `currency` 'SAR' | 'USD' | 'EUR' | 'GBP' | 'AED' | 'BHD' | 'KWD' | 'OMR' | 'QAR' — ISO 4217 currency codes supported by Moyasar. Includes all currencies supported by Moyasar payment gateway.
    - `scheduled_on` string — Scheduled date and time for the payment
    - `type` 'INITIAL' | 'INSTALLMENT' | 'SPLIT_PREPAID' | 'SPLIT_REMAINDER'
    - `payment_method` 'MADA' | 'MASTERCARD' | 'VISA' | 'APPLE_PAY' | 'SAMSUNG_PAY' | 'AMEX' | 'CASH' | 'PGW_CARD_UNSPECIFIED' | 'BANK_TRANSFER' | 'CARD' | 'QURRAH' | 'BNPL'
    - `current_status` 'PENDING' | 'PROCESSING' | 'FAILED_INITIATION' | 'SUCCEEDED' | 'FAILED' | 'CANCELED' | 'UNDER_REVIEW' | 'EXPIRED' | 'SETTLED' | 'REFUNDED' | 'PARTIALLY_REFUNDED'
    - `payed_at` string, date-time, nullable — Date and time when the payment was completed
    - `refunded_at` string, date-time, nullable — Date and time of the most recent refund
    - `refund_reason` 'REQUESTED_BY_CUSTOMER' | 'DUPLICATE' | 'FRAUDULENT' | 'OTHER'
    - `refund_note` string, nullable — Note for the most recent refund if set
    - `amount_refunded` string — Sum of all refund rows for this payment
    - `refunds` PaymentRefundResponse[] — Refund history for this payment
      - `id` string, uuid — Unique identifier of the refund row
      - `amount_refunded` string — Amount refunded in this refund
      - `refunded_at` string, date-time — When this refund was recorded
      - `refund_reason` 'REQUESTED_BY_CUSTOMER' | 'DUPLICATE' | 'FRAUDULENT' | 'OTHER'
      - `refund_note` string, nullable — Note explaining the refund if applicable
    - `latest_pgw_message` string, nullable — Latest payment gateway message for this payment
    - `amount_in_smallest_unit` integer — Payment amount in smallest currency unit (e.g. halala for SAR).
  - `pagination` Pagination
    - `total_count` integer
    - `max_page` integer
    - `current_page` integer
    - `limit` integer
    - `has_next_page` boolean
    - `has_previous_page` boolean

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/streampay/apis/stream-app.md) · [All operations](https://skmtc.dev/streampay/apis/stream-app/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/streampay/stream-app/revisions/515eeea7d260/schema)