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
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. - Identify token type
Readpan_typein the Apple Pay API v1 and order status API v1 responses and the card order status Webhook webhook to check whether you received a merchant token or a device token. - Charge with merchant tokens
Send follow-up charges with the receivedtokenin 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
PasspaymentIntent.apple.recurring_payment_requestfor the Apple Pay button andpaymentIntent.apple_pay_merchant_name, which is required to receive a merchant token. - Payment Page and Payment Link
Passapple.recurring_payment_requestin the create payment page API v1 or create payment link API v1 request.
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
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
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.
- Google Pay does not issue merchant tokens.