> This page is for version v1 (default).
> For other versions, use one of these documentation indexes:
> - v1 (default): https://developers.truemed.com/v-1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.truemed.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.truemed.com/_mcp/server.

# List Payment Sessions

GET https://dev-api.truemed.com/payments/v1/payment_sessions

All payment sessions created with the Create payment session API call can be listed
via a GET to `/payments/v1/payment_sessions`.

By default, all payment sessions, including those that are pending, created as auth
holds and those that have been manually voided or captured will be listed. Options are
provided for granular filtering, pagination, and search.

## Pagination

All results are paginated, with 30 per page. The response field `pagination` contains
information on how many payment sessions there are and how many pages are available
for the filtered query.

## Sorting

Payment sessions are sorted by the date they are created, with newer ones being returned first.

# Response Notes

The response is an array of payment sessions in the `payment_sessions` key. A few things to point out about
the response payload:

* `order_items` **(Optional)** - The list of the current state of the order items passed into
  `create_payment_session` if `include_order_items` is True
  * `total_refundable` **(Optional)** - If the Payment Session has been captured, this value
    will be the remaining amount refundable for this item. Otherwise it will not be included.
  * `quantity_refundable` **(Optional)** - If the Payment Session has been captured, this
    value will be the remaining quantity refundable for this item. Otherwise it will not be
    included.
  * `total_capturable` **(Optional)** - If the Payment Session is an authorization and is
    currently authorized, this value will be the remaining amount capturable for this item.
    Otherwise it will not be included.
  * `quantity_capturable` **(Optional)** - If the Payment Session is an authorization and is
    currently authorized, this value will be the remaining quantity capturable for this item.
    Otherwise it will not be included.
* `authorized_on` - the date the payment was authorized in ISO 8601 format
  * example: "2024-06-13T16:03:07.473Z"
  * For `kind`: `one_time_payment`, this will be the same as `captured_on`
* `refund_amount` **(Optional)** - int
  * Only present when `summarize_refunds=True` is included in the request.
  * The sum of processed refunds for the payment session, **in cents**
* `truemed_fee` **(Optional)** - decimal - **in dollars**
  * Only present when `include_truemed_fee=True` is included in the request.
  * The fee collected by truemed for this payment session.

The response also includes a `pagination` object:

```
{
  "pagination": {
    "current_page": 1,
    "page_size": 30,
    "count": 54,
    "last_page": 2
  },
  "payment_sessions": [
    ]
}
```

* `current_page` - the page requested. If none was provided, this will default to 1.
* `page_size` - the number of `payment_session`'s per page, which is always 30.
* `count` - the total number of `payment_session`'s matching the filters provided.
* `last_page` - the last page.
  * You can iterate through pages by providing integers up to `last_page` in the `page`
    parameter.

Reference: https://developers.truemed.com/api-reference/payment-sessions/list-payment-session

## Authentication

- `x-truemed-api-key` header (required) — Sales channel API key for merchant server-to-server authentication

## Servers

- `https://dev-api.truemed.com` (Development server, default)
- `https://api.truemed.com` (Production server)

## Request

### Query parameters

- `page` (integer, optional) — Optional field indicating which page to access. Defaults to 1.
- `page_size` (integer, optional) — Optional field indicating the number of records per page. Defaults to 30.
- `filter_pending` (boolean, optional) — Filter out pending payment sessions.
- `filter_voided` (boolean, optional) — Filter out voided payment sessions.
- `include_metadata` (boolean, optional) — Include metadata field in the response.
- `include_order_items` (boolean, optional) — Include order items in the response.
- `search` (string, optional) — Search by payment session ID, user business ID, email, or name.
- `created_on_start` (datetime, optional) — Filter payment sessions created on or after this date (ISO 8601 format).
- `created_on_end` (datetime, optional) — Filter payment sessions created on or before this date (ISO 8601 format).
- `captured_on_start` (datetime, optional) — Filter payment sessions captured on or after this date (ISO 8601 format).
- `captured_on_end` (datetime, optional) — Filter payment sessions captured on or before this date (ISO 8601 format).
- `include_refunds` (boolean, optional) — Include refund details in the response (default: true).
- `include_disputes` (boolean, optional) — Include dispute details in the response (default: true).
- `kind` (list of string, optional) — Filter by payment kind (comma-separated list: one_time_payment, authorization).
- `status` (list of string, optional) — Filter by payment session status (comma-separated list).
- `summarize_refunds` (boolean, optional) — Include refund_amount summary instead of full refund details.
- `include_truemed_fee` (boolean, optional) — Include Truemed fee in the response.
- `payment_token` (string, optional) — Filter payment sessions by payment token ID.

