Apple Pay merchant tokens

Request Apple Pay merchant tokens for recurring, deferred or automatic reload payments.

If your Apple Pay integration supports future merchant-initiated payments, such as recurring payments, automatic reloads or deferred payments, configure Apple Pay to request an Apple Pay Merchant Token (the related setting). Merchant tokens can help maintain payment continuity when a customer changes devices.

When a customer adds a card to Apple Pay, Apple Pay creates a network token instead of storing the card’s primary account number (PAN). By default, Apple Pay creates a Device Primary Account Number (the related setting), which is tied to a specific device. If a customer replaces their device or removes the card from it, the the related setting might no longer work.

This doesn’t affect one-time cardholder-initiated transactions (CIT), but it can cause failures for future merchant-initiated transactions (MIT).

An Apple Pay Merchant Token (the related setting) is associated with the customer, underlying card and your business, instead of with a single device. Use an the related setting for payments you initiate later, including:

• Subscriptions : Charge a monthly membership after the initial Apple Pay checkout.
• Automatic reloads : Replenish a stored balance when it falls below a threshold.
• Deferred payments : Authorise payment at booking, then charge after you provide the service, such as after a hotel stay.

Configure your integration to request Apple Pay merchant tokens

Configure your integration to request Apple Pay merchant tokens by providing additional information about the payment use case. If you use Elements with the Payment Intents API, follow the instructions below to request Apple Pay merchant tokens.

Note

If you use Stripe Checkout or Elements with the Checkout Sessions API, you don’t need to configure Apple Pay merchant tokens. Checkout automatically requests them when needed.

1. Integrate the Express Checkout Element .
2. Pass the applePay object relevant to your the related setting use case (choose from the drop-down to see use case code samples).
3. Include relevant parameters for your use case.

the related setting use case:

checkout.js

elements.create('expressCheckout', {
 applePay: {
 recurringPaymentRequest: {
 paymentDescription: "Standard Subscription",
 managementURL: "https://stripe.com",
 regularBilling: {
 amount: 1000,
 label: "Standard Package",
 recurringPaymentStartDate: new Date("2023-03-31"),
 recurringPaymentEndDate: new Date("2024-03-31"),
 recurringPaymentIntervalUnit: "year",
 recurringPaymentIntervalCount: 1,
 }
 },
 },
});

After you configure Apple Pay to request merchant tokens, you don’t need to complete additional the related setting-specific integration steps. When a customer pays with Apple Pay, Stripe requests a merchant token. If Apple Pay and the card issuer support merchant tokens, Apple Pay returns an the related setting. Otherwise, it returns a the related setting.

Stripe securely stores the returned Apple Pay credential and associates it with the resulting PaymentMethod. Continue to save and reuse the PaymentMethod in your standard off-session payment flow.

Merchant token auth rate monitoring

For Sigma users, the charges table contains a card_token_type enum field to indicate the charge is using an mpan or dpan card. The following Sigma query example calculates the the related setting auth rate:

-- deduplicated MPAN auth rate
select
 100.0 * count(
 case
 when charge_outcome in ('authorized', 'manual_review') then 1
 end
 ) / count(*) as deduplicated_auth_rate_pct,
 count(*) as n_attempts
from
 authentication_report_attempts a
 join charges c on c.id = a.charge_id
where
 c.created >= date('2021-01-01')
 and c.card_tokenization_method = 'apple_pay'
 -- The new field added to charges table.
 and c.card_token_type = 'mpan'
 -- deduplicate multiple manual retries to a single representative charge
 and is_final_attempt