Paddle Billing
Search

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 automatically saves payment methods for subscriptions when customers sign up, and you can also let customers save payment methods when buying one-time items 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.

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

Illustration of a sample inline checkout. It has two one-time items on the right: a sack of gems and a health boost powerup. The total is $5.48. On the left, there two saved payment methods with radio buttons next to them. One is a Visa card ending 4242 and another is a Mastercard ending 1234. There are buttons to pay by card or pay another way.

How it works

When customers sign up for a subscription using Paddle Checkout, Paddle automatically creates a saved payment method entity for renewals, upgrades and downgrades, and other charges related to that subscription. Customers purchasing one-time items can choose to save their payment method at checkout, too.

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

  1. Illustration showing an inline checkout. Sample card details are filled out. There is a box that says: save my payment details for next time. This box is checked.

    Initial purchase

    Paddle automatically saves payment methods for subscriptions.

     

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

  2. Illustration showing an inline checkout. There are list of saved payment card presented, including a Visa card with the last four showing 4242. There is an option to use another card or pay another way.

    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.

    You can only present saved payment methods when using one-page checkout.

  3. Illustration showing a customer portal. There's a gray sidebar, with nav items represented with solid blocks. There are two cards listed on the right side: a Visa card ending 4242, a Mastercard ending 1111, and an American Express card ending 10005. There are buttons to delete the cards.

    Manage saved payment methods

    Customers can view and delete their saved payment methods using the customer portal. Paddle automatically includes a unique link in transaction receipt emails.

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.

Don't expose your API key or make calls to the Paddle API from your frontend app code. Endpoints in the API have an Access-Control-Allow-Origin header to block direct access from browsers.

Payment method support

While Paddle creates a saved payment method for all kinds of payment methods when customers sign up for a subscription, only some payment methods can be presented 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.

Before you begin

Create products and prices

Paddle Checkout works with products and prices to say what you're billing for, so you'll need to create a product and at least one related price to pass to your checkout.

Set your default payment link

You'll also need to:

  • Set your default payment link under Paddle > Checkout > Checkout settings > Default payment link.
  • Get your default payment link domain approved, if you're working with the live environment.

We recommend starting the domain approval early in your integration process, so your domains are approved for when you're ready to go-live.

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.

Pass variant with the value one-page as a checkout setting to use one-page checkout.

Let customers save payment methods for one-time items

Paddle automatically saves payment methods for subscriptions. To give customers the option to save their payment method when purchasing one-time items, turn the option on in the Paddle dashboard.

This option is off by default.

  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 Save to apply.

Graphic of the saved payment methods checkbox in the Paddle dashboard. Only the checkbox and label text is present, on a Paddle gradient background.

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 restricted 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 send a POST request to the /customers/{customer_id}/auth-token endpoint to generate an authentication token.

POSThttps://api.paddle.com/customers/{customer_id}/auth-token
customer_idstring

Paddle ID of the customer to generate an authentication token for.

Response

If successful, Paddle returns a customer_auth_token, along with an expiry_date to let you know how long it's valid for.

For security, authentication tokens are not stored and cannot be retrieved later. They're valid for 30 minutes.

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.

allowLogout is ignored if passed because you've authenticated the customer using the customerAuthToken parameter.

Present saved payment methods alongside restricted 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.

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, then send a GET request to the /customers/{customer_id}/payment-methods endpoint to list payment methods for that customer.

You might present this list to a customer on a page in their account settings screen to let them select a preferred payment method.

Response

If successful, Paddle returns a paginated list of saved payment method entities for a customer.

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

You might like to save this in your database against the record for a customer account.

Generate a customer authentication token

Send a POST request to the /customers/{customer_id}/auth-token endpoint to generate an authentication token for a customer.

POSThttps://api.paddle.com/customers/{customer_id}/auth-token
customer_idstring

Paddle ID of the customer to generate an authentication token for.

Response

If successful, Paddle returns a customer_auth_token, along with an expiry_date to let you know how long it's valid for.

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

For security, authentication tokens are not stored and cannot be retrieved later. They're valid for 30 minutes.

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.

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.

Work with saved payment methods

Let customers manage their saved payment methods by:

  • Linking to the customer portal

    Customers can see and delete their saved payment methods using the customer portal, meaning you don't need to build any of your own logic to handle managing saved payment methods.

  • Building an integration using the Paddle API

    You can use the Paddle API to build billing screens to let customers see and delete their payment methods.

Events

payment_method.savedOccurs when a customer saves a payment method.
payment_method.deletedOccurs when a saved payment method for a customer is deleted.

Related pages