## Response

### 200

Successful response

- `payment_sessions` (list of PaymentSessionDetails, required) — List of payment session details.
- `pagination` (PaginationBody, optional, nullable) — A pagination object with information about the current page, page size, total count, and last page.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (enum, required)
  - Allowed values: `TotalAmountInvalid`, `ValidationError`
- `message` (string, required)

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `NotFound`
- `message` (string, required)

### 405 Method Not Allowed Error

Method Not Allowed

- `error` (enum, required)
  - Allowed values: `MethodNotAllowed`
- `message` (string, required)

### 500 Internal Server Error

Internal Server Error

- `error` (enum, required)
  - Allowed values: `ServerError`
- `message` (string, required)

### 501 Not Implemented Error

Not Implemented

- `error` (enum, required)
  - Allowed values: `NotImplemented`
- `message` (string, required)

## Types

### PaymentSessionDetails

- `authorize_amount` (integer, required) — The total_amount passed into `create_payment_session`.
- `created_at` (datetime, required) — The date the payment session was created in ISO 8601 format. Example: "2024-06-13T16:03:07.473Z".
- `id` (string, required) — The UUID returned by `create_payment_session`.
- `idempotency_key` (string, required) — The idempotency key passed into create_payment_session.
- `is_testing` (boolean, required) — The testing flag.
- `kind` (enum, required) — The payment kind, either one_time_payment or authorization.
  - Allowed values: `one_time_payment`, `authorization`
- `refund_count` (integer, required) — The number of refunds made on this payment.
- `status` (enum, required) — Status of the Payment Session (pending, processing, captured, authorized, or authorization_voided, or rejected).
  - Allowed values: `pending`, `canceled`, `processing`, `rejected`, `authorized`, `authorization_expired`, `authorization_voided`, `partially_captured`, `captured`
- `status_summary` (enum, required) — A summary of the overall payment session status.
  - Allowed values: `Incomplete`, `Canceled`, `Rejected`, `Processing`, `Authorized`, `Voided`, `Expired`, `Partially Captured`, `Captured`, `Partially Refunded`, `Refunded`, `PartiallyDisputed`, `Disputed`
- `user` (UserDetails, required) — The user attached to the payment session.
- `amount_details` (PaymentSessionAmountDetails, optional, nullable) — Detailed breakdown of the payment amount including discounts and charges.
- `authorized_on` (datetime, optional, nullable) — The date the payment was authorized in ISO 8601 format. Example: "2024-06-13T16:03:07.473Z". For kind: one_time_payment, this will be the same as captured_on.
- `capture_amount` (integer, optional, nullable) — For one time payments, same as authorize_amount. Otherwise, the captured amount.
- `captured_on` (datetime, optional, nullable) — The date the payment was captured in ISO 8601 format. Example: "2024-06-13T16:03:07.473Z".
- `disputes` (list of DisputeDetails, optional, nullable) — An array of dispute objects. Included if include_disputes is True (by default).
- `metadata` (string, optional, nullable) — The raw `metadata` field passed into `create_payment_session`.
- `order_items` (list of PaymentSessionOrderItemDetails, optional, nullable) — The list of the current state of the order items passed into `create_payment_session` if `include_order_items` is True.
- `refund_amount` (integer, optional, nullable) — Only present when summarize_refunds=True is included in the request. The sum of processed refunds for the payment session, in cents.
- `refunds` (list of RefundDetails, optional, nullable) — An array of refund objects. Included if include_refunds is True (by default).
- `stripe_payment_id` (string, optional, nullable) — The Stripe payment ID associated with this payment session.
- `truemed_fee` (PaymentSessionDetailsTruemedFee, optional, nullable) — Only present when include_trumed_fee=True is included in the request. The fee collected by truemed for this payment session. Will return 0 until the session has been captured.

