Hosted checkout

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:

number

required

Amount to collect, in major units (e.g. 50 = 50.00). Minimum 1.

string

required

ISO 4217 currency code, three uppercase letters (e.g. USD).

string

required

Payment description. Maximum 500 characters.

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

string

required

URL the customer is redirected to after the checkout session ends (success, failure, or expiry). Maximum 2048 characters.

Optional:

string

Your identifier for this payment. Maximum 191 characters and unique within your project.

integer

Session duration in minutes. Range: 30 to 1440 (24 hours). Defaults to the project setting when omitted.

string

URL to receive per-payment event notifications. Maximum 2048 characters. See Webhooks.

string

Descriptor that may appear on the customer’s statement. Max 22 characters. Allowed characters: A–Z a–z 0–9 space . , - +.

string

Email address to send a receipt to. Max 255 characters.

string

Your internal reference for the order or entity. Max 191 characters.

date

When the entity was created on your side. Must not be in the future.

object

Per-gateway options. See Custom checkout — gateway_options.

object

Up to 10 key/value pairs you want stored on the intent.

object

Narrow what the payer may do on this session. country_code and phone are mutually exclusive — pass one or the other, not both. The two method lists are independent of that pair and of each other.

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
`payment_methods`	object	`allow` and `deny` lists of method codes. See Method restrictions
`payment_method_categories`	object	`allow` and `deny` lists of method categories. See Method restrictions

A restriction your project cannot honour is rejected with 422 and no session is created.

object

Customise the hosted payment page. See Appearance below.

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

{
  "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_...",
      "reference": "ORDER-1042",
      "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. Only the keys you sent are present.

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.

Examples

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",
    "reference": "ORDER-1042",
    "return_url": "https://example.com/checkout/return",
    "customer": {
      "email": "[email protected]",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "appearance": {
      "template": "raven",
      "lang": "en"
    }
  }'

use Orqex\Client;

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

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

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

Get started

Payments

Payouts

Events

Utilities

MCP

Create a session

Request fields

Appearance

Response

Session lifecycle

After the customer returns

Examples

​Create a session

​Request fields

​Appearance

​Response

​Session lifecycle

​After the customer returns

​Examples

Create a session

Request fields

Appearance

Response

Session lifecycle

After the customer returns

Examples