Lock an on-ramp flow

Use an on-ramp flow when the customer wants to buy crypto with fiat inside the hosted 0Gate experience. Your server creates the intent, the session is locked to buy, and fulfillment still waits for a verified backend event.

Flow boundary

Implementation shape

1. Create a buy intent before you start 0Gate.
2. Create a server-side 0Gate session with the flow locked to on-ramp.
3. Store the 0Gate session id next to your buy intent.
4. Mount the on-ramp kit block or the full hosted widget with the session-bound flow.
5. Treat browser success as processing, then fulfill from signed backend state.

async function startOnRamp(input: OnRampIntent) {
  const intent = await buyIntents.create({
    accountId: input.accountId,
    fiatAmount: input.fiatAmount,
    fiatCurrency: input.fiatCurrency,
    targetAsset: input.targetAsset,
    walletAddress: input.walletAddress,
    status: 'pending_session',
  });

  const session = await gateSessions.createForAttempt({
    attemptId: intent.id,
    flow: 'on_ramp',
    userReference: intent.id,
    idempotencyKey: `on-ramp:${intent.id}`,
  });

  await buyIntents.attachGateSession(intent.id, session.id);
  return { intentId: intent.id, clientSecret: session.clientSecret };
}

State model

Browser behavior

Keep the browser path deliberately thin.

Webhook and reconciliation

The on-ramp terminal path is the same as the generic payment flow: verify the signature, dedupe by event id, and fulfill once. Reconciliation should read trusted server state only when webhook delivery is delayed, dead-lettered, or a support agent needs to resolve a stuck attempt.

async function applyOnRampEvent(event: GateSessionEvent) {
  const intent = await buyIntents.findByGateSession(event.data.id);
  if (!intent) return;

  if (event.type === 'gate_session.completed') {
    await fulfillBuyIntentOnce(intent.id, { sourceEventId: event.id });
  }

  if (event.type === 'gate_session.failed') {
    await buyIntents.markFailed(intent.id, { sourceEventId: event.id });
  }
}

Production checklist

• Lock the flow on the server, not only in browser UI.
• Store your intent id, 0Gate session id, and event ids.
• Redact browser session values and webhook payloads from logs.
• Keep support screens generic: do not expose provider, treasury, or compliance internals.
• Test refreshes, double-clicks, closed iframes, delayed webhook delivery, and duplicate events.

Related pages