# On-Behalf of Program source: https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md This guide covers use cases for a payment gateway implementing the [MDES Digital Enablement API](https://developer.mastercard.com/mdes-digital-enablement/documentation/) on-behalf-of model to provide tokenization services for Mastercard and Maestro Account PANs. The payment gateway can provide tokenization services directly on behalf of their merchants. This guide should be used alongside the MDES Digital Enablement API documentation and other applicable documentation. The payment gateway acts as an MDES Token Requestor and benefits from connectivity to all participating Mastercard issuers, allowing Mastercard and Maestro cards from those issuers to be tokenized and stored. This guide explains how a payment gateway can use MDES tokens, in place of PANs, as the basis for their own account PAN tokenization system. The uses cases contained in this guide support the following functions: * [Tokenizing Account PANs](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#tokenizing-account-pans) -- Tokenize an Account PAN by replacing it with a unique token, which represents the PAN but provides additional security benefits. * [Managing Tokens](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#managing-tokens) -- Handle consumer or issuer-initiated changes to the status of an MDES token or associated Account PAN. For example, when the issuer closes the consumer's card account, updates the Account PAN, or the payment gateway deletes a gateway token and its associated MDES token. * [Displaying Payment Information](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#displaying-payment-info) - Fetch card art for tokenized Account PANs for display by their merchants. * [Making Payments](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#making-payments) -- When a card has been tokenized, the payment gateway can use the TUR returned by MDES to obtain a cryptogram and the MDES token. This cryptogram must be submitted with the token to process a payment. Note it is also possible to store the token and cryptogram for future payments. * [Customer Service](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#customer-service) -- Facilitate customer service scenarios when Account PANs have been tokenized. This guide includes illustrative flows for these use cases. However, the design of a payment gateway's tokenization service is completely under their control subject to the constraints imposed by PCI-DSS compliance, the requirements and features of the [MDES Digital Enablement API](https://developer.mastercard.com/mdes-digital-enablement/documentation/index.md) , and the mandatory certification requirements for MDES for On-behalf of Token Requestors. The terms **card** and **Account PAN** are used interchangeably in this guide. Note: For full details of implementation certification requirements and recommendations, refer to the *On-behalf of Token Requestor Self-Assessment Questionnaire*. ## Tokenizing Account PANs {#tokenizing-account-pans} There are three scenarios in which an Account PAN can be tokenized: * [Tokenization while Transacting](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#tokenization-while-transacting)-- Creating a token when a consumer (or merchant) initiates a transaction on the account PAN already stored on file or by adding a new card during the checkout flow. * [Add Card Tokenization](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#add-card-tokenization) -- Creating MDES tokens as a result of a consumer action, such as when a consumer adds a new account PAN to their profile on a merchant website. This could occur when a consumer opts to store new payment details during checkout or when the consumer modifies the payment details associated with their profile. The payment gateway uses MDES to tokenize an account PAN and store a reference to the resulting MDES token. Typically, the payment gateway will then return a gateway token to the merchant. The MDES token reference stored by the payment gateway can then act as the payment instrument for the gateway token. It is also possible for a payment gateway to return a MDES network token and cryptogram to the merchant. In this case, the merchant will then have the option to process the payment authorization request through a different payment gateway. * [Existing Card Tokenization](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#existing-card-tokenization) -- Creating MDES tokens for account PANs stored on file. A payment gateway will typically use this option to replace Account PANs used as payment instruments for existing payment gateway tokens with MDES tokens. Note: The tokenize response returns an active token and token unique reference (TUR). Payment gateways can store the TUR to request for a token and cryptogram in the Transact API. If the account PAN being tokenized is in an account range that has not yet been enabled by the issuer for MDES for Merchants, the Account PAN will not be tokenized and MDES will return a PAN_INELIGIBLE response. ### Using Different Token Requestor IDs {#using-different-token-requestor-ids} In the MDES for Merchants on-behalf-of program, the payment gateway will need to use a different Token Requestor ID (TRID) for each merchant when making MDES API requests as an OBOTR (On-behalf-of Token Requestor). The OBOTR must therefore use the specific TRID allocated by MDES for this particular merchant during the onboarding process. When acting as an OBOTR for the MDES for Merchants program, the OBOTR must maintain a mapping between the Token Unique Reference (TUR) returned in the MDES response to the Tokenize request and the TRID used to request this token. Finally, the OBOTR will need to maintain a mapping between the unique ID it allocates internally for each merchant/the Merchant ID and the TRID. The OBOTR will use these mappings to update the internal status information it stores for each active MDES token. The following information should typically be retained and updated (with the information received in NTU requests) for each MDES token: * Token Status * Token Expiry Date * accountPanSuffix (last 4 digits of the account PAN associated with this token) * productConfig (contains customer service details and card art Asset ID information for the account PAN associated with the token) * cached card art for the token. If the payment gateway is using an MDES token as the underlying payment instrument for each payment gateway token then it will also need to maintain a mapping between these two token types. The following diagram summarizes the MDES for Merchants scenario: ![alt text](https://static.developer.mastercard.com/content/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/img/multiple-trids.png "Two Merchants Two TRIDs") ### Tokenization while Transacting {#tokenization-while-transacting} This use case describes how a token may be created and associated with a consumer profile during the transaction flow. For example: 1. The Consumer logs in to their profile, shops for items and clicks **Checkout**. 2. Your website displays the list of cards that the consumer has on file or an option to enter new card details. 3. The Consumer selects an available card or enters new card details and clicks **Pay**. 4. Your system sends a **Tokenize** request with the encrypted Account PAN details and optional data to support the decision to tokenize. 5. If the account range is enabled for MDES for Merchants, MDES contacts the issuer to check eligibility for tokenization. The issuer then responds with a tokenization decision: approved, additional authentication required, or declined. The response contains the token number in tokenDetails, last 4 digits of Account PAN in tokenInfo, and card art details in the **productConfig** object. The last 4 digits of the token are also returned; however, Mastercard recommends that the merchant only display the Account PAN last 4 digits to the consumer, not the token last 4 digits, as the consumer may not be aware of tokenization. 6. If MDES returns a declined decision in the previous step, you will not be able to tokenize the Account PAN and will need to proceed with the full Account PAN and re-try the tokenization process at a later stage, depending on the error type received. 7. If the tokenization request is not declined, you will receive an active token and TUR (Token Unique Reference). After receiving the Tokenize response, the token has been provisioned. 8. You can then call the Transact API with the TUR to fetch the actual token, token expiry \& cryptogram. The token and cryptogram can then be used for the transaction and associated with the consumer's merchant profile for future use. If you plan to display card art, you should use **Get Asset** requests to obtain (and cache) the card art image assets for display; see [Displaying Tokenized Account PANs](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#displaying-tokenized-account-pans) for more details. Update the state you maintain for this token in your system. See [Making Payments with Tokenized Account PANs](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#making-payments-with-tokenized-account-pans) and [Storing Cryptograms](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#storing-cryptograms) for details on performing the subsequent transactions. Note: The tokenization process may take a few seconds to complete. To avoid latency in tokenization during the consumer checkout flow, you may wish to proceed with the Account PAN for the first consumer transaction and initiate the tokenization process following a successful card add and checkout. Once the consumer's Account PAN is tokenized, the token can be used for subsequent transactions. To reduce the latency, you may choose to use the same responseHost returned in the Tokenize API call to perform Transact API call. Diagram obo-tokenization-while-transacting ### Add Card Tokenization {#add-card-tokenization} This use case describes how a payment gateway can allow a merchant to tokenize a card using MDES for Merchants: 1. The merchant sends a create payment gateway token request to the gateway with card details. 2. The payment gateway, acting as an OBOTR, sends a **Tokenize** request to MDES with the encrypted Account PAN details and optional data to support the decision to tokenize. 3. If the account range is enabled for MDES for Merchants, MDES contacts the account PAN issuer to check eligibility for tokenization and responds with a tokenization decision: approved, additional authentication required, or declined. The response contains the token number in tokenDetails, the last 4 digits of the Account PAN in tokenInfo, and card art details in a **productConfig** object. The last 4 digits of the token are also returned; however, Mastercard recommends that they are not used to represent Account PANs to ensure consumers remain unaware of the tokenization process. 4. If MDES returns a declined decision in the previous step, the OBOTR will not be able to tokenize the Account PAN and will need to decide whether to store the full Account PAN against a newly created payment gateway token or request another card to tokenize, based on PCI-DSS considerations. This business logic is defined solely by the payment gateway. 5. If the tokenization request is not declined, the OBOTR associates the returned token detail with a newly created payment gateway token as the payment instrument for this gateway token. 6. The OBOTR returns the payment gateway token to the merchant. 7. After receiving the Tokenize response, an active token has been provisioned and can be used for payments. The OBOTR will need to use the information received in the NTU request to update the state it stores internally for this MDES token in its system. The token is now active for creating cryptograms and making payments. Additionally, the OBOTR could proceed to make a **Transact** request to obtain the token and cryptogram needed for a later payment authorization request. See [Making Payments with Tokenized Account PANs](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#making-payments-with-tokenized-account-pans) and [Storing Cryptograms](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#storing-cryptograms) for details. **Technical Details:** 1. The merchant sends an account PAN, cardholder name, security or Card Verification Code (CVC) for the card, expiry year and month and billing address in their create PSP Token request to the payment gateway. Account PAN and expiry month and year (if the card has an expiry date) are mandatory; all other fields are optional. 2. The payment gateway, acting as an OBOTR, sends a **Tokenize** request to MDES with the encrypted Account PAN details and optional data provided by the merchant in step 1 to support the decision to tokenize. The OBOTR must use the appropriate token requestor ID for this merchant. Each merchant (in the MDES for Merchants scenario) onboarded by the OBOTR will have a different token requestor ID. Note: Optional fields are used by the card issuer to decide whether to approve or decline tokenization for the card. The OBOTR can include additional information in the optional **decisioningData** object to support the Issuer's decision making process. 3. The OBOTR combines the card data in step 1 with the **source** parameter, which must be set to CARD_ADDED_MANUALLY in this case, to create a JSON **fundingAccountInfo** object for the card data; see the first code sample below these steps. 4. The OBOTR generates a random single-use 128/256-bit AES encryption key and a random 128-bit initialization vector (**iv** ) using a cryptographically-secure random number generator or a Hardware Security Module (HSM). Encrypt the full JSON object string from step 2 (including the curly brackets) using AES CBC mode and the AES encryption key. The block size for this algorithm is 16 bytes or 128 bits. Pad the JSON string to the nearest multiple of 16 bytes using PKCS #7 padding and place the hex-encoded result in the **encryptedData** parameter as shown below. Insert the hex-encoded initialization vector in the **iv** parameter. See the second code sample below these steps. 5. The OBOTR encrypts the single-use AES key (generated in step 3) using RSA OAEP with their **public** key from the wrapped **encryption** key pair, using either SHA256 or SHA512 as the hash function. The hex-encoded result is sent as the **encryptedKey** parameter (see the code sample). Pass the chosen hashing function as the parameter **oaepHashingAlgorithm** . Add the fingerprint for the public key (do not calculate this value) provided in the OBOTR's Mastercard Developer project as the **publicKeyFingerprint** value; MDES uses this value to identify the correct key to use to decrypt this data. Steps 4 and 5, termed 'wrapped encryption', provide a second layer of security over and above HTTPS for the card data. 6. The OBOTR makes a **Tokenize** request with the fundingAccountInfo object created in steps 4 and 5. Supply **taskId** , **tokenRequestorId** (unique to each merchant onboarded to MDES by the payment gateway), a **requestId** (unique for each request), and **tokenType** = CLOUD. The OBOTR can supply more information to support the decision to tokenize the card using the **decisioningData** object. The **TaskID** can be used to monitor tokenization progress as tokens are provisioned and then activated on the MDES platform after the response in step 7 below. 7. The OBOTR receives the response with the following data: tokenization decision (APPROVED = Tokenization was approved, REQUIRE_ADDITIONAL_AUTHENTICATION = Approved but additional authentication is required, DECLINED = Tokenization was declined), **accountPanSuffix** (the last four digits of the Account PAN), **tokenPanSuffix** (the last four digits of the Token), **tokenExpiry** (the expiry date in mmyy format), and a **tokenUniqueReference** (TUR) which uniquely identifies this MDES token, and **tokenDetails** (tokenNumber, expiryMonth, expiryYear, dataValidUntilTimestamp, and PAR). Note: Currently, MDES creates a token if the issuer tokenization decision is either APPROVED or REQUIRE_ADDITIONAL_AUTHENTICATION. At this time, the OBOTR's system may handle these responses in the same manner. The OBOTR may also receive an **authenticationMethods** object, which it can ignore. 8. If MDES returns a decline decision in the previous step, the OBOTR will not be able to tokenize the card and will need to decide whether to associate the full Account PAN with a newly created payment gateway token or return a failure code to the merchant. 9. If the tokenization request is successful, the OBOTR associates the active token and **tokenUniqueReference** to a newly created payment gateway token and the last four digits of the Account PAN. After the tokenize response, tokens are active and are provisioned within the MDES platform. 10. The OBOTR returns the payment gateway token to the merchant. 11. After receiving the Tokenize response, an active token has been provisioned and can be used for payment. Additionally, the OBOTR can proceed to make a **Transact** request to obtain the token and cryptogram needed for a payment authorization request. See [Making Payments with Tokenized Account PANs](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#making-payments-with-tokenized-account-pans) and [Storing Cryptograms](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#storing-cryptograms) for details. * JSON ```JSON { "accountNumber": "5412345678901234", "expiryMonth": "12", "expiryYear": "20", "source": "CARD_ON_FILE" } ``` * JSON ```JSON "fundingAccountInfo" : { "encryptedPayload" : { "encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E824AA55BA67BF6A", "publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b", "encryptedKey" : "A1B2C3D4E5F6112233445566", "oaepHashingAlgorithm" : "SHA512" } }, ``` Note: * OBOTRs must acknowledge Notify Token Updated requests. To minimize network traffic, OBOTRs should useNotify Token Updated requests to monitor and keep a local copy of token state, rather than repeatedly polling MDES using Get Token requests. * OBOTRs will need to decrypt the **EncryptedPayload.encryptedData** parameter in the **Notify Token Updated** request. The encrypted data contains an array of token objects (in this case just a single token) containing the updated status of each token and any other changes to the token or associated payment account, such as changes to card art, expiry date, and last 4 digits of the Account PAN. The decryption process is the reverse of the encryption process detailed in steps 3 and 4 above, but using the **private** key from the RSA wrapped **decryption** key pair. **API Flow for Adding a Card** Diagram obo-tokenization-new-card-add ### Existing Card Tokenization {#existing-card-tokenization} Existing Card Tokenization is used to create multiple tokens by sending multiple tokenization requests as a bulk process. This is typically used to replace the Account PANs already stored in a card-on-file repository for existing payment gateway tokens with MDES tokens. No consumer action is required. Note: Only one Account PAN can be tokenized per API request When submitting multiple requests to MDES, a payment gateway must ensure: * The speed of tokenization does not exceed the TPS (transaction per second) limit specified by Mastercard. * The submitted PANs are selected on a pseudo-random basis or spread evenly across different account ranges. This ensures an even load across Mastercard issuers and maximizes tokenization performance. **Design Guidelines:** Mastercard recommends that OBOTRs implement one or more strategies during existing card tokenization to optimize the speed at which the card repository can be converted into MDES tokens. For example, when an Account PAN is not within an eligible account range for tokenization (as specified by the issuer), MDES will return a PAN_INELIGIBLE response. In this situation, OBOTRs can filter out other cards with the same first 11 PAN digits. For simplicity, OBOTRs do not need to persist the filter and should purge it after the bulk tokenization process is complete. This basic principle can be used or adapted (as necessary) to fit with the OBOTRs existing processes, technical architecture and environment. **Technical Details:** 1. The OBOTR fetches an Account PAN stored on file for a payment gateway token using an optimization strategy as described above. 2. The OBOTR combines the card data in step 1 with the **source** parameter, which must be set to CARD_ON_FILE in this case, to create a JSON **fundingAccountInfo** object for the card data; see the first code sample below these steps. 3. The OBOTR generates a random single-use 128/256-bit AES encryption key and a random 128-bit initialization vector (**iv** ) using a cryptographically-secure random number generator or an HSM. Encrypt the full JSON object string from step 2 (including the curly brackets) using AES CBC mode and the AES encryption key. The block size for this algorithm is 16 bytes or 128 bits. Pad the JSON string to the nearest multiple of 16 bytes using PKCS #7 padding and place the hex-encoded result in the **encryptedData** parameter as shown below. Insert the hex-encoded initialization vector in the **iv** parameter. See the second code sample below these steps. 4. The OBOTR encrypts the single-use AES key (generated in step 3) using RSA OAEP with the OBOTR's **public** key from the wrapped **encryption** key pair, using either SHA256 or SHA512 as the hash function. The hex-encoded result is sent as the **encryptedKey** parameter (see the code sample). Pass the chosen hashing function as the parameter **oaepHashingAlgorithm** . Add the fingerprint for the public key (do not calculate this value) provided in the Mastercard Developers Center project as the **publicKeyFingerprint** value; MDES uses this value to identify the correct key to use to decrypt this data. Steps 3 and 4, termed 'wrapped encryption', provide a second layer of security over and above HTTPS for the card data. 5. The OBOTR makes a **Tokenize** request with the cardInfo object created in steps 3 and 4. Supply **taskId** , **tokenRequestorId** (unique to the merchant which supplied the PAN), a **requestId** (unique for each request), and **tokenType** = CLOUD. It is possible to supply more information to support the decision to tokenize the card using the **decisioningData** object.The **TaskID** can be used to monitor tokenization progress as tokens are provisioned and activated on the MDES platform after the response in step 6 below. 6. The OBOTR receives a response from MDES with the following data: tokenization decision (APPROVED = Tokenization was approved, REQUIRE_ADDITIONAL_AUTHENTICATION = Approved but additional authentication is required, DECLINED = Tokenization was declined), **accountPanSuffix** (the last four digits of the Account PAN), **tokenPanSuffix** (the last four digits of the token), **tokenExpiry** (the expiry date in mmyy format), and a **tokenUniqueReference** (TUR) which uniquely identifies the token and **tokenDetails** (tokenNumber, expiryMonth, expiryYear, dataValidUntilTimestamp, and PAR). Note: Currently, MDES creates a token if the issuer tokenization decision is either APPROVED or REQUIRE_ADDITIONAL_AUTHENTICATION. At this time, the OBOTR's system may handle these responses in the same manner. The OBOTR may also receive an **authenticationMethods** object, which they can ignore. 7. If tokenization is declined, the OBOTR logs the reason and ends the process for this Account PAN. 8. If the tokenization request is not declined, the OBOTRs associates the active token and **tokenUniqueReference** for this MDES token to a newly created payment gateway token along and the last four digits of the Account PAN. After the tokenize response, tokens are active and are provisioned within the MDES platform. If card art is required for this token, the OBOTR could make **Get Asset** requests using the Asset ID values returned in the **productConfig** object to fetch and cache card and issuer art, etc. 9. After receiving the Tokenize response, an active token has been provisioned and can now be used for payments. If the OBOTR has not recevied the Notify Token Updated request within 1--2 seconds, they can make a request to monitor activation progress using **Get Task Status** and the TaskID from step 3. Additionally, the OBOTR can proceed to make a **Transact** request to obtain the token and cryptogram needed for a payment authorization request. See [Making Payments with Tokenized Account PANs](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#making-payments-with-tokenized-account-pans) and [Storing Cryptograms](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#storing-cryptograms) for details. * JSON ```JSON { "accountNumber": "5412345678901234", "expiryMonth": "12", "expiryYear": "20", "source": "CARD_ON_FILE" } ``` * JSON ```JSON "fundingAccountInfo" : { "encryptedPayload" : { "encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E824AA55BA67BF6A", "publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b", "encryptedKey" : "A1B2C3D4E5F6112233445566", "oaepHashingAlgorithm" : "SHA512" } }, ``` Note: * OBOTRs are required to acknowledge Notify Token Updated requests. To minimize network traffic, they should use Notify Token Updated requests, rather than polling using Get Token requests. * OBOTRs will need to decrypt the **EncryptedPayload.encryptedData** parameter in the **Notify Token Updated** request. The encrypted data contains an array of token objects (in this case just a single token) containing the updated status of each token and any other changes to the token or associated payment account, such as changes to card art, expiry date, and last 4 digits of the Account PAN. The decryption process is the reverse of the encryption process detailed in steps 3 and 4 above, but using the **private** key from the RSA wrapped **decryption** key pair. **API Flow for Tokenizing an Existing Payment Card Repository** Diagram obo-tokenization-existing-card-repo ## Managing Tokens {#managing-tokens} ### Issuer-Initiated Status Updates {#issuer-initiated-status-updates} This use case explains how an OBOTR can receive change notifications relating to a token or the underlying payment account based on the following events: * FPAN replacement within the same account range * FPAN replacement in a different account range * Routine issuer maintenance, such as moving from a 6 to 8-digit BIN, which may result in the token number being updated (even if underlying PAN does not change). * Token expiry extension In addition to these notifications, MDES seamlessly updates the Account PAN it associates with a consumer's token if the consumer loses their card and a new card is issued. This account PAN mapping may also be updated if a new card is issued due to card expiration, fraud, etc. 1. If the OBOTR server receives a **Notify Token Updated** request from MDES, the OBOTR must use the **tokenUniqueReference** value and **tokenInfo** object received to update the details and state stored for the appropriate token (or tokens---multiple tokens can be included in one request). For example, the issuer or consumer could close their card account, causing the token status to change to DEACTIVATED. 2. Send an acknowledgement response to the MDES server identified in the request received in the previous step. Note: OBOTRs are required to acknowledge Notify Token Updated requests. Diagram obo-issuer-account-update **Issuer Account Update** **Technical Details:** 1. Decrypt the **EncryptedPayload.encryptedData** in the **Notify Token Updated** request received from MDES to fetch the array of updated tokens. This is the reverse of the encryption process in steps 3 and 4 of the Technical Details section of the [Add Card Tokenization](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#add-card-tokenization) use case above, but using the **private** key from the RSA wrapped **decryption** key pair. 2. Use the **tokenUniqueReference** value and **tokenInfo** object received for each token to update status information stored for each token by the OBOTR. 3. A **Notify Token Updated** request can also contain information about new or changed card art in the productConfig object returned for each token. If a payment gateway plans to offer merchants the ability to obtain card art for a token, they can also store the **productConfig** information (in particular, the Asset IDs) alongside the state information for each MDES token. Every time the OBOTR identifies a new Asset ID value that has not previously been received, they can download and cache this image for future use. New Asset IDs are always used for both new and changed art, so an OBOTR can cache art for unchanged Asset IDs. The **productConfig** table below (in the next section) lists the different Asset IDs that can be returned. 4. Respond to the MDES server identified in the initial request with a 200 OK HTTP response code and a JSON message body containing the OBOTR server's hostname in the **responseHost** parameter and a unique identifier for this response, **responseId**. 5. In the case of **eventReasonCode = REDIGITIZATION_COMPLETE** , delete the old cryptogram and call **Transact API** to update the token (accountNumber), token expiry (applicationExpiryDate) and cryptogram (de48se43Data). Note: Failure to fetch the new token and other token related information after receiving a **REDIGITIZATION_COMPLETE** notification may cause future transactions to fail. It is important to call Transact to retrieve the latest token information before attempting to perform another transaction. In the case of a Merchant Initiated Transaction (MIT), if the token number has changed, you should restart the series with Security Level Indicator (SLI) value to 246 and establish domain control with a cryptogram. Subsequent transactions may revert to a 247 SLI value. Note: If a Notify Token Updated request fails with a timeout, connection failure, or an HTTP response code of 302, 500, or 503, MDES will automatically retry three times with a wait of up to 5 seconds between each try. If the call has not succeeded after the initial retries, MDES will attempt a second round of three retries, with increasing time intervals between each retry. Between attempts, the system will wait 15 minutes, 30 minutes, and then 2 hours. In the case of a 503 response code, the Retry-After header will be respected if present and will count as a retry. The diagram below shows an example token update notification. In this scenario, a consumer closes their payment account and the Issuer sends a delete account request to MDES. MDES in turn sends a Notify Token Updated request with status DEACTIVATED to the relevant token requestor (in this case, the relevant OBOTR). Diagram obo-issuer-account-delete **Example API Flow for Notify Token Update** #### List of Events which Trigger a Notify Token Update {#list-of-events-which-trigger-a-notify-token-update} Notify Token Updates are only sent in the following circumstances: * Issuer initiated Token lifecycle events: Delete, Suspend and Unsuspend * Token activated by MDES * ProductConfig changes (mainly card art changes) * TokenInfo changes e.g. a PAN change resulting in a change to the accountPanSuffix (typically, the last 4 digits of the PAN) **NOTE**: Notify Token Updates are not sent for Token Requestor initiated lifecycle events e.g. Suspend, Unsuspend, Delete. ### Deleting an MDES Token {#deleting-an-mdes-token} This section explain how a payment gateway can delete an MDES token. 1. The payment gateway, acting as an OBOTR, makes a **Delete** request to MDES containing the **tokenUniqueReference** for the MDES token. The OBOTR must use the TRID associated with the merchant that generated these tokens. 2. If the request is successful, archive the information associated with this token based on the payment gateway's internal policies, update the stored MDES token status for these tokens to DEACTIVATED. 3. Mastercard recommends that OBOTRs delete any cryptograms they may be storing for each MDES token as well as the token itself. OBOTRs should delete all archived information about the token when certain amount of time has passed, such as 2 years. The amount of time will depend on the OBOTR's internal policies and any regulatory requirements. Diagram obo-delete-a-token **API Flow for Deleting an MDES Token** ### Deleting Multiple MDES Tokens {#deleting-multiple-mdes-tokens} This use case describes how a payment gateway, acting as an OBOTR, can delete multiple MDES tokens in one operation. All tokens must be for the same merchant as an OBOTR can only supply a single TRID for each request. **Technical Details:** 1. Make a **Delete** request with an array of **tokenUniqueReference** values for all the MDES Tokens that must be deleted. The OBOTR must use the TRID associated with the merchant that generated these tokens. A single Delete request can delete a maximum of 10 tokens. If more than 10 tokens must be deleted, split the Delete requests into batches. For each Delete request: 1. If the request is successful, the OBOTR must archive the information associated with this token based on their internal policies. The OBOTR must also update the stored MDES token status for these tokens to DEACTIVATED. 2. Mastercard recommends that OBOTRs delete any cryptograms they may be storing for each MDES token as well as the token itself. OBOTRs should delete all archived information about the token when a certain amount of time has passed since the delete request, such as 2 years. The amount of time will depend on the OBOTR's internal policies and any relevant regulatory requirements. ## Displaying Payment Info {#displaying-payment-info} ### Display Tokenized Account PANs Associated with a Profile {#display-tokenized-account-pans-associated-with-a-profile} This use case describes how OBOTRs can fetch card art for tokenized Account PANs on-behalf of a merchant. This could allow a merchant to create a screen to manage Account PANs associated with a profile. **Example Manage Cards Screen** ![alt text](https://static.developer.mastercard.com/content/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/img/m4muc-example-manage-cards-screen.png "Example Manage Cards Screen") #### Displaying Card Art {#displaying-card-art} **Technical Details:** The payment gateway, acting as OBOTR, should make a **Get Asset** request for the composite image AssetID, **cardBackgroundCombinedAssetId** , returned in productConfig when tokenizing an Account PAN. If no composite image, is returned the OBOTR can instead make Get Asset requests for the brand logo, the issuer logo, a co-brand logo (if any) and the card background and create a composite image instead. See [Creating a Combined Image from Components](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#creating-a-combined-image-from-components) for more details. **NOTE:** Images may be received in either vector (PDF) or raster (PNG) format. the OBOTR's code must be able to handle images in either format. A payment gateway must ensure that they and their merchants adhere to Mastercard brand requirements when displaying card information. See the sections on 'Use at digital merchant locations' and 'Use in digital applications' at (target=undefined rel=undefined). The tables below describe the different components needed to create a combined image. | productConfig Field | Description | |-------------------------------|-----------------------------------------------------------------------------------------------------------------------------| | brandLogoAssetId | The Mastercard or Maestro brand logo associated with this card | | issuerLogoAssetId | The logo of the issuing bank | | coBrandLogoAssetId | The co-brand logo (if any) for this product | | cardBackgroundCombinedAssetId | The card image used to represent the digital card; this 'combined' option contains the brand, issuer and any co-brand logos | | cardBackgroundAssetId | The card image used to represent the digital card; does not include the brand, issuer or co-brand logo | | iconAssetId | The icon representing the primary brands associated with this product | | foregroundColor | Color of foreground text overlaid on the card image, e.g. product type, such as Debit or Credit | The images listed above are described in more detail below. | Example Images | Description | Fieldname | Details | |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------|-----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ![Composite Card](https://static.developer.mastercard.com/content/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/img/m4muc-combined-card-image.png) | Composite Card Image | cardBackgroundCombinedAsset | Background image + Issuer logo + Brand logo + product type text (e.g. Debit, Credit). Height-to-width ratio should be 63%. | | ![Example Card Icon](https://static.developer.mastercard.com/content/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/img/m4muc-example-card-icon.png) | Card Icon | iconAsset | Icon to represent the card. Supplied as a PNG image. PDF is not supported for the Icon asset. Dimensions 100 x 100 px. | | ![Brand Logo](https://static.developer.mastercard.com/content/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/img/m4muc-example-brand-logo.png) | Brand Logo | brandLogoAsset | Mastercard or Maestro logo supplied as a PNG image in RGB color format or a PDF vector resource. **NOTE:** A black background has been added for illustration purposes only. The actual PNG images would be transparent (alpha channel) with no background. The alpha channel can be used for compositing the brand logo onto the Card Background. | | ![Example Issuer Logo](https://static.developer.mastercard.com/content/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/img/m4muc-example-issuer-logo.png) | Issuer Logo | issuerLogoAsset | **NOTE:** A gray background has been added for illustration purposes only. The actual image would be transparent (alpha channel) with no background. Supplied as a PNG image in RGB color format or a PDF vector resource. PNG images will contain an alpha channel for compositing onto the Card Background. | | ![Example Background Image](https://static.developer.mastercard.com/content/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/img/m4muc-example-background-image.png) | Background Image | cardBackgroundAsset | **NOTE:** In this example, just a solid color. Supplied as a PNG image in RGB color format or a PDF vector resource. Height-to-width ratio should be 63%. | #### Creating a Combined Image from Components {#creating-a-combined-image-from-components} To create a combined image, a payment gateway will need to: 1. Scale the component images to fit within area CxD (co-brand and/or issuer logo area) or area ExD (brand logo area) shown in the diagram below. The combined image should have a width of 1536 pixels and a height of 969 pixels (a height-to-width ratio of 63%). 2. r code should be able to handle PDF or PNG images. 3. Using the alpha layer in the logo images, create a composite image by superimposing the logos over the background using the spacing described in the diagram below. Center the co-brand logo and/or issuer logo within the CxD area. 4. Optionally, superimpose text on the image such as the last 4 digits of the consumer's PAN, using the productConfig foregroundColor. ![alt text](https://static.developer.mastercard.com/content/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/img/m4muc-combining-card-art-wireframe.png "Combining Card Art") The table below shows the pixel dimensions for the measurements shown above. | Dimension | Description | Value (in Pixels) | |-----------|----------------------------------------|-------------------| | A | Side Padding | 82 | | B | Top / Bottom Padding | 57 | | C | Co-brand and/or Issuer logo area width | 1372 | | D | Height for the 2 logo areas | 283 | | E | Brand logo width | 459 | ### Displaying Detailed Information About a Tokenized Account PAN {#displaying-detailed-information-about-a-tokenized-account-pan} If an OBOTR needs to request detailed information about a specific Account PAN, Mastercard recommends using the **Get Token** request because this fetches the most up-to-date token state from MDES. An OBOTR should update any internal state it maintains for this **tokenUniqueReference** to ensure that its internal system state has not got out of sync with MDES due to network outages, etc. The **Get Token** request also returns Asset ID values for the different branding images associated with this card. If any new Asset ID values are returned, use the **Get Asset** request to fetch these new images for display. If the Asset ID values have not changed then the associate card art is unchanged. Note: * Assets retrieved through these requests may be cached in perpetuity. Any future updates to an asset will always result in a new Asset ID being issued. Mastercard strongly recommends that OBOTRs take advantage of caching to minimize Get Asset requests. * If the **includeTokenDetail** request flag to true, it is possible to receive an additional encrypted object, **tokenDetail** containing the token (in the field tokenNumber) ## Making Payments {#making-payments} ### MDES for Merchants Scenario {#mdes-for-merchants-scenario} #### Using the same Payment Gateway that Tokenized the Card {#using-the-same-payment-gateway-that-tokenized-the-card} This use case describes how a payment gateway can make payment authorizations for merchants using tokenized Account PANs. For example: 1. A merchant submits an authorization request to the payment gateway using a payment gateway token. 2. The payment gateway, acting as a OBOTR, retrieves the tokenUniqueReference (TUR) value for the MDES token associated with this payment gateway token and token requestor ID (TRID) for this merchant. 3. The OBOTR makes a **Transact** request using the tokenUniqueReference (TUR) value for a specific token and token requestor ID (TRID) 4. The OBOTR receives a token and cryptogram in the response. Note: It is also possible to make one or more Transact requests at an earlier time (for example, when the consumer tokenizes their card) and securely store the cryptograms generated for use in the above process; this would save an API call during payment. See [Storing Cryptograms](https://developer.mastercard.com/mdes-digital-enablement/documentation/use-cases/mdes-for-merchants-on-behalf-of-model-use-cases/index.md#storing-cryptograms) for further details. 1. The OBOTR submits the token (instead of the Account PAN), cryptogram and token expiry date (returned in the Transact response: applicationExpiryDate) to an acquirer for authorization. The acquirer must support Digital Secure Remote Payments (DSRP) transactions. For subsequent recurring or partial shipment transactions, the cryptogram and expiry date should not be sent. Consult the acquirer's documentation for details. 2. The OBOTR receives a payment authorization response from the acquirer or processor, and sends this transaction status information on to the merchant. **Technical Details:** 1. A merchant submits an authorization request to the payment gateway using a payment gateway token. 2. The payment gateway, acting as a OBOTR, retrieves the tokenUniqueReference (TUR) value for the MDES token associated with this payment gateway token and token requestor ID (TRID) for this merchant. 3. The OBOTR should have already received confirmation, via a Notify Token Updated notification, that the token has been activated. Otherwise, subsequent API requests will fail. 4. The OBOTR makes a **Transact** request using the **tokenUniqueReference** and TRID from step 2 and a unique requestId. **dsrpType** must be set to Universal Cardholder Authentication Field (UCAF). Optionally, provide a 4-byte hex-encoded value in string format for the **unpredictableNumber** parameter (The OBOTR must use a cryptographically-secure random number generator, such as an HSM). Note: Tokenize returns an active token and TUR. The TUR allows OBOTRs to obtain a cryptogram (and token) via the Transact API to make payments. 5. The OBOTR receives a response with an encrypted payload. The OBOTR decrypts the response to extract the token (**encryptedPayload.encryptedData.accountNumber** ) and the cryptogram contained in **encryptedPayload.encryptedData.de48se43Data**. 6. Finally, the OBOTR submits the OBOTR payment authorization requests, containing the token and cryptogram (from step 5), and token expiry date (returned in the Transact response: applicationExpiryDate) to an acquirer for payment authorization. For subsequent recurring or partial shipment transactions, the cryptogram and expiry date should not be sent. The OBOTR should consult the acquirer's technical documentation for details. Note: The acquirer used to process these transactions must accept DSRP card-on-file tokens and e-commerce Security Level Indicator (SLI) values of 246 for standard payments and 247 for recurring/partial shipment payments. DSRP cryptogram is required to be sent in the DE104 -- Digital Payment Data (DPD) field -- please refer to the [bulletin](https://techdocs.mastercard.com/bundle/m_AN3363/page/jvw1585260985294.html) for details. 7. The OBOTR receives a payment authorization response from the acquirer or processor, and sends this transaction status information on to the merchant. 8. Optionally, if the OBOTR is storing cryptograms, they can make a new Transact request after payment authorization and store the returned cryptogram for a later payment. **API Flow for Making a Payment** Diagram obo-making-a-payment #### Using an Alternative Payment Gateway {#using-an-alternative-payment-gateway} If a merchant wishes to submit authorization requests through an alternative payment gateway, the payment gateway acting as the OBOTR could offer an API endpoint which accepts either a PAN or a payment gateway token and returns a MDES token directly to the merchant. The OBOTR would need to tokenize the PAN and return an MDES token and token expiry date. The OBOTR, would just return the MDES token created at an earlier time for this PAN along with its expiry date. The OBOTR will also need to provide a second API endpoint for merchants to obtain additional cryptograms for a particular MDES token for future payments. Once the merchant has a cryptogram and token, they can submit authorization requests to an alternative payment gateway. The payment gateway and any acquirers it uses must support DSRP. Note: payment gateways processing authorization requests with an MDES token and cryptogram do not need to be Mastercard customers. ##### Request MDES Token {#request-mdes-token} **Technical Details:** 1. The merchant supplies a payment gateway token and requests an MDES token from the OBOTR. 2. The OBOTR fetches the associated stored MDES token, token expiry date, tokenUniqueReference (TUR) and TRID value. 3. The OBOTR should have already received confirmation, via a Notify Token Updated notification, that the token has been activated. Otherwise, subsequent API requests will fail. 4. The OBOTR makes a **Transact** request using the tokenUniqueReference (TUR) and TRID from step 2 and a unique requestId. **dsrpType** must be set to UCAF. The OBOTR optionally can provide a 4-byte hex-encoded value in string format for the **unpredictableNumber** parameter (the OBOTR must use a cryptographically-secure random number generator, such as an HSM). 5. The OBOTR receives a response with an encrypted payload. The OBOTR decrypts the response to extract the token (**encryptedPayload.encryptedData.accountNumbe** r) and the cryptogram contained in **encryptedPayload.encryptedData.de48se43Data**. 6. The OBOTR returns the token, token expiry date and cryptogram to the merchant. Merchants will need to follow the requirements for storing cryptograms. Note: Tokenize returns an active token and TUR. The TUR allows OBOTRs to obtain a cryptogram (and token) via the Transact API to make payments. If the merchant has supplied a PAN instead in step 1, then in step 2 the OBOTR will need to tokenize the PAN. After receiving the Tokenize response, an active token has been provisioned. The OBOTR can then store the MDES token along with the token expiry date and tokenUniqueReference (TUR). **API Flow for returning an MDES token to a merchant that submits a gateway token** Diagram obo-submit-gateway-token-return-mdes-token **API Flow for returning an MDES token to a merchant that submits a PAN** Diagram obo-submit-pan-return-mdes-token ##### Authorization {#authorization} **Technical Details:** 1. The merchant sends the token, cryptogram and expiry date received from the OBOTR to the alternative payment gateway. 2. The alternative payment gateway submits a payment authorization requests, containing the token and cryptogram, and token expiry date (returned in the Transact response: **applicationExpiryDate**) to an acquirer for payment authorization. For subsequent recurring or partial shipment transactions, the cryptogram and expiry date must not be sent. The payment gateway should consult the acquirer's technical documentation for details. 3. The payment gateway returns the payment status to the merchant. Note: The acquirer used to process these transactions must accept DSRP card-on-file tokens and e-commerce Security Level Indicator (SLI) values of 246 for standard payments and 247 for recurring/partial shipment payments. DSRP cryptogram is required to be sent in the DE104 -- Digital Payment Data (DPD) field -- please refer to [AN3363 bulletin](https://techdocs.mastercard.com/bundle/m_AN3363/page/jvw1585260985294.html) for more details. Note: If a payment has already been taken using this cryptogram and this is not a recurring or partial shipment transaction, then the merchant must request a new cryptogram for this payment, see Requesting Additional Cryptograms below. **API Flow for using separate payment gateways for requesting tokens and payment** Diagram obo-requesting-a-token-separate-gateways Note: The dotted section in the diagram is only required for new payments when a new cryptogram is needed. ##### Requesting Additional Cryptograms {#requesting-additional-cryptograms} **Technical Details:** 1. The merchant supplies an MDES token and requests a new cryptogram for this token. 2. The OBOTR locates the MDES token and associated TUR along with the TRID for this merchant. 3. The OBOTR makes a **Transact** request using the TUR and TRID from step 2 and a unique **requestId** . **dsrpType** must be set to UCAF. The OBOTR can optionally provide a 4-byte hex-encoded value in string format for the **unpredictableNumber** parameter ( The OBOTR must use a cryptographically-secure random number generator, such as an HSM). 4. The OBOTR receives a response with an encrypted payload. 5. The OBOTR decrypts the response to extract the token (**encryptedPayload.encryptedData.accountNumber** ) and the cryptogram contained in **encryptedPayload.encryptedData.de48se43Data**. 6. The OBOTR returns the token, token expiry date and cryptogram to the merchant. The merchant must follow the requirements for storing Cryptograms detailed below.

