Working with the Paddle sandbox

What is the Paddle sandbox?

The Paddle sandbox is a test environment where you can experiment with your integration without affecting your live environment - the two are completely separate.

Any setup completed in your sandbox (for example, creating subscription plans, customizing the checkout, etc.) must be replicated in your live environment when you decide that you're ready to start selling via Paddle.

What's the difference between sandbox and live environments?

Functionally, your Paddle sandbox is similar to your live environment, with a few key differences:

Test payment details must be used - actual payments cannot be processed, which means buyers cannot be charged (and Paddle does not pay out) from sandbox accounts.
To test PayPal, you will need a PayPal sandbox account.
To launch the Paddle checkout, you must specify the sandbox environment in the setup method on your frontend JavaScript code.
API calls require a sandbox prefix.
Direct Checkout links only work without approval in the sandbox environment. In the live environment, Paddle Checkouts can only be loaded on approved domains which need to be requested for manual approval via the Paddle Dashboard.
Checkout recovery emails aren't sent on the sandbox environment. This helps to protect our email sending reputation to make sure that legitmate checkout recovery emails don't go to spam.

How do I get a Paddle sandbox?

To create a Paddle sandbox see: Create a Paddle sandbox account.

How do I access my Paddle sandbox dashboard?

Use the link below to access your Paddle sandbox dashboard:
https://sandbox-vendors.paddle.com

The link for your live dashboard is:
https://vendors.paddle.com

Launching the Paddle checkout

Whether you're working in your sandbox or live environment, you must import the Paddle JS library into your frontend as part of connecting a Paddle checkout.

To do this in the sandbox, add the following code immediately before the closing </body> tag in the web page that you are using for testing:

Paddle sandbox
preparing...

Notice the Paddle.Environment.set('sandbox'); setting here - this is vital for launching the Paddle checkout in the sandbox environment.

If you don't specify the sandbox environment here, the Paddle checkout will not launch.

For your live environment, the Paddle.Environment.set('sandbox'); setting is not specified:

Live environment
preparing...

For instructions, see our Getting Started task: Import the Paddle JS Library.

Test payment cards

Actual payment card information cannot be used in the sandbox. Instead, use the test cards below. Enter a valid expiry date in the future.

We recommend you test with the 4000 0566 5566 5556 test card currently.

Card Type	Card Number	CVC
Valid Visa debit card	`4000 0566 5566 5556`	`100`
Valid card without 3DS	`4242 4242 4242 4242`	`100`
Valid card with 3DS	`4000 0038 0000 0446`	`100`
Declined card	`4000 0000 0000 0002`	`100`
Successful initial transaction, subsequent declined transactions	`4000 0027 6000 3184`	`100`

The billing country for each of these cards is set to U.S.

#	Item	Task	Notes
1	API endpoints	Remove the `sandbox-` prefix from API endpoints.	URLs for all sandbox API endpoints include a `sandbox-` prefix - this must be removed for your live environment.
2	API auth key	Update the API Auth Key wherever it is used.	You have one API Auth Key for your sandbox and another for live. To find your API Auth Key for each environment, log into your sandbox and live dashboards in turn, and navigate to Developer Tools > Authentication.
3	Vendor ID	Update the Vendor ID wherever it is used.	You have one Vendor ID for your sandbox and another for your live environment. The Vendor ID is required for API Authentication and also when importing the Paddle JS Library in your frontend code - so you may need to change it in more than one place. To find your Vendor ID for each environment, log into your sandbox and live dashboards, and navigate to Developer Tools > Authentication. For further information, see: Import the Paddle JS library.
4	Frontend JavaScript	Remove the sandbox environment setting from frontend JavaScript code	When testing the Paddle checkout in your sandbox environment, the `Paddle.Environment.set('sandbox')` setting is defined in your frontend JavaScript code. When switching to live, it must removed. For further information, see: Import the Paddle JS library.
5	Product & subscription plan IDs	Update Product/Plan IDs.	Any products and subscription plans created in your sandbox must be recreated in your live environment, which means you will have different product/plan IDs to associate with 'buy product' options on your live web page. For further information, see: Add a Paddle button.
6	Domain approval	Ensure that the domain for the website you will be using to sell products via Paddle is approved.	You can complete testing in your sandbox straight away; however you can't start selling products until your website is approved. For further information, see our: What is domain approval? FAQ.
7	Webhook alert IP allowlisting	If you are using webhooks to receive events from Paddle, ensure that Paddle's production (live) IP addresses are allowlisted.	Paddle sends webhook alerts from different IP addresses for sandbox and live environments. For your integration to receive Paddle’s webhook alerts, ensure that Paddle's IP addresses are allowlisted. For further information, see our Webhook security guide.