> 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.

# Get Payment Status

GET https://dev-api.truemed.com/payments/v1/payment_session/{business_id}

Get the status of a payment session based on the payment session id.

## Request Notes

To get the status of a Payment Session object, call the detail view with the ID of the
payment session returned by the `create_payment_session` endpoint.

## Response Notes

- `status` - the status of the initial payment, an enum with one of the following values:
  - `captured` - payment has completed
  - `canceled` - payment was canceled before the user entered payment information via a call
    to our cancel API.
  - `pending` - payment has not been successfully completed yet.
  - `processing` - the customer has entered their payment information, but it is under review
    by Truemed
    - Any customer facing communication should indicate successful payment at this point,
      such as on the `success_url`.
    - The merchant should not fulfill the order until the Payment Session Webhook indicates
      that the payment has been captured.
  - `rejected` - While in the `processing` state, Truemed reviewed and rejected the payment
    session.
    - The merchant should not fulfill these orders, and should communicate failure to the
      user via email.
  - `authorized` - an auth hold has been placed on the customer's card.
  - `authorization_voided` - the auth hold has been voided via a call to our Void Session api.
  - `authorization_expired` - the auth hold has expired and we were not able to re-auth the
    transaction. This state is only possible after a call to our Manual Capture api, and is
    only set after we attempt a re-auth hold on the existing payment method.
- `status_summary` - a summary of the overall payment session. This includes refunds and
  disputes, and is an enum of the following values:
  - `Incomplete` - Customer started checkout but did not complete
  - `Authorized` - Auth hold placed on customer's payment method
  - `Captured` - Payment has been processed
  - `Partially Captured` - The payment has been partially processed
  - `Refunded` - The full amount charged in this order has been refunded to customer
  - `Partially Refunded` - Part of the original order has been refunded to the customer
  - `Disputed` - The transaction has been disputed by the customer
  - `Voided` - The payment was voided by the partner
  - `Expired` - The partner did not capture an authorized session before it expired
- `order_items` - a list of order items, with the following fields per item:
  - `item_id` - The item_id that uniquely identifies this item. If the client specified one
    when creating the Payment Session, that item_id will be returned.
  - `name` - the name of the item
  - `price` - the unit price in cents charged for the item
  - `quantity` - the number of this item in the cart
  - `sku` - the partner's SKU for the item
  - `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.
- `capture_amount` **(Optional)** - the amount of funds actually captured.
  - For payment sessions of `kind=one_time_payment` this field will always be present and
    will be the same as `authorize_amount`.
  - For payment sessions of `kind=authorization` this field will not be present until the
    funds have been captured (via a call to Manual Capture).
- `capture_failed_on` **(Optional)** - the time the capture permanently failed. Present only for the
  rare session whose capture could not be completed; null otherwise.
- `capture_failed_details` **(Optional)** - a generic message indicating the capture could not be
  completed. Null when `capture_failed_on` is null.
- `capture_failed_amount_collected` **(Optional)** - funds already collected on a partially-charged
  split payment before the capture failed; null otherwise.

Reference: https://developers.truemed.com/api-reference/payment-sessions/retrieve-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

### Path parameters

- `business_id` (string, required) — The payment session ID.

## Response

### 200

Successful response

- `authorize_amount` (integer, required) — The amount the user's card will be authorized for. In the case of `kind=one_time_payment`, this will always the same same as `capture_amount`.
- `captures` (list of PaymentSessionCaptureDetails, required) — The completed captures for this payment session, each addressable by `id` when issuing a refund (`capture_id`). Empty until the session has at least one completed capture.
- `created_at` (datetime, required) — The date and time when the payment session was created.
- `disputes` (list of DisputeDetails, required) — A list of dispute objects that will be empty if the payment has no associated disputes.
- `is_testing` (boolean, required) — Whether the payment was executed in a test environment.
- `kind` (enum, required) — The type of payment session.
  - Allowed values: `one_time_payment`, `authorization`
- `order_items` (list of PaymentSessionOrderItemDetails, required) — A list of order items.
- `payment_session_id` (string, required) — The id of the payment session.
- `refunds` (list of RefundDetails, required) — A list of refund objects that will be empty if the payment has no associated refunds.
- `status` (enum, required) — The status of the initial payment.
  - 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.
  - Allowed values: `Incomplete`, `Canceled`, `Rejected`, `Processing`, `Authorized`, `Voided`, `Expired`, `Partially Captured`, `Captured`, `Partially Refunded`, `Refunded`, `PartiallyDisputed`, `Disputed`
- `total_amount` (integer, required) — The total amount captured, in cents.
- `amount_details` (PaymentSessionAmountDetails, optional, nullable) — Detailed breakdown of the payment amount.
- `authorization_expires_at` (datetime, optional, nullable) — The latest UTC time at which the authorization is valid for capture. Null until the session has an authorized transaction. When the transaction has multiple active payments (e.g. HSA + credit), this is the earliest expiration across them.
- `capture_amount` (integer, optional, nullable) — The amount of funds actually captured.
- `capture_failed_amount_collected` (integer, optional, nullable) — The amount of funds already collected on a capture that permanently failed. Set when part of a split payment succeeded before the capture failed; null otherwise.
- `capture_failed_details` (string, optional, nullable) — A generic message indicating the capture could not be completed. Null when capture_failed_on is null.
- `capture_failed_on` (datetime, optional, nullable) — The UTC time at which capturing the authorized funds permanently failed. Null unless the capture will not be retried.
- `customer_business_id` (string, optional, nullable) — The business id of the customer.
- `email` (string, optional, nullable) — The email of the user who executed the payment.
- `metadata` (string, optional, nullable) — Optional field echoed back if present in the call to `create_payment_session`.
- `name` (string, optional, nullable) — The name of the user who executed the payment.
- `stripe_payment_id` (string, optional, nullable) — The Stripe payment id.
- `truemed_fee` (PaymentSessionDetailResponseTruemedFee, optional, nullable) — The fee that Truemed received from the payment session. Will return 0 until the session has been captured.

## Errors

### 400 Bad Request Error

Bad Request

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

### 404 Not Found Error

Not Found

- `error` (enum, required)
  - Allowed values: `InvalidPaymentId`, `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

