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

# List payments

`GET /payments`

List payments initiated by the authenticated party.

## Query parameters

- `partyId` string — Party ID for delegated payment lookup
- `limit` integer — Results per page
- `cursor` string — Pagination cursor from previous response

## Headers

- `X-Agent-ID` string, nullable
- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` object[], required
    - `type` 'payment', required
    - `id` string, required
    - `attributes` object, required — Resource attributes
      - `amount` integer, required — Amount in cents
      - `currency` string, required — Currency code
      - `status` 'CREATED' | 'PROCESSING' | 'PENDING_CLAIM' | 'IN_REVIEW' | 'COMPLETED' | 'FAILED' | 'RETURNED' | 'APPROVAL_DENIED' | 'CANCELED', required — Payment status
      - `description` string, nullable, required — Payment description
      - `createdAt` string, required — When this payment was created
      - `updatedAt` string, nullable, required — When this payment was last updated
    - `relationships` object, required — Resource relationships
      - `sender` object, required — Party that initiated the payment, when the sender is on Natural.
        - `data` object, nullable, required — Related resource identifier
          - `type` 'party', required — Resource type
          - `id` string, required
      - `recipient` object, required — Recipient party for this payment, when known.
        - `data` object, nullable, required — Related resource identifier
          - `type` 'party', required — Resource type
          - `id` string, required
      - `recipientAgent` object, required — Recipient agent when the caller addressed an agent ID. Null otherwise, including when the recipient was addressed as an email, phone, or party ID.
        - `data` object, nullable, required — Related resource identifier
          - `type` 'agent', required — Resource type
          - `id` string, required
      - `transaction` object, required — Sender-side transaction row for this payment, when available.
        - `data` object, nullable, required — Related resource identifier
          - `type` 'transaction', required — Resource type
          - `id` string, required
      - `paymentRequest` object, required — Payment request that produced this payment, when applicable.
        - `data` object, nullable, required — Related resource identifier
          - `type` 'paymentRequest', required — Resource type
          - `id` string, required
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required
      - `nextCursor` string, nullable, required

## Other responses

- `400` — Validation Error
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found — returned when the resource does not exist, or when it exists but is not accessible to your account. The two cases are intentionally indistinguishable, so that resource IDs cannot be enumerated by probing.
- `409` — Conflict
- `422` — Validation Error
- `428` — Precondition Required
- `429` — Too Many Requests
- `500` — Internal Server Error
- `501` — Not Implemented
- `502` — Bad Gateway
- `503` — Service Unavailable

---

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