Update payment details
Build a workflow for updating customer payment details for a subscription using the Paddle API and Paddle.js.
It's good practice to give customers a way to change the payment method that they use to pay for future subscription renewals and charges. It's especially important where subscriptions are past due, meaning customers have an outstanding payment.
Payment methods can be updated for automatically-collected subscriptions that are active or past due.
How it works
When payment fails for an automatically-collected subscription, the subscription status changes to past_due. If you've integrated with Paddle Retain, it works to automatically recover the payment for you by intelligently retrying the payment method on file and sending payment recovery reminders by email, in-app, and SMS.
You can build a workflow to let a customer update their payment details using Paddle Checkout, which handles securely capturing card details or payment using another payment method.
To open Paddle Checkout for an existing subscription, you need a transaction for that subscription. You can use the get a transaction to update payment method operation to get a transaction that you can pass to Paddle.js to open a Paddle Checkout for it.
The returned transaction depends on the status of the related subscription:
Past due subscription
If the subscription is past_due, the last past_due transaction is returned.
Overlay checkout displays the items and totals for the overdue transaction, so that customers know they'll be charged when they update their details.
The inline checkout frame includes a button that says "Update payment method."
Active subscription
If the subscription is active, Paddle creates a zero-value transaction for the items on the subscription.
Overlay checkout displays the items on the subscription and a message to let customers know that they're updating their details.
The inline checkout frame includes a button that says "Update payment method."
When the checkout for the returned transaction completes, Paddle saves the payment details that the customer entered and uses them for future renewals and charges.
Before you begin
You'll need the ID for a subscription that's active or past due.
To pass a payment method update transaction to a checkout, you'll need a page that includes Paddle.js. This is typically your default payment link.
If you haven't already, you'll need to:
- Add a default payment link to your checkout under Paddle > Checkout > Checkout settings > Default payment link.
- Get your default payment link domain approved if you're working with the live environment.
Get a payment method update transaction
Send a GET request to the /subscriptions/{subscription_id}/update-payment-method-transaction endpoint.
Pass a transaction to a checkout
Once you have a payment method update transaction, pass it to Paddle.js to open a checkout for it. To do this, you can either:
- Use the
checkout.urlfield in the transaction response to automatically open a checkout for the transaction using your default payment link. - Extract the
idand pass to Paddle.js to open a checkout. To learn more, see Pass a transaction to a checkout
Show on-page information
Overlay checkout includes items, totals, and a message to let customers know what the checkout is for.
Inline checkout doesn't include items or totals. It's designed to capture payment information, letting you embed information about the transaction on your page.
You might like to build your own logic to display information about this transaction. Pass an eventCallback to Paddle.Initialize() to listen for the checkout.loaded event, then update on-page elements based on the event emitted.
For past due subscriptions,
data.statusispast_due.You should include items and totals, and may like to show a message to let customers know this checkout is to pay for a past due payment and update the payment method on file.
For active subscriptions,
data.totals.subtotalis0.You should show a message to let customers know this checkout is to update the payment method on file.
Events
For a full list of events that occur when a payment method is updated, see Payment method update
