# Migration Guide for Masterpass Checkout Merchants and PSPs moving to the V7 API source: https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/migration-for-masterpass-checkout-merchants-and-psps-moving-to-v7api/index.md ## Introduction {#introduction} This document explains how Merchants and Payment Service Providers can migrate to Masterpass Checkout API V7 and covers the main differences between V6 and V7; it should be read by developers and project managers. Finally, the document provides pointers to the relevant information in the V7 documentation to help complete the integration work for the new API. Note: The content in this document is written from the perspective of Merchants or PSPs using the V6 API but also applies when migrating from V3, V4 or V5. Warning: V3 and V4 will be deprecated later this year (deprecation dates for V5 and V6 are yet to be confirmed) ## Pre-requisites for integration {#pre-requisites-for-integration} As with previous versions of Masterpass Checkout, the following are pre-requisites which a Merchant must comply with before they can integrate with Masterpass. Merchants must: * Accept Mastercard and Maestro cards. * Be in good standing with their acquirer or payment processor. * Adhere to the Masterpass branding requirements. * Follow the [Merchant and PSP integration requirements and best practices](https://developer.mastercard.com/masterpass-merchant-onboarding/documentation/masterpass-implementation-requirements/). * Abide by the[Masterpass operating rules](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/uploads/masterpassoperatingrules.pdf) * If performing integration on their own, demonstrate the appropriate level of PCI DSS compliance to handle cardholder PANs (known as PCI DSS in scope). Otherwise, Merchants must use a Payment Service Provider (PSP) which supports Masterpass. Merchants and PSPs must confirm that the above are all still true before integrating V7. Note: V7 provides additional features but migrating current functionality should be the first priority. ## Advantages of V7 {#advantages-of-v7} The advantages of the new V7 Checkout API are as follows: * 'Push' model that allows Payment Service Providers to receive payment data notifications from Masterpass on behalf of Merchants. * The PaymentData service used by Merchants to fetch payment data can operate in two modes: PCI DSS in scope and PCI DSS out of scope. In the latter mode, the last 4 digits of the account PAN are returned rather than the full PAN. The Merchant then uses a PSP to handle payment for this card. * New features are only being added to the V7 Checkout API. API versions V6 and earlier are no longer being enhanced. * Quicker initialization for the Masterpass UI in Standard Checkout due to the reduction in the number of API calls for this step. * New Masterpass Mobile Checkout SDK for iOS. * Updated Masterpass Mobile Checkout SDK for Android. ## Summary of changes {#summary-of-changes} The V7 version aims to provide a simpler integration than V6 for Standard Checkout. Only a few lines of code are required, with only two service calls. Merchants who are in scope for PCI DSS can integrate directly. Alternatively, Merchants can make use of a PSP to ensure PCI Compliance. Payment Service Providers are provided with flexible integration models (fully hosted, or payment data only via either push or pull methods). Before going into the detail, remember that at a conceptual level, nothing has really changed -- the situation is still largely as shown in the following component diagram: ![alt text](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/documentation/images/mp-merchant-diagrams-updated-for-v7-mp-merchant-integration-2-overview.png "Masterpass v7 Integration Overview") In order to migrate current integrations from V6 to V7, Merchants and PSPs must address the following: * Replace the old V6 client.js with the V7 merchant.js on all web pages containing the Masterpass button or payment option and modify the front end code accordingly. * Use the new Masterpass Checkout PSP Server SDK and / or Merchant Server SDKs (or the new API endpoints) for server-side integration, as appropriate. For those not using Server SDKs, Masterpass offers new V7 RPC APIs that can be called directly. The RPC API endpoints continue to use OAuth1 for authentication. See the [following article](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/) for details. * Use the latest Masterpass Checkout Mobile SDKs for [iOS](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/mobile-integration/masterpass-checkout-ios-sdk-v28/). * Mastercard will no longer support **Demandware** and **Magento** plugins for V7. * Client callback handling is no longer supported; all callback handling now takes place on the server. Note: existing consumer_key values can still be used for authentication along with the associated API key in .p12 format. Merchants can also continue to use their old checkoutId value configured in the Portal; this value is used for the Merchant.js checkout function as well as the PaymentData and ExpressCheckout Services. ## Onboarding / portal differences -- managing a Masterpass project via the portal {#onboarding--portal-differences--managing-a-masterpass-project-via-the-portal} V7 has put an emphasis on self-service. The following list illustrates some of the questions that may arise when using the new portal: * **Is it necessary to repeat the onboarding process in the Mastercard Developers portal to setup a new project?** - No, even when creating new keys, PSPs or Merchants can still use their existing project and perform Sandbox testing once they have made the required changes. * **Are there any changes to the project setup in the portal?** -- Merchants will need to set up their callback URL in the Merchant profile in order to perform Sandbox testing, but if they already have a callback URL defined in their project they can carry on using it. Note that Merchants can provide multiple call-back URLs for different channels (providing different URLs for the iOS, Android and Web channels, for example) if desired; note that all existing call-back URLs default to the web channel. It is also possible to pass the CallbackURL as a parameter in the merchant.js checkout function which overrides the portal setting. * **Are new keys required?** -- Existing keys will also work with the V7 API. However, if Merchants or PSPs are using legacy keys (user-based keys, created prior to October 2017), they will need to create new project-based keys when those keys expire; as legacy key renewal is not supported. For this reason, it is best to create new keys as part of V7 migration work. The new, simplified experience, launched in October 2017, uses project-based keys, rather than user-based keys. Project-based keys can be renewed by any user added to the project, avoiding issues that can occur if an individual project member is no longer available to renew their keys. ## Implementation differences {#implementation-differences} The following sections give a more detailed overview of the differences to the integration in terms of API / SDK use etc. ### Client-side changes {#client-side-changes} #### Web integrations {#web-integrations} Add the new Masterpass JavaScript library to all web pages containing the Masterpass button or payment option. For V7, merchant.js replaces the client.js used in V6, and provides additional functionality The links for this new library are as follows: * Sandbox - * Production - The section below explains the differences between client.js in V6 and merchant.js in V7: * Use the **masterpass.checkout(**) function provided in merchant.js for Standard Checkout. * For Express Checkout, Merchants must first request that the consumer pairs their Masterpass wallet with the site before using the Precheckout and Expresscheckout Services to fetch payment data; this can take place either during a Standard Checkout, or outside of the checkout flow. * To pair outside checkout, use the **masterpass.pair()** function. * To pair during a Standard Checkout, use **masterpass.checkout()** as usual for a standard checkout, but set the**requestPairing** parameter to true and provide a unique **userId** for this consumer. * amount and currency parameters are now passed to the **masterpass.checkout()** . See the full list of [checkout parameters](https://developer.mastercard.com/drafts/masterpass-merchant-integration-v7/staging/documentation/checkout-solutions/#standard-checkout). #### Mobile integrations {#mobile-integrations} * New SDKs are provided for [iOS](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/mobile-integration/masterpass-checkout-ios-sdk-v28/) and [Android](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/mobile-integration/masterpass-checkout-android-sdk-v28/) to enable Merchants to add the Masterpass payment method to their mobile apps. * Amount and currency parameters are now passed to the client. See the relevant mobile integration documentation for a full list of checkout parameters. #### Amount value representation change {#amount-value-representation-change} V6 and earlier API versions used integer minor units (so for example $9.99 would be passed as 999). V7 uses decimal/float values with an accuracy of two decimal places so $9.99 would be passed as 9.99. Note however that there are some discrepancies for some mobile platforms, see table below. Ensure that all client code is passing these values correctly during integration testing. | SDK | Client / Server | Amount / total representation (V7) | Amount / total representation (V6 and earlier) | |-----------------------------------------------|-----------------|-------------------------------------------------------------------------|---------------------------------------------------------------------| | Server | Server | decimal valid to two decimal places e.g. 9.99 = $9.99 if currency = USD | long integer (using minor units) e.g. 999 = $9.99 if currency = USD | | JavaScript (client.js - V6, merchant.js - V7) | Client | decimal valid to two decimal places e.g. 9.99 = $9.99 if currency = USD | n/a | | iOS SDK | Client | decimal valid to two decimal places e.g. 9.99 = $9.99 if currency = USD | n/a | | Android SDK | Client | long integer (using minor units) e.g. 999 = $9.99 if currency = USD | n/a | ### Server-side changes {#server-side-changes} This section explains the server integration changes that a Merchant (and PSP where needed) must make for the V7 Checkout API. These changes vary depending on whether the user is integrating Standard Checkout or Express Checkout and whether the Merchant is using a PSP or not. The changes are also written from the perspective of a web rather than mobile client. Standard Checkout, Express Checkout and Standard Checkout with PSP are all described below. Other integrations will follow a similar model, refer to the integration links at the end of the guide for other integrations. Note: For those using the Masterpass Checkout RPC APIs rather than the Checkout SDKs, it is important to be aware that V7 Checkout API payloads and responses are **JSON**, not XML
#### Standard Checkout {#standard-checkout} The following table shows the server-side calls used in the V6 Standard Checkout and their equivalents in V7 (where present) - server calls are show with an asterix. | **V6 and below Integration** | **V7 Integration** | |------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| | Call Request Token Service \* | Invoke Masterpass UI using the new merchant.js | | Call Shopping Cart Service \* | | | Invoke Masterpass UI (lightbox) for checkout using client.js | | | Redirect to callback URL | Redirect to callback URL | | Call Access Token Service \* | | | Retrieve payment data, shipping data and 3DS details using the Checkout Service \* | Retrieve payment, shipping data, and 3DS details using the new PaymentData Service \* | | Make an authorization request to an acquirer to take payment \* | Make an authorization request to an acquirer to take payment \* | | Call the Postback Service to report the payment status from the previous step to Masterpass \* | Call the Postback Service to report the payment status from the previous step to Masterpass \* | Note that there is a new Service to retrieve payment data, and also that the Postback Service call will be slightly different. The following diagram summarizes the new Standard Checkout payment flow: ![alt text](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/documentation/images/mp-merchant-diagrams-updated-for-v7-04.png "Masterpass Standard Checkout V7 API") Non PCI scope Merchants must select a PSP that supports Masterpass; they can select from a list of available PSPs in the Portal. There are three integration options available when using a PSP: * **Hosted** - the current hosted model where the PSP hosts a payment page for the Merchant. * **Pull**-- in this model, the Merchant sends the PSP the Transaction ID, amount and currency for the payment and the PSP server calls the Masterpass Checkout API on behalf of the merchant to retrieve the sensitive PCI payment data (a new PSP PaymentData Service is provided for this purpose). The PSP then processes the payment on behalf of the Merchant. * **Push** - in this model, the PSP provides a URL which can receive encrypted payment data from Masterpass. Masterpass pushes payment data to this URL. The URL must return a transaction ID which Masterpass then passes to the Merchant. The Merchant can then send the transaction ID to the PSP along with the amount and currency to take payment. Note that currently, there is no provision via the portal to set this up in a self-service manner, PSPs will have to contact Mastercard support and provide details of their URL, and Mastercard support staff will alter project settings accordingly. #### Express Checkout {#express-checkout} The following section explains the Express Checkout flow in V7. Express Checkout is an alternative to Standard Checkout which reduces the number of steps a consumer must complete for subsequent payments with a Merchant. Merchants that implemented Express Checkout in V6 will need to re-implement as described below. Note Express Checkout has additional security restrictions that are not required for Standard Checkout; contact [merchant.integration@masterpass.com](mailto:merchant.integration@masterpass.com) for details. Express Checkout contains two stages: **Setup** - in this stage a consumer's Masterpass wallet is paired with the consumer's Merchant site / app profile. **Subsequent checkouts** - once the consumer's wallet is paired, the consumer can make payments on the Merchant site / app without launching the Masterpass UI. These stages are described in detail below. ##### Setup pairing {#setup-pairing} Setup pairing during checkout (note it is also possible to setup pairing outside checkout using the merchant.js pairing function): 1. Implement [Standard Checkout](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/backend-integration/#standard-checkout). 2. Launch the Masterpass UI to obtain the consumer's consent for pairing their Masterpass wallet with the consumer's Merchant site / app profile during a Standard Checkout or outside of checkout. 3. Extract the**pairing_verifier** value from the callback URL and use this value to request a **pairingId** from Masterpass via the Pairing Service. Store this **pairingId** with the consumer's profile. Note that **pairingId** values are single-use i.e. they can only be used for one Masterpass API/SDK Service request. 4. Follow Standard Checkout flow. ##### Subsequent payments {#subsequent-payments} Once, the consumer's wallet is paired with the consumer's profile at the Merchant site/app, subsequent Express Checkout payments use the following simpler flow: 1. Initiate a checkout from the Merchant site / app and retrieve the consumer's payment card/s (last 4 digits only) and shipping addresses (where relevant) using the PreCheckout Service. A new **pairingId** is returned; use this Id for the next ExpressCheckout Service request for this consumer. 2. Display the consumer's card/s and shipping address/es (where relevant). Request PCI payment data for the selected card (account PAN) using the ExpressCheckout Service. A new **pairingId** is returned; use this Id for the next PreCheckout Service request for this consumer. 3. Authorize payment via a PSP or acquirer using the data returned in step 3 4. Use the Postback Service to record the result of the authorization from the previous step. 5. Display a payment success screen with order details. The API call sequence is shown in the following diagram: ![alt text](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/documentation/images/mp-merchant-diagrams-updated-for-v7-03.png "Masterpass Express Checkout V7 API") #### Standard Checkout with PSP (PSP pull model) {#standard-checkout-with-psp-psp-pull-model} This section explains the Standard Checkout payment flow for Non PCI scope Merchants using a PSP. The steps are described below: 1. The Merchant launches the Masterpass UI following the same process used in Standard Checkout (no PSP) 2. Once a callback is received by the Merchant's server, the Merchant extracts the Transaction ID from the callback and makes a PaymentData Service call to request the consumer's payment data (selected card and shipping address - optional). In this case, the PaymentData Service only returns Non PCI payment data i.e. the full card PAN is replaced with the last four digits of the PAN. 3. The Merchant sends the Transaction ID obtained in Step 2 along with the payment amount and currency to a PSP endpoint to take payment. 4. The PSP uses the Transaction ID with the new PSPPaymentData Service to fetch the PCI payment data from Masterpass and then processes payment with the acquirer. 5. The PSP returns the payment status to the Merchant. 6. Use the Postback Service to record the result of the authorization from the previous step. 7. Display a payment success screen with order details. ![alt text](https://static.developer.mastercard.com/content/masterpass-merchant-integration-v7/documentation/images/mp-merchant-diagrams-updated-for-v7-05.png "Masterpass Standard Checkout PSP Pull V7 API") ## Integration guide links {#integration-guide-links} The following integration guides provide detailed integration information for the V7 API: | Product | New Integration Link | |-----------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Merchant Integration Guide for V7 | | | PSP Integration Guide for V7 | | | Mobile Integration Guides fo V7 | - **iOS -** **Android** - | Other useful links: | Page | Link | |------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | Merchant Onboarding | | | PSP Onboarding | | | Masterpass Branding Requirements | | | Merchant Integration Requirements and Best Practices | | ## Testing {#testing} The testing guidelines have been updated. This [page](https://developer.mastercard.com/masterpass-merchant-integration-v7/documentation/masterpass-sandbox-testing-guidelines/index.md) contains details explaining how to test V7 in Sandbox. Express Checkout is now available automatically on Sandbox for new Mastercard Developers accounts. For existing accounts, you will need to email the address below to request Express Checkout be enabled for the account. ## Further information {#further-information} If Merchants or PSPs have any questions about the migration or require integration support, please email [merchant.integration@masterpass.com](mailto:merchant.integration@masterpass.com.).