How 0Gate works
How 0Gate separates trusted server work, browser-safe embedding, hosted UX, signed webhooks, and reconciliation.
0Gate uses a hosted-checkout architecture. Your backend creates the trusted session, the browser renders only the hosted 0Gate surface, and your backend listens for signed events before updating durable records.
Runtime architecture
This architecture keeps privileged decisions out of the browser. If the browser refreshes, closes, or receives a success callback before the webhook arrives, your backend still waits for the signed event or a server-side read before final fulfillment.
Responsibility map
| Layer | Owns | Does not own |
|---|---|---|
| Partner product UI | User intent, button placement, checkout route, UX loading and completion screens. | Secret keys, final settlement, or compliance bypass. |
| Partner backend | Session creation, idempotency keys, order records, webhook verification, reconciliation, support logs. | Hosted payment screens or private 0Bit internals. |
| 0Gate API | Session lifecycle, capability data, embed bootstrap, webhook delivery records, branding tokens, transaction reads. | Your internal order model. |
| Hosted 0Gate surface | User-facing payment, ramp, swap, verification, and completion UX. | Partner ledger writes or final fulfillment. |
| Webhook worker | Durable delivery of signed events to your backend. | Browser navigation state. |
Data flow
| Data | Direction | Rule |
|---|---|---|
sk_* secret key | Partner backend -> 0Gate API | Never send to browser, mobile app, URL, logs, analytics, or support screenshots. |
pk_* publishable key | Browser/mobile -> 0Gate embed | Browser-safe, but still scoped by origin and product configuration. |
client_secret | Partner backend -> browser/mobile | Session-scoped; use it to mount one hosted flow. |
Gate-Signature | 0Gate webhook -> partner backend | Verify against the raw body before processing event data. |
event.id | 0Gate webhook -> partner backend | Dedupe and store permanently. |
user_reference | Partner backend -> 0Gate -> webhook | Use opaque ids, not emails, documents, or raw PII. |
Failure handling
| Situation | Product behavior | Partner response |
|---|---|---|
| Browser callback says success but webhook is missing | User may have finished the hosted UX before backend delivery completes. | Show pending UI, poll your backend, and inspect webhook deliveries. |
| User closes the widget | Session may remain open until cancelled or expired. | Keep the order pending or cancelled according to your own UX policy. |
| Webhook is delivered more than once | At-least-once delivery can repeat the same event id. | Dedupe by event id and make fulfillment idempotent. |
| Session is expired or cancelled | Hosted flow is no longer usable for that journey. | Create a new session if the user restarts. |
| Capability becomes unavailable | Region, asset, method, or partner settings no longer support the requested path. | Hide the path or show an unavailable state; do not force a hosted flow. |
Operational trace
For every production journey, keep enough data to answer support questions without exposing secrets:
- Your order id and
user_reference. - 0Gate session id.
- Transaction reference when present.
- Webhook event id and event type.
- Request id from API responses.
- Environment: sandbox/test or live.
- Return URL and cancel URL origins.
- Final state recorded in your own ledger.
Related pages
Keys and environments
Keep secret, publishable, webhook, sandbox, and live values separated.
Allowed domains and redirects
Configure exact browser origins and safe return routes.
Webhook event delivery
Test, inspect, replay, and monitor signed events.
Settlement tracking
Turn hosted events and transactions into operational records.