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
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
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.
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.
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.
Go to Paddle > Checkout > Checkout settings.
On the General tab, check the Allow buyers to opt in to save their payment methods for future purchases box.
Click Save to apply.
Present all saved payment methods at checkout
Present all compatible saved payment methods for a customer at checkout in three steps:
Generate a customer authentication token
Use the Paddle API to generate an authentication token for a customer.
Pass the customer authentication token to Paddle.js
Pass
customerAuthToken
to Paddle.js when opening a checkout, along with your items or a transaction.Present saved payment methods alongside restricted payment options — optional
Optionally pass
saved_payment_methods
as a value in theallowedPaymentMethods
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.
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.
1234567891{
2 "data": {
3 "customer_auth_token": "pca_01hwyzq8hmdwed5p4jc4hnv6bh_01hwwggymjn0yhhb2gr4p91276_6xaav4lydudt6bgmuefeaf2xnu3umegx",
4 "expires_at": "2024-05-03T10:34:12.34Z"
5 },
6 "meta": {
7 "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"
8 }
9}
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.
12345678910111213141516171var itemsList = [
2 {
3 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
4 quantity: 1
5 }
6];
7
8Paddle.Checkout.open({
9 customerAuthToken: "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
10 settings: {
11 displayMode: "inline",
12 frameTarget: "checkout-container",
13 frameInitialHeight: "450",
14 frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
15 items: itemsList
16 }
17});
allowLogout
is ignored if passed because you've authenticated the customer using thecustomerAuthToken
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.
1234567891011121314151617181var itemsList = [
2 {
3 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
4 quantity: 1
5 }
6];
7
8Paddle.Checkout.open({
9 customerAuthToken: "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
10 settings: {
11 displayMode: "inline",
12 frameTarget: "checkout-container",
13 frameInitialHeight: "450",
14 frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
15 allowedPaymentMethods: ["saved_payment_methods", "paypal"],
16 items: itemsList
17 }
18});
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:
Use the Paddle API to get a saved payment method ID for a customer.
Generate a customer authentication token
Use the Paddle API to generate an authentication token for a customer.
Pass the saved payment method ID and customer authentication token to Paddle.js
Pass
savedPaymentMethodId
andcustomerAuthToken
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.
Paddle ID of the customer to list payment methods for.
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.
12345678910111213141516171819201{
2 "data": [
3 {
4 "customer_id": "ctm_01hv6y1jedq4p1n0yqn5ba3ky4",
5 "address_id": "add_01j2jfab8zcjy524w6e4s1knjy",
6 "id": "paymtd_01j2jff1m3es31sdkejpaym164",
7 "type": "card",
8 "card": {
9 "cardholder_name": "Sam Miller",
10 "type": "visa",
11 "last4": "4242",
12 "expiry_month": 5,
13 "expiry_year": 2025
14 },
15 "paypal": null,
16 "origin": "saved_during_purchase",
17 "saved_at": "2024-07-12T03:23:26Z",
18 "updated_at": "2024-10-29T14:12:28.018784Z"
19 }
20 ],
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.
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.
1234567891{
2 "data": {
3 "customer_auth_token": "pca_01hwyzq8hmdwed5p4jc4hnv6bh_01hwwggymjn0yhhb2gr4p91276_6xaav4lydudt6bgmuefeaf2xnu3umegx",
4 "expires_at": "2024-05-03T10:34:12.34Z"
5 },
6 "meta": {
7 "request_id": "fa176777-4bca-49ec-aa1e-f53885333cb7"
8 }
9}
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.
1234567891011121314151617181var itemsList = [
2 {
3 priceId: 'pri_01gm81eqze2vmmvhpjg13bfeqg',
4 quantity: 1
5 }
6];
7
8Paddle.Checkout.open({
9 customerAuthToken: "pca_01hwz42rfyaxw721bgkppp66gx_01h282ye3v2d9cmcm8dzpawrd0_otkqbvati3ryh2f6o7zdr6owjsdhkgmm",
10 savedPaymentMethodId: "paymtd_01hs8zx6x377xfsfrt2bqsevbw",
11 settings: {
12 displayMode: "inline",
13 frameTarget: "checkout-container",
14 frameInitialHeight: "450",
15 frameStyle: "width: 100%; min-width: 312px; background-color: transparent; border: none;",
16 items: itemsList
17 }
18});
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.saved | Occurs when a customer saves a payment method. |
payment_method.deleted | Occurs when a saved payment method for a customer is deleted. |
Related pages
- Present saved payment methods
- How it works
- Customer journey
- Authentication
- Payment method support
- Allowed payment options
- Before you begin
- Create products and prices
- Set your default payment link
- Use one-page checkout
- Let customers save payment methods for one-time items
- Present all saved payment methods at checkout
- Generate a customer authentication token
- Pass the customer authentication token to Paddle.js
- Present saved payment methods alongside restricted payment options — optional
- Preselect a specific saved payment method
- Get a saved payment method ID
- Generate a customer authentication token
- Pass the saved payment method ID and customer authentication token to Paddle.js
- Work with saved payment methods
- Events
- Related pages