Sandbox Environment

Overview

The Inflow sandbox is a fully isolated test environment designed to mirror production as closely as possible. Use it to build, validate, and iterate on your integration without ever processing real transactions or moving real money.

The sandbox shares the same API surface, event model, and webhook delivery system as production. Every feature you test in sandbox behaves identically in production — there are no behavioral differences, no stub endpoints, and no simplified responses. Once your integration works in sandbox, it works in production.

📘

Note

The sandbox is intended for integration testing only. It is not suitable for load testing or performance benchmarking. See Limitations for details.

Requesting Sandbox Access

Sandbox accounts are not created self-serve. To get access, contact the Inflow technical team and request a sandbox account for your organization.

How it works:

1. Reach out to the Inflow team and request sandbox access.
2. The Inflow team creates a sandbox merchant account and sends you an invitation email.
3. Follow the link in the email to activate your sandbox account and set a password.
4. Log in to the sandbox dashboard using the URL provided in your invitation.

📘

Note

The sandbox dashboard is accessible at a different URL than production. This URL is included in your invitation email. Bookmark it separately to avoid confusion.

Key generation in sandbox follows the exact same steps as in production — there is no separate process.

Sandbox vs Production

⚠️

Warning

Sandbox and production environments are fully isolated. API keys, customers, payments, subscriptions, and webhook configurations created in one environment are never visible in the other. Always verify which environment you are targeting before making API calls.

API Endpoints

Use the correct base URL for each environment. Mixing environments (e.g., using a sandbox key with a production URL) will result in a 401 Unauthorized error.

REST API

Dashboard

Checkout

Example sandbox checkout URL:

https://sandbox.checkout.inflowpay.com/subscribe/sub_offer_xxx

📘

Note

The {offerId} in a subscription checkout URL (e.g., sub_offer_xxx) is generated when you create an offer in the sandbox dashboard or via the API. It is unique to each environment — sandbox offer IDs are not valid in production.

SDK

If you use @inflow_pay/sdk to collect card payments, you must be on version 1.2.0 or later to target the sandbox. Starting with 1.2.0, the SDK automatically routes to https://sandbox.api.inflowpay.xyz when the public key passed to InflowPayProvider contains _sandbox_ (e.g. inflow_pub_sandbox_...). Older versions will fail with 401 Unauthorized when given a sandbox key.

npm install @inflow_pay/sdk@^1.2.0

API Keys

Each environment has its own set of API keys. Sandbox keys are generated from the sandbox dashboard and are completely independent from your production keys.

Key Types

How to Generate Sandbox Keys

1. Log in to your sandbox dashboard.
2. Go to the Developers panel.
3. Generate your sandbox private and public API keys.
4. Copy the keys and store the private key securely.

⚠️

Warning

Never use sandbox keys in a production environment, and never use production keys in sandbox. Beyond being a security risk, mismatched keys will cause 401 errors and pollute your live data. Store each environment's keys in separate environment variables (e.g., INFLOW_API_KEY_SANDBOX vs INFLOW_API_KEY_PROD).

Security Best Practices for Keys

• Store all keys — sandbox and production — in environment variables, never hardcoded in source files.
• Do not commit keys to version control, even sandbox keys.
• Grant access to sandbox keys only to team members who need them for development.
• Rotate keys immediately if they are accidentally exposed.

No Real Charges

In the sandbox environment, no payment is ever processed and no money is ever moved. All transaction flows — authorizations, captures, refunds, failures — are fully simulated.

This means you can:

• Trigger successful payments, declines, and partial refunds freely.
• Create and cancel subscriptions without financial consequence.
• Simulate every payment status (authorized, settled, failed, refunded) to test your error handling and UI states.
• Run your entire QA suite against real API responses without any billing risk.

📘

Note

Even though no money moves, the sandbox API returns realistic payment objects with real-looking IDs, amounts, and timestamps. Your integration code does not need to behave differently in sandbox — it can treat sandbox responses as structurally identical to production responses.

Webhook Behavior

Webhooks in sandbox are fully operational and behave identically to production.

Register a dedicated sandbox webhook endpoint for your local or staging server. Tools such as ngrok or Hookdeck are useful for exposing a local development server to receive webhook deliveries during testing.

Registering a sandbox webhook:

curl -X POST https://sandbox.api.inflowpay.xyz/api/webhook \
  -H "X-Inflow-Api-Key: inflow_priv_your_sandbox_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-staging-server.example.com/webhooks/inflow"
  }'

⚠️

Warning

Always verify webhook signatures, even in sandbox. Skipping signature verification in your test environment is a common source of bugs that only surface in production. Test your verification logic early.

For full webhook setup instructions, refer to Setting Up Webhooks.

Limitations

The sandbox is a full-fidelity environment for integration testing, but it has the following known constraints:

⚠️

Warning

Do not run load tests against the sandbox. Sustained high-volume traffic will exhaust your rate limit quota and may result in temporary API access suspension for your sandbox account. If you need to validate performance characteristics, contact the Inflow team.

Best Practices

Follow these guidelines to get the most out of your sandbox testing:

• Mirror your production setup exactly. Use the same API call sequences, the same webhook registration flow, and the same error handling logic. The sandbox is only useful if it represents your real integration.
• Test all payment outcomes. Validate your UI and backend logic for every status: successful payment, card decline, insufficient funds, 3DS authentication required, and refund. Do not only test the happy path.
• Test webhook failure and retry. Temporarily return a non-2xx status from your endpoint to confirm your system handles delayed webhook delivery correctly.
• Verify webhook signatures. Ensure your signature verification code works end-to-end in sandbox before going live.
• Use realistic test data. Use accurate email formats, realistic amounts, and valid currency codes. Garbage inputs may return validation errors that mask real integration issues.
• Automate your test suite. Write automated integration tests that run against sandbox. This gives you fast feedback when you change your integration code.
• Keep sandbox and production credentials separate. Use distinct environment variable names (e.g., INFLOW_API_KEY for production, INFLOW_API_KEY_SANDBOX for sandbox) and never mix them.
• Clean up after tests. Cancel test subscriptions and webhooks you no longer need to keep your sandbox account tidy.