SettleSettleSettleSettle Dev Hub
Console →
Guides

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_...
  3. 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:

text
⚠️ [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.
← PREVIOUSGlobal Payments & CurrenciesNEXT →Automated Settlement & Payouts