Working with 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.

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.

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

Use the link below to access your Paddle sandbox dashboard:

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

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:

Live environment

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

Card TypeCard NumberCVC
Valid Visa debit card4000 0566 5566 5556100
Valid card without 3DS4242 4242 4242 4242100
Valid card with 3DS4000 0038 0000 0446100
Declined card4000 0000 0000 0002100
Successful initial transaction, subsequent declined transactions4000 0027 6000 3184100

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.

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

The Paddle sandbox and live environments are separate. When you're ready to start selling, make some changes to your integration to start using the live environment:

1API endpointsRemove the sandbox- prefix from API endpoints.URLs for all sandbox API endpoints include a sandbox- prefix - this must be removed for your live environment.
2API auth keyUpdate 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.
3Vendor IDUpdate 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.
4Frontend JavaScriptRemove the sandbox environment setting from frontend JavaScript codeWhen 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.
5Product & subscription plan IDsUpdate 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.
6Domain approvalEnsure 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.
7Webhook alert IP allowlistingIf 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.