Embed the widget

Mount a session-bound Gate iframe or use hosted redirect.

The recommended integration is session-bound: your server fixes the amount, currency, flow, and allowed return URL in a GateSession; the browser receives only client_secret and pk_*.

Iframe embed

import { GateRamp } from '@0bit/gate/browser';

const ramp = new GateRamp({
  environment: 'sandbox',
  publishableKey: 'pk_test_...',
  clientSecret: session.client_secret,
  theme: 'light',
});

await ramp.mount('#gate', {
  onReady: () => console.log('Gate ready'),
  onSuccess: result => showPendingConfirmation(result),
  onError: ({ code }) => showRecoverableError(code),
});

The SDK first calls POST /embed/bootstrap. Gate checks the publishable key, client secret, credential mode, session ownership, and embedding origin. It then mounts the configured Gate iframe and uses origin-checked postMessage events.

Do not treat onSuccess as settlement confirmation. Wait for gate_session.completed and reconcile the transaction.

Flow locking

Set flow when creating the session:

{
  "amount": "100.00",
  "currency": "BRL",
  "flow": "on_ramp",
  "return_url": "https://partner.example/gate/complete"
}

Valid values are on_ramp and off_ramp. A null or omitted flow lets the user choose inside the widget.

Hosted redirect

For native apps or pages that cannot host an iframe, redirect to the hosted Gate surface:

GateRamp.redirectToCheckout({
  environment: 'sandbox',
  publishableKey: 'pk_test_...',
  clientSecret: session.client_secret,
});

Hosted redirect is always session-bound. The session's allowlisted return_url controls where the user returns.

Unmount the SDK when removing the checkout so its message listener and iframe are cleaned up.