Checkout sessions

A Checkout Session represents a customer's intent to pay. Rollo hosts the payment page and applies your theme. When payment completes, customers land on Rollo's confirmation page, then optionally continue to your success_url.

success_url is optional. If you omit it (or pass a Rollo /pay/… stub), customers stay on the confirmation page and can go back to the site they came from — we never send them to a missing Rollo route.

Lifecycle

Sessions are created in open status and expire two hours after creation if unpaid. While open, you may edit amount, plan type, interval, and trial days from the dashboard. Completed sessions cannot be modified. Expired sessions must be replaced.

One-time payment

Example request

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",
  "customer_email": "buyer@example.com"
}

Example response

{
  "id": "cs_01HXYZ...",
  "object": "checkout_session",
  "amount": 4900,
  "currency": "usd",
  "status": "open",
  "mode": "sandbox",
  "plan_type": "one_time",
  "url": "https://rollopayments.com/pay/cs_01HXYZ...",
  "expires_at": 1723014400000,
  "livemode": false
}

How to handle it

Redirect (or open overlay) to url.
On success URL, show confirmation UI only — fulfill on payment.succeeded / checkout_session.completed.
Optionally GET /v1/checkout_sessions/:id to confirm status.

Per-session merchant fee

Platforms can add a named fee on a single checkout without enabling Settings → Fees (which would apply to every checkout). Pass merchant_fee with a label (or name), plus percent and/or amount (fixed cents). That fee is 100% yours; Rollo's 7.9% + $0.75 still applies only to the product. Send merchant_fee: null to skip Settings defaults for one session. Full fee rules: Payments & fees.

Checkout with merchant_fee

Example request

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

{
  "amount": 4900,
  "currency": "usd",
  "mode": "payment",
  "success_url": "https://example.com/thanks",
  "merchant_fee": {
    "label": "Platform fee",
    "percent": 2.5,
    "amount": 100
  }
}

Example response

{
  "id": "cs_01HXYZ...",
  "object": "checkout_session",
  "amount": 5430,
  "currency": "usd",
  "status": "open",
  "mode": "live",
  "plan_type": "one_time",
  "url": "https://rollopayments.com/pay/cs_01HXYZ...",
  "merchant_fee": { "label": "Platform fee", "amount": 223 },
  "expires_at": 1723014400000,
  "livemode": true
}

How to handle it

Response amount is the buyer total (product + optional Rollo pass-through + your fee). Response merchant_fee.amount is the computed fee in cents. Use percent only, fixed only, or both.

Retrieve a session

Example request

GET /v1/checkout_sessions/cs_01HXYZ...
Authorization: Bearer rk_test_...

Example response

{
  "id": "cs_01HXYZ...",
  "object": "checkout_session",
  "amount": 4900,
  "currency": "usd",
  "status": "complete",
  "mode": "sandbox",
  "plan_type": "one_time",
  "url": "https://rollopayments.com/pay/cs_01HXYZ...",
  "customer_email": "buyer@example.com",
  "created": 1723000000000,
  "expires_at": 1723014400000,
  "livemode": false
}

How to handle it

Useful statuses: open, complete, expired. Prefer webhooks for fulfillment; use GET to reconcile.

Fee pass-through & theming

If fee pass-through is enabled, the charged amount includes Rollo's fee so you net the product price. Your optional merchant_fee stacks on top either way. Theme values (accent, background, radius) are snapshotted onto each session under Dashboard → Checkout.

Overlay and ad-hoc

Embed checkout in a modal with Overlay checkout. Charge custom amounts via Ad-hoc pricing. For recurring, see Subscriptions.