Test & go live

Every 0Gate integration is built and proven in the sandbox first, then promoted to production by swapping credentials and hosts — same routes, same response shapes, no flow changes. This page covers both halves: testing safely in the sandbox (where no real money moves), and the exact checklist for going live.

0Gate is 0Bit's embeddable buy / sell / swap ramp. You create a session on your server, mount the widget in the browser, and treat the signed webhook as the authoritative settlement signal. If you have not built that flow yet, start with the 0Gate quickstart.

Part 1 — Test in the sandbox

Environments at a glance

Local development can point baseUrl at http://localhost:4000/v1 if you run the backend yourself.

How a key chooses its environment

There is no separate "test mode" flag — the key prefix is the mode. A *_test_ key is test-mode; a *_live_ key is live-mode. The mode is baked into the session at create time (mode: "test" | "live" on the gate_session) and inherited by everything downstream: the embed token, the webhook event, and which test-helper routes will touch it. You cannot promote a test session to live or vice versa — you recreate it with the other key.

1. Get sandbox keys

Sign in to Partner Hub (or receive them from the team during private beta) and grab your test pair plus the test-mode webhook signing secret:

GATE_KEY=sk_test_XyZwQrStuvwxyz0987654321zyxwvuts   # server-only — creates sessions
VITE_GATE_PUBLISHABLE_KEY=pk_test_AbCdEfGh1234567890abcdefghijklmn  # browser-safe — widget bootstrap
WEBHOOK_SECRET=whsec_...                            # verifies inbound webhook signatures

Where each key may travel

Both are accepted in the canonical Authorization: Bearer <key> form (checked first), or via the explicit X-Secret-Key / X-Publishable-Key headers. The publishable key is the only one that may appear in a URL — the secret-key guard refuses query-string keys outright.

2. Create a session against the sandbox host

Call POST /v1/gate_sessions with your sk_test_ key. Bind amount, currency, and return_url server-side so the browser cannot tamper with them. The response includes a one-time client_secret (gsec_<sessionId>_<random>) that is safe to hand to your page.

curl -X POST https://gate-api-sandbox.0bit.app/v1/gate_sessions \
  -H "Authorization: Bearer $GATE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": "100.00",
    "currency": "EUR",
    "return_url": "https://yourapp.example/checkout/done"
  }'

import { GateClient } from '@0bit/gate';

const client = new GateClient({
  apiKey: process.env.GATE_KEY,                 // sk_test_...
  baseUrl: 'https://gate-api-sandbox.0bit.app',   // SDK origin; resource paths append /v1
});

const session = await client.sessions.create({
  amount: '100.00',
  currency: 'EUR',
  return_url: 'https://yourapp.example/checkout/done',
});

// Hand this to your front-end. Never send your sk_ key to the browser.
console.log(session.client_secret); // gsec_..._...

import os
from zerobit.gate import GateClient  # PyPI dist is "0bit-gate"

client = GateClient(
    api_key=os.environ["GATE_KEY"],                 # sk_test_...
    base_url="https://gate-api-sandbox.0bit.app",     # SDK origin; resource paths append /v1
)

session = client.sessions.create({
    "amount": "100.00",
    "currency": "EUR",
    "return_url": "https://yourapp.example/checkout/done",
})

print(session["client_secret"])  # gsec_..._...

You get back a gate_session:

{
  "id": "67a1f3b9e4b0c10001234567",
  "object": "gate_session",
  "client_secret": "gsec_67a1f3b9e4b0c10001234567_AbCdEfGhIjKlMnOpQrStUvWxYz012345",
  "amount": "100.00",
  "currency": "EUR",
  "status": "open",
  "expires_at": "2026-05-26T13:45:00Z"
}

Session create parameters

Only amount, currency, and return_url are required; the rest tune the flow. Set the ones you depend on server-side — the browser never sees them until bootstrap echoes them back.

Session statuses and lifetime

