Pass a transaction to a checkout

Transactions hold all the information about a customer purchase, 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

All purchases are transactions. You can work with transactions using Paddle.js in two ways:

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 customers sign up and pay using your website.

Learn more: 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.

Learn more: Create a transaction

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 a 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, and get it approved.

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.

Pass transactionId to the Paddle.Checkout.open() method to open a checkout for the passed transaction.

JavaScript

Paddle.Checkout.open({
  settings: {
    theme: "light",
    locale: "en"
  },
  transactionId: "txn_01h0j589qt1nee24210teqtz57"
});

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

HTML

<a href="#"
  class="paddle_button"
  data-display-mode="overlay"
  data-theme="light"
  data-locale="en"
  data-transaction-id="txn_01h0j589qt1nee24210teqtz57"
>
 Buy now
</a>