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, complete these steps in order:

  1. Request merchant tokens
    Add the recurring payment request to your Apple Pay payment request when the customer subscribes to your product.
  2. Identify token type
    Read transaction.card.pan_type in 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.
  3. Charge with merchant tokens
    Send follow-up charges with the received token in the recurring API v1 request as merchant-initiated payments.
  4. 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 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:

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 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 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.