> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getruba.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Keep Checkout Inside Your Interface
> Open a Ruba payment flow without sending the buyer to another page
export const RubaSocials = () => {
if (typeof document === "undefined") {
return null;
}
const inject = () => {
const footer = document.getElementById("footer");
if (!footer || document.getElementById("ruba-socials")) {
return false;
}
const isDark = document.querySelector("html.dark") || document.querySelector('html[class*="dark"]');
const lineColor = isDark ? "#383838" : "#e8e8ed";
const iconColor = isDark ? "#8e8e93" : "#86868b";
const markColor = isDark ? "#ffffff" : "#08080c";
const hoverColor = "#0071e3";
const div = document.createElement("div");
div.id = "ruba-socials";
div.style.cssText = `display:flex;align-items:center;gap:20px;padding-top:20px;margin-top:20px;border-top:1px solid ${lineColor};width:100%`;
const logo = `Ruba`;
const spacer = ``;
const ig = ``;
const li = ``;
const x = ``;
const github = ``;
div.innerHTML = logo + spacer + ig + li + x + github;
footer.appendChild(div);
return true;
};
if (!document.documentElement.dataset.rubaSocialsObserver) {
document.documentElement.dataset.rubaSocialsObserver = "true";
const observer = new MutationObserver(() => {
if (!document.getElementById("ruba-socials")) {
inject();
}
});
observer.observe(document.body, {
childList: true,
subtree: true
});
}
setTimeout(() => {
if (!inject()) {
const interval = setInterval(() => {
if (inject()) {
clearInterval(interval);
}
}, 500);
setTimeout(() => clearInterval(interval), 10000);
}
}, 300);
return null;
};
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 Link](/features/checkout/links), copy its embed code, and place it on any page that accepts HTML:
```html theme={"system"}
Purchase
```
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:
```bash npm theme={"system"}
npm install @getruba/checkout
```
```bash pnpm theme={"system"}
pnpm add @getruba/checkout
```
```bash yarn theme={"system"}
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.
```tsx theme={"system"}
import { RubaEmbedCheckout } from '@getruba/checkout/embed'
import { useEffect } from 'react'
export function PurchaseLink() {
useEffect(() => {
RubaEmbedCheckout.init()
}, [])
return (
Purchase
)
}
```
The URL may come from a reusable Checkout Link or a dynamically created [Checkout Session](/features/checkout/session). For a session, set [`embed_origin`](/api-reference/checkouts/create-session#body-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.
```ts theme={"system"}
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 |
```ts theme={"system"}
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.
```tsx theme={"system"}
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
}
```
## 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.
```ts theme={"system"}
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](mailto:support@getruba.com) with your organization slug and the domain that will host the embed.
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 Link](/features/checkout/links), copy its embed code, and place it on any page that accepts HTML:
```html theme={"system"}
Purchase
```
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: