Loading search…

Loading search…

Skip to content
Products & subscriptionsPayment methods

Payment methods & consent

Subscriptions only support card payment methods (including Google Pay and Apple Pay). This page explains how recurring-charge consent works and how a consumer updates the card on an existing subscription.

Renewal charges are billed automatically, without the consumer present to enter a card or complete a challenge. To do this safely, Tokenz uses merchant-initiated transaction (MIT) consent: when a consumer first provides a card for a subscription, Tokenz records their permission to charge that card again in the future. Every subsequent renewal and dunning retry is charged as an MIT using this stored consent — the consumer is not asked to re-enter their card or pass a 3D Secure (3DS) challenge on every cycle.

Consent is captured automatically by the Tokenz-hosted flow the first time a payment method is attached to a subscription:

  • No trial: Consent is captured as part of the initial checkout payment.
  • Trial period: Consent is captured when the consumer starts the trial.
  • Updating the payment method later: Consent is captured again for the new payment method.

Updating the payment method

A consumer can update their payment method at any time while the subscription is trialing, active, or unpaid — for example, when their card is about to expire, or to recover from a declined renewal. The change can be initiated by the consumer in the consumer dashboard or requested by the merchant via the API. Note that latter option behaves differently depending on the subscription's state:

  • for active or trialing subscriptions it follows the payment method update flow described below.
  • for unpaid subscriptions it redirects to the recovery checkout session described in section Recovering from a declined renewal.

The flow:

  1. The consumer is redirected to the hosted flow for their subscription.
  2. They enter their new card. If the issuer requires it, they complete a 3D Secure challenge.
  3. Tokenz captures a new consent record for the card.
  4. If consent is granted, the subscription's payment method is swapped to the new card immediately. If it's denied, the existing card stays in place and nothing changes.
  5. Tokenz notifies your backend with a subscription.payment_method_updated webhook once the update is confirmed.
Diagram
Diagram
100%
Scroll to explore · Zoom for detail

Using a saved payment method

If the consumer already has a saved, previously-consented payment method on file (for example from an earlier subscription or purchase), the hosted flow lets them reuse it directly instead of entering card details again, skipping a new consent step entirely.

Recovering from a declined renewal

When a renewal charge fails, the subscription moves to unpaid and Tokenz emails the consumer a recovery checkout link (see Lifecycle & billing). The same checkout session is also returned by the API when requesting a payment method change. The consumer can either let the existing card retry automatically, or use the recovery checkout session to directly pay for the unpaid order and update the payment method. When successful, the subscription is reactivated and Tokenz sends subscription.activated webhook.