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.
Update your integration
To use merchant tokens, complete these steps in order:
- Request merchant tokens
Add the recurring payment request to your Apple Pay payment request when the customer subscribes to your product. - Identify token type
Readtransaction.card.pan_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
When a token stops working, ask the customer to confirm a new Apple Pay payment.
Request merchant tokens
Display the Apple Pay button on your side, 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 displays the recurring billing details on the payment sheet. One-time Apple Pay payments do not need this configuration.
The recurring payment request contains:
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
and
order status
API v1
responses and the
card order status
Webhook
webhook return transaction.card.pan_type
mpan
for a merchant token or
dpan
for a device 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
A merchant token stops working when the customer removes it in Wallet or the issuer deletes it. Apple sends these updates to the notification URL that you set, so you manage the token lifecycle on your side. When a merchant token stops working, ask the customer to confirm a new Apple Pay payment.
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.