# Merchant tokens > Learn how to use Apple Pay merchant tokens for recurring, deferred, and automatic reload payments. > **Capability required — Recurring tier.** Merchant tokens (MPANs) require the `apple_pay_recurring` capability on your VINR account. Contact your VINR account manager to enable it. An [Apple Pay merchant token (MPAN)](https://developer.apple.com/apple-pay/merchant-tokens/) ties together a payment card, a business, and a customer, and enables the wallet holder to manage access to a card stored in their Apple wallet. Apple Pay's latest guidelines recommend merchant tokens over device tokens (DPANs) because merchant tokens: - Allow for continuity across multiple devices - Enable recurring payments independent of a device - Keep payment information active in a new device even when it's removed from a lost or stolen device ## Merchant token types You can use Apple Pay to request an MPAN in three ways. Each type of request has different parameters that affect how the user is presented with Apple Wallet. Almost all request types provide the option to supply a `managementURL`, which routes customers to a webpage to manage their payment methods. If you request an MPAN and the issuer supports MPAN generation, you receive an MPAN. Otherwise, you receive a DPAN. | MPAN request type | Use case | Support | | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | Recurring [PKRecurringPaymentRequest](https://developer.apple.com/documentation/passkit/pkrecurringpaymentrequest) | Issues an MPAN for use in a recurring payment such as a subscription. | Apple Pay on the Web · iOS > v16.0 | | Automatic reload [PKAutomaticReloadPaymentRequest](https://developer.apple.com/documentation/passkit/pkautomaticreloadpaymentrequest) | Issues an MPAN for use in a store card top-up or prepaid account. `automaticReloadBilling` shows billing details when you present Apple Pay. | Apple Pay on the Web · iOS > v16.0 | | Deferred payment [PKDeferredPaymentRequest](https://developer.apple.com/documentation/passkit/pkdeferredpaymentrequest) | Issues an MPAN for use in reservations such as hotels. `freeCancellationDate` shows the cancellation deadline. `billingAgreement` shows the terms of service. | Apple Pay on the Web · Xcode 14.3 · iOS > v16.4 | ## Add Apple Pay merchant tokens You can add a merchant token when presenting Apple Pay in the Express Checkout Element, web Payment Element, and mobile Payment Element. VINR automatically handles merchant token requests in VINR Checkout integrations. ### Express Checkout Element 1. Set up your [Express Checkout Element integration](/docs/payments/payment-methods/add-payment-methods/wallets/apple-pay). 2. Pass the `applePay` object relevant to your MPAN use case. 3. Include relevant parameters for your use case. ##### Recurring payments ```javascript elements.create('expressCheckout', { applePay: { recurringPaymentRequest: { paymentDescription: 'Standard Subscription', regularBilling: { amount: 1000, label: 'Standard Package', recurringPaymentStartDate: new Date('2023-03-31'), recurringPaymentEndDate: new Date('2024-03-31'), recurringPaymentIntervalUnit: 'year', recurringPaymentIntervalCount: 1, }, billingAgreement: 'billing agreement', managementURL: 'https://example.com/billing', }, }, }); ``` ##### Automatic reload ```javascript elements.create('expressCheckout', { applePay: { automaticReloadPaymentRequest: { paymentDescription: 'My automatic reload payment', managementURL: 'https://example.com/billing', automaticReloadBilling: { amount: 2500, label: 'Automatic Reload', automaticReloadPaymentThresholdAmount: 500, }, }, }, }); ``` ##### Deferred payment ```javascript elements.create('expressCheckout', { applePay: { deferredPaymentRequest: { paymentDescription: 'My deferred payment', managementURL: 'https://example.com/billing', deferredBilling: { amount: 2500, label: 'Deferred Fee', deferredPaymentDate: new Date('2024-01-05'), }, }, }, }); ``` ### Web Payment Element 1. Create an instance of the Payment Element. 2. Pass the `applePay` object relevant to your MPAN use case. 3. Include relevant parameters for your use case. ##### Recurring payments ```javascript const paymentElement = elements.create('payment', { applePay: { recurringPaymentRequest: { paymentDescription: 'My subscription', managementURL: 'https://example.com/billing', regularBilling: { amount: 2500, label: 'Monthly subscription fee', recurringPaymentIntervalUnit: 'month', recurringPaymentIntervalCount: 1, }, }, }, }); ``` ##### Automatic reload ```javascript const paymentElement = elements.create('payment', { applePay: { automaticReloadPaymentRequest: { paymentDescription: 'My subscription', managementURL: 'https://example.com/billing', automaticReloadBilling: { amount: 2500, label: 'Automatic Reload', automaticReloadPaymentThresholdAmount: 500, }, }, }, }); ``` ##### Deferred payment ```javascript const paymentElement = elements.create('payment', { applePay: { deferredPaymentRequest: { paymentDescription: 'My deferred payment', managementURL: 'https://example.com/billing', deferredBilling: { amount: 2500, label: 'Deferred Fee', deferredPaymentDate: new Date('2024-01-05'), }, }, }, }); ``` ## Token lifecycle notifications Apple sends lifecycle events to your `tokenNotificationURL` when a card linked to an MPAN changes — for example, when a card is re-issued, expires, or is removed. Handle these notifications to keep recurring billing working without requiring the customer to re-enter payment details. ### Register your tokenNotificationURL Pass `tokenNotificationURL` when creating an MPAN request. VINR forwards this to Apple: ```javascript elements.create('expressCheckout', { applePay: { recurringPaymentRequest: { paymentDescription: 'Standard Subscription', managementURL: 'https://example.com/billing', tokenNotificationURL: 'https://api.example.com/apple-pay/token-notifications', regularBilling: { amount: 1000, label: 'Standard Package', recurringPaymentIntervalUnit: 'month', recurringPaymentIntervalCount: 1, }, }, }, }); ``` The URL must be HTTPS and publicly reachable by Apple's servers. ### Handle notification events Apple sends a `POST` request with a JSON body to your `tokenNotificationURL`: ```json { "notificationType": "CARD_REISSUED", "merchantIdentifier": "merchant.com.example", "tokenUniqueReference": "DNITHE302244754939649", "newTokenUniqueReference": "DNITHE302244754939650", "previousTokenUniqueReference": "DNITHE302244754939649" } ``` | `notificationType` | What happened | Action | | ---------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `CARD_REISSUED` | Card was re-issued (new card number, same account). A new MPAN is issued. | Update the stored MPAN reference to `newTokenUniqueReference`. No customer action needed. | | `CARD_EXPIRY_UPDATED` | Card expiry date was updated. | No action needed — the MPAN continues to work. | | `TOKEN_DELETED` | Customer removed the card from Apple Wallet or revoked merchant access. | Mark the payment method as invalid. Notify the customer to re-add a payment method. | | `TOKEN_STATUS_CHANGED` | MPAN was suspended or resumed by the issuer. | Check the `tokenStatus` field and pause or resume billing accordingly. | Respond with `200 OK` to acknowledge receipt. Apple will retry on non-2xx responses. ### Validate Apple's signature Apple signs notification requests with a certificate from its PKI. Verify the `x-apple-pay-token-notification-signature` header before processing: ```javascript import crypto from 'crypto'; function verifyApplePayNotification(body, signature, applePublicKey) { const verifier = crypto.createVerify('SHA256'); verifier.update(body); return verifier.verify(applePublicKey, signature, 'base64'); } ``` Reject any request that fails signature verification with `401 Unauthorized`. ## managementURL requirements `managementURL` is required for all MPAN request types (recurring, deferred, auto-reload). It must point to a page where the customer can: - View the payment method associated with the recurring agreement - Update or replace the payment method - Cancel or revoke the recurring agreement Apple enforces this requirement — omitting or providing an unreachable URL causes the MPAN request to fail on some issuer/network combinations. ## Merchant Token Management API VINR provides a centralised API for querying and managing MPAN state across your merchant account, so you don't need to maintain your own token registry. ### List tokens for a customer ```bash curl https://api.vinr.com/v1/customers/cus_123/payment_methods?type=card&wallet=apple_pay \ -u YOUR_SECRET_KEY: ``` Each returned payment method includes: ```json { "id": "pm_123", "type": "card", "card": { "wallet": { "type": "apple_pay", "apple_pay": { "token_type": "mpan", "token_unique_reference": "DNITHE302244754939649", "token_status": "active" } } } } ``` ### Deactivate a token If a customer revokes access or you receive a `TOKEN_DELETED` notification, deactivate the payment method: ```bash curl https://api.vinr.com/v1/payment_methods/pm_123/deactivate \ -u YOUR_SECRET_KEY: \ -X POST ``` Deactivated payment methods cannot be used for new charges. Existing subscriptions linked to the payment method will transition to `past_due` and trigger the dunning flow configured on your account. ## Merchant token auth rate monitoring You can track MPAN authorization rates in two ways: **VINR Dashboard** — Go to **Analytics → Payment methods** and filter by `wallet: apple_pay`. The auth rate metric there breaks down by token type when MPAN capability is enabled on your account. **Data warehouse** — If you export VINR data to your own analytics environment, the `charges` table contains a `card_token_type` enum field (`mpan` or `dpan`) and a `card_tokenization_method` field. Use these to calculate MPAN-specific auth rates in your data warehouse (Redshift, BigQuery, Snowflake, etc.): > The query below runs against exported VINR data in a data warehouse — it does not run in the VINR Dashboard or via the VINR API. Column names and table structure match the VINR data export schema. ```sql -- Deduplicated MPAN auth rate (data warehouse query) 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' AND c.card_token_type = 'mpan' -- Deduplicate multiple manual retries to a single representative attempt AND is_final_attempt ```