Checkout Sessions

A checkout session is a short-lived, single-use URL that hosts the payment page. You create it on your server, redirect the customer to it, and verify the result on return. The customer's card data never touches your servers.

Live redirect domains

Before using a live API key, add the hostname from each success_url, failure_url, and cancel_url under Merchant Portal → Domains. Choose Plugin or payment redirects. The domain becomes active immediately and does not require a DNS change. DNS verification is only required when you use a domain to host a white-label Genius Checkout page.

Create a Checkout Session

POST /api/v1/checkout-sessions

Request body

Field	Type	Required	Description
amount	integer	Yes	Amount in the smallest currency unit (e.g., 1000 = $10.00)
currency	string	Yes	ISO 4217: USD, JMD, TTD, BBD, EUR, GYD
success_url	string	Yes	Redirect URL after successful payment
failure_url	string	Yes	Redirect URL after failed payment
cancel_url	string	No	Redirect URL for the cancel button
description	string	No	Shown on the checkout page and the receipt
customer	object	No	{name, email}
line_items	array	No	Itemized order details — see Line Items, Tax & Order Details
subtotal	integer	No	Subtotal before tax (cents)
tax_name	string	No	Tax label (GCT, VAT, Sales Tax)
tax_rate	number	No	Decimal rate (0.15 = 15%)
tax_amount	integer	No	Tax amount in cents
metadata	object	No	Arbitrary data (returned in webhooks and on retrieve)
gateway	string	No	Preferred gateway slug (e.g., powertranz_direct)
expires_in_minutes	integer	No	1–1440. Defaults to 30.

Response

{
  "id": "cs_abc123def456",
  "status": "open",
  "amount": 2500,
  "currency": "USD",
  "checkout_url": "https://app.geniuscheckout.com/checkout/cs_abc123def456",
  "expires_at": "2026-05-05T12:30:00+00:00"
}

Redirect the customer to checkout_url. They'll see the payment page with your branding, order summary, and card entry form.

Retrieve a Checkout Session

GET /api/v1/checkout-sessions/{id}

Verify before fulfilling

Use this endpoint to confirm payment status after the customer is redirected back. Never trust URL parameters — the redirect URLs do not contain payment data, only the session ID.

Response

{
  "id": "cs_abc123def456",
  "status": "completed",
  "amount": 2500,
  "currency": "USD",
  "description": "Order #1042",
  "completed_at": "2026-05-05T12:15:00+00:00",
  "transaction": {
    "id": "txn_789xyz",
    "receipt_number": "RCT-000042",
    "status": "captured",
    "card_brand": "Visa",
    "card_last4": "0071",
    "gateway_transaction_id": "5ABCABEC-4867-410B-B76C-E85721CF859B",
    "token_id": "tok_abc123"
  }
}

Session statuses

Status	Meaning
open	Customer has not completed checkout yet
completed	Payment captured
failed	Payment was attempted and declined
expired	Session passed its expires_at without completion
cancelled	Customer used the cancel button

Next

• Payment Flow — the full diagram from create to webhook
• Webhooks — the authoritative source of truth
• Tokenization & Recurring — reuse the token for renewals