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

# Payments overview

> The payment intent is the core unit — one amount to collect from one customer.

A **payment intent** represents a single collection request: a fixed amount, a currency, and a customer. Orchestrate routes the intent through one or more attempts until one succeeds or you abandon the intent.

## Integration paths

|                                | Hosted checkout                                      | Direct API                                         |
| ------------------------------ | ---------------------------------------------------- | -------------------------------------------------- |
| **Who renders the payment UI** | Orchestrate                                          | You                                                |
| **Setup effort**               | Minimal — redirect and done                          | More — you call discovery and attempt endpoints    |
| **Customisation**              | Appearance settings on the session                   | Full control                                       |
| **Entrypoint**                 | [POST /payment/checkouts](/payments/hosted-checkout) | [POST /payment/intents](/payments/custom-checkout) |

Choose **hosted checkout** when you want Orchestrate to handle the payment page. Choose the **direct API** when you need to build the UI yourself, embed the payment flow inside a native app, or control every step of the interaction.

## Intent lifecycle

A payment intent moves through these statuses:

| Status               | Meaning                                                  |
| -------------------- | -------------------------------------------------------- |
| `pending`            | Created; no successful attempt yet                       |
| `completed`          | A payment attempt succeeded                              |
| `failed`             | All attempts exhausted; no further attempts are possible |
| `expired`            | The intent passed its expiry time without completing     |
| `refunded`           | Fully refunded after completion                          |
| `partially_refunded` | Partially refunded after completion                      |

## Attempt lifecycle

Each attempt against an intent has its own status:

| Status            | Meaning                                                                       |
| ----------------- | ----------------------------------------------------------------------------- |
| `processing`      | Submitted to the provider; awaiting result                                    |
| `action_required` | The customer must take an action — see [next actions](/payments/next-actions) |
| `completed`       | The attempt succeeded                                                         |
| `failed`          | The attempt failed                                                            |
| `expired`         | The attempt timed out                                                         |

A **failed attempt does not end the intent.** While the intent is `pending`, you may start another attempt — with a different method or the same one. The intent moves to `failed` only when no further attempts are possible.

## Refunds

A completed intent can be refunded in full or in part. The intent carries a `refunds_summary` object that tracks refunded amounts and in-flight refunds. See [Refunds](/payments/refunds) for the full reference.

## Listing and retrieving intents

**Retrieve one intent:**

```bash theme={null}
curl https://api.orqex.com/v1/payment/intents/pi_... \
  -H "Authorization: Bearer sk_live_..."
```

**List intents** with `GET /payment/intents`. Supported filters:

| Parameter         | Type    | Description             |
| ----------------- | ------- | ----------------------- |
| `status`          | string  | Filter by intent status |
| `channel`         | string  | Filter by channel       |
| `customer_id`     | string  | Filter by customer      |
| `created_at[gte]` | date    | Created on or after     |
| `created_at[lte]` | date    | Created on or before    |
| `per_page`        | integer | Results per page        |

The response uses **cursor-based pagination**. See [API conventions](/api-conventions) for the full pagination shape.

```bash theme={null}
curl "https://api.orqex.com/v1/payment/intents?status=pending&per_page=25" \
  -H "Authorization: Bearer sk_live_..."
```

## Countries and methods

Which countries and methods are available depends on your project's configuration. Never hard-code them: read them for the specific payment using the discovery endpoints documented in [Custom checkout](/payments/custom-checkout), or look them up in your [dashboard](https://app.orqex.com).