0Gate core concepts
The product vocabulary behind 0Gate sessions, flow locks, embeds, callbacks, webhooks, capabilities, and reconciliation.
0Gate integrations are easier to reason about when every value has one owner. Your backend owns the intent and durable state, the hosted 0Gate surface owns the user-facing payment or ramp journey, and webhooks carry the backend event stream that your ledger can trust.
Concepts at a glance
| Concept | What it means | Integration rule |
|---|---|---|
| Session | A server-created hosted flow object that binds amount, currency, return URL, optional flow, user reference, metadata, and constraints. | Create it with sk_*; share only client_secret with the browser. |
| Client secret | A browser-safe session secret returned once when the session is created. | Treat it as scoped to one hosted session; do not log it broadly. |
| Publishable key | A browser-safe key shaped pk_*. | Use it for embed bootstrap, not for privileged server actions. |
| Secret key | A server-only key shaped sk_*. | Keep it in your backend or secret manager only. |
| Flow lock | A session or SDK option that forces on_ramp, off_ramp, or swap. | Use it when your UI already knows the user's task. |
| Hosted surface | The iframe, kit block, redirect, or WebView that runs the user journey. | Do not rebuild compliance, payment-method, or settlement UX outside the hosted path. |
| Browser callback | A client-side UX signal such as success, error, close, or unavailable. | Use it for interface state only; do not fulfill from it. |
| Webhook event | A signed backend event delivered to your webhook URL. | Verify signature, dedupe by event id, then update durable state. |
| Capability | Approved support data for region, currency, asset, method, payout method, or eligibility. | Check capabilities before displaying a path as available. |
Trust boundaries
The most important rule is that the browser never becomes the authority for money movement or fulfillment. Browser code can render a hosted experience and react to callbacks. It cannot create privileged sessions, approve unsupported flows, override compliance decisions, or mark a partner ledger as settled.
Session fields that shape product behavior
| Field | Product use | Public-safe wording |
|---|---|---|
amount and currency | Lock the value the hosted flow must use. | Server-bound values; users should not be able to tamper with them in the browser. |
return_url and cancel_url | Route users after hosted completion or abandonment. | UX navigation only; backend fulfillment still waits for verified events. |
flow | Locks the hosted surface to on_ramp, off_ramp, or swap. | Use for dedicated product buttons or kit blocks. |
target_token and target_network | Constrain asset and chain choices. | Only present constraints that are enabled for the partner and market. |
wallet_address | Prefills destination where supported. | Validate ownership and chain compatibility in your app before sending it. |
user_reference | Correlates 0Gate events to your user, order, or CRM id. | Keep it opaque; avoid raw PII. |
metadata | Carries partner-controlled notes. | Use support-safe ids, not secrets or sensitive customer data. |
Event model
The 0Gate OpenAPI contract includes session events such as gate_session.created, gate_session.processing, gate_session.completed, gate_session.failed, gate_session.cancelled, and gate_session.expired. Treat completed, failed, cancelled, and expired as backend-state transitions that must be verified and deduped before they touch your ledger.
Callbacks are not settlement proof
onSuccess can move the user to a confirmation screen, but it should not ship goods, release balance, or mark an
invoice as paid. Use the signed webhook and a server read for durable state.