Pass a transaction to a checkout

Pass an existing transaction to Paddle.js to open a checkout to collect for it. You can do this for automatically and manually-collected transactions.

Transactions hold all the information about a charge you're billing for, including customer details, items, calculated tax and localized pricing, and payments.

Paddle creates transactions automatically when checkouts are opened, but you can also create your own transactions and pass them to a checkout.

How it works

There are two ways to work with transactions using Paddle.js. You can either pass items, then let Paddle.js create a transaction; or create a transaction manually, then pass this to to Paddle.js.

Pass items

When you open a checkout, Paddle.js automatically creates a transaction for you.

Pass items to Paddle.js using HTML data attributes or Paddle.Checkout.open().
Paddle.js automatically creates a transaction for the items passed.
Customers pay using Paddle Checkout.

This is a typical self-service workflow, where customer sign up and pay using your website.

See: Pass or update checkout items

Pass transactions

You can also create a transaction manually using the API, then pass this to Paddle.js.

You create a transaction using the API or the Paddle dashboard.
Pass transaction to Paddle.js using HTML data attributes or Paddle.Checkout.open().
Customers pay using Paddle Checkout.

This is more typical when working with sales-assisted customers who want to pay an invoice by card.

You can pass automatically-collected transactions and manually-collected transactions where billing_details.enable_checkout is true to a checkout.

Before you begin

To pass a transaction to a checkout, you'll need to first create a transaction using the API.

You'll also need to build an inline or overlay checkout to pass your transaction to.

If you haven't already, you'll need to:

Add a default payment link to your checkout under Paddle > Checkout > Checkout settings > Default payment link.
Get your default payment link domain approved if you're working with the live environment.

Use checkout payment link

The simplest way to pass a transaction to a checkout is to use a checkout payment link.

Automatically-collected transactions, and manually-collected transactions where billing_details.enable_checkout is true, include a checkout.url. This is made up of your default payment link, with a _ptxn query parameter and the transaction ID appended.

Provided your default checkout link page includes Paddle.js, it automatically opens a checkout for the transaction passed in the URL. The opened checkout inherits settings from checkout.settings in Paddle.Initialize().

You can:

Set allowLogout to false to prevent customers from changing their details
Mark a transaction as billed to stop customers from editing items on it

Pass an approved domain as checkout.url when creating or updating a transaction to override the domain that Paddle uses to generate your checkout payment link.

Pass a transaction to Paddle.js

When building pages with Paddle.js, you can pass a transaction ID to a checkout using HTML data attributes or when you call Paddle.Checkout.open().

You should do this instead of passing an array of items.

HTML data attributes

JavaScript properties

Add data-transaction-id as an attribute to your checkout trigger to open a checkout for the passed transaction.

Checkout trigger element

1
2
3
4
5
6
7
8
9
1<a href="#" 
2  class="paddle_button"
3  data-display-mode="overlay"
4  data-theme="light"
5  data-locale="en"
6  data-transaction-id="txn_01h0j589qt1nee24210teqtz57"
7>
8	Buy now
9</a>

Set your default payment link

Create a transaction

Create and issue an invoice (a manually-collected transaction)

Sign up to get notified when our API evolves