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

# List payment requests

`GET /payments`

## Request

- Base URL: `https://osis.co/api/v1/comms`
- URL: `https://osis.co/api/v1/comms/payments`
- Auth: HTTP bearer

Needs comms_read. Lists your most recent payment requests, newest first. There's no pagination. The Payments API is off until an owner or admin accepts the merchant terms. Until then, this returns 403 payments_api_disabled. This still works while payments are suspended.

## Query parameters

- `status` 'pending' | 'paid' | 'canceled' | 'partially_refunded' | 'refunded'
- `limit` integer

## Response `200`

Your payment requests.

- object
  - `payment_requests` PaymentRequest[], required
    - `id` string, required
    - `agent_id` string, nullable
    - `conversation_id` string, nullable
    - `contact_id` string, nullable
    - `to` string, nullable
    - `amount_cents` integer, required: Amount in cents (or the currency's smallest unit). For Shopify, this is an estimate until the paid order is confirmed.
    - `currency` string, required
    - `amount_formatted` string
    - `description` string
    - `creator_name` string
    - `status` 'pending' | 'paid' | 'canceled' | 'partially_refunded' | 'refunded', required: pending: waiting for payment. paid: the provider confirmed it. canceled: you canceled a Whop or Stripe request, or the order was canceled in Shopify. partially_refunded and refunded: part or all of a Shopify payment was refunded.
    - `refunded_cents` integer, required: Total refunded so far, in the payment's currency. 0 if nothing was refunded. Only Shopify reports refunds for now.
    - `refunded_at` string, date-time, nullable: When the latest refund came in.
    - `canceled_at` string, date-time, nullable: When the order was canceled in Shopify. Null for requests canceled in Comms.
    - `settlement` 'org' | 'platform'
    - `url` string, uri, required
    - `checkout_url` string, uri, nullable
    - `rail` 'whop' | 'stripe' | 'shopify', required
    - `whop_plan_id` string, nullable
    - `whop_checkout_config_id` string, nullable
    - `whop_payment_id` string, nullable
    - `stripe_checkout_session_id` string, nullable
    - `metadata` object
    - `paid_at` string, date-time, nullable
    - `created_at` string, date-time, nullable
    - `updated_at` string, date-time, nullable
    - `provider` 'whop' | 'shopify' | 'stripe', required

## Other responses

- `400`: invalid_status: status isn't pending, paid, canceled, partially_refunded, or refunded.
- `401`: API key is missing or wrong.
- `403`: payments_api_disabled: accept the merchant terms to turn on the Payments API. merchant_terms_update_required: accept the new terms version. You also get 403 if your key is missing a scope.

---

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