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

# Hosted checkout

> Let Orchestrate render the payment page. Redirect the customer to checkout.url and handle the return.

Create a checkout session. Orchestrate hosts the payment page, collects the customer's method choice, and redirects the customer back to your `return_url` when they are done.

## Create a session

```
POST /payment/checkouts
```

### Request fields

**Required:**

<ParamField body="amount" type="number" required>
  Amount to collect, in **major units** (e.g. `50` = 50.00). Minimum `1`.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code, three uppercase letters (e.g. `USD`).
</ParamField>

<ParamField body="description" type="string" required>
  Payment description. Maximum 500 characters.
</ParamField>

<ParamField body="customer" type="object" required>
  Customer information. All sub-fields below are required unless noted.

  | Field        | Type   | Notes                                                    |
  | ------------ | ------ | -------------------------------------------------------- |
  | `email`      | string | Required                                                 |
  | `first_name` | string | Required. Max 100 characters                             |
  | `last_name`  | string | Required. Max 100 characters                             |
  | `address`    | string | Optional. Max 200 characters                             |
  | `city`       | string | Optional. Max 100 characters                             |
  | `state`      | string | Optional. Max 100 characters                             |
  | `country`    | string | Optional. Max 5 characters; must be a valid country code |
  | `zip`        | string | Optional                                                 |
</ParamField>

<ParamField body="return_url" type="string" required>
  URL the customer is redirected to after the checkout session ends (success, failure, or expiry). Maximum 2048 characters.
</ParamField>

**Optional:**

<ParamField body="expires_in_minutes" type="integer">
  Session duration in minutes. Range: `30` to `1440` (24 hours). Defaults to the project setting when omitted.
</ParamField>

<ParamField body="webhook_url" type="string">
  URL to receive per-payment event notifications. Maximum 2048 characters. See [Webhooks](/webhooks).
</ParamField>

<ParamField body="statement_descriptor" type="string">
  Descriptor that may appear on the customer's statement. Max 22 characters. Allowed characters: `A–Z a–z 0–9 space . , - +`.
</ParamField>

<ParamField body="receipt_email" type="string">
  Email address to send a receipt to. Max 255 characters.
</ParamField>

<ParamField body="entity_id" type="string">
  Your internal reference for the order or entity. Max 191 characters.
</ParamField>

<ParamField body="entity_created_at" type="date">
  When the entity was created on your side. Must not be in the future.
</ParamField>

<ParamField body="gateway_options" type="object">
  Per-gateway options. See [Custom checkout — gateway\_options](/payments/custom-checkout#gateway-options).
</ParamField>

<ParamField body="metadata" type="object">
  Up to 10 key/value pairs you want stored on the intent.
</ParamField>

<ParamField body="restriction" type="object">
  Pre-fill or lock the checkout to a specific country or phone number. `country_code` and `phone` are **mutually exclusive** — pass one or the other, not both.

  | Field          | Type   | Notes                                                      |
  | -------------- | ------ | ---------------------------------------------------------- |
  | `country_code` | string | 2-character country code. Locks the country selector       |
  | `phone`        | object | A validated phone number object. Pre-fills the phone field |
</ParamField>

<ParamField body="appearance" type="object">
  Customise the hosted payment page. See [Appearance](#appearance) below.
</ParamField>

### Appearance

All appearance fields are optional. Omit any field to use the project default.

| Field                    | Type    | Allowed values                                                                                                                                                        |
| ------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `template`               | string  | `raven`, `magpie`, `rook`                                                                                                                                             |
| `color`                  | string  | Any hex colour (e.g. `#1a1a2e`)                                                                                                                                       |
| `font`                   | string  | `inter`, `poppins`, `roboto`, `open_sans`, `lato`, `montserrat`, `source_sans_pro`, `nunito`, `raleway`, `work_sans`, `dm_sans`, `plus_jakarta_sans`, `space_grotesk` |
| `border_style`           | string  | `rounded`, `square`                                                                                                                                                   |
| `display_platform_badge` | boolean | Show or hide the "Powered by" badge                                                                                                                                   |
| `brand`                  | string  | Brand name displayed on the checkout page. Max 50 characters                                                                                                          |
| `icon_url`               | string  | URL of your brand icon. Max 2048 characters                                                                                                                           |
| `lang`                   | string  | `en`, `fr`                                                                                                                                                            |

## Response

`201 Created`

```json theme={null}
{
  "message": "Checkout session created.",
  "data": {
    "checkout": {
      "id": "cs_...",
      "status": "open",
      "environment": "live",
      "url": "https://checkout.orqex.com/...",
      "expires_at": "2025-01-01T01:00:00Z",
      "created_at": "2025-01-01T00:00:00Z",
      "appearance": { ... }
    },
    "payment": {
      "id": "pi_...",
      "status": "pending",
      "amount": { "value": 50.00, "formatted": "50.00 USD", "short": "$50", "currency": "USD" },
      ...
    }
  }
}
```

**Redirect the customer to `checkout.url`.** Do not present the payment form yourself — the hosted page handles method discovery, input collection, and error handling.

If `restriction` was set, the response `checkout.restriction` object echoes the applied restriction with the phone number obfuscated.

## Session lifecycle

| Status      | Meaning                                                     |
| ----------- | ----------------------------------------------------------- |
| `open`      | Session is active; customer can pay                         |
| `completed` | Payment was attempted (check intent status for the outcome) |
| `expired`   | Session expired before the customer completed               |

## After the customer returns

When the customer arrives at your `return_url`, the session is over — but the URL redirect is **not proof of payment**. A network interruption or browser close can bring the customer back without a completed payment.

Always confirm the outcome by fetching the session:

```
GET /payment/checkouts/{checkoutId}
```

Or listen for the `payment.completed` webhook. See [Webhooks](/webhooks).

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.orqex.com/v1/payment/checkouts \
    -H "Authorization: Bearer sk_live_..." \
    -H "Content-Type: application/json" \
    -d '{
      "amount": 50,
      "currency": "USD",
      "description": "Order #1042",
      "return_url": "https://example.com/checkout/return",
      "customer": {
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe"
      },
      "appearance": {
        "template": "raven",
        "lang": "en"
      }
    }'
  ```

  ```php PHP theme={null}
  use Orqex\Client;

  $client = new Client('sk_live_...');

  $result = $client->checkouts->create([
      'amount'      => 50,
      'currency'    => 'USD',
      'description' => 'Order #1042',
      'return_url'  => 'https://example.com/checkout/return',
      'customer'    => [
          'email'      => 'jane@example.com',
          'first_name' => 'Jane',
          'last_name'  => 'Doe',
      ],
      'appearance'  => [
          'template' => 'raven',
          'lang'     => 'en',
      ],
  ]);

  // Redirect the customer
  header('Location: ' . $result->data->checkout->url);
  ```
</CodeGroup>