> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getopenrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payments

> List and retrieve payment records for checkout sessions.

A payment record is created when a buyer completes or attempts checkout. Use these endpoints to look up payment status and link payments to customers and invoices.

## GET /api/gateway/payments

Returns a paginated list of payments.

```bash theme={null}
curl "https://dash.getopenrails.com/api/gateway/payments?limit=20"
```

### Query parameters

| Parameter    | Type   | Description                                                                |
| ------------ | ------ | -------------------------------------------------------------------------- |
| `limit`      | number | Maximum number of records to return. Defaults to 20.                       |
| `customerId` | string | Filter by customer `cus_*` ID.                                             |
| `invoiceId`  | string | Filter by invoice `inv_*` ID.                                              |
| `paymentId`  | string | Filter to a specific payment by `pay_*` ID or checkout session `chk_*` ID. |
| `status`     | string | Filter by payment status.                                                  |

### Response

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "pay_abc123",
      "object": "payment",
      "customerId": "cus_7G42M9",
      "invoiceId": "inv_xyz789",
      "sessionId": "chk_nimbus_1056",
      "amount": 116,
      "currency": "USD",
      "status": "paid",
      "ledgerStatus": "settled",
      "created": "2026-05-24T17:37:00Z"
    }
  ],
  "hasMore": false
}
```

## GET /api/gateway/payments/{paymentId}

Fetches a single payment. The `paymentId` path parameter accepts either a `pay_*` payment ID or a `chk_*` checkout session ID.

```bash theme={null}
curl https://dash.getopenrails.com/api/gateway/payments/pay_abc123
# or look up by session ID
curl https://dash.getopenrails.com/api/gateway/payments/chk_nimbus_1056
```

### Response

```json theme={null}
{
  "id": "pay_abc123",
  "object": "payment",
  "customerId": "cus_7G42M9",
  "invoiceId": "inv_xyz789",
  "sessionId": "chk_nimbus_1056",
  "amount": 116,
  "currency": "USD",
  "status": "paid",
  "ledgerStatus": "settled",
  "route": {
    "id": "card-bridge-a",
    "kind": "card",
    "label": "Credit card"
  },
  "fees": {
    "buyer_fee": 3.72,
    "gateway_fee": 3.48,
    "merchant_net": 112.52,
    "total": 119.72
  },
  "metadata": {
    "order_id": "ord_284"
  },
  "created": "2026-05-24T17:37:00Z"
}
```

### Status values

| Status    | Meaning                                  |
| --------- | ---------------------------------------- |
| `pending` | Payment initiated but not yet confirmed. |
| `paid`    | Payment confirmed. Safe to fulfill.      |
| `failed`  | Payment failed or was rejected.          |

### Ledger status values

| Ledger status | Meaning                      |
| ------------- | ---------------------------- |
| `pending`     | Settlement not yet recorded. |
| `settled`     | Funds settled to merchant.   |
| `refunded`    | Payment was refunded.        |