Keep Checkout Inside Your Interface

Embedded checkout places Ruba’s hosted payment experience in an iframe over your product. Start with an HTML trigger when you only need to open it; install the package when your application must control its lifecycle or react to events.

Choose the integration depth

Approach	Best fit	Your responsibility
HTML trigger	Websites and CMS pages	Add one attribute and load the global script
Package initialization	React and bundled JavaScript apps	Install the package and initialize matching triggers
Programmatic instance	Custom flows and analytics	Create, observe, and close the checkout instance

Open checkout from HTML

Create a checkout page, copy its embed code, and place it on any page that accepts HTML:

<a
  href="__CHECKOUT_LINK__"
  data-ruba-checkout
  data-ruba-checkout-theme="light"
>
  Purchase
</a>

<script
  defer
  data-auto-init
  src="https://cdn.jsdelivr.net/npm/@getruba/checkout@latest/dist/embed.global.js"
></script>

The library finds elements carrying data-ruba-checkout and opens the URL inline. The trigger can use your own markup and styling; keep the attribute in place.

Initialize it in an application

Install the checkout package with your package manager:

npm install @getruba/checkout

pnpm add @getruba/checkout

yarn add @getruba/checkout

Call RubaEmbedCheckout.init() once after the application mounts. It attaches behavior to the same declarative triggers used by the HTML version.

import { RubaEmbedCheckout } from '@getruba/checkout/embed'
import { useEffect } from 'react'

export function PurchaseLink() {
  useEffect(() => {
    RubaEmbedCheckout.init()
  }, [])

  return (
    <a
      href="__CHECKOUT_LINK__"
      data-ruba-checkout
      data-ruba-checkout-theme="light"
    >
      Purchase
    </a>
  )
}

The URL may come from a reusable checkout page or a dynamically created Checkout Session. For a session, set embed_origin to the exact origin that hosts the iframe. A page at https://example.com/checkout uses https://example.com.

Control an instance directly

create() opens checkout without a declarative trigger and resolves after the iframe is ready. Supply light or dark as the theme.

import { RubaEmbedCheckout } from '@getruba/checkout/embed'

async function openCheckout() {
  return RubaEmbedCheckout.create('__CHECKOUT_LINK__', {
    theme: 'light',
    onLoaded: () => {
      console.log('Checkout is ready')
    },
  })
}

Use onLoaded instead of registering a later loaded listener. It cannot miss a checkout that finishes loading immediately.

Respond to the payment lifecycle

An instance emits three events:

Event	Moment	Default behavior you can prevent
`close`	The buyer closes checkout	Closing the interface
`confirmed`	The order is confirmed and payment processing starts	Making checkout non-closable
`success`	The purchase completes	Redirecting when `event.detail.redirect` is true

const checkout = await RubaEmbedCheckout.create('__CHECKOUT_LINK__', {
  onLoaded: () => console.log('Checkout loaded'),
})

checkout.addEventListener('close', (event) => {
  console.log('Checkout closed')
})

checkout.addEventListener('confirmed', (event) => {
  console.log('Payment processing started')
})

checkout.addEventListener('success', (event) => {
  console.log('Purchase completed', event.detail)

  if (!event.detail.redirect) {
    showSuccessMessage()
  }
})

Call event.preventDefault() inside a listener only when your application will replace the corresponding default behavior.

Manage it in React

Keep the active instance in state, register events immediately after creation, and close it when the component unmounts.

import { RubaEmbedCheckout } from '@getruba/checkout/embed'
import { useEffect, useState } from 'react'

export function CheckoutButton() {
  const [activeCheckout, setActiveCheckout] = useState(null)

  useEffect(() => {
    return () => activeCheckout?.close()
  }, [activeCheckout])

  async function handleCheckout() {
    try {
      const checkout = await RubaEmbedCheckout.create('__CHECKOUT_LINK__', {
        theme: 'light',
        onLoaded: () => console.log('Checkout is ready'),
      })

      setActiveCheckout(checkout)

      checkout.addEventListener('success', (event) => {
        analytics.track('Purchase Completed', {
          productId: 'your-product-id',
        })

        if (!event.detail.redirect) {
          // Render your own completion state.
        }
      })

      checkout.addEventListener('close', () => {
        setActiveCheckout(null)
      })
    } catch (error) {
      console.error('Checkout could not be opened', error)
    }
  }

  return <button onClick={handleCheckout}>Complete Purchase</button>
}

Close checkout from your code

Store the instance returned by create() and call close() when another application state must take priority. The normal close event still fires, so clear your reference in its listener.

let activeCheckout = null

async function openCheckout() {
  activeCheckout = await RubaEmbedCheckout.create('__CHECKOUT_LINK__')
  activeCheckout.addEventListener('close', () => {
    activeCheckout = null
  })
}

function closeCheckout() {
  activeCheckout?.close()
}

Wallet availability

Apple Pay appears when the buyer uses Safari on an Apple device with Apple Pay configured. Google Pay appears in Chrome when the browser is connected to a Google account with Google Pay configured. Hosted checkout needs no additional wallet setup. Embedded checkout requires domain validation before wallet methods can be enabled. Email support@getruba.com with your organization slug and the domain that will host the embed.

Launch Path

Shape the Offer

Run the Revenue Model

Deliver Customer Access

Build the Integration

Operate the Business

Implementation Playbooks

Keep Checkout Inside Your Interface

Choose the integration depth

Open checkout from HTML

Initialize it in an application

Control an instance directly

Respond to the payment lifecycle

Manage it in React

Close checkout from your code

Wallet availability

​Choose the integration depth

​Open checkout from HTML

​Initialize it in an application

​Control an instance directly

​Respond to the payment lifecycle

​Manage it in React

​Close checkout from your code

​Wallet availability

Choose the integration depth

Open checkout from HTML

Initialize it in an application

Control an instance directly

Respond to the payment lifecycle

Manage it in React

Close checkout from your code

Wallet availability