> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Present saved payment methods

Let customers securely save payment methods when making a purchase and present saved payment methods to customers when they return. You can manage saved payment methods using the API.

---

Paddle lets customers save their payment methods when purchasing one-time items and subscriptions using [Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md).

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.

{% callout type="info" %}
This guide walks through presenting customers with their saved payment methods when they're making a new purchase. To update payment details for an existing subscription, see [Update payment details](https://developer.paddle.com/build/subscriptions/update-payment-details.md)
{% /callout %}

## How it works

Customers can purchase one-time items and recurring subscriptions using [Paddle Checkout](https://developer.paddle.com/concepts/sell/self-serve-checkout.md) 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](https://developer.paddle.com/paddlejs/overview.md).

### Customer journey

{% journey level=4 %}
{% journey-step title="Initial purchase" %}

When purchasing one-time items and subscriptions, customers may check a box to save their payment method when completing payment.

{% /journey-step %}

{% journey-step title="Repeat purchase" %}

When customers come back in the future, you can securely present them with their saved payment methods to make checkout quick and easy.

{% callout type="info" %}
You can only present saved payment methods when using one-page checkout.
{% /callout %}

{% /journey-step %}

{% journey-step title="Manage saved payment methods" %}

Customers can view and delete their saved payment methods using [the customer portal](https://developer.paddle.com/concepts/customer-portal.md). Paddle automatically includes a unique link in transaction receipt emails.

{% /journey-step %}
{% /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](https://developer.paddle.com/api-reference/customers/generate-customer-authentication-token.md) 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](https://developer.paddle.com/api-reference/about/api-keys.md).

{% callout type="warning" %}
To avoid exposing your API key and other sensitive data, don't make requests to the Paddle API directly from your frontend. Build functionality into your backend to handle requests and serve just the information you need to your frontend.

Entities in the API have an `Access-Control-Allow-Origin` header to block access from browsers.
{% /callout %}

### Payment method support

Paddle creates a [saved payment method entity](https://developer.paddle.com/api-reference/payment-methods/overview.md) for supported payment methods when customers opt to save them for future purchases.

Check [the payment methods guides](https://developer.paddle.com/concepts/payment-methods/overview.md) 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](https://developer.paddle.com/concepts/payment-methods/paypal.md) 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](https://developer.paddle.com/concepts/payment-methods/overview.md).

### 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](https://developer.paddle.com/concepts/payment-methods/paypal.md) 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](https://developer.paddle.com/build/subscriptions/replace-products-prices-upgrade-downgrade.md), 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](https://developer.paddle.com/api-reference/payment-methods/overview.md) 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](https://developer.paddle.com/concepts/customer-portal.md) 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**](#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](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md) to pass to your checkout.
- [**Set your default payment link**](#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**](#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.

{% callout type="note" %}
To get a step-by-step overview of how to build a complete checkout, including passing checkout settings and prefilling properties, see [Build an overlay checkout](https://developer.paddle.com/build/checkout/build-overlay-checkout.md) or [build an inline checkout](https://developer.paddle.com/build/checkout/build-branded-inline-checkout.md)
{% /callout %}

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

{% instruction-steps %}

1. Go to **Paddle > Checkout > Checkout settings**.
2. On the General tab, check the **Allow buyers to opt in to save their payment methods for future purchases** box.
3. Click {% mock-button %}Save to apply.
{% /instruction-steps %}

{% /dashboard-instructions %}

## 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**](#present-payment-methods-generate)  
   Use the Paddle API to generate an authentication token for a customer.
2. [**Pass the customer authentication token to Paddle.js**](#present-payment-methods-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**](#present-payment-methods-restricted) {% badge label="Optional" variant="outline" /%}  
   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 {% step=true %}

Get the Paddle ID [for the customer](https://developer.paddle.com/api-reference/customers/overview.md) 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.

{% api-example method="POST" path="/customers/{customer_id}/auth-token" href="/api-reference/customers/generate-customer-authentication-token" %}
```json
{
  "data": {
    "customer_auth_token": "pca_01hwyzq8hmdwed5p4jc4hnv6bh_01hwwggymjn0yhhb2gr4p91276_6xaav4lydudt6bgmuefeaf2xnu3umegx",
    "expires_at": "2024-05-03T10:34:12.34Z"
  },
  "meta": {
    "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"
  }
}
```
{% /api-example %}

### Pass the customer authentication token to Paddle.js {% step=true %}

Take the `customer_auth_token` from the last step and pass it to [`Paddle.Checkout.open()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md) as `customerAuthToken`. [You should pass `items`](https://developer.paddle.com/build/checkout/pass-update-checkout-items.md) or [a `transactionId` when opening a checkout](https://developer.paddle.com/build/transactions/pass-transaction-checkout.md) 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()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md), so the customer is presented with any payment methods they previously saved.

```javascript {% highlightLines="10" %}
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;",
  }
});
```

{% callout type="info" %}
`allowLogout` is ignored if passed because you've authenticated the customer using the `customerAuthToken` parameter.
{% /callout %}

### Present saved payment methods alongside payment options {% step=true badge="Optional" %}

You can pass an array of payment method types as a value for the `allowedPaymentMethods` parameter for [checkout settings](https://developer.paddle.com/build/checkout/set-up-checkout-default-settings.md) to determine which [payment options](https://developer.paddle.com/concepts/payment-methods/overview.md) 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](https://developer.paddle.com/concepts/payment-methods/paypal.md), 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.

```javascript {% highlightLines="9,15" %}
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](https://developer.paddle.com/api-reference/payment-methods/overview.md) 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**](#preselect-payment-method-get-id)  
   Use the Paddle API to get a saved payment method ID for a customer.
2. [**Generate a customer authentication token**](#preselect-payment-method-generate)  
   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**](#preselect-payment-method-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 {% step=true stepReset=true %}

Get the Paddle ID [for the customer](https://developer.paddle.com/api-reference/customers/overview.md) 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.

{% api-example method="GET" path="/customers/{customer_id}/payment-methods" href="/api-reference/customers/list-payment-methods" %}
```json
{
  "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
    }
  }
}
```
{% /api-example %}

### Generate a customer authentication token {% step=true %}

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.

{% api-example method="POST" path="/customers/{customer_id}/auth-token" href="/api-reference/customers/generate-customer-authentication-token" %}
```json
{
  "data": {
    "customer_auth_token": "pca_01hwyzq8hmdwed5p4jc4hnv6bh_01hwwggymjn0yhhb2gr4p91276_6xaav4lydudt6bgmuefeaf2xnu3umegx",
    "expires_at": "2024-05-03T10:34:12.34Z"
  },
  "meta": {
    "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"
  }
}
```
{% /api-example %}

### Pass the saved payment method ID and customer authentication token to Paddle.js {% step=true %}

Take the `id` for the saved payment method and the `customer_auth_token` from the last steps and pass them to [`Paddle.Checkout.open()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md) as `savedPaymentMethodId` and `customerAuthToken`. [You should pass `items`](https://developer.paddle.com/build/checkout/pass-update-checkout-items.md) or [a `transactionId` when opening a checkout](https://developer.paddle.com/build/transactions/pass-transaction-checkout.md) 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()`](https://developer.paddle.com/paddlejs/methods/paddle-checkout-open.md), so the customer is presented with the option to pay with the passed saved payment method when they open checkout.

```javascript {% highlightLines="9,10" %}
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
  }
});
```

{% callout type="info" %}
If a passed saved payment method isn't compatible with a checkout, Paddle Checkout presents the customer with other ways to pay. For example, PayPal isn't supported for all currencies and regions supported by Paddle. In this case, customers are presented with options that are compatible.
{% /callout %}

## 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](https://developer.paddle.com/concepts/customer-portal.md), 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](https://developer.paddle.com/api-reference/payment-methods/overview.md) 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.