### PaginationBody

- `count` (integer, required) — The total number of items associated with the provided API key.
- `current_page` (integer, required) — The page requested. If none was provided, this will default to 1.
- `last_page` (integer, required) — The last page. You can iterate through pages by providing integers up to last_page in the page parameter.
- `page_size` (integer, required) — The number of items per page applied to this response.

### UserDetails

- `business_id` (string, required) — The unique business ID of the user.
- `email` (string, required) — The email of the user who executed the payment.
- `name` (string, required) — The name of the user who executed the payment.

### PaymentSessionAmountDetails

- `additional_charges_details` (list of PaymentSessionAmountDetail, optional, nullable) — An array of individual additional charge line items with names and amounts.
- `discounts_details` (list of PaymentSessionAmountDetail, optional, nullable) — An array of individual discount line items with names and amounts.
- `total_additional_charges` (integer, optional, nullable) — The total amount of additional charges (e.g., shipping, tax), in cents.
- `total_discounts` (integer, optional, nullable) — The total amount of discounts applied, in cents.

### DisputeDetails

- `description` (string, required) — Further details about the state of a dispute.
- `dispute_id` (string, required) — Stable Truemed dispute ID (UUID). Use this as the dispute's identifier.
- `disputed_on` (datetime, required) — The date that the dispute was created.
- `processor_dispute_id` (string, required) — Raw payment-processor dispute ID (e.g. Stripe `du_…`). Provided for reconciliation against processor records; prefer `dispute_id` (the stable Truemed UUID) as the identifier.
- `reason` (enum, required) — Specific reason the dispute was created.
  - Allowed values: `credit_not_processed`, `duplicate`, `fraudulent`, `general`, `noncompliant`, `product_not_received`, `product_unacceptable`, `subscription_canceled`, `unrecognized`
- `state` (enum, required) — Canonical dispute state. Finer-grained than `status`: distinguishes `inquiry` and `needs_response` (both surfaced as `Investigating` in `status`).
  - Allowed values: `inquiry`, `needs_response`, `under_review`, `won`, `lost`, `accepted`, `expired`, `closed`
- `status` (enum, required) — Status of this dispute.
  - Allowed values: `Lost`, `Won`, `Closed`, `Investigating`, `Under Review`, `Unknown`
- `amount` (integer, optional, nullable, default: 0) — The original disputed amount in cents. Always reflects what the dispute was filed for, independent of resolution. For Won disputes this stays non-zero even though `withdrawn_amount` becomes 0 after reinstatement, so consumers can show 'this dispute was for $X' regardless of outcome.
- `phase` (enum, optional, nullable) — Which round of the dispute (inquiry, dispute, pre-arbitration, arbitration).
  - Allowed values: `inquiry`, `dispute`, `pre_arbitration`, `arbitration`
- `resolved_on` (datetime, optional, nullable) — The date that the dispute was resolved.
- `withdrawn_amount` (integer, optional, nullable, default: 0) — The total amount of money withdrawn based on the ruling.

### PaymentSessionOrderItemDetails

- `name` (string, required) — The name of the item.
- `price` (integer, required) — The unit price in cents charged for the item.
- `quantity` (integer, required) — The number of this item in the cart.
- `total` (integer, required) — The post-discount, post-charge line total in cents — `(price × quantity) + total_additional_charges - total_discounts`. Use this when displaying the per-item total or when computing capture `item_details.total` for a fresh capture.
- `amount` (integer, optional, nullable) — The total amount for this line item in cents (quantity × price).
- `amount_details` (PaymentSessionAmountDetails, optional, nullable) — Itemized discounts and charges applied to this specific item.
- `item_id` (string, optional, nullable) — Optional unique identifier for this item provided by the merchant.
- `quantity_capturable` (integer, optional, nullable) — The quantity of this item that can still be captured (for manual capture authorizations).
- `quantity_refundable` (integer, optional, nullable) — The quantity of this item that can be refunded.
- `sku` (string, optional, nullable) — The SKU (Stock Keeping Unit) for this item.
- `total_capturable` (integer, optional, nullable) — The total amount in cents that can still be captured for this item.
- `total_refundable` (integer, optional, nullable) — The total amount in cents that can be refunded for this item. Truemed tracks this per item, so an order-level charge or discount appears in none of them: when the session carried a top-level `amount_details`, the sum of `total_refundable` across items falls below the session's refundable amount.

