Subscription payment details update

Updating payment information is a key subscription workflow.

You should offer customers whose subscription is past due a way to update their payment details so they can maintain access to your app and avoid cancellation.

Providing a way for customers to update their payment details at any time is good practice, helping reduce churn by letting customers proactively update their payment method before there's a problem.

How it works

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.

Updating a payment method requires a payment method update transaction, which can be:

• A new, zero-value transaction for items on a subscription

  Where a subscription is active, the Paddle API creates a new zero-value transaction. On checkout complete, Paddle updates the saved payment method.

• The last past due transaction for a subscription

  Where a subscription is past_due, the Paddle API returns the last past_due transaction for the subscription. On checkout complete, Paddle collects for the outstanding balance and updates the saved payment method.

For compliance reasons, subscription-related emails sent from Paddle to customers include a link to update payment method. When customers update payment method using the link in the email from Paddle, Paddle passes a payment method update transaction to your default checkout page.

How to update payment details

Events

Active subscription

1. New zero-value transaction created

   transaction.created	Paddle creates a new zero-value transaction for payment method update. Its status is ready because the transaction has customer and address information. Its origin is subscription_payment_method_change.
   transaction.ready	Occurs because the transaction status changes to ready.

2. Checkout opened and customer updates payment details successfully

   transaction.updated	The transaction status changes to paid now that the customer has paid successfully. The transaction is updated with information about the successful payment.
   transaction.paid	Occurs because the transaction status changes to paid.
   transaction.updated	An invoice number is assigned to the transaction. Its status changes to completed as Paddle has finished processing it.
   transaction.completed	Occurs because the transaction status changes to completed.

Past due subscription

1. Checkout opened and customer updates payment details successfully

   This step occurs when a past due transaction for a subscription is passed to Paddle Checkout using Paddle.js and a customer enters updated payment details.

   transaction.updated	The transaction status changes to paid now that the customer has paid successfully. The transaction is updated with information about the successful payment.
   transaction.paid	Occurs because the transaction status changes to paid.
   subscription.updated	The subscription status is updated to active.
   subscription.activated	Occurs because the subscription status changes to active.
   transaction.updated	An invoice number is assigned to the transaction. Its status changes to completed as Paddle has finished processing it.
   transaction.completed	Occurs because the transaction status changes to completed.

Recommended workflow

1. Listen for events

   We recommend that you listen for:

   transaction.created	Get notified when a transaction is created. Transactions with the origin of subscription_payment_method_change are zero-value payment method update transactions for active subscriptions; transaction where the status is past_due are used when updating payment method for past due subscriptions.
   transaction.completed	Get notified when a transaction is completed. This means it is fully paid and Paddle has completed processing.
   subscription.activated	Get notified when a past due subscription becomes active. The subscription status is updated to active. This means that payment method was updated successfully for a past due subscription.

2. Update information in your database

   Update the record for a subscription in your database for the payment method update based on webhooks received. As well as checking and storing the occurred_at date against notifications, you'll typically need to update:

   Description	Field name	Reason to store
   Subscription status	subscription.status	Used to determine if a past due subscription is now active.

   You may like to store and update other fields if you want to build a more complete billing and subscription management experience. In particular, transaction.payments[].method_details includes information about the saved payment method. See: Handle provisioning and fulfillment

3. Provision

   Provision so that a customer has continued access to your app.

    

   Use the subscription.status field to determine whether a subscription should have access to your app. Where status is active, customers should have full access to your app.

Related pages