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

# Payments

> Retrieve payment records

A payment is created automatically when a customer completes a checkout. Payments are confirmed on the Stellar ledger and carry a transaction hash.

## The payment object

<ResponseField name="id" type="string">
  Unique identifier. Prefixed with `pay_`.
</ResponseField>

<ResponseField name="object" type="string">
  Always `"payment"`.
</ResponseField>

<ResponseField name="checkout_id" type="string">
  The checkout this payment originated from.
</ResponseField>

<ResponseField name="customer_id" type="string">
  The customer who made the payment.
</ResponseField>

<ResponseField name="subscription_id" type="string">
  If this payment is a subscription renewal, the subscription ID.
</ResponseField>

<ResponseField name="amount" type="string">
  Amount and asset code, e.g. `"50 XLM"`.
</ResponseField>

<ResponseField name="status" type="string">
  `pending`, `confirmed`, or `failed`.
</ResponseField>

<ResponseField name="transaction_hash" type="string">
  The Stellar transaction hash.
</ResponseField>

<ResponseField name="billing_details" type="object | null">
  Snapshot of the customer's billing info at the time of payment. `null` if no customer was attached.

  <Expandable title="billing_details fields">
    <ResponseField name="email" type="string">
      Customer's email address.
    </ResponseField>

    <ResponseField name="name" type="string">
      Customer's full name.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="payment_method_details" type="object | null">
  The Stellar wallet used to make the payment. `null` if unavailable.

  <Expandable title="payment_method_details fields">
    <ResponseField name="id" type="string">
      Wallet identifier. Prefixed with `cwl_`.
    </ResponseField>

    <ResponseField name="address" type="string">
      The Stellar public key (G-address).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="line_items" type="array">
  Refunds issued against this payment. Empty array if no refunds exist.

  <Expandable title="line item fields">
    <ResponseField name="id" type="string">
      Unique identifier for the refund. Prefixed with `ref_`.
    </ResponseField>

    <ResponseField name="amount" type="string">
      Refunded amount and asset code, e.g. `"10 XLM"`.
    </ResponseField>

    <ResponseField name="reason" type="string">
      The reason provided when the refund was issued.
    </ResponseField>

    <ResponseField name="status" type="string">
      `pending`, `confirmed`, or `failed`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="metadata" type="object">
  Arbitrary key-value data.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp.
</ResponseField>

***

## Retrieve a payment

`GET /payment/{id}`

Fetches a single payment by ID. Before returning, the Stellar network is queried for any `pending` payments and their status is updated accordingly.

```bash theme={null}
curl https://api.stellartools.dev/payment/pay_01jx... \
  -H "x-api-key: YOUR_API_KEY"
```

Returns a payment object.

***

## List payments

`GET /payment`

Returns a paginated list of payments for your account, ordered by creation date descending.

```bash theme={null}
curl https://api.stellartools.dev/payment \
  -H "x-api-key: YOUR_API_KEY"
```

### Query parameters

<ParamField query="customer" type="string">
  Filter payments by customer ID. Returns only payments made by this customer.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of payments to return. Defaults to `10`.
</ParamField>

<ParamField query="starting_after" type="string">
  Return payments after this payment ID (exclusive). Use the last `id` in the previous page to paginate forward.
</ParamField>

Returns a [list object](/api-reference/introduction#pagination) containing payment objects.