Checkout sessions

A Checkout Session represents a customer's intent to pay. Rollo hosts the payment page, applies your theme, and returns the customer to your success URL when payment completes.

Lifecycle

Sessions are created in open status and expire two hours after creation if unpaid. While open, you may edit amount, plan type (one-time or recurring), interval, and trial days from the dashboard. Editing extends expiry by a short window so customers are not dropped mid-flow. Completed sessions cannot be modified. Expired sessions must be replaced with a new session.

The hosted page shows a countdown while the session remains valid, displays a Secure payment badge, and links to Rollo's Terms of Service and Privacy Policy. Card fields for live payments load in an isolated frame so your site never handles raw card data.

One-time and subscription modes

Set the session to one-time when you want a single charge. Set it to recurring when you want a subscription (optionally with a trial). You can change an open session between these modes before the customer pays. If a catalog price is attached, the price definition takes precedence over ad-hoc amount fields.

Fee pass-through

If fee pass-through is enabled on the account, the amount charged to the customer includes Rollo's fee so you net the full product price. The checkout UI itemizes the processing component when applicable.

Theming

Configure accent color, background, border radius, and field collection under Dashboard → Checkout. A live preview updates as you edit. Theme values are snapshotted onto each session at creation time.

Create a session

Always create sessions from your server using a secret key. Never embed rk_live_ keys in client-side code.

POST /v1/checkout_sessions
Authorization: Bearer rk_test_...
Content-Type: application/json

{
  "amount": 4900,
  "currency": "usd",
  "mode": "payment",
  "success_url": "https://example.com/thanks",
  "cancel_url": "https://example.com/cancel"
}

{
  "id": "cs_...",
  "url": "https://rollopayments.com/pay/cs_...",
  "status": "open",
  "expires_at": 1723007200
}

Overlay and ad-hoc

Embed checkout in a modal with Overlay checkout. Charge custom amounts without a catalog price via Ad-hoc pricing.