Just launched
We're actively working on new content and improvements to our documentation. We'd love to hear your thoughts, launch quick survey
Paddle Billing
Search

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.

  1. Pass items to Paddle.js using HTML data attributes or Paddle.Checkout.open().

  2. Paddle.js automatically creates a transaction for the items passed.

  3. 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.

  1. You create a transaction using the API or Dashboard.

  2. Pass transaction to Paddle.js using HTML data attributes or Paddle.Checkout.open().

  3. 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 default payment link

The simplest way to pass a transaction to a checkout is to use your default 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.Setup().

You can:

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.

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

Related pages