# Enable a Card for Apple Pay in Issuer’s Mobile App
source: https://developer.mastercard.com/mastercard-processing-digital/documentation/use-cases/enable-card-apple-pay-issuer-mobile-app/index.md

## Overview {#overview}

The use case describes the process for a cardholder to enable a card for Apple Pay using the issuer's mobile application. This process is applicable when Mastercard Processing (MP) exchanges Tokenization Authentication Value (TAV) keys with Mastercard on behalf of the issuer.

## Sequence diagram {#sequence-diagram}

Diagram enable-card-apple-pay

### Explanation {#explanation}

1. The cardholder decides to add a card to Apple Pay in the issuer mobile application.
2. The mobile application calls Apple Wallet to retrieve nounce, nounce signature, and certificates required to prepare Issuer-Initiated Digitization Data (IIDD). Tip: Refer to [Apple Pay documentation](https://developer.apple.com/documentation/passkit/apple_pay) to learn how to integrate the mobile application with Apple Wallet to support this use case.
3. The Apple Wallet returns nounce, nounce signature, and certificates to the mobile application.
4. The mobile application sends the request, with the data fetched in step 3 to generate IIDD Apple Pay, to the issuer server.
5. The issuer server sends the `POST` request to the `/cards/{card_contract_id}/apple-iidds` endpoint with the data received from the mobile application in step 4. Note: Although the `cardContractName` field is optional, your server must send it in the request if you have not sent the following fields while creating the basic structure (client, account contract, and card contract) in the Card Management System (CMS) using the [Core API](https://developer.mastercard.com/mastercard-processing-core/documentation):
   * During the client creation (`createClient`), you have not sent `clientPersonalData.firstName`, `clientPersonalData.lastName`, and `clientPersonalData.shortName` in the request.
   * During the card contract creation (`createCardContract`), you have not sent `cardContractName` in the request.

   Otherwise, the API will return the `CARD_CONTRACT_NAME_IS_MISSING` error reason code.
6. The Mastercard Processing Digital API returns `issuerInitiatedDigitizationData`, a Base64-encoded JSON object containing `activationData`, `ephemeralPublicKey`, and `encryptedPassData`, to the issuer server. Note: To generate IIDD for you, during the onboarding project, Mastercard Processing must first exchange TAV keys with Mastercard MDES on your behalf.
7. The issuer server forwards `issuerInitiatedDigitizationData` from step 6 to the mobile application.
8. The mobile application passes the `encryptedPassData`, the `ephemeralPublicKey`, and the `activationData` to the Apple Wallet Server, where validation checks are performed.
9. The Apple Wallet Server sends the digitization request to the MDES, and regular provisioning flow commences.
10. The MDES returns a successful response that the card can be tokenized and provides terms and conditions (T\&C) to the Apple Wallet.
11. The Apple Wallet displays your T\&C to the cardholder.
12. The cardholder accepts the T\&C in Apple Wallet.
13. The Apple Wallet sends the token activation request to MDES.
14. The MDES sends the pre-digitization message, Tokenization Authorization Request (TAR), to the Mastercard Processing for tokenization decision.
15. After internal checks (that is, card product tokenization eligibility, card status, and expiry date) done by the Mastercard Processing CMS, the Mastercard Processing sends the TAR response back to the MDES with the response code = 00, meaning that the card can be tokenized without any additional authentication. Note: During the onboarding process, the Mastercard Processing applies to every selected wallet a default set of tokenization rules that covers specific functional requirements of wallet providers, schemes, or fraud recommendations linked with, applying the appropriate path whether to:
    * Approve tokenization request (green path, Mastercard Processing returns response code 00 in the TAR response),
    * Decline (red path, Mastercard Processing returns response code 05 in the TAR response),
    * Or approval is subject to further cardholder authentication (yellow or orange path, Mastercard Processing returns response code 85 in the TAR response).

    The use case describes one of the scenarios when a green path is applied. In case of a yellow or orange path, you must configure cardholder identification and verification (ID\&V) methods that are supported by you and the MDES:
    * Authentication by an activation code generated by the MDES and delivered to the cardholder in SMS (by Mastercard Processing or by you) or e-mail (by you).
    * Authentication by your call center.
    * Authentication by your website.
    * Authentication by your mobile application. It is not recommended to use your mobile application both for push provisioning and the ID\&V method. It is recommended for tokenization initiated in the wallet application.
    Tip: Any time during the card lifecycle, you can use the [Core API `setCardContractClassifier`](https://developer.mastercard.com/mastercard-processing-core/documentation/use-cases/classifiers-and-parameters-management/set-classifier/) to override the tokenization rules to always approve the tokenization attempt or always decline the tokenization attempt for a specific card. To do that, you must pass `TKN_PAN_AC` as a `classifier_code` path parameter with the appropriate `classifierValue` value in the request body:
    * `BLACKLIST`: Always decline the tokenization in the TAR response.
    * `NORMAL`: TAR response depends on the tokenization rules.
    * `WHITELIST`: Always approve the tokenization in the TAR response.
16. The Mastercard Processing concurrently sends the TAR notification to the issuer server.
17. The MDES returns the pre-digitization TAR response to the Apple Wallet Server. The pre-digitization TAR response contains the following details:

* Token number (last four digits).
* Token unique reference (TUR).
* Token expiry date.
* Response code indicating that the token can be activated without additional ID\&V method.

18. The MDES sends the Tokenization Complete Notification (TCN) to the Mastercard Processing.
19. The Mastercard Processing sends the TCN acknowledgment to MDES.
20. The Mastercard Processing concurrently sends the TCN notification to the issuer server. Note: Optionally, Mastercard Processing can send an SMS to the cardholder with confirmation that the card has been added to Apple Pay.
21. The MDES sends the TCN notification to the Apple Wallet Server, informing that the token has been activated.
22. The cardholder is notified in Apple Wallet that the card has been activated in Apple Wallet. Note: Not all interactions between the Apple Wallet and Apple Wallet Server have been described in the diagram. Refer to the Apple Pay detailed documentation for the detailed internal flows. Tip: You can use the [Core API `setContractCustomData`](https://developer.mastercard.com/mastercard-processing-core/documentation/use-cases/data-management/add-update-custom-data/) to display card art, coherent with product configuration in MDES, to the cardholder. To do that, you must send the `setContractCustomData` request with the following request body:

    ```JSON
    [
      {
        "tagContainer": "ADD_INFO_01",
        "tagName": "MDES_ISS_ID",
        "tagValue": "Product Configuration ID"
      }
    ]
    ```

    In the `tagValue` field, you must send the Issuer Product Configuration ID created in the Product Configuration Profiles in the MDES Manager you want to use for a specified card contract. Suppose the `MDES_ISS_ID` custom data tag is set in the CMS for the card contract. In that case, Mastercard Processing will send the Issuer Product Configuration ID in the TAR response for a specified card contract to override the default profile defined in the MDES.

Refer to [Sandbox testing](https://developer.mastercard.com/mastercard-processing-digital/documentation/sandbox-testing/enable-card-for-apple-pay/index.md) for more information on how to execute the use case in the Sandbox environment.

## Endpoint {#endpoint}


API Reference: `POST /cards/{card_contract_id}/apple-iidds`