Test mode

Test mode lets you buy from your own checkout page, event or form without paying. Use it to check the whole flow before you take real payments: the checkout itself, the emails and files your buyer receives, your webhooks and your integrations. Each page has its own switch, and while it's on, every purchase on that page is a test purchase.

How test mode works

Test mode is a switch on each checkout page, event and form. You test the real page, with the same URL, products and settings your buyers see.

While the switch is on:

• Every purchase on the page is a test purchase. No money is taken and no payment is created in Stripe.
• The buyer still gets everything the page delivers: confirmation emails, files, license keys, tickets, customer portal access, integrations and webhooks.
• The records the purchase creates, such as the payment, booking or submission, have livemode: false.
• Every visitor sees a Test payments only banner on the page.

This works the same on your hosted page, your custom domain, embeds and popups. Nothing changes in your embed code.

Switch test mode off and the page takes live payments again straight away.

What test mode labels

The records in the first column carry a livemode field: false for a test purchase and true for a live one. Everything in the second column has no mode and is shared between live and test purchases.

There are no test customers

There is no test checkout, test event or test customer. Checkout Page matches buyers to customers by email address, so one person has one customer record across all of their purchases, live or test. A test purchase creates or reuses the same customer record a live purchase with that email address would, and the customer isn't labelled as test.

This means:

• If you test with a real customer's email address, the test purchase appears on their customer record. Use a new email address for each test.
• customer.created webhooks carry no livemode, so a new customer from a test purchase looks like any other.
• If your Stripe account is connected, a new email address also creates a customer in Stripe, just as a live purchase would.

To find the customers behind your test purchases, list your test payments and read each payment's customerId.

Turn test mode on

In the dashboard

1. Open the page in the page editor.
2. Click Test payments in the toolbar. On a form it's called Test submissions.
3. Under Where should test payments work? (Where should test submissions work? on a form), choose Everywhere.

Preview only lets you make test payments inside the dashboard preview, but it doesn't switch the page: your visitors keep paying for real. Only Everywhere puts the page in test mode.

To switch it off, click Turn off test mode.

With the API

Set testmode when you create or update a checkout page, event or form:

curl -X PATCH https://api.checkoutpage.com/v1/checkout-pages/{pageId} \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "testmode": true }'

For an event, use /v1/events/{eventId}, and for a form, /v1/forms/{formId}. To create a page that starts in test mode, send "testmode": true in the POST body.

The response includes testmode, and testmodeEnabledAt, the time test mode was switched on. testmodeEnabledAt is read-only and is null while test mode is off. Trimmed:

{
  "data": {
    "id": "{pageId}",
    "type": "checkout",
    "status": "published",
    "testmode": true,
    "testmodeEnabledAt": "2026-09-14T13:15:06.239Z"
  }
}

To find pages you left in test mode, filter the list with testmode=true. /v1/events and /v1/forms take the same filter, and testmode=false returns only pages that are not in test mode.

curl "https://api.checkoutpage.com/v1/checkout-pages?testmode=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

With the MCP server

With the Checkout Page MCP server connected, ask your AI assistant, for example "Put my Spring Workshop checkout in test mode." It calls update_checkout_page, update_event or update_form with testmode: true. To find pages still in test mode, ask "Which of my pages are in test mode?" and it calls list_checkout_pages, list_events and list_forms with testmode: true.

Make a test purchase

1. Switch test mode on for the page.
2. Open the page wherever your buyers use it: its URL, your custom domain, or your own site with the embed or popup. Check that you see the Test payments only banner. In a popup, it sits above the title.
3. Fill in the checkout with a new email address you can read, and pay with the test card:
   • Card number: 4242 4242 4242 4242
   • Expiry: any future date
   • CVC: any 3 digits
   • Postcode: any
4. Check your inbox for the confirmation email, and your webhook endpoint or integration for the events.

Real cards are rejected while test mode is on, so you can't be charged by mistake.

Embeds and popups need no changes. Test mode belongs to the page, so your embed or popup code stays the same. If an older guide had you add ?preview=true&testing=true&testingPayments=true to the checkout URL, you don't need those parameters: they don't put the page in test mode for your visitors. Use the switch instead.

Read test data

Test records are kept apart from live ones. To read them with your API key, add livemode=false:

# List the test payments on a page
curl "https://api.checkoutpage.com/v1/payments?pageId={pageId}&livemode=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get one test payment
curl "https://api.checkoutpage.com/v1/payments/{paymentId}?livemode=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

livemode=false works on these endpoints:

Without livemode=false, a live API key returns live records only. Fetching a test record by its id without it returns 404.

With the MCP server, pass livemode: false to the list and get tools for the same records, and to list_tickets.

Keys that start with sk_test_ can only read test data: livemode=true returns 403 with the message Test API keys can only read test data. Remove livemode=true or use a live API key. See Authentication for how API keys and test mode fit together.

Webhooks

Webhooks fire for test purchases just as they do for live ones, so you can test your handler end to end. livemode sits on the object inside data, for example data.payment.livemode or data.booking.livemode. The event itself has no top-level livemode. Trimmed:

{
  "event": "payment.paid",
  "eventId": "payment_paid_{paymentId}",
  "sellerId": "{sellerId}",
  "timestamp": "2026-09-14T13:20:11.000Z",
  "data": {
    "payment": {
      "id": "{paymentId}",
      "status": "paid",
      "livemode": false
    }
  }
}

Branch on it in your handler, for example to skip shipping an order. Verify the signature first, as for any webhook:

// payload is the webhook body, after you verify its signature
const [record] = Object.values(payload.data);

if (record.livemode === false) {
  // A test purchase: skip anything that should only happen for a real order.
}

customer.created and customer.updated events carry no livemode, because customers have no mode.

Limitations

• Cards that normally decline or ask for 3D Secure succeed, because the payment never goes to Stripe. You can't test failed payments or payment retries in test mode.
• License keys from a test purchase aren't labelled as test.
• Test purchases don't use up stock or ticket quantities, don't count towards a coupon's usage limit, and aren't recorded in Stripe Tax.
• Subscriptions still need your Stripe account connected.
• A page the buyer reaches after checkout through the after-payment "go to another checkout" action isn't an upsell, so it doesn't pick up test mode from the first purchase. Switch test mode on for that page too.
• A one-click upsell shown on your own site (the redirect action) doesn't pick up test mode from the first purchase either. See Test an upsell funnel.

Next steps