### PaymentSessionCaptureDetails

- `amount_refundable` (integer, required) — The amount in cents still refundable against this capture — the captured amount net of prior refunds and any dispute-locked funds. Use this as the ceiling for a refund targeting this capture.
- `capture_amount` (integer, required) — The amount captured in cents for this capture.
- `captured_at` (string, required) — ISO-8601 timestamp of when this capture completed.
- `id` (string, required) — The stable id of this capture; pass it as `capture_id` to refund against it.
- `item_details` (list of CaptureItemDetails, required) — The per-item breakdown of this capture (empty for amount-only captures).

### 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.

### 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.

### PaymentSessionDetailResponseTruemedFee

The fee that Truemed received from the payment session. Will return 0 until the session has been captured.

- double
- string

### CaptureItemDetails

- `item_id` (string, required) — ID that uniquely identifies the item within the Payment; optionally specified when creating the payment and retrievable from payment session status or list payment sessions.
- `quantity` (integer, required) — The quantity to capture for this order_item, up to the quantity_capturable for the item, retrievable from payment session status or list payment sessions.
- `total` (integer, required) — The total amount in cents to capture for this order_item, up to the total_capturable for the item, retrievable from payment session status or list payment sessions.

### 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
{
  "authorize_amount": 1,
  "captures": [
    {
      "amount_refundable": 1,
      "capture_amount": 1,
      "captured_at": "string",
      "id": "string",
      "item_details": [
        {
          "item_id": "string",
          "quantity": 1,
          "total": 1
        }
      ]
    }
  ],
  "created_at": "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
    }
  ],
  "is_testing": true,
  "kind": "one_time_payment",
  "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
    }
  ],
  "payment_session_id": "string",
  "refunds": [
    {
      "amount": 1,
      "id": "string",
      "refunded_on": "2024-01-15T09:30:00Z",
      "truemed_fee_returned": 1
    }
  ],
  "status": "pending",
  "status_summary": "Incomplete",
  "total_amount": 1,
  "amount_details": {
    "additional_charges_details": [
      {
        "amount": 1,
        "name": "string"
      }
    ],
    "discounts_details": [
      {
        "amount": 1,
        "name": "string"
      }
    ],
    "total_additional_charges": 1,
    "total_discounts": 1
  },
  "authorization_expires_at": "2024-01-15T09:30:00Z",
  "capture_amount": 1,
  "capture_failed_amount_collected": 1,
  "capture_failed_details": "string",
  "capture_failed_on": "2024-01-15T09:30:00Z",
  "customer_business_id": "string",
  "email": "string",
  "metadata": "string",
  "name": "string",
  "stripe_payment_id": "string",
  "truemed_fee": 1.1
}
```

**SDK Code**

```python
import requests

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

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_session/business_id';
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);
}
```