Sandbox is a separate Paddle environment for building and testing your integration without affecting real data or accepting real payments.
Create a sandbox account in addition to your live account, then point your integration at sandbox during development and staging.
Types of Paddle accounts
Paddle has two types of account:
- Sandbox accounts for building and testing integrations.
- Live accounts for accepting real payments.
Sandbox and live accounts have the same features and APIs but completely separate datasets, credentials, and dashboards. API keys, client-side tokens, notification destinations, products, prices, and customers aren't shared between environments.
We recommend using sandbox whenever you want to test without impacting real data or accepting real payments, including in local development and staging. Use environment variables to switch between sandbox and live.
Create a sandbox account
Sandbox accounts are separate from live accounts. You need to create a sandbox account even if you already have a live account.
- Go to the sandbox signup page.
- Enter your personal and business details.
- Click Continue to create your account.
Authenticate with sandbox
Sandbox and live accounts use different credentials. Generate them in each account separately.
| Credential | Sandbox identifier |
|---|---|
| API key | Contains _sdbx. |
| Client-side token | Prefixed with test_. |
Using a sandbox credential against the live API (or vice versa) returns a forbidden error.
For SDK-specific setup, including how to select the sandbox environment in code, see the relevant library page. For Paddle.js, see include and initialize Paddle.js.
API base URLs
| Environment | Base URL |
|---|---|
| Live | https://api.paddle.com |
| Sandbox | https://sandbox-api.paddle.com |
Go live
When you've tested your integration, work through the go-live checklist to move to a live account. You'll swap credentials, recreate catalog and notification data in your live account, and switch base URLs.
Differences between sandbox and live
Core functionality is the same in both environments. A handful of differences make sandbox safer and faster to work against.
| Area | Sandbox | Live |
|---|---|---|
| Website approval | No approval required. | Approval required. |
| Default payment link | Any domain, no verification. | Verified, approved domain. |
| Card payments | Test cards only, no real money. | Real cards, real money. |
| Checkout appearance | 'Test Mode' watermark. | No watermark. |
| Hosted checkouts | No approval required. | Approval required. |
| Adjustment approvals | Refunds auto-approved every 10 minutes. | Paddle approval needed for most refunds. |
| Webhook retries | 3 retries in 15 minutes. | 60 retries in 3 days. |
| Email delivery | Sent to your account's domain; others forwarded to your main email. | Sent to the customer's email or the email provided. |
| Paddle Retain | Not available. May be simulated. | Available. |
Test cards
Sandbox accounts reject real card numbers. Use these test cards to complete checkouts:
| Card type | Card number |
|---|---|
| Valid Visa debit card | 4000 0566 5566 5556 |
| Valid card without 3DS | 4242 4242 4242 4242 |
| Valid card with 3DS | 4000 0038 0000 0446 |
| Declined card | 4000 0000 0000 0002 |
| Initial success, subsequent decline | 4000 0027 6000 3184 |
Enter any cardholder name and a valid expiry date in the future.
Test cards don't work in live accounts, and live cards don't work in sandbox.
Email delivery in sandbox
Paddle sends emails to customers when they make a purchase and when subscription lifecycle events occur, like subscription renewals or cancellations. These emails are required for compliance reasons.
Sandbox emails are only sent to email addresses that match your account's registered domain. Emails to other addresses are forwarded to the main address on your account.
For example, if your account's registered email is team@aeroedit.com:
| Sent to | Reason | |
|---|---|---|
team@aeroedit.com | team@aeroedit.com | Matches your main address. |
sam@aeroedit.com | sam@aeroedit.com | Same domain as your main address. |
jo@example.com | team@aeroedit.com | Forwarded because the domain doesn't match. |
Free email addresses like gmail.com or hotmail.com always forward to your main address, regardless of the local part.
Webhook retries
Sandbox retries failed webhook deliveries 3 times within 15 minutes. Live retries 60 times within 3 days. Make sure your notification endpoint returns a 2xx response within 5 seconds, see Respond to webhooks.
Adjustments and refunds
Sandbox auto-approves refund adjustments every 10 minutes so you can test the full flow end to end. In live accounts, most refunds require Paddle approval.
Paddle Retain
Retain only works with live accounts. You can't set up Retain on a sandbox account, but you can simulate its frontend interventions to test cancellation flows, payment recovery, and term optimization.