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

## Overview {#overview}

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

## Sequence diagram {#sequence-diagram}

Diagram enable-card-samsung-pay

### Explanation {#explanation}

1. The cardholder decides to add a card to Samsung Pay in the issuer mobile application.
2. The mobile application sends the request to the issuer server to generate an Issuer-Initiated Digitization Data (IIDD) for Samsung Pay.
3. The issuer server sends the `POST` request to the `/cards/{card_contract_id}/android-iidds` endpoint with the `SAMSUNG_PAY` value in the `walletSelector` field in the request body. Note: Although the `cardContractName` field is optional, your server must send it in the request if, in creating a basic structure (client, account contract, and card contract) in the Card Management System using the [Core API](https://developer.mastercard.com/mastercard-processing-core/documentation/), you have not sent the following fields:
   * 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.
4. The Mastercard Processing Digital API returns `issuerInitiatedDigitizationData`, a Base64-encoded JSON object containing data required for push provisioning, 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.
5. The issuer server forwards `issuerInitiatedDigitazationData` from step 4 to the mobile application.
6. The mobile application sends the digitization request to Samsung Wallet with the IIDD from step 5. Tip: Refer to [Samsung Pay documentation](https://pay.samsung.com/developers) to learn how to integrate your mobile application with the Samsung Wallet to support this use case.
7. The Samsung Wallet Server sends the request to the MDES to check if the card is eligible to be tokenized.
8. The MDES returns a successful response that the card can be tokenized and provides terms and conditions (T\&C) to the Samsung Wallet.
9. The Samsung Wallet displays your T\&C to the cardholder.
10. The cardholder accepts T\&C in Samsung Wallet.
11. The Samsung Wallet Server sends the token activation request to the MDES.
12. The MDES sends the pre-digitization message, Tokenization Authorization Request (TAR), to the Mastercard Processing for tokenization decision.
13. 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 activation code generated by the MDES and delivered to the cardholder by SMS (by Mastercard Processing or by you) or e-mail (by you).
    * Authentication by your call center.
    * 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 the specific card to always approve the tokenization attempt or always decline the tokenization attempt. 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.
14. The Mastercard Processing concurrently sends a TAR notification to the issuer server.
15. The MDES returns the pre-digitization TAR response to the Samsung Wallet Server. The pre-digitization TAR response contains:

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

16. The MDES sends the Tokenization Complete Notification (TCN) to the Mastercard Processing.
17. The Mastercard Processing sends the TCN acknowledgment to MDES.
18. 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 their card has been added to Samsung Pay.
19. The MDES sends the TCN notification to the Samsung Wallet, informing that the token has been activated.
20. The cardholder is notified in the Samsung Wallet that the card has been activated in Samsung Wallet. Note: Not all interactions between the Samsung Wallet and Samsung Wallet Server have been described in the diagram. Refer to the Samsung 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-samsung-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}/android-iidds`