Collect a Payment Method In-App

The payment-method embed keeps card collection inside Ruba while your product controls where and when the UI appears.

Getting a session token

Create a customer session on the server, where the organization access token remains private. Send only its one-hour, customer-scoped token to the browser.

Server

import { Ruba } from "@getruba/sdk";

const ruba = new Ruba({ accessToken: process.env.RUBA_ACCESS_TOKEN });
const { data: session, error } = await ruba.POST("/v1/customer-sessions/", {
  body: { customer_id: "<customer_id>" },
});

if (error) throw new Error("Unable to create customer session");

Build sequence

pnpm add @getruba/checkout

Browser

import { RubaEmbedPaymentMethod } from "@getruba/checkout/payment-method";

const embed = await RubaEmbedPaymentMethod.create({
  sessionToken: session.token,
});

embed.addEventListener("success", ({ detail }) => {
  console.log(detail.paymentMethodId);
});

Mount inline

Browser

const embed = RubaEmbedPaymentMethod.createInline({
  sessionToken: session.token,
  element: document.getElementById("payment-method"),
});

React applications can render the frame directly:

React

import { RubaPaymentMethod } from "@getruba/checkout/react/payment-method";

<RubaPaymentMethod
  sessionToken={session.token}
  onSuccess={(paymentMethodId) => console.log(paymentMethodId)}
/>

Initialize from HTML

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

Localization

Pass a BCP 47 value such as fr-FR through locale. The setting applies to both embed copy and Stripe Elements. See checkout localization for supported languages.

Events

Every signal is a cancelable CustomEvent on the embed instance.

Event	Detail	Built-in reaction
`loaded`	—	Removes the loading state.
`close`	—	Removes the frame unless confirmation has locked it.
`confirmed`	—	Prevents closing during processor work.
`success`	`{ paymentMethodId }`	Closes automatically unless `preventDefault()` is called.
`error`	`{ code }`	Unlocks closing after failure. Codes: `invalid_request`, `unauthorized`, `processing_failed`, `unknown`.

Redirect-based payment methods

Amazon Pay, Klarna, and other off-site authorization methods navigate the complete tab to the provider and back to returnUrl. Read the returned status once the page loads again:

Browser

const result = RubaEmbedPaymentMethod.getRedirectResult();
// { status: "succeeded" | "failed" } | null

React can use usePaymentMethodRedirectResult. Both routes remove the status query parameter after reading it, preventing a refresh from replaying an old result. Card 3DS stays inside the modal and does not use this return path.

Configure behavior

Option	Default	Effect
`sessionToken`	Required	Authenticates the one customer allowed to save the method.
`theme`	`light`	Chooses `light` or `dark`.
`setAsDefault`	`true`	Makes the saved method the customer default when enabled.
`returnUrl`	Current page	Destination after an off-site authorization method returns. Modal only.
`locale`	`en`	BCP 47 UI locale; unsupported values fall back to English.
`onLoaded`	—	Callback equivalent to listening for `loaded`.
`element`	Required inline	Container receiving the inline frame.

HTML triggers use the same settings through data-ruba-payment-method-theme, data-ruba-payment-method-set-as-default, data-ruba-payment-method-return-url, and data-ruba-payment-method-locale.

Launch Path

Shape the Offer

Run the Revenue Model

Deliver Customer Access

Build the Integration

Operate the Business

Implementation Playbooks

Collect a Payment Method In-App

Getting a session token

Build sequence

Mount inline

Initialize from HTML

Localization

Events

Redirect-based payment methods

Configure behavior

​Getting a session token

​Build sequence

​Open a modal

​Mount inline

​Initialize from HTML

​Localization

​Events

​Redirect-based payment methods

​Configure behavior

Getting a session token

Build sequence

Open a modal

Mount inline

Initialize from HTML

Localization

Events

Redirect-based payment methods

Configure behavior