Pre-fill and constrain a session

Bind 0Gate flow, amount, asset, wallet, return URLs, and correlation fields on the server before the browser opens the hosted flow.

Pre-fill and constraints belong on the server-created 0Gate session. The browser should receive a session secret that reflects your approved intent; it should not be able to widen the flow, change amount, or invent settlement references.

Use constraints to narrow choices, not to bypass 0Gate

Constraints shape the hosted user journey. They do not turn 0Gate into a headless payment, quote, KYC, swap, or payout API.

Constraint path

What to constrain

Field	Use it for	Public guidance
`flow`	Lock to `on_ramp`, `off_ramp`, or `swap`.	Set it when your UI already captured the action.
`amount` + `currency`	Bind the fiat amount and currency.	Treat them as server-owned commercial intent.
`target_token`	Pin or suggest the crypto asset.	Use when the customer selected an asset before checkout.
`target_network`	Pin or suggest the network.	Pair with wallet validation in your app where possible.
`wallet_address`	Pre-fill destination wallet.	Validate on your side before session creation.
`user_reference`	Correlate session and webhooks to your records.	Use an opaque attempt/order id.
`metadata`	Store partner notes for support and reconciliation.	Avoid raw PII, secrets, or internal diagnostics.
`return_url` + `cancel_url`	Route the user back to your status pages.	Use allowed origins and read final state from your server.

Create a constrained session

const session = await gate.sessions.create({
  amount: '250.00',
  currency: 'EUR',
  flow: 'on_ramp',
  target_token: 'USDC',
  target_network: 'BASE',
  wallet_address: customerWallet.address,
  user_reference: attempt.id,
  return_url: `https://app.example.com/checkout/${attempt.id}/return`,
  cancel_url: `https://app.example.com/checkout/${attempt.id}/cancel`,
  metadata: {
    product: 'wallet_top_up',
    checkout_version: '2026-06',
  },
});

Return only the values needed by the browser:

return {
  attemptId: attempt.id,
  gateSessionId: session.id,
  clientSecret: session.client_secret,
};

Browser behavior

The browser can choose a mount style, but it should not loosen session constraints.

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

const ramp = new GateRamp({
  publishableKey,
  clientSecret,
  environment: 'sandbox',
});

await ramp.mount('#gate-checkout', {
  onSuccess: () => showProcessingState(),
});

Constraint rules

Rule	Reason
Validate user intent before session creation.	The session becomes the hosted expression of your product action.
Lock `flow` on the session for production.	Browser factories are useful, but server state should be canonical.
Treat wallet constraints as customer-sensitive data.	Redact logs and support views.
Do not put secrets in metadata.	Metadata can appear in support and event workflows.
Create a new session for materially different intent.	A changed amount, asset, wallet, or flow is a new checkout attempt.
Put exact validation in API reference.	Guides should stay focused on workflow and safety boundaries.

Common patterns

Pattern	Server constraints
“Buy USDC” button	`flow: 'on_ramp'`, `target_token`, optional `target_network`.
“Top up this wallet”	`flow: 'on_ramp'`, amount/currency, `wallet_address`, `user_reference`.
“Cash out” screen	`flow: 'off_ramp'`, amount/currency, return/cancel URLs.
“Convert asset” action	`flow: 'swap'`, source/target context in your own intent, 0Gate session reference.