Sandbox vs Production Mode

Testing and staging are critical for building reliable billing flows. SettleSettle operates a strict sandbox mechanism designed to isolate test simulations from production financials.

Key Prefix Identification

Your active SettleSettle state is determined strictly by the prefix of the API Key you supply:

• Sandbox Test Mode: Key prefix starts with **ss_test_**. All transactions, checkouts, and micro-debits are simulated. No real currency is charged.
• Production Live Mode: Key prefix starts with **ss_live_**. Real-world payment gateways are initialized, real bank accounts are credited, and transactions represent binding value.

Simulated Sandbox Checkout

When initializing checkouts with a Sandbox credential, the payment engine bypasses third-party provider gateways completely:

1. Records a local reference starting with **ss_sandbox_...**.
2. Dynamically generates a secure local sandbox checkout redirect URL:

http://localhost:3000/v1/payments/sandbox-checkout?reference=ss_sandbox_...

1. Allows developers to simulate success and failure callback hooks without entering real credit card details, facilitating rapid local prototyping.

SDK Sandbox Mismatch Warning

To protect your business from accidentally deploying test configurations to live users, the official SettleSettle SDK automatically runs background checks on startup.

If you load a sandbox test key (ss_test_...) while your host server is running in a production environment (process.env.NODE_ENV === 'production'), the SDK will print a warning to the console:

⚠️ [SettleSettle SDK Warning]: Utilizing sandbox test key (ss_test_...) in production environment. Sandbox transactions will not charge real money.

Go-Live Eligibility Checklist

Before SettleSettle will activate production live modes and provision your real ss_live_ API key, your application must fulfill 4 platform-level checks. You can audit these anytime from your App Details page:

1. App Description: Ensure your app description is defined (between 10 and 500 characters) to describe your service to gateways.
2. Business Category: Assign an active market sector (e.g. AI, SaaS, Finance) under your settings panel.
3. Active Webhook: Configure at least one operational Webhook URL to securely capture live transaction alerts.
4. Bank Account linked: Connect a valid bank account or Solana wallet address to enable dynamic payment splits.