Build an overlay checkout
Get a step-by-step overview of how to build a complete overlay checkout — including initializing Paddle.js, passing settings and items, prefilling customer information, and next steps.
The checkout is where customers make purchases. For SaaS businesses, it's the process where customers enter their details and payment information, and confirm that they'd like to sign up for a subscription with you.
You can use Paddle.js to quickly add an overlay checkout into your app. Overlay checkout lets you present customers with an overlay that handles all parts of the checkout process — minimal frontend coding required.
What are we building?
In this tutorial, we'll launch an overlay checkout for two items in our product catalog, then we'll extend it by passing customer information.
We'll learn how to:
- Include and set up Paddle.js using a client-side token
- Pass items to overlay checkout using
Paddle.Checkout.open()or HTML data attributes - Take a test payment
- Prefill customer information using
Paddle.Checkout.open()or HTML data attributes
If you like, you can copy-paste the sample code in your editor or view on CodePen and follow along.
Before you begin
Choose a type of checkout
This tutorial walks through creating an overlay checkout. You can also create inline checkouts, which lets you build Paddle Checkout right into your app or website.
We recommend building an overlay checkout if you're new to Paddle. Inline checkouts use the same JavaScript methods as overlay checkouts, so you can switch to an inline checkout later.
Create products and prices
Paddle Checkout works with products and prices to say what you're billing for, so you'll need to create a product and at least one related price to pass to your checkout.
Set your default payment link
You'll also need to:
- Set your default payment link under Paddle > Checkout > Checkout settings > Default payment link.
- Get your default payment link domain approved, if you're working with the live environment.
Get started
Add an overlay checkout to your website or app in four steps:
Include and initialize Paddle.js
Add Paddle.js to your app or website, so you can securely capture payment information and build subscription billing experiences.
Add an overlay checkout button
Set any element on your page as a trigger for Paddle Checkout.
Make sure that your checkout loads successfully, then take a test payment.
Prefill customer information — optional
Extend your checkout by prefilling customer and address information.
1. Include and initialize Paddle.js
Paddle.js is a lightweight JavaScript library that lets you build rich, integrated subscription billing experiences using Paddle. We can use Paddle.js to securely work with products and prices in our Paddle system, as well as opening checkouts and capturing payment information.
Include Paddle.js script
Start with a blank webpage, or an existing page on your website. Then, include Paddle.js by adding this script to the <head>:
<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>Set environment (optional)
We recommend signing up for a sandbox account to test and build your integration, then switching to a live account later when you're ready to go live.
If you're testing with the sandbox, call Paddle.Environment.set() and set your environment to sandbox:
12341<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
2<script type="text/javascript">
3 Paddle.Environment.set("sandbox");
4</script>Pass a client-side token
Next, go to Paddle > Developer tools > Authentication and generate a client-side token. Client-side tokens let you interact with the Paddle platform in frontend code, like webpages or mobile apps. They have limited access to the data in your system, so they're safe to publish.
In your page, call Paddle.Initialize() and pass your client-side token as token. For best performance, do this just after calling Paddle.Environment.set(), like this:
12345671<script src="https://cdn.paddle.com/paddle/v2/paddle.js"></script>
2<script type="text/javascript">
3 Paddle.Environment.set("sandbox");
4 Paddle.Initialize({
5 token: "test_7d279f61a3499fed520f7cd8c08" // replace with a client-side token
6 });
7</script>2. Add an overlay checkout button
Next, we'll set an element on our page as a trigger for our overlay checkout. Overlay checkout works by presenting an overlay to handle the entire checkout process. When our button or other trigger element is clicked, Paddle.js launches a checkout for us.
Create checkout button element
Any element can be a trigger for an overlay checkout. In our sample, we're using a link (<a>) that points to #. This means it doesn't open a new page.
11<a href='#'>Sign up now</a>Set as a checkout trigger
Next, we'll make our checkout element open an overlay checkout by making it a trigger.
There are two ways we can do this:
Paddle.Checkout.open() method
- Works using JavaScript to open a checkout when an element is clicked.
- You can pass items and settings as parameters to
Paddle.Checkout.open(). - Recommended in most cases.
- No styles applied to your element.
- Best for passing multiple attributes.
HTML data attributes
- Works by adding a
paddle_buttonclass to an element, which Paddle.js turns into a checkout trigger. - You can pass items and settings as data attributes against the element.
- Recommended when you can't use JavaScript.
- Optionally styles your element to look like a button.
- Best for passing few attributes.
In general, we recommend using the Paddle.Checkout.open() method, but you can choose the option that makes the most sense for you.
Paddle.js comes with the Paddle.Checkout.open() method, which lets you open a checkout with settings, items, and customer information.
In our sample, we've created a function called openCheckout() to open a checkout. Here's how it works:
We create a variable called
itemsListand pass an array of objects, where each object contains apriceIdandquantity.We create a function called
openCheckout()that takes a parameter calleditems.In our
openCheckout()function, we callPaddle.Checkout.open(), passing the value ofitemsas the items list for the checkout.We add an
onclickevent to our checkout button to callopenCheckout()when clicked, passing ouritemsListvariable as a parameter.
12345678910111213141516171819201<script type="text/javascript">
2 Paddle.Environment.set("sandbox");
3 Paddle.Initialize({
4 token: "test_7d279f61a3499fed520f7cd8c08" // replace with a client-side token
5 });
6
7 // define items
8 let itemsList = [
9 {
10 priceId: "pri_01gsz8ntc6z7npqqp6j4ys0w1w",
11 quantity: 5
12 },
13 {
14 priceId: "pri_01h1vjfevh5etwq3rb416a23h2",
15 quantity: 1
16 }
17 ];
18
19 // open checkout
20 function openCheckout(items){
3. Take a test payment
We're now ready to test! Save your page, then open it in your browser. Click on your "Sign up now" button and Paddle.js should open an overlay checkout for the items that we passed.
If you're using the sandbox environment, you can take a test payment using our test card details:
| Email address | An email address you own |
| Country | Any valid country supported by Paddle |
| ZIP code (if required) | Any valid ZIP or postal code |
| Card number | 4242 4242 4242 4242 |
| Name on card | Any name |
| Expiration date | Any valid date in the future. |
| Security code | 100 |
4. Prefill customer information (optional)
So far, we've passed items to our checkout. When we click our trigger, Paddle opens a checkout for the items that we passed.
Paddle.js also lets you pass customer information to a checkout. When we click our trigger, Paddle opens a checkout with the customer information prefilled. This means the first page of checkout is skipped entirely, so customers land on a screen where they can enter their payment information.
Paddle.Checkout.open() takes a customer parameter, which lets you pass customer and address information.
In our sample, we've extended our openCheckout() function so that it passes customer and address information to our checkout. Here's what's going on:
We create a variable called
customerInfo, with anemailkey and an object foraddress. You may also pass Paddle IDs for an existing customer or address here.We update our
openCheckout()function so it takes another parameter calledcustomer.In our
openCheckout()function, we added thecustomerparameter and passing the value ofcustomerto this.We updated the
onClickevent on our checkout button to pass ourcustomerInfovariable as the parameter forcustomer.
12345678910111213141516171819201<script type="text/javascript">
2 Paddle.Environment.set("sandbox");
3 Paddle.Initialize({
4 token: "test_7d279f61a3499fed520f7cd8c08" // replace with a client-side token
5 });
6
7 // define items
8 let itemsList = [
9 {
10 priceId: "pri_01gsz8ntc6z7npqqp6j4ys0w1w",
11 quantity: 5
12 },
13 {
14 priceId: "pri_01h1vjfevh5etwq3rb416a23h2",
15 quantity: 1
16 }
17 ];
18
19 // define customer details
20 let customerInfo = {
Test your work
Save your page, then open it in your browser. Click on your "Sign up now" button and Paddle.js should open an overlay checkout with the customer information prefilled. You should land on the second screen, ready to enter payment information.
Next steps
That's it! Now you've built a checkout, you might like to extend Paddle Checkout by automatically applying a discount, passing optional checkout settings, or building a success workflow.
Automatically apply a discount
Extend your checkout by passing a discount. When we click our trigger, Paddle opens a checkout with the discount automatically applied (where it's valid).
Pass checkout settings
You don't need to pass checkout settings when working with overlay checkout, but you can use them to give you more control over how opened checkouts work. For example, you can set the language that Paddle Checkout uses, hide the option to add a discount, or restrict payment methods shown to customers.
Build a success workflow
When customers complete checkout, Paddle Checkout has a final screen that lets customers know that their purchase was successful. If you like, you can redirect customers to your own page or use JavaScript event callbacks to build a more advanced success workflow.