## Customer Service {#customer-service} ### Consumer Contacts a Merchant's Customer Service Helpline {#consumer-contacts-a-merchants-customer-service-helpline} This use case describes how a consumer can provide their Account PAN as an additional form of identity verification for various customer service tasks. #### Search by Full Account PAN {#search-by-full-account-pan} MDES provides a mechanism to return a list of all tokens created by a Token Requestor for a given Account PAN as well as the status of each token. Either Merchants (in the MDES for Merchants program) can use the returned token information to cross reference against all the consumer profiles stored by their system to locate the relevant profile. This technique can be used as an additional identity verification step for a consumer. **Technical Details:** 1. A consumer contacts a merchant customer service team (as appropriate) and provides their Account PAN. An example scenario would be that the consumer is locked out of their profile and cannot access their email to do a password reset. 2. The customer service representative requests additional information from the consumer, such as their full name, etc. in accordance with the merchant's policies. 3. The merchant makes a Search Tokens request to the payment gateway using the full Account PAN using the consumer's Account PAN and, optionally, an expiry date. 4. The payment gateway, acting as an OBOTR, makes a **Search Tokens** request using the full Account PAN and token requestor ID (TRID) allocated for this merchant. This request only accepts an Account PAN and, optionally, an expiry date. All other **fundingAccountInfo** parameters are unsupported. The request is constructed in a similar way to a **Tokenize** request. 5. The OBOTR receives a response containing a list of token objects that match to the Account PAN. For each object, the response contains a **tokenUniqueReference** value, the token status (INACTIVE, ACTIVE, SUSPENDED or DEACTIVATED), and the date and time that the token changed to the latest status (statusTimestamp). Suspended tokens have an additional field, suspendedBy, which identifies who suspended the token: either ISSUER (card issuer) or TOKEN_REQUESTOR (the OBOTR on behalf of a specific merchant). Consumer-initiated suspension is not applicable to this program. 6. The OBOTR locates the payment gateway tokens associated with the **tokenUniqueReference** values returned in the MDES response and returns a list of payment gateway tokens associated with this PAN. 7. The merchant can then match the list of payment gateway tokens with the consumer profiles stored in their system to confirm the consumer's identity. **API Flow for Customer Service Account PAN Lookup** Diagram customer-service-account-PAN-lookup