Update payment details

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.

This guide walks through updating details for an existing subscription. To present saved payment methods at checkout for new purchases, see: Present saved payment methods at checkout

How it works

When payment fails for an automatically-collected subscription, the subscription status changes to past_due and it enters dunning. This is the process where Retain attempts to collect for the payment by sending reminders and, where applicable, automatically retrying the payment.

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. It includes a message that lets customers know that they need to pay for the outstanding balance.

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, with totals shown at 0.00. It includes a message that lets customers know that they're updating their payment method.

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "txn_01h2ast61chjbjmz9z4pvwvt0h",
4    "status": "past_due",
5    "customer_id": "ctm_01h2asct98zxebssbkt1q6tfyr",
6    "address_id": "add_01h2asctbmeekr9364bjgjdbxe",
7    "business_id": null,
8    "custom_data": null,
9    "origin": "subscription_recurring",
10    "collection_mode": "automatic",
11    "subscription_id": "sub_01h2ase3pcjyhmc25h57t7qe2e",
12    "invoice_id": null,
13    "invoice_number": null,
14    "billing_details": null,
15    "billing_period": null,
16    "currency_code": "USD",
17    "discount_id": null,
18    "created_at": "2023-06-07T11:28:01.053056Z",
19    "updated_at": "2023-06-07T11:28:04.127729Z",
20    "billed_at": "2023-06-07T11:28:00.556475Z",

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
1{
2  "data": {
3    "id": "txn_01hv8zbfzrnfr6b4hfexhk4e7h",
4    "status": "ready",
5    "customer_id": "ctm_01hv8wt8nffez4p2t6typn4a5j",
6    "address_id": "add_01hv8y4jk511j9g2n9a2mexjbx",
7    "business_id": null,
8    "custom_data": null,
9    "origin": "subscription_payment_method_change",
10    "collection_mode": "automatic",
11    "subscription_id": "sub_01hv8y5ehszzq0yv20ttx3166y",
12    "invoice_id": null,
13    "invoice_number": null,
14    "discount_id": null,
15    "billing_details": null,
16    "billing_period": {
17      "starts_at": "2024-04-12T10:37:59.556997Z",
18      "ends_at": "2024-04-12T10:37:59.556997Z"
19    },
20    "currency_code": "USD",

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.url field in the transaction response to automatically open a checkout for the transaction using your default payment link.
• Extract the id and pass to Paddle.js to open a checkout. 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.status is past_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.subtotal is 0.

  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

Related pages