For AI agents and LLMs: a structured documentation index is available at /llms.txt. Every page has a Markdown sibling — append .md to any URL. To search these docs, send a GET request to https://paddle-docs-retrieval.kapa-paddle.workers.dev/?q=<question> with a URL-encoded question. No authentication needed.

Skip to content
Paddle Docs home

Set your default payment link

Your default payment link is a quick way to open Paddle Checkout for a transaction, and used when updating a payment method. Set it in the Paddle dashboard.

AI summary

Set a default payment link in your Paddle dashboard or via the API so Paddle knows which approved page in your app or website should open Paddle Checkout for transactions and payment method updates.

  • •You must set a default payment link before you can create transactions, including manually-collected transactions (invoices).
  • •Checkout payment links are your default payment link with a _ptxn query parameter containing the transaction ID, returned as checkout.url.
  • •The domain must be on your approved websites list (Paddle > My account > Settings > Website approval) before you can use it, and sandbox and live need separate default links.

Transactions have a checkout payment link that you can use to open a checkout to collect for payment. Set a default payment link to tell Paddle which page in your app or website that checkout payment links should point to by default.

Your default payment link is also used to open a checkout to let customers update their payment method. It's included automatically in emails sent by Paddle to customers.

You must set your default payment link to start selling with Paddle. You can't create transactions without it — including manually-collected transactions (invoices).

How it works

Every Paddle account has a default payment link. It's used for:

  • Unique payment links against transactions that automatically open a Paddle Checkout to collect for payment.
  • As a redirect for the payment method update URL against automatically-collected subscriptions to let customers update payment details.
  • In emails sent by Paddle to customers to let them update their payment details for automatically-collected subscriptions.

Your default payment link should be a page for an approved website that includes Paddle.js. You don't need to do anything to get Paddle.js to open a checkout, it automatically opens a checkout for the transaction when the query parameter is present.

All automatically-collected transactions include a checkout payment link.

Manually-collected transactions don't include a checkout payment link by default, but you can set billing_details.enable_checkout to true when creating or updating to include one. When enabled, this link is automatically included on invoice documents sent by Paddle.

Checkout payment links are returned in transaction responses as checkout.url. They're made up of your default payment link with a _ptxn query parameter appended. The value of the query parameter is the transaction ID. For example:

Example checkout payment link
https://aeroedit.com/pay?_ptxn=txn_01h2b0qpjc0xt8k5aw6nsdec4p

In this example:

DescriptionURL component
Default payment linkhttps://aeroedit.com/pay
Query parameter key?_ptxn=
Query parameter value (transaction ID)txn_01h2b0qpjc0xt8k5aw6nsdec4p

You can pass any of your other approved websites as checkout.url when creating or updating a transaction to override the default checkout link, if you want to point to another page.

For compliance, subscription emails from Paddle include a link to let customers update their payment method and cancel their subscription. Links are also returned when working with subscription entities against subscription.management_urls.

The link to update a payment method redirects to your default payment URL to open a checkout to update a payment method.

Before you begin

You'll need to add your website to Paddle > My account > Settings > Website approval, then wait for approval.

Build your default payment link page

Your default payment link should be a page for an approved website that includes Paddle.js. It might be your checkout page, or you might create a separate page specifically for it.

If your page calls Paddle.Checkout.open() on load with a list of items or a transactionId, this takes priority over the query parameter.

By default, Paddle.js opens an overlay checkout for the passed transaction. You can set default checkout settings by passing them to Paddle.Initialize(). Paddle.js uses default settings when opening a checkout payment link.

This example sets default checkout settings for all checkouts opened on a page. When using a checkout payment link, Paddle.js opens an inline checkout with these settings.

JavaScript
Paddle.Initialize({
  token: 'live_7d279f61a3499fed520f7cd8c08', // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "inline",
      theme: "light",
      locale: "en",
      frameTarget: "checkout-container",
      frameInitialHeight: "450",
      frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;"
    }
  }
});

This example sets default checkout settings for all checkouts opened on a page. When using a checkout payment link, Paddle.js opens an overlay checkout with these settings.

Paddle.js opens an overlay checkout by default, but this is a good way to pass additional settings like locale and theme.

JavaScript
Paddle.Initialize({
  token: 'live_7d279f61a3499fed520f7cd8c08', // replace with a client-side token
  checkout: {
    settings: {
      displayMode: "overlay",
      theme: "light",
      locale: "en"
    }
  }
});

You can set your default payment link in the Paddle dashboard. You must set a default payment link — even if you only sell by invoice or only sell one-time products.

Your sandbox and live systems are separate. You should set a default payment link for both systems. They don't have to be the same.

  1. Go to Paddle > Checkout > Checkout configuration.
  2. Enter your website homepage under the Default payment link heading. Use your own domain, not localhost.
  3. Click Save when you're done.

Checkout settings screen showing the Paddle dashboard. The default payment URL is set to https://example.com/

You can also set your default payment link using the API. Send a PATCH request to /settings/checkout-url with default_url. In live accounts, the domain must be approved for your account first. The link's host must match an approved domain exactly, or be its www. version, so app.example.com needs its own approval even if example.com is approved. In sandbox, the domain doesn't need to be approved.

Was this page helpful?