A gate_session has exactly four statuses: open (live, mountable), completed (the user paid — terminal), expired (passed expires_at without completing — terminal, fired lazily on the first read past expiry), and cancelled (terminal). There is no failed session status — failure is an intent-level concept that surfaces as a webhook, never as a session field. Sessions default to a 24-hour expires_at; cancelling an already-terminal session returns 409.

3. Mount the sandbox widget

Install the browser SDK and mount the widget, pointing it at the sandbox environment. The SDK performs the embed handshake for you: it calls POST /v1/embed/bootstrap with your pk_test_ key, receives a short-lived embed token, and renders the iframe from https://gate-sandbox.0bit.app.

npm install @0bit/gate/browser

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

const ramp = new GateRamp({
  publishableKey: import.meta.env.VITE_GATE_PUBLISHABLE_KEY, // pk_test_...
  clientSecret: 'gsec_..._...',  // from step 2, fetched from your server
  environment: 'sandbox',        // routes to gate-sandbox.0bit.app
});

await ramp.mount('#ramp', {
  onReady:   () => console.log('widget ready'),
  onSuccess: ({ sessionId }) => {
    // UX only — do NOT grant value here. Wait for the webhook.
    window.location.href = '/checkout/done';
  },
  onError: ({ code, message }) => console.warn(code, message),
  onClose: () => console.log('widget closed'),
});

Or drop it in with a CDN tag and no build step — the IIFE bundle exposes the global GateJS:

<div id="ramp"></div>
<script src="https://cdn.jsdelivr.net/npm/@0bit/gate/browser"></script>
<script>
  const ramp = new GateJS.GateRamp({
    publishableKey: 'pk_test_...',
    clientSecret: 'gsec_..._...',
    environment: 'sandbox',
  });
  ramp.mount('#ramp', {
    onSuccess: () => { window.location.href = '/checkout/done'; },
  });
</script>

What mount resolves to and how callbacks map

ramp.mount(target, callbacks) returns a Promise<void> that resolves on WIDGET_READY (15-second timeout, surfaced as a mount error). The widget speaks a typed postMessage protocol back to the host; the SDK translates each message into a callback:

The onSuccess payload is { txId, sessionId? } — there is no refid field on the browser callback. Treat all of these as UX signals; the webhook is the settlement record. Companion methods: ramp.unmount(), ramp.setTheme('light' | 'dark'), ramp.updateConfig({…}), and the static GateRamp.redirectToCheckout({ publishableKey, clientSecret, theme }) for hosted-redirect mode (where clientSecret is required).

Origin gating in the sandbox

