Request Apple Pay merchant tokens for subscriptions and recurring billing that remain valid when customers change devices
Apple Pay merchant tokens (MPANs) are network tokens designed to facilitate and ensure uninterrupted recurring payments on the web and in apps. A merchant token corresponds to the card that the customer adds to Apple Pay and is associated with your business, not with the customer’s device, so recurring payments continue after the customer replaces the device. Payments continue even after a card is reissued.
A merchant token is issued when the customer confirms an Apple Pay payment that includes a recurring payment request and the issuer supports merchant tokens. Otherwise, it issues a device token (DPAN). A device token stops working when the customer changes the device or removes the card from Wallet.
Merchant token (MPAN)
Device token (DPAN)
Associated with Merchant, cardholder, and issuing bank
Associated with A single device
Device change The token remains valid
Device change The token stops working
Issued for Apple Pay payments with a recurring payment request when the issuer supports merchant tokens
Issued for One-time Apple Pay payments and payments where the issuer does not support merchant tokens
Recommended for Subscriptions and recurring billing
Recommended for One-time payments
Card schemes recommend merchant tokens for recurring Apple Pay payments.
Update your integration
To use merchant tokens through the Payment Form, Payment Page, or Payment Link, complete these steps in order:
Request merchant tokens Add the recurring payment request to the Apple Pay payment when the customer subscribes to your product.
Charge with merchant tokens Send follow-up charges with the received token in the
recurring
API v1 request as merchant-initiated payments.
Manage merchant tokens Build a flow on your side that sends the
deactivate token
API v1 request when the customer cancels the subscription or changes the payment method. When a token stops working, ask the customer to confirm a new Apple Pay payment.
With Solidgate Billing, a deactivated token also changes the subscription, both when you deactivate it and when Solidgate deactivates it after an update from Apple:
Billing 2.0
Billing 1.0
Subscription Solidgate revokes the payment instrument, and the subscription stays active until the next renewal. At renewal, the flow depends on your configuration
Subscription Scheduled to cancel at the end of the billing period
Notification You receive a notification
Notification You receive a notification
Request merchant tokens
Merchant tokens are available for Apple Pay payments through the Payment Form, Payment Page, and Payment Link:
Payment Form Pass paymentIntent.apple.recurring_payment_request for the
Guide
Pass the recurring payment request in the Apple Pay button intent to request a merchant token.
Apple Pay button
and paymentIntent.apple_pay_merchant_name, which is required to receive a merchant token.
Apple displays the recurring billing details on the payment sheet. One-time Apple Pay payments do not need this configuration.
If you display the Apple Pay button on your side and integrate with Solidgate through host-to-host requests, add the recurring payment request to your own Apple Pay payment request and send the payment data in the
Guide
Decrypt Apple Pay payment tokens server-side and submit the extracted card data directly to the payment API for host-to-host processing.
Apple Pay H2H
request the same way as for device tokens. Solidgate processes merchant tokens without changes to this request and returns the token type in transaction.card.pan_type. Apple sends token updates to the notification URL that you set, so you manage the token lifecycle on your side.
The recurring payment request contains:
Payment description
Describes the recurring payment to the customer on the payment sheet.
Regular billing
The label, amount, and payment timing of the recurring charge.
Management URL
A page on your website where the customer updates or deletes the payment method for the recurring payment. Apple Pay requires this URL.
A merchant token is issued only when the issuer supports merchant tokens. Otherwise, a device token is issued, and the payment continues as a regular Apple Pay payment. The token type cannot be determined before the payment.
Merchant tokens require iOS or iPadOS 16 and later, or macOS 13 and later, on the customer device.
Use merchant tokens
After the payment, check which token you received and use it for follow-up charges.
Identify token type
The
Apple Pay
API v1 response and the
card order status
Webhook webhook return transaction.card.pan_type and transactions.{id}.card.pan_type. The
order status
API v1 response returns only transactions.{id}.card.pan_type. The value is
mpan
for a merchant token or
dpan
for a device token. Only merchant tokens can be deactivated, so store this value with the token.
Charge with merchant tokens
Solidgate returns a token for both token types, and follow-up charges use the same
recurring
API v1 request. A merchant token follows the same
Guide
Apply token management best practices for recurring charges, including validity rules, scheme restrictions, and credential update handling.
token usage
rules as a device token. The merchant token is issued during the customer-initiated Apple Pay payment, and follow-up charges with the token are merchant-initiated.
Manage merchant tokens
For payments through the Payment Form, Payment Page, or Payment Link, Solidgate receives merchant token updates from Apple. When Apple reports that a merchant token is no longer active, Solidgate deactivates every token linked to that merchant token. Recurring payments with a deactivated token are declined, so ask the customer to confirm a new Apple Pay payment.
When the customer cancels the subscription or changes the payment method, deactivate the token by sending the recurring_token in the
deactivate token
API v1 request. Solidgate deactivates this token and asks Apple to remove the merchant token when no other active token uses it. The request returns an error for a device token, and deactivation cannot be reversed. The request is idempotent, so a repeated request for a deactivated token returns {}.
Limitations
The Apple Pay sandbox issues only device tokens. Merchant tokens are issued only in the production environment.
Existing device tokens are not converted. The customer confirms a new Apple Pay payment with a recurring payment request to receive a merchant token.
Request a merchant token only when the customer subscribes to your product during the Apple Pay payment.