Merchant tokens

An Apple Pay merchant token (MPAN) 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 typesAskCopy

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.

Add Apple Pay merchant tokensAskCopy

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.
2. Pass the applePay object relevant to your MPAN use case.
3. Include relevant parameters for your use case.

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',
    },
  },
});

elements.create('expressCheckout', {
  applePay: {
    automaticReloadPaymentRequest: {
      paymentDescription: 'My automatic reload payment',
      managementURL: 'https://example.com/billing',
      automaticReloadBilling: {
        amount: 2500,
        label: 'Automatic Reload',
        automaticReloadPaymentThresholdAmount: 500,
      },
    },
  },
});

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.

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,
      },
    },
  },
});

const paymentElement = elements.create('payment', {
  applePay: {
    automaticReloadPaymentRequest: {
      paymentDescription: 'My subscription',
      managementURL: 'https://example.com/billing',
      automaticReloadBilling: {
        amount: 2500,
        label: 'Automatic Reload',
        automaticReloadPaymentThresholdAmount: 500,
      },
    },
  },
});

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 notificationsAskCopy

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:

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:

{
  "notificationType": "CARD_REISSUED",
  "merchantIdentifier": "merchant.com.example",
  "tokenUniqueReference": "DNITHE302244754939649",
  "newTokenUniqueReference": "DNITHE302244754939650",
  "previousTokenUniqueReference": "DNITHE302244754939649"
}

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:

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 requirementsAskCopy

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 APIAskCopy

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

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:

{
  "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:

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 monitoringAskCopy

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

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