### RefundDetails

- `amount` (integer, required) — The amount refunded, in cents.
- `id` (string, required) — The UUID of the refund.
- `refunded_on` (datetime, required) — The date the refund was made in ISO 8601 format. Example: "2024-06-13T16:03:08.386Z"
- `truemed_fee_returned` (integer, optional, nullable, default: 0) — The amount of Truemed fees returned with this refund, in cents.

### PaymentSessionDetailsTruemedFee

Only present when include_trumed_fee=True is included in the request. The fee collected by truemed for this payment session. Will return 0 until the session has been captured.

- double
- string

### PaymentSessionAmountDetail

- `amount` (integer, required) — The amount in cents for this discount or charge.
- `name` (string, required) — The name or description of the discount or charge.

## Examples

**Response**

```json
{
  "payment_sessions": [
    {
      "authorize_amount": 1,
      "created_at": "2024-01-15T09:30:00Z",
      "id": "string",
      "idempotency_key": "string",
      "is_testing": true,
      "kind": "one_time_payment",
      "refund_count": 1,
      "status": "pending",
      "status_summary": "Incomplete",
      "user": {
        "business_id": "string",
        "email": "string",
        "name": "string"
      },
      "amount_details": {
        "additional_charges_details": [
          {
            "amount": 1,
            "name": "string"
          }
        ],
        "discounts_details": [
          {
            "amount": 1,
            "name": "string"
          }
        ],
        "total_additional_charges": 1,
        "total_discounts": 1
      },
      "authorized_on": "2024-01-15T09:30:00Z",
      "capture_amount": 1,
      "captured_on": "2024-01-15T09:30:00Z",
      "disputes": [
        {
          "description": "string",
          "dispute_id": "string",
          "disputed_on": "2024-01-15T09:30:00Z",
          "processor_dispute_id": "string",
          "reason": "credit_not_processed",
          "state": "inquiry",
          "status": "Lost",
          "amount": 1,
          "phase": "inquiry",
          "resolved_on": "2024-01-15T09:30:00Z",
          "withdrawn_amount": 1
        }
      ],
      "metadata": "string",
      "order_items": [
        {
          "name": "string",
          "price": 1,
          "quantity": 1,
          "total": 1,
          "amount": 1,
          "amount_details": {
            "additional_charges_details": [
              {
                "amount": 1,
                "name": "string"
              }
            ],
            "discounts_details": [
              {
                "amount": 1,
                "name": "string"
              }
            ],
            "total_additional_charges": 1,
            "total_discounts": 1
          },
          "item_id": "string",
          "quantity_capturable": 1,
          "quantity_refundable": 1,
          "sku": "string",
          "total_capturable": 1,
          "total_refundable": 1
        }
      ],
      "refund_amount": 1,
      "refunds": [
        {
          "amount": 1,
          "id": "string",
          "refunded_on": "2024-01-15T09:30:00Z",
          "truemed_fee_returned": 1
        }
      ],
      "stripe_payment_id": "string",
      "truemed_fee": 1.1
    }
  ],
  "pagination": {
    "count": 1,
    "current_page": 1,
    "last_page": 1,
    "page_size": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://dev-api.truemed.com/payments/v1/payment_sessions"

headers = {"x-truemed-api-key": "<apiKey>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://dev-api.truemed.com/payments/v1/payment_sessions';
const options = {method: 'GET', headers: {'x-truemed-api-key': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```