Developer docs

Hosted checkout API for partner stores.

Create a payment session, send the customer to a hosted checkout, and receive a signed callback when the payment processor confirms the payment was captured.

Create sessionsGenerate hosted checkout URLs for orders from your shop. Receive paid eventsUse a signed webhook to update the customer order. Trust server capturePaid status comes from the processor's server API response.

Authentication

Every private API request uses the partner API key and PIN issued in the portal. Send the API key as a bearer token and the PIN in the x-pin header.

Authorization: Bearer pk_live_your_key
x-pin: 123456
Idempotency-Key: order-1001

Create a checkout session

Create a session from your shop backend when the customer is ready to pay. Amounts are integer cents. Configure one paid-event endpoint under Settings → Developer webhook; every new session automatically inherits it.

Developer workspace showing a laptop and payment workflow

POST/v1/checkout/sessions

POST /v1/checkout/sessions
Content-Type: application/json

{
  "amount": 1499,
  "currency": "usd",
  "product_name": "Product name",
  "description": "Optional checkout description",
  "redirect_url": "https://shop.example.com/orders/order-1001/thank-you",
  "customer_email": "buyer@example.com",
  "reference": "order-1001",
  "metadata": {
    "cart_id": "cart_123"
  }
}

Response

{
  "id": "cs_live_xxxxx",
  "object": "checkout.session",
  "status": "pending",
  "amount": 1499,
  "amount_cents": 1499,
  "currency": "usd",
  "product_name": "Product name",
  "description": "Optional checkout description",
  "redirect_url": "https://shop.example.com/orders/order-1001/thank-you",
  "customer_email": "buyer@example.com",
  "reference": "order-1001",
  "webhook_url": "https://shop.example.com/webhooks/xohus-paid",
  "metadata": {
    "cart_id": "cart_123"
  },
  "url": "https://xohuspay.com/pay/cs_live_xxxxx",
  "success_url": "https://shop.example.com/orders/order-1001/thank-you",
  "created_at": "2026-06-10T18:00:00.000Z",
  "expires_at": "2026-06-10T18:30:00.000Z"
}

redirect_url is optional. It must be an absolute http:// or https:// URL. After payment is captured, the hosted checkout sends the customer there. If omitted, the customer sees the built-in payment confirmation page.

Paid webhook

When the customer completes checkout, Xohus Pay captures the payment order server-side. If capture succeeds, a signed checkout.session.paid event is sent to your webhook_url.

POST https://shop.example.com/webhooks/xohus-paid
Content-Type: application/json
X-Xohus-Event: checkout.session.paid
X-Xohus-Signature: sha256=<hmac_sha256_raw_body_with_partner_secret>

{
  "id": "evt_xxxxx",
  "object": "event",
  "type": "checkout.session.paid",
  "created_at": "2026-06-10T18:02:00.000Z",
  "data": {
    "object": {
      "id": "cs_live_xxxxx",
      "status": "paid",
      "reference": "order-1001",
      "amount_cents": 1499,
      "currency": "usd",
      "processor_order_id": "PROCESSOR_ORDER_ID",
      "processor_capture_id": "PROCESSOR_CAPTURE_ID"
    }
  }
}

Verify the X-Xohus-Signature header before marking an order paid. The signature is an HMAC SHA-256 of the raw request body using the partner signing secret shown when it is rotated in the workspace.

Get session

Use this endpoint when your shop wants to poll a checkout session directly.

GET/v1/checkout/sessions/cs_live_xxxxx

GET /v1/checkout/sessions/cs_live_xxxxx

List sessions

Returns the latest checkout sessions for the authenticated partner.

GET/v1/checkout/sessions

GET /v1/checkout/sessions

Expire session

Expire a pending checkout session when the customer abandons an order or the cart changes.

POST/v1/checkout/sessions/cs_live_xxxxx/expire

POST /v1/checkout/sessions/cs_live_xxxxx/expire

How paid status is verified

The browser never decides that an order is paid. After the customer approves payment, the server calls the processor capture API and only marks the checkout paid when the processor returns a completed order or completed capture.

The processor order ID must match the checkout session.
The captured amount and currency must match the original session.
The database is updated to paid before the partner webhook is delivered.