# Issuer Interface Implementation Guide - Pull Provisioning source: https://developer.mastercard.com/mdes-token-connect/documentation/tutorials-and-guides/pull-provisioning-issuer-implementation-guide/index.md This guide explains the enhancements for issuer's user interfaces to support the MDES Token Connect framework. It provides developers with a detailed user experience of pull provisioning an account to the wallet. ## Pre-requisite {#pre-requisite} **Onboarding:** To enable pull provisioning, issuers must complete the [onboarding](https://developer.mastercard.com/mdes-token-connect/documentation/tutorials-and-guides/index.md#onboarding) process and provide the following information: * **Display Name**: The name should be displayed on wallet screen to identify the issuer. * **Logo Images**: The logo images (PNG and SVG format) to display on wallet screen to recognize issuer. * **Country**: Share a list of countries where the issuer wants to support pull provisioning use case. * **Supported Pull Methods** : Issuers must specify one or more of the following supported pull methods: * **Android** - The issuer supports app-to-app and web-to-app communication on Android same device. * **iOS** - The Token Requestor supports app-to-app and web-to-app communication on iOS same device. * **Web** - The Token Requestor supports web-to-web or app-to-web communication on same device. **The issuer must also support** * Normal provisioning (tokenization) for the wallet. * Token Connect Push Provisioning. ## Ready to Receive Pull Provisioning Request {#ready-to-receive-pull-provisioning-request} The issuer must be prepared to receive a cardholder redirection request via one of the supported push methods. Upon receiving the redirection, the issuer is responsible for authenticating the cardholder, if required, in accordance with its own security policies. Mastercard considers the cardholder to be authenticated once the issuer shares the relevant information with Mastercard. ## Data ready to receive from the Token Requestor {#data-ready-to-receive-from-the-token-requestor} | Parameter | Description | |----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Token Requestor ID | MDES generated and shared identification for Token Requestor. | | Token Requestor Session ID | Session ID of the Token Requestor. | | Locale | Locale information on the Token Requestor user experience. | | User Interface | Token Requestor user interface where currently user is logged in and initiating the pull provisioning. Possible values are: * Android: User is logged in to the Token Requestor Android mobile application. * iOS: User is logged in to the Token Requestor iOS mobile application. * Web: User is logged in to the Token Requestor web portal is running on the web browser. | Sample URL: `moonbank://pullProvision?trid=50000&sessionId=asdf23432423safsa2323&locale=en_US&userInterface=ANDROID` Note: Supply Token Requestor ID and Token Requestor Session ID to MDES in [pushMultipleAccounts](https://developer.mastercard.com/mdes-token-connect/documentation/api-reference/index.md) ### Present Eligible User Accounts {#present-eligible-user-accounts} The figure demonstrates how a user can select a card/account to initiate a pull provisioning request. ![alt text](https://static.developer.mastercard.com/content/mdes-token-connect/documentation/tutorials-and-guides/img/issuer-choosecard-small.png "Integration") Note: Do not give option to cardholder to choose a Token Requestor. ## User Experience {#user-experience} To enhance the user experience, implement the following flow: #### Display Token Requestor Name {#display-token-requestor-name} * Issuer will display Token Requestor name on the screen. Issuer can retrieve Token Requestor name from previously stored Token Requestor information. * Issuer will give an option to cancel the usecase. #### Option to Cancel {#option-to-cancel} If an cardholder is canceling the usecase, then the issuer will redirect back to the Token Requestor with the following information. * Status = CANCELLED * Token Requestor Session ID `Sample URL: mywallet://pushProvision?status=CANCELLED&sessionId=asdf23432423safsa2323` #### Authentication Failure {#authentication-failure} If cardholder authentication fails, the issuer provides an error message to the cardholder and redirects back to the Token Requestor with the following information. * Status = ERROR * Error Description = AUTH_FAILED * Token Reqeustor Session ID `Sample URL: mywallet://pushProvision?status=ERROR&errDescription=AUTH_FAILED&sessionId=asdf23432423safsa2323` #### General Error Handling {#general-error-handling} In case of any other errors, the issuer must provide error message to the cardholder and redirect back to the Token Requestor with the following information. * Status = ERROR * Error Description * Token Requestor Session ID `Sample URL: mywallet://pushProvision?status=ERROR&errDescription=Technical%20Error&sessionId=asdf23432423safsa2323` #### Token Requestor URL Retrieval {#token-requestor-url-retrieval} * The issuer can retrieve the Token Requestor URL from the previously stored Token Requestor information. ## Sending User's Choice to MDES {#sending-users-choice-to-mdes} When a user has sourced cards or financial accounts, they confirm their selection through a user gesture (for example, clicking a button) to continue. The user interface must then transmit the selected choices to the issuer's back-end system. * It is the issuer's responsibility to establish a secure, encrypted communication channel between the user interface and their back-end system. It is assumed that such a channel already exists and can be readily utilized. * Upon receiving the user's selection, the issuer's back-end system must invoke the [pushMultipleAccounts](https://developer.mastercard.com/mdes-token-connect/documentation/api-reference/index.md) function from the MDES Token Connect API to initiate the push provisioning process. * The following parameters and account details must be included in the API call: * Token Requestor Identifier (TRID) * Token Requestor Session ID * Selected cards and/or financial accounts details * The MDES response will include a list of `pushAccountReceipt` objects, each representing a card or account to be provisioned. * The issuer must then transmit these receipts to the Token Requestor. The Token Requestor will use the receipts instead of the original card/account data to request tokenization from MDES. * Each `pushAccountReceipt` is valid for 15 minutes from the time of issuance. * The response may also include one or more URI(s) that the issuer can use to redirect the user to the Token Requestor's user interface. Note: Supply Token Requestor ID and Token Requestor Session ID to MDES in [pushMultipleAccounts](https://developer.mastercard.com/mdes-token-connect/documentation/api-reference/index.md) * [Supply Account Holder Data to the Token Requestor](https://developer.mastercard.com/mdes-token-connect/documentation/tutorials-and-guides/issuer-implementation-guide/index.md#supply-account-holder-data-to-the-token-requestor) * [Redirect to the Token Requestor interface](https://developer.mastercard.com/mdes-token-connect/documentation/tutorials-and-guides/issuer-implementation-guide/index.md#redirect-to-the-token-requestor-interface) ## What's new {#whats-new} Significant changes are tracked here: | Date | Description of Change | |-------------|-----------------------| | Nov 1, 2025 | Initial Document |