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.

What’s the difference between sandbox and live environments?

Functionally, your Paddle sandbox is very 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 payout) 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 production environment, Paddle Checkouts can only be loaded on approved domains which need to be requested for manual approval via the Paddle Dashboard.

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

Launching the Paddle checkout

Irrespective of 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:

<script src="https://cdn.paddle.com/paddle/paddle.js"></script>
<script type="text/javascript">
  Paddle.Environment.set("sandbox");
  Paddle.Setup({ vendor: 1234567 });
</script>

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

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

<script src="https://cdn.paddle.com/paddle/paddle.js"></script>
<script type="text/javascript">
  Paddle.Setup({ vendor: 1234567 });
</script>

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 and any random CVC number.

Card Type	Card Number
Valid card without 3DS	4242 4242 4242 4242
Valid card with 3DS	4000 0038 0000 0446
Declined card	4000 0000 0000 0002

Testing PayPal

To make test transactions using PayPal, you need a PayPal sandbox account. You can then enter your PayPal sandbox credentials into the Paddle checkout to complete test transactions.

Sandbox API calls

To make API calls to your sandbox environment, you must add the sandbox- prefix in the URL hostname. For example:

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

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

Moving from sandbox to live

Having already noted that Paddle sandbox and live environments are entirely separate, it follows that some steps must be completed when you’ve finished testing in the sandbox and are ready to start selling in your live environment. These are summarized below:

#	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 whitelisting	If you are using webhooks to receive events from Paddle, ensure that Paddle’s production (live) IP addresses are whitelisted.	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 whitelisted. For further information, see our Webhook security guide.