Use hosted redirect & WebViews
Send users to the hosted 0Gate checkout when iframe embedding is blocked, then return them to a status page backed by your server.
Hosted redirect is the fallback for environments where an iframe is not reliable: strict content-security policies, managed pages, mobile WebViews, in-app browsers, email links, or surfaces where you cannot mount the browser SDK.
Return URL arrival is not final state
A redirect back to your app improves UX, but it does not prove the flow completed. Show a status page backed by your server, and close the attempt only after a verified backend event or trusted reconciliation read.
Redirect contract
When to use redirect
| Situation | Why redirect is better |
|---|---|
| Strict CSP blocks third-party frames. | Top-level navigation avoids the embedding page’s frame-src restrictions. |
| In-app browser or mobile WebView breaks iframe behavior. | Hosted checkout becomes the top document with its own origin. |
| CMS or no-code surface strips scripts or iframes. | You can route through a plain checkout button or link. |
| Email, SMS, or support-generated payment link. | There is no DOM container to mount into. |
Start redirect from the browser
redirectToCheckout is a static browser SDK method. It requires a server-created clientSecret.
import { GateRamp } from '@0bit/gate/browser';
GateRamp.redirectToCheckout({
publishableKey: import.meta.env.VITE_GATE_PUBLISHABLE_KEY,
clientSecret,
environment: 'sandbox',
theme: 'light',
});Embed first, redirect fallback
For normal web pages, you can attempt an iframe mount and fall back when mount or bootstrap fails.
import { GateRamp } from '@0bit/gate/browser';
async function openGateCheckout(clientSecret: string) {
const ramp = new GateRamp({
publishableKey: import.meta.env.VITE_GATE_PUBLISHABLE_KEY,
clientSecret,
environment: 'sandbox',
});
try {
await ramp.mount('#gate-frame', {
onSuccess: () => showProcessingState(),
onClose: () => showRetryState(),
});
} catch {
GateRamp.redirectToCheckout({
publishableKey: import.meta.env.VITE_GATE_PUBLISHABLE_KEY,
clientSecret,
environment: 'sandbox',
});
}
}Return URL rules
| Rule | Implementation |
|---|---|
| Use allowed origins. | Register the exact origins you use for return_url and cancel_url. |
| Include your attempt reference. | Route to /checkout/{attemptId}/return or equivalent so your page can read server state. |
| Ignore browser-only status. | Do not fulfill from query parameters, fragments, or local storage. |
| Support processing. | A user can return before webhook delivery finishes. |
| Keep copy generic. | Avoid provider, compliance, treasury, or raw webhook details on outcome pages. |
Outcome page shape
export async function loadCheckoutOutcome(attemptId: string) {
const attempt = await checkoutAttempts.get(attemptId);
if (attempt.status === 'fulfilled') return { view: 'success' };
if (attempt.status === 'failed') return { view: 'failed', canRetry: true };
if (attempt.status === 'expired') return { view: 'expired', canRetry: true };
if (attempt.status === 'cancelled') return { view: 'cancelled', canRetry: true };
return { view: 'processing' };
}Related pages
Integrate mobile WebViews
Use hosted redirect safely in native mobile containers.
Configure return URLs and outcome pages
Build success, failure, processing, and retry pages.
Handle failed or cancelled flows
Recover from abandoned, failed, delayed, and expired attempts.
Embed the 0Gate widget
Use iframe mount where the page can support it.
Embed a single flow with kit blocks
Use 0Gate kit blocks to open the hosted iframe directly into on-ramp, off-ramp, or swap while keeping the session and webhook model unchanged.
Integrate mobile WebViews
Use the hosted 0Gate redirect flow inside mobile WebViews without putting secret credentials or settlement decisions in the app.