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

# List card payments

`GET /card-payments`

## Request

- Base URL: `https://api.natural.com`
- URL: `https://api.natural.com/card-payments`
- Auth: HTTP bearer

List card payment attempts, newest first. Filter by paymentIntentId to see attempts for one intent.

## Query parameters

- `customerPartyId` string: Customer party to act for (pty_*). Omit for your own account. Requires authorization from that customer.
- `paymentIntentId` string: Only attempts for this payment intent (pmi_*).
- `subscriptionId` string: Early access (subscriptions). Only attempts whose `subscription` is this subscription (sub_*): each attempt at each of its payments, payment 1's checkout attempts included.
- `status` 'processing' | 'succeeded' | 'failed': Only attempts with this status.
- `createdAfter` string: Only attempts created after this RFC 3339 timestamp (exclusive).
- `createdBefore` string: Only attempts created before this RFC 3339 timestamp (exclusive).
- `limit` integer: Maximum results per page.
- `cursor` string: Cursor from the previous page.

## Headers

- `X-Instance-ID` string, nullable

## Response `200`

Successful Response

- object
  - `data` CardPayment[], required
    - `id` string, required: Card payment ID (cpy_*).
    - `type` 'cardPayment', required: Resource type. Always `cardPayment`.
    - `attributes` object, required
      - `amount` integer, required: Attempted amount in US cents.
      - `currency` 'USD', required: Currency code.
      - `status` 'processing' | 'authorized' | 'succeeded' | 'failed' | 'canceled', required: Payment attempt status. A succeeded payment was accepted, but funds may not be settled yet. Early access (holds): `authorized`, `canceled`.
      - `brand` string, nullable, required: Card brand, when known.
      - `last4` string, nullable, required: Last four card digits, when known.
      - `channel` 'link' | 'voice' | 'api', required: Where the payer submitted the payment. Early access (subscriptions, mandates): `api`.
      - `subscription` object: Early access (subscriptions). The subscription this payment pays, and which of its payments it is. Only on a subscription's payments.
        - `id` string, required: Subscription ID (sub_*).
        - `paymentNumber` integer, required: Which payment of the subscription this is. Payment 1 is paid in checkout.
        - `paymentCount` integer, nullable, required: How many payments the subscription has. Null when it has no end.
      - `receiptUrl` string, nullable, required: Hosted receipt page for the payer. Null until the payment succeeds.
      - `failure` object, nullable, required: Failure details. Null unless the attempt failed.
        - `code` string, nullable, required: Failure code, when known. New codes may be added.
        - `reason` string, nullable, required: Explanation of the failure.
        - `advice` 'doNotRetry' | 'tryAgainLater' | 'confirmCardData', nullable, required: Recommended payer action, when known.
      - `fee` object, nullable, required: Fee deducted from your proceeds as the recipient. Null when no fee applies, the payment failed, the fee was voided, or your party is not the fee payer.
        - `amount` integer, required: Fee amount in cents.
        - `currency` 'USD', required: Currency of the fee.
        - `payer` 'recipient', required: Party role charged the fee.
        - `applied` 'deducted', required: The fee is subtracted from the principal amount before the recipient receives it.
      - `refundedAmount` integer, required: Cents returned by successful refunds.
      - `refundableAmount` integer, required: Amount in US cents remaining after pending and successful refunds. Zero unless the payment succeeded. Other refund restrictions may apply.
      - `settledAt` string, nullable, required: RFC 3339 timestamp when the funds reached your wallet, or null while the payout is still settling.
      - `createdAt` string, required: RFC 3339 creation timestamp.
      - `updatedAt` string, required: RFC 3339 update timestamp. Refund changes may not advance this timestamp.
    - `relationships` object, required
      - `paymentIntent` object, required: The payment intent this attempt belongs to.
        - `data` object, required: Related resource identifier.
          - `type` 'paymentIntent', required: Resource type. Always `paymentIntent`.
          - `id` string, required
      - `refunds` object, required: Up to 25 newest refund references, including pending and failed refunds. List refunds by cardPaymentId for the full history.
        - `data` object[], required
          - `type` 'refund', required: Resource type. Always `refund`.
          - `id` string, required
      - `transaction` object, required: The same payment in GET /transactions. Null until the payment first changes status.
        - `data` object, nullable, required: Related resource identifier.
          - `type` 'transaction', required: Resource type. Always `transaction`.
          - `id` string, required: Transaction ID (txn_*).
  - `meta` object, required
    - `pagination` object, required
      - `hasMore` boolean, required: Whether more results are available.
      - `nextCursor` string, nullable, required: Cursor for the next page, or null when there are no more results.

## 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. The response contains one error object for each invalid request value.
- `428`: Precondition Required
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `502`: Bad Gateway
- `503`: Service Unavailable

## Changes

- **2026-10-28** `46c3e5516668`: 3 warning, 2 info
  - added the new `api` enum value to the `data/items/attributes/channel` response property for the response status `200`
  - added the new `authorized` enum value to the `data/items/attributes/status` response property for the response status `200`
  - added the new `canceled` enum value to the `data/items/attributes/status` response property for the response status `200`
  - added the new optional `query` request parameter `subscriptionId`
  - …1 more
- **2026-10-22** `84d3e68026cf`: 1 info
  - added the required property `data/items/relationships/transaction` to the response with the `200` status
- **2026-09-29** `4fab756be152`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/natural/apis/natural-api/changes/card-payments/get.md)

---

[API](https://skmtc.dev/natural/apis/natural-api.md) - [All operations](https://skmtc.dev/natural/apis/natural-api/llms.txt) - [OpenAPI document](https://skmtc.dev/natural/apis/natural-api/revisions/59c1208fa5dc?raw)