Overlay checkout

Keep customers on your site by opening hosted Checkout in a modal iframe. Card fields stay inside Rollo's secure frame; your parent page never handles raw card data.

Flow

  1. Create a Checkout Session on your server.
  2. Pass the hosted url to the overlay helper.
  3. Listen for rollo_checkout_complete via postMessage, then still fulfill via webhooks.

Server: create session

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
  }
}

Example response

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

How to handle it

Return only url (and optionally id) to your frontend. Never send the secret API key to the browser. Optional merchant_fee is set on the server session — same fields as Checkout.

Drop-in snippet

<!-- After bundling or copying src/lib/rolloOverlay.ts -->
<script type="module">
  import { openRolloCheckout } from '/rollo-overlay.js'

  document.querySelector('#buy').addEventListener('click', async () => {
    const { url } = await fetch('/api/create-checkout', { method: 'POST' })
      .then((r) => r.json())

    openRolloCheckout({
      checkoutUrl: url,
      onComplete: ({ sessionId }) => {
        // Optimistic UI only — unlock access from payment.succeeded webhook
        window.location.href = '/thanks?cs=' + sessionId
      },
    })
  })
</script>

Full webhook handling: Webhooks.