Present saved payment methods

Paddle lets customers save their payment methods when purchasing one-time items and subscriptions using Paddle Checkout.

Once saved, you can securely present returning customers with their saved payment methods in the future. This creates a friction-free checkout experience by removing the need to manually enter payment details each time.

How it works

Customers can purchase one-time items and recurring subscriptions using Paddle Checkout and choose to save their payment method when purchasing.

Once saved, you can securely present customers with their saved payment methods when making purchases in the future by passing a customer authentication token to Paddle.js.

Customer journey

Authentication

You can choose to present all compatible payment methods, or present a single payment method at checkout — useful for building workflows that let customers set a preferred payment method for particular purchases.

To present customers with their saved payment methods, you must generate a customer authentication token and pass it to Paddle.js when opening a checkout.

Customer authentication tokens are important for security. They let you authenticate a customer, so Paddle.js can present their payment methods to them. They're unique and impossible to guess, restricted to a particular customer, and only valid for 30 minutes. They can only be generated with the Paddle API using a valid API key.

Payment method support

Paddle creates a saved payment method entity for supported payment methods when customers opt to save them for future purchases.

Check the payment methods guides to learn which payment methods support being presented when saved.

Keep in mind that some saved payment methods may not be compatible with a checkout when presented. For example, PayPal isn't supported for all currencies and regions supported by Paddle. In this case, Paddle Checkout falls back to presenting customers with all compatible payment options.

Allowed payment options

You can pass an array of payment methods to Paddle.js to present only those payment options at checkout. For example, you can open checkouts that only present PayPal as a payment option.

Saved payment methods for a customer are considered their own payment option, with their own saved_payment_methods value. This means that if a customer has a saved payment method for PayPal, it's not presented if you open a checkout that's set to present only PayPal as a payment option.

Subscriptions

When a customer purchases a subscription, Paddle stores their payment method against that subscription to bill for renewals, upgrades and downgrades, and other charges related to that subscription.

However, customers must explicitly opt in to save their payment method for future purchases. Without this opt-in, the payment method won't be saved as a saved payment method entity for you to present at checkout.

This means a customer could have an active subscription with a stored payment method, but that same payment method won't appear as an option when they make new purchases unless they previously opted in to save it.

Payment methods stored against subscriptions always appear in the customer portal regardless of whether the customer opted to save them for future purchases, letting customers manage their payment methods used for recurring billing.

Before you begin

• Create products and prices]
  Paddle Checkout works with products and prices to say what customers are purchasing, so you'll need to create a product and at least one related price to pass to your checkout.
• Set your default payment link
  Set a payment link under Paddle > Checkout > Checkout settings > Default payment link, then get it approved if you're working with the live environment.
• Use one-page checkout
  You can only present saved payment methods when using one-page checkout. Multi-step checkouts don't support presenting saved payment methods.

Let customers save payment methods

To give customers the option to save their payment method when purchasing, turn the option on in the Paddle dashboard.

This option is off by default.

Present all saved payment methods at checkout

Present all compatible saved payment methods for a customer at checkout in three steps:

1. Generate a customer authentication token
   Use the Paddle API to generate an authentication token for a customer.
2. Pass the customer authentication token to Paddle.js
   Pass customerAuthToken to Paddle.js when opening a checkout, along with your items or a transaction.
3. Present saved payment methods alongside payment options Optional
   Optionally pass saved_payment_methods as a value in the allowedPaymentMethods list to present saved payment methods when restricting a checkout to particular payment methods.

Generate a customer authentication token

Get the Paddle ID for the customer that you want to present payment methods for, then use the API to generate an authentication token.

For security, authentication tokens aren't stored and can't be retrieved later. They're valid for 30 minutes.

{
  "data": {
    "customer_auth_token": "pca_01hwyzq8hmdwed5p4jc4hnv6bh_01hwwggymjn0yhhb2gr4p91276_6xaav4lydudt6bgmuefeaf2xnu3umegx",
    "expires_at": "2024-05-03T10:34:12.34Z"
  },
  "meta": {
    "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"
  }
}

Pass the customer authentication token to Paddle.js

Take the customer_auth_token from the last step and pass it to Paddle.Checkout.open() as customerAuthToken. You should pass items or a transactionId when opening a checkout to tell Paddle what a checkout is for, as normal.

When passing a transactionId, the customer entity against the transaction must match the customer that the customerAuthToken is for.

This example opens an inline checkout for a one-time item. customerAuthToken is passed to Paddle.Checkout.open(), so the customer is presented with any payment methods they previously saved.

var itemsList = [
  {
    priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
    quantity: 1
  }
];

Paddle.Checkout.open({
  items: itemsList,
  customerAuthToken: "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: "450",
    frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
  }
});

Present saved payment methods alongside payment options Optional

You can pass an array of payment method types as a value for the allowedPaymentMethods parameter for checkout settings to determine which payment options are presented to customers.

