Test a Paddle integration end-to-end using the sandbox environment, test cards, the webhook simulator, and local tunnels — without taking real money.
82%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
The canonical home for this skill is paddle-sandbox-testing in PaddleHQ/paddle-agent-skills
Use this skill when verifying a Paddle integration before going live — running real-looking checkouts, triggering webhook events, and exercising subscription state changes without taking real money. Covers sandbox configuration, test card numbers, the webhook simulator (single events and scenarios), local development with public tunnels, and the differences between sandbox and live behavior that bite people in production.
This skill is the safety net for everything else. Apply it alongside checkout-web, webhooks, and subscription-sync whenever you ship — sandbox testing is the cheapest way to catch integration bugs.
Paddle gives you two completely separate environments:
| Sandbox | Production | |
|---|---|---|
| Purpose | Development and testing | Real customers, real money |
| API base | sandbox-api.paddle.com | api.paddle.com |
| Dashboard | sandbox-vendors.paddle.com | vendors.paddle.com |
| API keys | Separate set | Separate set |
| Client tokens | Separate set | Separate set |
| Notification destinations | Separate set | Separate set |
| Checkout and account settings | Separate set | Separate set |
| Products / prices / customers | Separate (none synced) | — |
| Cards accepted | Test cards only (real cards rejected) | Real cards |
| Refunds | Approved automatically (~10 minutes) | Most reviewed by Paddle |
| Tax | Calculated but not collected | Real tax handling |
| Domain approval | No approval required (any domain) | Manual approval per domain |
Nothing crosses between them. A sandbox pri_01h... does not exist in production. Notification destinations are separate. Customers are separate. This is intentional — it makes "test in sandbox, then promote to live" the safe default.
Sign up for the sandbox at sandbox-login.paddle.com/signup (separate signup from production). Then:
catalog-setup if you haven't done this yet.Paddle.js.notification_simulation.write and notification_simulation.read (simulator), notification.read and notification.write (notification logs and replays), client_token.write if you create client-side tokens by API, and checkout_settings.write to check and set the default payment link. To use the Paddle CLI with this key, ask the user to log it in to sandbox themselves: paddle login --environment sandbox --api-key ….client.settings.checkoutUrl.get() (GET /settings/checkout-url) on paddle-sandbox; a null default_url means it isn't set. Use a page on the user's own domain, not localhost. Sandbox doesn't need an approved domain. If the update returns checkout_url_domain_not_approved, add the domain under Paddle > My account > Settings > Website approval, where sandbox approves it straight away, and try again. Ask the user for the URL before setting it with client.settings.checkoutUrl.update({ default_url: "https://example.com/checkout" }). With the Paddle CLI, use paddle --environment sandbox settings checkout-url get and … settings checkout-url update --json '{"default_url": "…"}'. Or have them set it under Paddle > Checkout > Checkout configuration.# .env.local — sandbox values
NEXT_PUBLIC_PADDLE_ENV=sandbox
NEXT_PUBLIC_PADDLE_CLIENT_TOKEN=test_...
PADDLE_API_KEY=pdl_sdbx_apikey_...
PADDLE_NOTIFICATION_WEBHOOK_SECRET=pdl_ntfset_...The PADDLE_API_KEY for sandbox is prefixed pdl_sdbx_apikey_ — production keys are prefixed pdl_live_apikey_. Glance at the prefix anytime you're not sure which environment you're hitting.
In sandbox, only test cards work. Real cards are rejected. The standard test card:
Card number: 4242 4242 4242 4242
Expiry: any future month/year
CVC: any 3 digits
ZIP/Postal: any value
Name: any valueOther test cards trigger specific scenarios:
| Card number | Result |
|---|---|
4242 4242 4242 4242 | Valid card without 3DS |
4000 0038 0000 0446 | Valid card with 3DS |
4000 0566 5566 5556 | Valid Visa debit card |
4000 0000 0000 0002 | Declined card |
4000 0027 6000 3184 | Initial success, subsequent renewals decline (dunning) |
Full list at developer.paddle.com/sdks/sandbox#test-cards. Use the failure cards to confirm your checkout.payment.failed handling (it fires on each failed payment attempt), dunning flow, and subscription.past_due handling work end-to-end. checkout.payment.error is different: it means no payment methods are available.
The simulator sends fake-but-correctly-signed webhook events to one of your notification destinations without going through a real flow. Simulated events don't change any real data in your account. Two modes:
Single event. Pick one event type (e.g. subscription.canceled) — the simulation type is the event name. Edit the JSON payload or let Paddle fill in a demo example, then run it. Paddle signs it with the destination's secret and POSTs it to the destination's URL. Use this to test specific handlers in isolation — e.g. "what does my UI do when subscription.paused arrives?"
Scenario. A pre-defined sequence of events that mirrors a real flow:
Scenario type | Events (default options) |
|---|---|
subscription_creation | transaction.created, customer.created, address.created, transaction.ready, transaction.paid, subscription.created, subscription.activated (or subscription.trialing), transaction.completed, payment_method.saved — with transaction.updated between steps |
subscription_renewal | subscription.updated, transaction.created, transaction.billed, transaction.updated, transaction.paid, transaction.updated, transaction.completed |
subscription_pause | subscription.updated, subscription.paused |
subscription_resume | subscription.updated, subscription.resumed, transaction.created, transaction.billed, then the same payment events as a renewal |
subscription_cancellation | subscription.updated, subscription.canceled |
Options change the sequence. Pause and cancellation default to effective_from: "immediately"; "next_billing_period" adds a subscription.updated with scheduled_change first. Renewal and resume take a payment_outcome — "failed" swaps the payment events for transaction.payment_failed, transaction.past_due and subscription.past_due. Add real sandbox entities (e.g. a subscription_id) to fill payloads with their details; the entities themselves aren't changed, but the API key needs read permission for them (e.g. subscription.read).
Find the simulator at Paddle > Events > Simulations. If a Paddle MCP server is available to you, you can drive the simulator programmatically inside one execute call instead of using the dashboard — create the simulation, then create a run against it:
async (client) => {
const sim = await client.simulations.create({
name: "Subscription created flow",
type: "subscription_creation",
// Required: the destination that receives the simulated events.
notification_setting_id: "ntfset_...",
});
const run = await client.simulations.runs.create(sim.id);
return { simulation_id: sim.id, run_id: run.id };
}Note client.simulations.runs.create is nested under simulations (not a top-level client.simulationRuns), and the simulation ID is a positional path param. Scenario options go in config, keyed by the scenario type — e.g. config: { subscription_cancellation: { entities: { subscription_id: "sub_..." }, options: { effective_from: "next_billing_period" } } }.
The Paddle MCP exposes three tools per server (
search,execute,report_missing_tool). Workflow: callsearchto confirm the exact method name and parameter shapes, then callexecutewith an async function that callsclient.<resource>.<operation>(...). Method paths are camelCase (client.clientTokens.create,client.pricingPreview.preview). Body params and response fields are snake_case (tax_category,product_id,unit_price,currency_code). List methods return{ pagination: { hasMore, estimatedTotal }, <resource>: [...] }, notdata. The array's key is the resource's API path segment, so it's kebab-case where the method path is camelCase:(await client.products.list()).products,(await client.clientTokens.list())["client-tokens"]. Page with{ after: "<last_id>" }whilepagination.hasMoreis true, not.next(). Lists that aren't paginated, likeclient.currencies.list(), return a plain array. Single-entity methods return the entity. Chain multi-step workflows inside oneexecute; variables don't persist between calls. Hard caps: 50 API calls per execute, 30s timeout, and 32,000 characters of code.
The Paddle CLI (
paddle, v0.2.0 or later) runs Paddle API operations from the terminal with the user's saved login. Resource commands mirror the API reference:paddle products createis "create a product". Runpaddle <resource> --helpto find a command, add--schemato a create or update command to see its request body, and usepaddle api <path>for an endpoint without a command. It starts in the live account, so pass--environment sandboxunless the user is working in live. When an agent runs it, it returns the API's JSON (data,meta), andmeta.environmentnames the account it used. Cancel and delete commands need--confirm <id>. Add it only after the user has agreed to that specific cancel or delete, and never use it to work around a refusal.paddle apiwrites aren't checked at all, so treat them the same way. Exit code5is a403: a missing permission, or a login for the other account. Exit code7is a validation error. Ifpaddle whoamishows no login, ask the user to runpaddle loginthemselves (sandbox takes an API key:paddle login --environment sandbox --api-key …), and never ask for a key in the chat. A live login with OAuth can change anything the user's Paddle role allows, so name each live change and wait for a yes before you run it. For CI/CD, set a live API key with only the permissions it needs asPADDLE_API_KEY. To install it, see Paddle CLI.
With the Paddle CLI, run the same steps as separate commands. The body is the same snake_case JSON:
paddle --environment sandbox simulations create --jq '.data.id' --json '{
"name": "Subscription created flow",
"type": "subscription_creation",
"notification_setting_id": "ntfset_..."
}'
paddle --environment sandbox simulation-runs create ntfsim_...To use the simulator:
customer_id you've already created in your DB). For a scenario, add real sandbox entities.failed to simulate a failed payment).The destination must have Usage type "Simulation" or "Both" (traffic_source: "simulation" or "all") — "Platform" destinations can't be used. It must also be active and subscribed to each event type in the simulation; any event it can't receive is marked aborted and not sent. A "Simulation" destination gets no real events, so use "Both" for a local destination you also use for real checkouts.
Each simulated event gets one delivery attempt, with no retries. Check results on the run in Paddle > Events > Simulations, or with client.simulations.runsEvents.list(simulationId, runId) — each event has a status (success, failed, aborted, pending) plus the request and response. Resend one with client.simulations.runsEvents.replay(simulationId, runId, eventId). With the CLI, use paddle simulation-run-events list <simulation_id> <run_id> and paddle simulation-run-events replay <simulation_id> <run_id> <event_id>.
The signature on a simulated event uses the destination's secret, so your normal verification code works without changes. If verification fails, the secret you've set in PADDLE_NOTIFICATION_WEBHOOK_SECRET doesn't match the destination you're simulating against.
To check a deployed preview on every change, run a simulation from CI with the Paddle CLI. Create the simulation once, pointed at a destination for the preview URL, then start a new run in each build and fail if any event wasn't delivered. Store a sandbox API key with the simulator permissions as a CI secret, and never commit it:
# CI secrets and variables: PADDLE_API_KEY (sandbox key), PADDLE_SIMULATION_ID (ntfsim_...)
export PADDLE_ENVIRONMENT=sandbox
RUN_ID=$(paddle simulation-runs create "$PADDLE_SIMULATION_ID" --jq '.data.id')
while [ "$(paddle simulation-runs get "$PADDLE_SIMULATION_ID" "$RUN_ID" --jq '.data.status')" = pending ]; do
sleep 5
done
FAILED=$(paddle simulation-run-events list "$PADDLE_SIMULATION_ID" "$RUN_ID" \
--jq '[.data[] | select(.status != "success")] | length')
[ "$FAILED" = 0 ] || { echo "$FAILED simulated events weren't delivered"; exit 1; }The simulator covers most testing. For real flows (e.g. completing an actual sandbox checkout to verify the full chain), Paddle needs to reach your local machine. Use a tunnel:
Hookdeck (recommended):
# Install: brew install hookdeck
hookdeck listen 3000 paddle --path /api/webhook
# Copy the source URL it prints ("Requests to → https://...")paddle is the Hookdeck source name and --path is your webhook route. Point a sandbox notification destination at the source URL, with Usage type "Both" so it gets real and simulated events. The source URL stays the same when you restart the CLI, so you only set it once. Hookdeck keeps your event history between sessions, so if events arrived while the CLI was stopped, replay them from Hookdeck or Paddle.
Debug delivery. For real events, open the notification in Paddle > Events > Notifications, or use client.notifications.logs.list("ntf_...") to see each delivery attempt and client.notifications.replay("ntf_...") to send it again. For simulated events, check the simulation run's events (see Step 3).
Here's the loop for verifying a fresh integration:
hookdeck listen 3000 paddle --path /api/webhook.4242 4242 4242 4242.successUrl.subscription-sync).subscription-cancel).subscription_cancellation simulation with that subscription's ID in entities.subscription_id and effective_from: "next_billing_period". This only sends events whose payloads use the subscription's details — the real subscription stays active, so your DB and Paddle will disagree afterwards.effective_from: "next_billing_period": a subscription.updated event arrives with scheduled_change.action: "cancel" and status still active. subscription.canceled only arrives when the billing period ends.effective_from: "immediately": a subscription.canceled event arrives with status canceled; your row should flip to canceled.subscription.updated with scheduled_change, then subscription.updated and subscription.canceled with status canceled, all in the same run.These behave differently in sandbox and live.
| Behavior | Sandbox | Live | Why it matters |
|---|---|---|---|
| Adjustments (refunds/credits) | Refunds are created pending_approval and approved automatically within about 10 minutes. Credits are approved straight away. | Most refunds stay pending_approval until Paddle reviews them. Credits are approved straight away. | Don't treat a refund as done on adjustment.created — handle adjustment.updated moving status from pending_approval to approved (or rejected). |
| Webhook retries | 3 attempts in total, all within about two minutes | Up to 60 attempts in total over about two days | A failing sandbox handler gets no more attempts after about two minutes — fix it, then replay the event. Don't write tests that rely on exact timing. |
| Payouts | No payouts | Real money to your bank | Test payout webhook handling against simulated payouts only. |
| Domain approval | Checkout opens on any page, including localhost, and domains are approved as soon as you add them. The default payment link doesn't need an approved domain, but use a page on your own domain, not localhost | Approve each domain in Paddle > My account > Settings > Website approval. Your default payment link (Paddle > Checkout > Checkout configuration) must be on an approved domain. | Forgetting domain approval means production checkout fails to load. Check each domain's status with GET /checkout-domains. |
| Checkout "test mode" flag | Shown on checkouts | Not shown | A quick visual check of which environment a checkout is using. |
| Dunning (Retain) | Not available | Available | Retain handles canceling or pausing past due subscriptions. |
| Email delivery | Only sent to addresses on your account email's domain. Emails to other addresses go to your account email instead. | Sent to the email on the customer record (real) | You receive the emails for every test customer, so check your own inbox. |
PADDLE_API_KEY and NEXT_PUBLIC_PADDLE_ENV are for the correct environment.production when initializing Paddle.js in production.aborted. The destination's Usage type isn't "Simulation" or "Both", it's inactive, or it isn't subscribed to that event type.4000 0000 0000 0002 to confirm checkout.payment.failed handling, then use the simulator to test a failed subscription renewal (payment_outcome: "failed").PaddleHQ/paddle-agent-skills
f2e0af8
Canonical home
since May 15, 2026
Also appears in
since Oct 8, 2026
since Sep 13, 2026
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.