Paddle Billing Sandbox Guide
Learn how to simulate payments, configure sandbox webhooks, and utilize test credit cards.
Paddle Sandbox Overview
Paddle Sandbox is a fully-featured, separate environment that replicates production. You can register for a sandbox account at sandbox-login.paddle.com .
Important Check: Make sure your `.env` contains `PADDLE_ENVIRONMENT=sandbox` during testing, and you are using API keys starting with `paddlesandbox_`. Do not mix production secrets with sandbox configs.
Test Credit Card Numbers
Use the following card credentials inside the Paddle checkout overlay to simulate successful transactions:
| Brand | Card Number | Expiry Date | CVV | Test Country |
|---|---|---|---|---|
| Visa | 4000 0020 0000 0000 | Any future date | Any 3 digits | United States (US) |
| Mastercard | 5105 1051 0510 5100 | Any future date | Any 3 digits | United Kingdom (GB) |
| American Express | 3700 0000 0000 002 | Any future date | Any 4 digits | United States (US) |
| Diners Club | 3000 0000 0000 02 | Any future date | Any 3 digits | United States (US) |
| JCB | 3528 0000 0000 0002 | Any future date | Any 3 digits | Japan (JP) |
Configuring Webhooks
To synchronize transactions and subscription statuses (such as cancellations, upgrades, or updates) with your local database, you must route Paddle webhook events to this platform:
- Go to your **Paddle Sandbox Dashboard** → **Developer** → **Webhooks**.
- Click **Add endpoint** and input your public server address:
https://your-domain.com/api/webhooks/paddle - Select the following event subscriptions:
- subscription.created
- subscription.updated
- transaction.completed
- Copy the generated **Webhook Secret Key** and set it in your local environment file as `PADDLE_WEBHOOK_SECRET`.