Saved payment methods for a customer are considered a discrete payment option. This means that if a customer has a saved payment method for PayPal, it's not presented if you open a checkout that's set to present only PayPal as a payment option.

To present a customer with all their saved payment methods when restricting a checkout to certain payment options, include saved_payment_methods in your allowedPaymentMethods array.

This example shows opening a checkout that presents a customer the option to pay with PayPal or a saved payment method.

var itemsList = [
  {
    priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
    quantity: 1
  }
];

Paddle.Checkout.open({
  customerAuthToken: "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: "450",
    frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
    allowedPaymentMethods: ["saved_payment_methods", "paypal"],
    items: itemsList
  }
});

Preselect a specific saved payment method

Paddle creates a saved payment method entity for a customer when they choose to save a payment method. You can pass a saved payment method entity ID to Paddle.js to open a checkout for that payment method. Instead of seeing all their compatible saved payment methods, the customer is only presented with the saved payment method you passed.

You can use this to build custom checkout workflows that let customers pick a payment method before launching Paddle Checkout, or to let customers set a preferred payment method for specific purchases.

Open a checkout for a saved payment method in three steps:

1. Get a saved payment method ID
   Use the Paddle API to get a saved payment method ID for a customer.
2. Generate a customer authentication token
   Use the Paddle API to generate an authentication token for a customer.
3. Pass the saved payment method ID and customer authentication token to Paddle.js
   Pass savedPaymentMethodId and customerAuthToken to Paddle.js when opening a checkout, along with your items or a transaction.

Get a saved payment method ID

Get the Paddle ID for the customer that you want to get a payment method for. You might present this list to a customer on a page in their account settings screen to let them select a preferred payment method.

Extract the id for the saved payment method you want to present at checkout — we'll pass this to Paddle.js in the next step.

{
  "data": [
    {
      "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
      "address_id": "add_01j2jfab8zcjy524w6e4s1knjy",
      "id": "paymtd_01j2jff1m3es31sdkejpaym164",
      "type": "card",
      "card": {
        "cardholder_name": "Sam Miller",
        "type": "visa",
        "last4": "4242",
        "expiry_month": 5,
        "expiry_year": 2025
      },
      "paypal": null,
      "origin": "saved_during_purchase",
      "saved_at": "2024-07-12T03:23:26Z",
      "updated_at": "2024-10-29T14:12:28.018784Z",
      "underlying_details": null,
      "south_korea_local_card": null
    }
  ],
  "meta": {
    "request_id": "0a5ed361-6e13-4cf0-bcad-cca2fca21dca",
    "pagination": {
      "per_page": 50,
      "next": "https://api.paddle.com/customers/ctm_01hv6y1jedq4p1n0yqn5ba3ky4/payment-methods?after=paymtd_01j2jff1m3es31sdkejpaym164",
      "has_more": false,
      "estimated_total": 1
    }
  }
}

Generate a customer authentication token

Use the API to generate an authentication token for a customer.

Extract the customer_auth_token and save it for later — we'll pass this to Paddle.js in the next step. For security, authentication tokens aren't stored and can't be retrieved later. They're valid for 30 minutes.

{
  "data": {
    "customer_auth_token": "pca_01hwyzq8hmdwed5p4jc4hnv6bh_01hwwggymjn0yhhb2gr4p91276_6xaav4lydudt6bgmuefeaf2xnu3umegx",
    "expires_at": "2024-05-03T10:34:12.34Z"
  },
  "meta": {
    "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"
  }
}

Pass the saved payment method ID and customer authentication token to Paddle.js

Take the id for the saved payment method and the customer_auth_token from the last steps and pass them to Paddle.Checkout.open() as savedPaymentMethodId and customerAuthToken. You should pass items or a transactionId when opening a checkout to tell Paddle what a checkout is for, as normal.

When passing a transactionId, the customer entity against the transaction must match the customer that the customerAuthToken is for. The address entity against the transaction is updated so that it matches the address for the saved payment method passed.

This example opens an inline checkout for a one-time item. customerAuthToken and savedPaymentMethodId are passed to Paddle.Checkout.open(), so the customer is presented with the option to pay with the passed saved payment method when they open checkout.

var itemsList = [
  {
    priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
    quantity: 1
  }
];

Paddle.Checkout.open({
  customerAuthToken: "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
  savedPaymentMethodId: "paymtd_01hs8zx6x377xfsfrt2bqsevbw",
  settings: {
    displayMode: "inline",
    frameTarget: "checkout-container",
    frameInitialHeight: "450",
    frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
    items: itemsList
  }
});

Work with payment methods

Let customers manage payment methods by:

• Linking to the customer portal
  Customers can see and delete their subscription payment methods using the customer portal, meaning you don't need to build any of your own logic. This includes all payment methods associated with their subscriptions, whether they opted to save them for future purchases or not.
• Building an integration using the Paddle API
  You can use the Paddle API to build billing screens to let customers see and delete their saved payment methods. This only includes payment methods that customers opted to save for future purchases.