bootstrap checks the request Origin (with Referer as a fallback) against your allowed_domains — exact match, no wildcards. While testing locally you must add the exact origin you load the page from (e.g. http://localhost:5173) or bootstrap returns 403. The one exception is hosted-redirect mode: when the page loads top-level on the widget origin itself, the allowlist is skipped — but a clientSecret is then required (anonymous hosted access is disabled).

4. Run a test purchase with the 4242 card

1. Open your page with the mounted widget.
2. Click through, pick a payment method, and enter the test card 4242 4242 4242 4242 with any future expiry and any CVC. Complete any 3DS prompt.
3. Watch your server logs — a gate_session.completed webhook should arrive within a few seconds.
4. The browser onSuccess fires at roughly the same time. Treat it as UX confirmation only; the webhook is what you act on.

Because nothing settles and KYC is skipped in sandbox, the flow completes quickly.

5. Drive terminal states with the test-helper routes

Instead of clicking the card flow, you can fast-forward a session straight to a terminal/intent state — ideal for exercising your webhook handler's branches in CI. These are the real backend routes under v1/test_helpers:

# Force a session to completed (sandbox only) — fires gate_session.completed
curl -X POST https://gate-api-sandbox.0bit.app/v1/test_helpers/sessions/<id>/complete \
  -H "Authorization: Bearer $GATE_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

# Mark the session's intent failed (sandbox only) — session STAYS open, NO webhook
curl -X POST https://gate-api-sandbox.0bit.app/v1/test_helpers/sessions/<id>/fail \
  -H "Authorization: Bearer $GATE_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "code": "provider_declined", "message": "Test-induced failure" }'

complete vs fail — they are not symmetric

This asymmetry mirrors real life: a successful intent settles the session, but a failed intent does not kill the session — the user can retry inside the iframe.

So complete is the way to test your fulfilment path end to end; fail is the way to assert that an intent failure on its own does not terminate the session or fire an event. If you want to test your gate_session.cancelled / gate_session.expired branches, use POST /v1/gate_sessions/{id}/cancel (cancel) or let the session pass expires_at (expiry).

Response shapes

complete returns the updated session:

{ "session": { "id": "…", "object": "gate_session", "status": "completed", "amount": "100.00", "currency": "EUR", "…": "…" } }

fail returns the still-open session plus the failed intent (note status: "open" on the session):

{
  "session": { "id": "…", "object": "gate_session", "status": "open", "…": "…" },
  "intent": {
    "id": "…",
    "tx_refid": "test_tx_…",
    "status": "failed",
    "failure_code": "provider_declined",
    "failure_message": "Test-induced failure"
  }
}

Both fields on the fail body are optional — omit the body entirely and the backend defaults to code: "provider_declined", message: "Test-induced failure". Pass a stable failure code (provider_declined, kyc_failed, insufficient_funds, user_cancelled, …) so your handler can branch on it.

6. Receive and verify webhooks locally

Webhooks are the source of truth — so test them locally before you ship. Your laptop is not reachable from the internet, so put a tunnel in front of your handler and register that public URL as your test-mode webhook_url.

Start a tunnel to your local port:

# ngrok
ngrok http 3000
# → forwards https://<random>.ngrok-free.app  →  http://localhost:3000

# or Cloudflare Tunnel
cloudflared tunnel --url http://localhost:3000

Register the resulting HTTPS URL (e.g. https://<random>.ngrok-free.app/webhooks/0bit) as your test webhook_url in Partner Hub (or via support during private beta). Then verify the signature on every inbound event.

The Gate-Signature scheme

The SDK helper (constructEvent / construct_event) does the parse, timestamp-tolerance check, and constant-time compare for you — you only hand it the raw body, the header value, and the secret. It throws WebhookSignatureError on any failure.

import express from 'express';
import { GateClient, WebhookSignatureError } from '@0bit/gate';

const app = express();
const client = new GateClient({
  apiKey: process.env.GATE_KEY,
  baseUrl: 'https://gate-api-sandbox.0bit.app',
});

app.post(
  '/webhooks/0bit',
  express.raw({ type: 'application/json' }), // RAW body required for verification
  (req, res) => {
    let event;
    try {
      event = client.webhooks.constructEvent(
        req.body,                          // raw Buffer/bytes
        req.headers['gate-signature'],     // Gate-Signature header value
        process.env.WEBHOOK_SECRET,
      );
    } catch (err) {
      if (err instanceof WebhookSignatureError) return res.status(400).end();
      throw err;
    }

    // Dedupe on event.id — delivery is at-least-once.
    switch (event.type) {
      case 'gate_session.completed':
        // authoritative settlement signal
        fulfillOrder(event.data.id, event.data.tx_refid);
        break;
      case 'gate_session.failed':
      case 'gate_session.cancelled':
      case 'gate_session.expired':
        releaseOrder(event.data.id);
        break;
    }
    res.status(200).end(); // return 2xx fast; queue heavy work async
  },
);

import os
from flask import Flask, request
from zerobit.gate import GateClient, WebhookSignatureError

app = Flask(__name__)
client = GateClient(
    api_key=os.environ["GATE_KEY"],
    base_url="https://gate-api-sandbox.0bit.app",
)

@app.route("/webhooks/0bit", methods=["POST"])
def obit_webhook():
    try:
        event = client.webhooks.construct_event(
            payload=request.get_data(),                     # RAW bytes — not request.json
            sig_header=request.headers.get("Gate-Signature", ""),
            secret=os.environ["WEBHOOK_SECRET"],
        )
    except WebhookSignatureError:
        return "", 400

    # Dedupe on event["id"] — delivery is at-least-once.
    if event["type"] == "gate_session.completed":
        fulfill_order(event["data"]["id"], event["data"]["tx_refid"])  # authoritative
    elif event["type"] in ("gate_session.failed",
                            "gate_session.cancelled",
                            "gate_session.expired"):
        release_order(event["data"]["id"])
    return "", 200

Trigger an event with the 4242 card flow or a complete helper call, and confirm your handler verifies and 2xx-es. If verification fails, check that you captured the raw body and that you are loading the test-mode whsec_. Because the fail helper emits no webhook, drive completed/cancelled/expired to exercise the rest of your branches.

Lifecycle events

The platform also emits gate_session.kyc_package_accepted, kyc.required, partner.quota.warning, and partner.quota.exhausted. The OpenAPI spec documents only created/completed/expired/cancelled/kyc_package_accepted — the failed, kyc.required, and partner.quota.* events are emitted by the backend beyond the spec, so handle the ones you depend on and ignore the rest rather than asserting an exhaustive list.

Part 2 — Go live

Promotion is a credentials-and-host swap — no flow changes. Work the checklist top to bottom.

Swap credentials and hosts

Production environment

GATE_KEY=sk_live_...                  # server-only
VITE_GATE_PUBLISHABLE_KEY=pk_live_... # browser-safe
WEBHOOK_SECRET=whsec_...              # the LIVE webhook secret

import { GateClient } from '@0bit/gate';

const client = new GateClient({
  apiKey: process.env.GATE_KEY,            // sk_live_...
  baseUrl: 'https://gate-api.0bit.app',      // production SDK origin
});

const ramp = new GateRamp({
  publishableKey: import.meta.env.VITE_GATE_PUBLISHABLE_KEY, // pk_live_...
  clientSecret,
  environment: 'production',  // serves the iframe from gate.0bit.app
});

Register and verify the production webhook

Pin allowed_domains exactly

POST /v1/embed/bootstrap matches the browser's Origin (falling back to Referer) against allowed_domains with exact string equality — no wildcards, no subdomain matching. Add every production origin you embed from (apex and www, plus any preview/marketing hosts). A missing origin returns 403 at bootstrap and the widget never renders. Note that a quota-exhausted partner is the one case that returns 200 with available: false instead — wire onUnavailable to show a neutral state rather than treating that as an error.

Confirm signatures against the live secret

Live and test webhook secrets are independent. After registering the live webhook_url, switch your verifier to the live whsec_, send one real (small) event, and confirm the handler verifies and returns 2xx. 100% signature failures immediately after go-live almost always means the verifier is still loaded with the test secret — or is reading x-0bit-signature instead of Gate-Signature.

Idempotency and the settlement contract

Two layers of idempotency keep you safe under at-least-once delivery and client retries:

• Inbound — dedupe handler work on event.id (mirrored in X-0bit-Event-Id). Replays and retries carry the same id; a unique constraint on it makes double-fulfilment impossible.
• Outbound — the SDKs auto-attach an Idempotency-Key (UUID v4) on every write, so a retried sessions.create returns the original session instead of creating a duplicate. Keep that behaviour; do not strip the header.

Monitor in production

Watch these signals from day one:

• Delivery success rate and dead-lettered webhooks (5 failed attempts → dead-letter; replay from the portal once the endpoint is healthy).
• Signature-failure rate — a spike means a wrong/rotated secret or a body-parsing regression (re-serializing JSON before verification).
• partner.quota.warning / partner.quota.exhausted — exhaustion flips bootstrap to available: false, so the widget goes unavailable for end users; alert before you hit it.

Pre-launch verification

A short list catches most launch-day incidents:

• A live sk_live_ session creates successfully against https://gate-api.0bit.app/v1.
• The widget loads from https://gate.0bit.app on each production origin (no 403 — origin is in allowed_domains).
• A real (small) purchase delivers a signed gate_session.completed to your live endpoint and your handler verifies it and returns 2xx.
• Replaying the same webhook does not double-fulfill (idempotency works).
• sk_live_ appears nowhere in your client bundle (audit SSR boundaries and any /api/config endpoint).

Next steps