<!--
{
  "availability" : [
    "App Store Connect API: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "ApplePayMerchantTokenManagementAPI",
  "identifier" : "/documentation/MerchantTokenNotificationServices",
  "metadataVersion" : "0.1.0",
  "role" : "Web Service",
  "symbol" : {
    "kind" : "Web Service",
    "modules" : [
      "Apple Pay Merchant Token Management API"
    ],
    "preciseIdentifier" : "MerchantTokenNotificationServices"
  },
  "title" : "Apple Pay Merchant Token Management API"
}
-->

# Apple Pay Merchant Token Management API

Retrieve and manage payment life-cycle events for your Apple Pay merchant tokens.

## Overview

The Apple Pay Merchant Token Management API is a REST API that enables merchants to get the details of a life-cycle event after receiving a merchant token event notification. You can also use this API to inform Apple Pay servers to invalidate your token when it’s no longer in use.

Merchant tokens offer a reliable solution for taking recurring, deferred, and automatic reload payments with Apple Pay. Users can manage their merchant tokens in Wallet. You can enrich the token management experience by providing usage information, using the [`Apple Pay Merchant Token Usage Information API`](/documentation/ApplePayMerchantTokenUsageInformation). This helps users understand past payments and keep track of upcoming payments.

Apple Pay utilizes a tap-and-pull model to deliver events related to merchant tokens. In this process, the Apple Pay server notifies you of an event. Then you can subsequently retrieve the event details using the provided `eventId`. You can access the event details for seven days. The API between the device and you, the merchant, requires Transport Layer Security (TLS), and the device presents the merchant-provided `authenticationToken` to authenticate requests.

In addition, you can call the Apple Pay server to unlink Merchant Payment Account Numbers (MPANs). Access to the APIs between the Apple Pay server and the merchant requires mutual TLS.

A *merchant token* associates a payment card, merchant, and user. Apple Pay issues a merchant token when a customer initiates a purchase using Apple Pay in your app or on your website. When your app or website creates a payment request for a recurring payment or an automatic reload payment, it passes your server’s notification URL in the `tokenNotificationURL` parameter. For more information about `tokenNotificationURL`, see <doc://com.apple.documentation/documentation/PassKit/PKAutomaticReloadPaymentRequest>, <doc://com.apple.documentation/documentation/PassKit/PKRecurringPaymentRequest>, <doc://com.apple.documentation/documentation/ApplePayontheWeb/ApplePayAutomaticReloadPaymentRequest>, <doc://com.apple.documentation/documentation/ApplePayontheWeb/ApplePayRecurringPaymentRequest>, <doc://com.apple.documentation/documentation/PassKit/PKDeferredPaymentRequest>, and <doc://com.apple.documentation/documentation/ApplePayontheWeb/ApplePayDeferredPaymentRequest>.

If a life-cycle event affects the token — for example, the card’s expiration date changes, or the user or issuer deletes the token — Apple Pay sends you a notification with an event identifier to that `tokenNotificationURL`. You retrieve the details of the event by calling [`Get Details of a Merchant Token Event`](/documentation/MerchantTokenNotificationServices/Merchant-Token-Event-Retrieval) with the event identifier.

## Topics

### Essentials

  <doc://com.apple.applepaymerchanttokenmanagementapi/documentation/ApplePayMerchantTokenManagementAPI/adding-merchant-token-usage-information>

[`Apple Pay Merchant Token Usage Information API`](/documentation/ApplePayMerchantTokenUsageInformation)

Add details about your merchant token usage information package.

### Merchant token notification handling

  <doc://com.apple.applepaymerchanttokenmanagementapi/documentation/ApplePayMerchantTokenManagementAPI/receiving-and-handling-merchant-token-notifications>

[`Send Merchant Token Event`](/documentation/MerchantTokenNotificationServices/Send-Merchant-Token-Event)

Receive and handle merchant token life-cycle updates from Apple Pay.

[`Update Merchant Metadata`](/documentation/MerchantTokenNotificationServices/Update-Merchant-Metadata)

Update the merchant token’s notification URL.

### Merchant token event retrieval

[`Get Details of a Merchant Token Event`](/documentation/MerchantTokenNotificationServices/Merchant-Token-Event-Retrieval)

Get the details of a merchant token event after receiving a notification.

[`MerchantTokenEventResponse`](/documentation/MerchantTokenNotificationServices/MerchantTokenEventResponse)

A response body that contains information about a life-cycle event for a merchant token.

[`MerchantTokenMetadata`](/documentation/MerchantTokenNotificationServices/MerchantTokenMetadata)

The card information related to a merchant token, including its card art and metadata.

[`CardArt`](/documentation/MerchantTokenNotificationServices/CardArt)

Data for displaying art to represent a card.

[`CardMetadata`](/documentation/MerchantTokenNotificationServices/CardMetadata)

Data about the card, including its expiration date and suffix.

### Merchant token usage information

[`Retrieve Merchant Token Public Key`](/documentation/MerchantTokenNotificationServices/Retrieve-Merchant-Token-Public-Key)

Get the merchant token public key.

[`MerchantToken Usage Data Availability Notification`](/documentation/MerchantTokenNotificationServices/MerchantToken-Usage-Data-Availability-Notification)

Notify Apple servers that the user’s devices can retrieve merchant token usage information.

[`MerchantTokenUsageDataAvailabilityNotificationRequest`](/documentation/MerchantTokenNotificationServices/MerchantTokenUsageDataAvailabilityNotificationRequest)

The data for the merchant token usage data availability notification request.

[`Get MerchantToken Usage Information Package`](/documentation/MerchantTokenNotificationServices/Get-MerchantToken-Usage-Information-Package)

Retrieve the merchant token usage information package from the merchant server.

[`GetMerchantTokenUsageInformationPackageResponse`](/documentation/MerchantTokenNotificationServices/GetMerchantTokenUsageInformationPackageResponse)

The encrypted merchant token usage information package.

[`AutomaticReloadPaymentDetails`](/documentation/ApplePayMerchantTokenUsageInformation/AutomaticReloadPaymentDetails)

Details about an automatic reload payment.

[`CurrencyAmount`](/documentation/ApplePayMerchantTokenUsageInformation/CurrencyAmount)

An amount of money.

[`DeferredPaymentDetails`](/documentation/ApplePayMerchantTokenUsageInformation/DeferredPaymentDetails)

Details about a deferred payment, such as a hotel booking or a preorder.

[`PastPayment`](/documentation/ApplePayMerchantTokenUsageInformation/PastPayment)

A past payment.

[`PaymentIssueDetails`](/documentation/ApplePayMerchantTokenUsageInformation/PaymentIssueDetails)

Details about a payment issue, such as a declined payment.

[`RecurringPaymentDetails`](/documentation/ApplePayMerchantTokenUsageInformation/RecurringPaymentDetails)

Details about a recurring payment, typically a subscription.

[`UpcomingPayment`](/documentation/ApplePayMerchantTokenUsageInformation/UpcomingPayment)

An upcoming payment.

[`UsageInformation`](/documentation/ApplePayMerchantTokenUsageInformation/UsageInformation)

Information about the usage of a merchant token, such as past and upcoming payments.

### Merchant token invalidation

[`Invalidate a Merchant Token`](/documentation/MerchantTokenNotificationServices/Unlinking-MerchantToken)

Invalidate a merchant token associated with your merchant identifier, making it invalid for future transaction authorizations.

[`MerchantTokenUnlinkRequest`](/documentation/MerchantTokenNotificationServices/MerchantTokenUnlinkRequest)

The request body you use to invalidate a merchant token.

### Error handling

[`ErrorResponse`](/documentation/MerchantTokenNotificationServices/ErrorResponse)

Information about errors that the API returns in the response body whenever an API request is unsuccessful.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)