Set up your environment

tiun runs two fully independent environments in parallel: live (real customers, real payments) and sandbox (simulated payments, separate catalog and credentials). They are not two modes of the same data — each has its own domain, snippet ID, products, product IDs, and API keys.

Most teams set up sandbox first while building, test the integration there, then set up live separately and swap environment-specific values when they ship. You can configure either environment first; both can be active at the same time.

For the full picture, see Sandbox in Reference.

---

Set up live

Live is set up through the Get Started modal in the dashboard. Open the dashboard (with the Sandbox toggle off) and you'll be prompted to:

1. Pick a platform — Web app or Native app. This tells tiun how to deliver the SDK and what kind of integration you're building.

2. Enter a primary domain — the domain where your production app is hosted (for example yoursite.com). tiun authorizes this domain for secure CORS access so the SDK can talk to the API from your origin. You can add more domains later.

Once that's done, create your live products in Products. Copy your live snippet ID and p-live-... product IDs from this dashboard view — they only work with live traffic.

localhost is blocked in live. Use live only from your registered production domains.

In your production app, initialize the SDK without sandbox (or with sandbox: false) and use those live IDs:

import { tiun } from '@tiun/sdk';

tiun.init({
  snippetId: 'YOUR_LIVE_SNIPPET_ID',
  language: 'en',
});

---

Set up sandbox

Sandbox is a parallel copy of your tiun setup. Configure it in the dashboard, then point your dev or staging app at it with sandbox: true.

Configure sandbox in the dashboard

In the dashboard, turn on the Sandbox toggle in the sidebar. The entire view switches to sandbox data — products, customers, snippet ID, and API keys are all separate from live.

The first time you open sandbox, enter a test domain for that environment. Prefer your test/staging domain (for example staging.yoursite.com); if you do not have one yet, use your live domain as a fallback. You do not need to add localhost explicitly — it is enabled by default in sandbox. You can add more domains later from the same settings area.

Create your sandbox products here (mirroring what you plan to sell in live). Copy your sandbox snippet ID and p-test-... product IDs from this view.

Point your app at sandbox

In the app you use for development or staging, pass sandbox: true and your sandbox snippet ID:

import { tiun } from '@tiun/sdk';

tiun.init({
  snippetId: 'YOUR_SANDBOX_SNIPPET_ID',
  language: 'en',
  sandbox: true,
});

In sandbox, localhost is enabled by default on any port. To test locally, run with sandbox: true and your sandbox snippet ID.

While you're building, keep the dashboard and your app on the same environment. If the dashboard shows live but your SDK has sandbox: true (or the other way around), IDs and sessions won't match what you see in the UI.

If you verify purchases or sessions on your server during development, use the sandbox API base URL and a sandbox API key. Live and sandbox keys are not shared.

---

Going live from sandbox

When your sandbox integration works and you're ready for production traffic:

1. Set up live in the dashboard (if you haven't already) — production domain, products, snippet ID, and API keys.

2. In your production deployment, remove sandbox: true from tiun.init (or set it to false).

3. Replace environment-specific values with their live counterparts:

   • Snippet ID

   • Product IDs (p-test-... → p-live-...)

   • Server-side API base URL and API key (if applicable)

The SDK API is identical across environments — only these IDs and credentials change. Your sandbox environment stays available for continued testing in parallel.