Use sandbox accounts

You can build and test your integration without creating and affecting real data, including accepting real payments and money. Use a sandbox account to help you locally develop, stage changes, and identify bugs or errors before going live to ensure your integration works as expected.

How it works

Paddle has two types of accounts:

• Sandbox accounts

  Use sandbox accounts to build and test your integration without affecting real data.

• Live accounts

  Use live accounts to accept real payments and money.

Sandbox and live accounts have the same features, but totally separate datasets. This means sandbox accounts provide a risk-free environment where you can accurately experiment, build, and test your integration without affecting real customer data or processing actual transactions.

We strongly recommend using a sandbox account when building your initial integration or new workflows. By first implementing and testing in sandbox, you ensure a smoother transition when launching your integration and avoid issues that could impact your business and customers.

Differences between accounts

Core functionality is the same between live and sandbox accounts. However, there are a few differences to be aware of which make sandbox accounts useful for development and testing.

Summary

Breakdown

Set up a sandbox account

As sandbox accounts are totally separate from live accounts, you need to create a new sandbox account even if you already have a live account.

Integrate with sandbox accounts

You can use the same implementation and core code for both sandbox and live accounts. However, you need to provide different variables for each environment.

Make sure to integrate using sandbox in all places where you don't want to use real data or accept real payments, like in your local and staging environments. We advise using environment variables to switch between sandbox and live.

Backend

You may want to integrate with the Paddle API to create and manage your products, customers, transactions, and subscriptions.

Authentication

Both sandbox and live accounts require authentication credentials when making calls to the Paddle API. Backend authorization uses API keys.

Sandbox and live accounts use different API keys which are created in their own accounts. Cross-environment API keys don't exist. Sandbox API keys created after May 6, 2025 contain _sdbx so you can identify them easily.

1
1pdl_sdbx_apikey_01jt3bpm61fltrr8ammc13579t_4d3M3f7Lx2kzgPqrBwnXhP_A4c

Base URLs

The Paddle API has different base URLs for sandbox and live accounts.

1
1https://api.paddle.com

1
1https://sandbox-api.paddle.com

Environment

If you're integrating using SDKs, you need to tell the SDK which environment to use. By default, Paddle.js uses the live environment. The method for setting the environment to sandbox varies across SDKs.

1
2
3
4
5
1import { Paddle, Environment } from '@paddle/paddle-sdk-node';
2
3const paddle = new Paddle('PADDLE_API_KEY', {
4  environment: Environment.sandbox // or Environment.production for accessing live API
5})

Using a sandbox API key for requests to the live API, or vice versa, results in a forbidden error (403). Check your API key, the base URL used for requests, or the environment set for the SDK.

Frontend

You may want to integrate with Paddle.js to create checkouts and manage your customers.

Authentication

Both sandbox and live accounts require authentication credentials when initializing Paddle.js in your frontend. Frontend authorization uses client-side tokens.

Sandbox and live accounts use different client-side tokens which are created in their own accounts. Cross-environment client-side tokens don't exist. Sandbox client-side tokens are prefixed with test_.

1
1test_757933v746814124c804c21l55n

Environment

Before you initialize Paddle.js, you need to say which environment to use. By default, Paddle.js uses the live environment.

1
2
3
4
5
1Paddle.Environment.set("sandbox");
2Paddle.Initialize({
3  token: 'test_757933v746814124c804c21l55n',
4  pwCustomer: { }
5});

Migrate from sandbox to live

When you've built and tested your integration with a sandbox account, you need to move to a live account to start accepting real payments.

This involves creating a live account, switching to using live authentication credentials in your integration, and recreating some data from your sandbox account in your live account.

Use our go-live checklist to guide you through the steps needed to move from sandbox to live.

Related pages