MasterPass Service Provider Onboarding & Integration Guide Merchant by Merchant Model Global Version 6.13

Transcription

1 MasterPass Service Provider Onboarding & Integration Guide Merchant by Merchant Model Global Version June 2016 SPMM

2 Summary of Changes, 24 June 2016 Summary of Changes, 24 June 2016 This document reflects changes made since the previous publication. To locate these changes online, click the hyperlinks in the following table. Change Date Description of Change Where to Look 24 June 2016 Updated the Lightbox dimensions provided in the Standard Lightbox Display (desktop and laptop) section. 24 June 2016 Updated the Lightbox Integration instructions to reflect the new sandbox and production JavaScript URLs that merchants must incorporate into the source of their checkout page. Standard Lightbox Display (desktop and laptop) Lightbox Integration 24 June 2016 Updated the Sample Integration of the Android and ios App Integration section to indicate that upon the user s clicking of MasterPass Checkout, the merchant application must redirect the user to a mobile browser that launches the MasterPass experience, and that MasterPass does not support webview for in-app implementation. Android and ios App Integration 24 June 2016 Updated the MasterPass Sandbox Testing section to indicate that MasterPass has eliminated the following pre-set MasterPass wallet accounts from use in the sandbox environment: joe.test@ .com joe.test3@ .com 3ds.masterpass +securecode@gmail.com 3ds.masterpass +verifiedbyvisa@gmail.com MasterPass Sandbox Testing Global Version June

3 Summary of Changes, 24 June 2016 Change Date Description of Change Where to Look 24 June 2016 Added the following bullet to the Checklist for MasterPass Asset Placement : Verify that the MasterPass checkout button is used appropriately on the checkout page to initiate the MasterPass experience. 24 June 2016 Updated the following bullet in the In-Wallet Experience checklist to account for the required enablement of 3-D Secure for the MasterPass wallet: Merchants requesting liability shift for MasterPass transactions should use Advanced Checkout/3-D Secure within MasterPass. Merchants must enable 3-D Secure such that it is invoked within the MasterPass wallet. 24 June 2016 Added the following bullet to the Post-Wallet Experience checklist: Verify that any information provided by a consumer s MasterPass wallet (for example, payment, shipping, profile information, and so on) is used only for that transaction and is not stored for subsequent use. 24 June 2016 Added the following bullet to the Postback checklist: Ensure that you are submitting postback for all MasterPass transactions initiated with the consumer s click of the MasterPass checkout button (approved, declined, or abandoned). Checklist for MasterPass Asset Placement In-Wallet Experience Post-Wallet Experience Postback Global Version June

4 Summary of Changes, 24 June 2016 Change Date Description of Change Where to Look 24 June 2016 Added the following bullet to the General checklist: Verify that your implementation follows the standard process and utilizes all calls (to the MasterPass wallet, complete postback, and so on) for each and every transaction initiated by a consumer s click of the MasterPass checkout button. Verify that you are accepting and passing the wallet identifier (WID) when present for MasterPass transactions. 11 May 2016 Added onboarding content to reflect changes to the Merchant Portal, including updates to the Authentication Settings page and new logic related to Advanced Checkout. Added and updated integration content to to reflect changes to 3-D Secure authentication. Updated the EciFlag and PaResStatus elements in the Checkout Resource section of the Appendix to reflect 3-DS updates. 11 April 2016 Updated onboarding content to reflect a new and improved workflow within the merchant portal. Added content to the integration steps to reflect updates to the Lightbox integration and Android/iOS integration. 29 February 2016 Added a new section dedicated to the Android merchant app-towallet checkout experience. General Merchant Registration and Setup Merchant Activity 3-D Secure Overview Checkout Resource Overview MasterPass Checkout Experiences Service Provider Merchant by Merchant Onboarding Service Provider Merchant by Merchant Onboarding Steps Integration Process Android and ios App Integration MasterPass Branding Appendix Android Merchant App-to- Wallet App Checkout Global Version June

5 Summary of Changes, 24 June 2016 Change Date Description of Change Where to Look 29 February 2016 Made the following updates to the Implementing DSRP and Tokenization (formerly Implementing DSRP ) section: Merged this section with the formerly named DSRP and Tokenization section. Added the following verbiage: For MasterPass transactions that start on a merchant's Android application and complete on a consumer s Android MasterPass wallet application, a DSRP cryptogram will be generated. A DSRP cryptogram will be accompanied by a 16-digit token rather than the actual MasterCard card brand primary account number (PAN). Whenever a token is passed instead of the actual account number, the last four digits of the consumer s actual PAN will be passed in an extension point so that they can be displayed to the consumer if so desired. Added requirement regarding the implementation of the MasterPass Merchant Mobile Checkout SDK. Clarified the payment gateway s and acquirer s requirement to indicate that they must update their Dual Message and Single Message System interfaces to pass and receive DSRP data elements. Implementing DSRP and Tokenization 29 February 2016 Added maestro as a valid value of the BrandId element in the MerchantInitializationRequest with DSRP Extension Points V6 XML Details table. DSRP Extension Points in the MasterPass Merchant API Global Version June

6 Summary of Changes, 24 June 2016 Change Date Description of Change Where to Look 29 February 2016 Added a note to the DSRP Extension Points in the MasterPass Checkout XML section indicating that a value of 24X in Authorization DE 48 (Additional Data Private Data), subelement 42 (Electronic Commerce Indicators), subfield 1 (Electronic Commerce Security Level Indicator and UCAF Collection Indicator) reflects a DSRP transaction. DSRP Extension Points in the MasterPass Checkout XML 29 February 2016 Removed the MasterPass Mobile Checkout section. 29 February 2016 Added a note to the Displaying Buy with MasterPass Button and Acceptance Marks section to clarify that it is against MasterPass integration guidelines to download and locally host the MasterPass acceptance-mark and checkoutbutton images. Displaying the Buy with MasterPass Button and Acceptance Marks 29 February 2016 Added sub-bullets to the Security Level Indicator bullet within step 9 of the Service Process Flow for Merchant that Selects Advanced Checkout subsection to indicate that the SLI for MasterPass transactions is 22X and the SLI for MasterPass DSRP transactions is 24X. 7 January 2016 Updated the MerchantInitializationRequest with DSRP Extension Points V6 XML Details table to indicate that the UnpredictableNumber element contains a maximum of eight characters. 7 January 2016 Updated the Checkout XML DSRP Details table to indicate that the UnpredictableNumber element contains a maximum of eight characters. General Overview of MasterCard SecureCode and Verified by Visa Transaction Authentication DSRP Extension Points in the MasterPass Merchant API DSRP Extension Points in the MasterPass Checkout XML Global Version June

7 Summary of Changes, 24 June 2016 Change Date Description of Change Where to Look 7 January 2016 Removed the first two paragraphs from the 3-D Secure Considerations section. 3-D Secure Considerations Global Version June

8 Contents Contents Summary of Changes, 24 June Chapter 1: Overview How does MasterPass Work? MasterPass User Interface Chapter 2: MasterPass Checkout Experiences...16 Overview...17 MasterPass Standard Checkout Process Flow MasterPass Connected Checkout Experience...24 Pairing of Wallet Return Checkout Unpairing Android Merchant App-to-Wallet App Checkout...43 Chapter 3: Service Provider Merchant by Merchant Onboarding Incorporating MasterPass into Your Site or App Merchant by Merchant Onboarding Process...45 Chapter 4: Service Provider Merchant by Merchant Onboarding Steps Service Provider Registration and Setup Service Provider Activity Add Developer to Service Provider Profile Service Provider Activity...51 Make Available as Third Party Platform Provider Service Provider Activity Merchant Registration and Setup Merchant Activity...54 Invite Service Provider to be Merchant s Developer Merchant Activity Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity...67 MasterPass Merchant Portal Developer Account...67 Create a MasterCard Developer Zone Account...67 Generate MasterCard Developer Zone API Keys Initiate Development and MasterPass Implementation Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) Review Key Request and Approve/Reject Merchant Activity...77 Deploy Application Using Production Credentials Developer Activity Global Version June

9 Contents Chapter 5: Integration Process...81 Lightbox Integration...82 Standard checkout Standard Checkout Callback...84 Implementing DSRP and Tokenization Split/Partial Shipments and Recurring Payment Transactions D Secure Considerations...97 Testing DSRP...97 Pairing with MasterPass Merchant outside of Checkout Pairing with MasterPass Merchant During Checkout Return Checkout (Checkout after Pairing) MasterPass Service Descriptions Android and ios App Integration Completing the Integration Chapter 6: MasterPass Branding Displaying Buy with MasterPass Button and Acceptance Marks Buy With MasterPass Button Example MasterPass Checkout Images Displaying the Connect with MasterPass Button Connect with MasterPass Button Example Connect with MasterPass Image Files MasterPass Learn More Page Chapter 7: Testing MasterPass Sandbox Testing Sign up for a Test MasterPass Wallet Account during Checkout Q/A Checklist Checklist for MasterPass Asset Placement In-Wallet Experience Post-Wallet Experience Postback Checklist for the Connected Checkout Experience General Chapter 8: Troubleshooting Common Errors Support Global Version June

10 Contents Appendix A: Appendix Lightbox Parameters OAuth Samples Request Token Merchant Initialization Service Shopping Cart Service Access Token Service Checkout Resource Pre-Checkout Resource Postback Service Renew Your Developer Zone Key Developer Zone Key Tool Utility D Secure Overview D Secure Service Description General Overview of MasterCard SecureCode and Verified by Visa Transaction Authentication Important Merchant Information Notices Global Version June

11 Overview Chapter 1 Overview This document is intended to orient service partners and their developers seeking to integrate MasterPass as a checkout option for merchant s commerce sites or mobile application. How does MasterPass Work? MasterPass User Interface...12 Standard Lightbox Display (desktop and laptop)...12 Standard Mobile Display (.mobi) Standard Full-Screen Display Global Version June

12 Overview How does MasterPass Work? How does MasterPass Work? MasterPass is a wallet service that enables consumers to store, manage and securely share their payment information, shipping information, billing address, and rewards information with the websites and mobile apps they transact with. MasterPass supports checkout on full and mobile websites, as well as in-app purchases on Android and ios apps. In addition, MasterPass recently added the ability to quickly implement native, app-to-app checkout experiences with EMV-like security within Android smartphone applications. MasterPass User Interface The MasterPass user interface, or Lightbox, floats the MasterPass wallet interface on top of the merchant s web page through illuminated overlays, and backgrounds dimmed to 0.7 opacity. This modern method allows a consumer to interact with their MasterPass digital wallet without having to leave the merchant s page. The MasterPass Lightbox is built in a responsive design style allowing it to respond dynamically to the various screen sizes and orientations. MasterPass supports the following displays: Standard Lightbox Standard Full Screen Standard Lightbox Display (desktop and laptop) At full screen, where the browser is set to 100% height and width, the overall Lightbox dimensions are 730 pixels (height) by 680 pixels (width). This is inclusive of the height of the Lightbox header (70 pixels) and footer (70 pixels). The interior Lightbox dimensions are 590 pixels (height) by 680 pixels (width). If the height of the browser is reduced to 800 pixels or less, the entire Lightbox has a height of 620 pixels, and the width is maintained, the content container has dimensions of 530 pixels (height) by 680 pixels (width). If the browser is set to 100% maximum width but is less than 620 pixels in height, vertical scrolling will appear. Global Version June

13 Overview How does MasterPass Work? If the browser is set to less than 680 pixels in width the Lightbox layout will change to accommodate small screen formats (for example, phones and smaller tablets). There is a 320 pixel width threshold for the content container. Standard Mobile Display (.mobi) Within the.mobi experience, the header and footer are approximately 70 pixels high except for the iphone 5/5S, of which the header and footer are approximately 30 pixels high. The interior content area for mobile devices is content-dependent. The initial view of content is based on the overall screen sizes. Content that does not fit within the initial view of content can be accessed by scrolling. There will not be a landscape view for mobile; only portrait will be supported.the mobile interface fills the screen and does not use modal windows such as the Lightbox display. Global Version June

14 Overview How does MasterPass Work? Standard Full-Screen Display Special conditions apply to the standard full-screen display. Under certain conditions, such as the following: 1. The consumer s browser does not support the Lightbox display (older browser) 2. The merchant has not yet made coding changes to invoke the Lightbox display 3. The URL requesting the Lightbox display is different from the merchant-specified origin URL 4. Third-party cookies are blocked by the browser (currently Safari versions 8 and higher) MasterPass will render the wallet experience in full screen as our Lightbox experience requires MasterPass cookies to be dropped in the browser. In the case of scenario four above, we are able to drop cookies during the full-screen redirect experience, and subsequent MasterPass checkouts on that browser will show the Lightbox experience. Global Version June

15 Overview How does MasterPass Work? Global Version June

16 MasterPass Checkout Experiences Chapter 2 MasterPass Checkout Experiences This section provides information on the MasterPass checkout experiences. Overview MasterPass Standard Checkout Process Flow...17 MasterPass Connected Checkout Experience...24 Pairing of Wallet...25 Return Checkout...37 Unpairing Android Merchant App-to-Wallet App Checkout...43 Global Version June

17 MasterPass Checkout Experiences Overview Overview MasterPass offers checkout options that give merchants flexibility and control over the MasterPass checkout experience. With connected checkout, MasterPass allows merchants to control their user experience even during checkout and offers a more seamless experience for consumers. The connected checkout flow allows consumers to check out with fewer clicks and a simple password entry when they choose to Buy with MasterPass. MasterPass makes select wallet data (all data but only the last four digits of the primary account number [PAN]) available to merchants on the back end so consumers can seamlessly select the card and address they want to use on the merchant site and simply enter a password to checkout with MasterPass. MasterPass Standard Checkout Process Flow This topic provides information on the standard checkout process flow using the MasterPass user interface or Lightbox where the merchant/service provider integrates with MasterPass through the service provider. The merchant/service provider initiates the MasterPass user interface but does not receive consumer s PAN. The merchant/service provider must use this process flow for a non-registered (guest) user. Global Version June

18 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow The following diagram illustrates the standard MasterPass checkout process flow with the MasterPass Lightbox UI. The merchant must use this process flow for a non-registered (guest) user. NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must use the Merchant Initialization service to send the Origin URL. Standard Checkout User Flow The following steps explain the standard MasterPass checkout process flow: NOTE: The product images in the following screenshots are blurred for trademark reasons. Global Version June

19 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow 1. The consumer clicks the Buy with MasterPass button. 2. The consumer logs in to their wallet. Global Version June

20 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow 3. The consumer selects their payment method and shipping address. Global Version June

21 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow 4. The consumer reviews and submits the order. Global Version June

22 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow 5. The merchant confirms the order. Global Version June

23 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow The following diagram illustrates the MasterPass merchants standard checkout process flow for registered users: NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must use the Merchant Initialization service to send the Origin URL. Global Version June

24 MasterPass Checkout Experiences MasterPass Connected Checkout Experience MasterPass Connected Checkout Experience Connected Checkout enables MasterPass merchants to provide a customized checkout experience to their registered consumers across all connected channels. In the connected checkout model, consumers who have paired their wallet with the merchant allow that merchant to retrieve the consumer s precheckout data (shipping and other wallet information) without the actual card number and without the consumer having to log in to their wallet. The actual PAN will be provided to the merchant only after the consumer logs in to their wallet (by entering only their wallet password). Data shared in connection with the Connected Checkout can only be used to implement checkout and must be deleted Global Version June

25 MasterPass Checkout Experiences MasterPass Connected Checkout Experience immediately following the checkout experience. After checkout is completed, merchants must not retain any data shared during the Connected Checkout experience, nor may they use this data to update a user s profile on the merchant s system. Adherence to MasterPass branding requirements is required for display of Wallet Partner logo and MasterPass logo near the precheckout information. Connected checkout is supported by three components: Pairing of wallet Return checkout Unpairing Pairing of Wallet The consumer consents to "pair" their wallet account with their merchant account by agreeing to Connected Checkout. There are two points at which consumers may pair their MasterPass wallet with a merchant account: (1) during checkout and (2) outside of a checkout (typically in the merchant account settings) When the consumer pairs with the merchant, MasterPass sends an to the consumer confirming the wallet pairing. The name of the merchant as stated in the Legal Business Name field during merchant registration is used. Pairing enables the consumers MasterPass wallet data to be shared with the merchant during checkout transactions. This is accomplished by passing a Long Access token to the merchant. No cardholder data should be retained by the merchant or service provider between checkouts. NOTE: The long access token is a one-time use token. Each time a call using long access token is made, a new long access token will be passed back to the merchant. This new long access token will then need to be stored to be used the next time. Global Version June

26 MasterPass Checkout Experiences MasterPass Connected Checkout Experience Pair with MasterPass Merchant during Checkout In this scenario, the consumer pairs their wallet with a merchant while performing checkout. The pairing process starts when a consumer clicks the Buy with MasterPass button on the merchant site. This begins a set of exchanges that will bring the consumer through MasterPass and back out to the merchant again. If the consumer agrees to pair their wallet with the merchant, the consumer s precheckout data will be available to the merchant during the Global Version June

27 MasterPass Checkout Experiences MasterPass Connected Checkout Experience subsequent checkouts without the consumer having to log in to their wallet. When checkout is completed, the consumer data must be immediately deleted. The following steps explain the process in which a consumer pairs with a MasterPass merchant during checkout: 1. The consumer clicks the Buy with MasterPass button. 2. The consumer logs in to their wallet. Global Version June

28 MasterPass Checkout Experiences MasterPass Connected Checkout Experience 3. The consumer selects their payment method and shipping address. Global Version June

29 MasterPass Checkout Experiences MasterPass Connected Checkout Experience 4. The consumer agrees to pair their wallet with the merchant. Global Version June

30 MasterPass Checkout Experiences MasterPass Connected Checkout Experience 5. The merchant confirms the order. Global Version June

31 MasterPass Checkout Experiences MasterPass Connected Checkout Experience The following diagram illustrates the consumer s pairing process with a MasterPass merchant during the checkout: NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must use the Merchant Initialization service to send the Origin URL. Global Version June

32 MasterPass Checkout Experiences MasterPass Connected Checkout Experience Pair with MasterPass Merchant outside of a Checkout In this scenario, the consumer pairs their wallet with a merchant while not performing checkout, for example, account management. The pairing process starts when the consumer clicks the Connect with MasterPass button on the merchant site. This begins a set of exchanges that will bring the consumers through MasterPass and back out to the merchant again. If the consumer agrees to pair their wallet with the merchant, the consumer s precheckout data will be available to the merchant during their subsequent checkouts without the consumer having to log in to their wallet. When checkout is completed, the consumer s data must be immediately deleted. The following steps explain the process in which a consumer pairs with a MasterPass merchant outside of a checkout: 1. The consumer clicks the Connect with MasterPass button. Global Version June

33 MasterPass Checkout Experiences MasterPass Connected Checkout Experience 2. The consumer agrees to pair their wallet with the merchant. Global Version June

34 MasterPass Checkout Experiences MasterPass Connected Checkout Experience 3. A message is displayed confirming that the consumer s account is paired with the consumer s wallet. Global Version June

35 MasterPass Checkout Experiences MasterPass Connected Checkout Experience The following diagram illustrates the consumer s pairing process with a MasterPass merchant outside of a checkout: Global Version June

36 MasterPass Checkout Experiences MasterPass Connected Checkout Experience NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must use the Merchant Initialization service to send the Origin URL. Global Version June

37 MasterPass Checkout Experiences MasterPass Connected Checkout Experience Return Checkout Once the consumer (a) has paired their wallet account with merchant account and (b) logs into their merchant account or has otherwise been recognized by the merchant on the merchant site/app, the merchant will submit the token to MasterPass to retrieve the consumer s up-to-date wallet information (card details [including the last four digits of the card number], addresses, and loyalty program number). Global Version June

38 MasterPass Checkout Experiences MasterPass Connected Checkout Experience The merchant can then present this information to the consumers as part of their own experience, with the ability to streamline/personalize the consumer s experience during precheckout. Consumers can then checkout easily. The actual PAN will be provided to the merchant only after the consumers log in to their MasterPass wallets. NOTE: Data shared in connection with the Return/Connected Checkout can only be used for the purposes permitted in the MasterPass Operating Rules and must be removed immediately following the check-out experience. No data shared during the Return/Connected Checkout experience may be retained after the checkout is completed except for legitmate refunds, chargebacks, or other purposes for that transaction only. Service Providers are responsible for ensuring that merchants participating in MasterPass through the merchant by merchant model comply with this requirement. The following steps explain the return checkout process: 1. The consumer adds a product to their shopping cart on the merchant site. 2. The consumer clicks the Buy with MasterPass button. The consumer s wallet information is paired and listed in the shopping cart. Global Version June

39 MasterPass Checkout Experiences MasterPass Connected Checkout Experience 3. The consumer provides wallet authentication and confirms their purchase. Global Version June

40 MasterPass Checkout Experiences MasterPass Connected Checkout Experience 4. The merchant confirms the order. Global Version June

41 MasterPass Checkout Experiences MasterPass Connected Checkout Experience The following diagram illustrates the return checkout process: NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must use the Merchant Initialization service to send the Origin URL. Global Version June

42 MasterPass Checkout Experiences MasterPass Connected Checkout Experience Global Version June

43 MasterPass Checkout Experiences Android Merchant App-to-Wallet App Checkout Unpairing A consumer can unpair their pairing consent for the merchant at any time using MasterPass account management. When a consumer unpairs, they will receive an notification. When this happens, the precheckout call from the merchant to MasterPass will return an empty response. In such situations, the merchant can proceed with standard checkout. The merchant can also request pairing with this consumer again. Android Merchant App-to-Wallet App Checkout Starting in 2016, MasterPass is introducing a multi-channel checkout solution that allows merchants to integrate MasterPass as a secure checkout experience within their native Android applications. This checkout solution provides merchants with (a) a simplified, unified checkout experience across all merchant channels, including in-store contactless and in-app, and (b) the ability to generate transactions that are secured with Digital Secure Remote Payment (DSRP). DSRP is a MasterCard payment solution through which card-not-present merchants benefit from the dynamic secure data generated by contactless M/Chip applications. DSRP transactions contain dynamic data (cryptograms) generated by a payment application using EMV-based cryptography. Currently, DSRP cryptograms can only be generated for transactions initiated on an Android mobile app or mobile browser that has incorporated the MasterPass Mobile Checkout SDK, and transactions completed on a MasterPass Android wallet application. If Mobile Checkout is available in your country, refer to the MasterPass - Merchant Android SDK page of the MasterCard Developer Zone. Global Version June

44 Service Provider Merchant by Merchant Onboarding Chapter 3 Service Provider Merchant by Merchant Onboarding This topic provides information on service provider merchant by merchant onboarding process. Incorporating MasterPass into Your Site or App...45 Merchant by Merchant Onboarding Process Global Version June

45 Service Provider Merchant by Merchant Onboarding Incorporating MasterPass into Your Site or App Incorporating MasterPass into Your Site or App Enabling checkout with MasterPass on behalf of your merchant site or mobile app is straightforward here are the required activities for the Merchant by Merchant onboarding process. Merchant by Merchant Onboarding Process This process must be used if merchants create their own accounts. Step by step instructions can be found here. Activity Actor Steps Environment 1. Service Provider Registration and Setup 2. Add Developer to Service Provider Profile 3. Make Available as Third Party Platform Provider 4. Merchant Registration and Setup 5. Add Service Provider to be Merchant Developer 6. Developer Registration Service Provider Service Provider Service Provider Merchant Merchant Developer Create Service Provider account Add Developer to Service Provider Profile Make Service Provider Available as Third Party Platform Provider Create Merchant account, set shipping profile, rewards, and advanced authentication Invite Service Provider to manage integration Log in to MasterPass Developer account that is created upon invite Create consumer key requests and submit to service provider business owner Create Developer Zone account Generate developer s sandbox and production keys Review sample code/sdk and design services integration MasterPass Partner Portal MasterPass Partner Portal MasterPass Partner Portal MasterPass Merchant Portal MasterPass Merchant Portal MasterPass Merchant Portal MasterCard Developer Zone Global Version June

46 Service Provider Merchant by Merchant Onboarding Incorporating MasterPass into Your Site or App Activity Actor Steps Environment 7. Review and approve sandbox and/or production consumer key approval request Service Provider Business Owner Approve consumer key request(s) MasterPass Merchant Portal 8. Test Integration in Sandbox Developer Obtain checkout IDs for each successfully provisioned merchant from results file. Map each checkout ID to the correct merchant. Test against MasterPass sandbox environment 9. Production Migration Developer Update MasterPass API endpoints, consumer key, callback URL and Private Key (.p12 file), if different than Sandbox MasterPass Merchant Portal Service Provider Engineering Environment Service Provider Production Environment The following accounts will be created during the onboarding process. Use the following table to record the account information for future reference. NOTE: address must be unique for each account. Account Type Details Account Info Merchant Portal Service Provider Account Merchant Portal Service Provider Developer Account(s) Created by Service Provider business owner. This id should be used to login at masterpass.com/sp/merchant/ Home Go here to create Service Provider account, invite developers. Created when the Service Provider invites a developer. It is a system generated user id. This id should be used to login at Merchant/Home Go here to request consumer keys. Userid: Userid: Global Version June

47 Service Provider Merchant by Merchant Onboarding Incorporating MasterPass into Your Site or App Account Type Details Account Info Developer Zone Developer Account(s) Merchant Portal Merchant Account(s) Created by developer and is used for key exchange. This id should be used to login at developer.mastercard.com Go here to perform key exchange, download SDKs and Sample Applications, integration guides, and to access FAQs. Created by the merchant business owner. This ID will be used to login at masterpass.com/sp/merchant/ Home Go here to create merchant account, invite Service Provider, create shipping profiles, rewards, etc. Userid: Userid: Global Version June

48 Service Provider Merchant by Merchant Onboarding Steps Chapter 4 Service Provider Merchant by Merchant Onboarding Steps This section contains the steps that service providers must follow when assisting one merchant at a time with their MasterPass integration. Service Provider Registration and Setup Service Provider Activity Add Developer to Service Provider Profile Service Provider Activity Make Available as Third Party Platform Provider Service Provider Activity...53 Merchant Registration and Setup Merchant Activity...54 Invite Service Provider to be Merchant s Developer Merchant Activity...65 Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity MasterPass Merchant Portal Developer Account Create a MasterCard Developer Zone Account Generate MasterCard Developer Zone API Keys...69 Generate MasterCard Developer Zone API Key for Sandbox Environment...69 Generate MasterCard Developer Zone API Key for Production Environment Initiate Development and MasterPass Implementation Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) Review Key Request and Approve/Reject Merchant Activity...77 Deploy Application Using Production Credentials Developer Activity Global Version June

49 Service Provider Merchant by Merchant Onboarding Steps Service Provider Registration and Setup Service Provider Activity Service Provider Registration and Setup Service Provider Activity Before beginning this process, request an invitation code from your MasterCard representative; this will grant you access and allow you to register as a service provider within the merchant portal. About this task Developers invited to integrate MasterPass on behalf of a service provider will manage their integration activities through following portals. MasterPass Merchant Portal ( MasterCard Developer Zone ( Procedure 1. From the MasterPass Merchant Portal, select the country language from the dropdown and click the Create an Account button. You will be presented with a modal window, into which you will enter the invitation code. 2. Enter the invitation code into the Create A MasterPass Account window. NOTE: Service provider invitation codes should begin with the prefix SP. Global Version June

50 Service Provider Merchant by Merchant Onboarding Steps Service Provider Registration and Setup Service Provider Activity 3. Select Service Provider and click the Continue button. 4. Complete all of the required fields in the Enter Account Information screen. Global Version June

51 Service Provider Merchant by Merchant Onboarding Steps Add Developer to Service Provider Profile Service Provider Activity 5. In the Enter Security Information screen, choose your security questions and enter the answers. 6. Complete all of the required fields in the Enter Business Information screen. At this point, you will have created a service provider account. Add Developer to Service Provider Profile Service Provider Activity The next step is to add developers who will integrate MasterPass into the checkout flow on behalf of your merchant(s). About this task From the landing page, you will add developers to the service provider profile. These developers will handle the technical implementation of MasterPass. Global Version June

52 Service Provider Merchant by Merchant Onboarding Steps Add Developer to Service Provider Profile Service Provider Activity Procedure 1. Click Manage Setup and add developers to your service provider account. To get started, click the Start This Step button under the 2. Add developers option on the MasterPass Setup page. 2. You will need to indicate who will perform the technical integration. Service providers that have an internal or contracted engineering team must select An internal or contracted developer. 3. Provide contact information for each developer you want to invite and click Complete. Global Version June

53 Service Provider Merchant by Merchant Onboarding Steps Make Available as Third Party Platform Provider Service Provider Activity Results MasterPass will send two separate s to each newly added developer indicating that he/she has been invited to handle the technical integration of MasterPass on-behalf of your company. These s will contain the username and password to log in to the MasterPass Merchant Portal. Invitation s sent to the developer will contain links to the MasterPass integration guides that developers can use to get started with MasterPass integration. Make Available as Third Party Platform Provider Service Provider Activity Service providers should complete these instructions to make themselves visible and available to merchants in the portal for assistance with MasterPass implementation. Procedure 1. Sign in to your service provider account. 2. Go to the Account Settings window and select I want merchants to be able to select me to perform their MasterPass implementation checkbox. You can change this setting by clearing this checkbox. Global Version June

54 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity Merchant Registration and Setup Merchant Activity Before beginning this process, request an invitation code from your MasterCard representative; this will grant you access and allow you to register within the merchant portal. About this task Developers invited to integrate MasterPass on behalf of a service provider will manage their integration activities through following portals. MasterPass Merchant Portal ( MasterCard Developer Zone ( Procedure 1. From the MasterPass Merchant Portal, select the country language from the dropdown and click the Create an Account button to start the registration process. 2. You will be presented with a modal window, into which you will enter the invitation code and click the Continue button. NOTE: Merchant invitation codes should begin with the prefix MT. Global Version June

55 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity After entering the invitation code, you will be presented with the option to select the registration type. 3. Select Merchant to continue with the registration process. If you need to register as a Service Provider, access the Service Provider Integration Guide(s). 4. Complete all of the required fields in the Enter Account Information screen. 5. From the Enter Security Information screen, choose your security questions and enter the answers. Global Version June

56 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity 6. Complete all of the required fields on the Enter Business Information screen. 7. After the merchant account has been created, select Shipping Profiles to indicate the countries to which your company ships your goods. NOTE: The following module will appear with a different graphical design than others, as the MasterPass merchant portal is being redesigned on a module-by-module basis. Global Version June

57 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity Merchants must have at least one shipping profile (and no more than 25). 8. Merchants may set a default shipping profile by clicking the box next to Save as Default. Global Version June

58 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity To edit this information at any time, click the View link. 9. Select Loyalty Program to enter details about your loyalty program. The loyalty program s name and logo will be displayed to the consumer when they are registering or updating their wallet. The recommended dimensions for a loyalty program logo are 65x60 pixels. NOTE: The MasterPass Merchant Portal is currently being redesigned and parts of experience may vary during the transition to the new experience. Global Version June

59 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity NOTE: Your loyalty program will initially be in test status, and the Sandbox Only option will be selected by default. To add this loyalty program to Production, you must select the Production option and click Save. 10. If 3-D Secure is not available to you, you will not see the Authentication Settings option. If the option is available in your country, select Authentication Settings to enable 3-D Secure Authentication. Where available, 3-D Secure can be enabled for MasterCard (which includes Maestro) and Visa cards. 3-D Secure authentication allows merchants to gain liability shift on fraudulent ecommerce transactions. You will first need to supply the details of your merchant acquirer accounts Global Version June

60 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity 11. To add an acquirer, select Add Acquirers. Complete the form, including acquirer name and ID number, your assigned merchant ID, and supported currencies under that acquirer. NOTE: MasterCard SecureCode is used to set up acquirers for both MasterCard and Maestro transactions. Global Version June

61 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity Once saved, successfully added acquirer profiles will appear on the page by card brand. To complete the setup for 3-DS, select the Advanced Checkout check box for each card brand to enable 3-DSfor that brand. NOTE: If you enable your account for 3-DS, you will have the option to out of 3-DS checkout by clearing the Advanced Checkout check box on this page. Global Version June

62 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity Results MasterCard uses a third party, Cardinal Commerce, to act as a Merchant Plug In (MPI) for the 3-D Secure step-up process. When set up, the 3-D Secure user interface will be involved for all checkout transactions for the selected card brand. The 3-D Secure onboarding status for an acquiring account will be provided in the acquirer list under each card brand. Global Version June

63 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity The possible merchant 3-D Secure statuses are as follows: SUBMITTED: The merchant's acquirer information has been submitted to Cardinal Commerce. ACQUIRER PENDING: Cardinal Commerce is in the process of onboarding the merchant to its system, and the merchant s acquirer information has been sent to the card brand company and is waiting completion. ACTIVE: The merchant has been successfully registered in the Cardinal Commerce system, and the acquirer is participating. You are ready to process 3-D Secure production transactions. ACQUIRER NOT SUPPORTED: The acquirer ID (BIN) used in the merchant registration is not valid. Upon receiving this message, you will receive an from Masterpass Merchant support team attached with an unknown acquirer form. Global Version June

64 Service Provider Merchant by Merchant Onboarding Steps Merchant Registration and Setup Merchant Activity When adding your acquirer accounts, it is possible that your acquirer has not previously been onboarded to Cardinal s system. In this case, you will need to download and complete the Acquirer Certificate Request and submit it to Cardinal Commerce for processing. The form will be available in the portal upon submission of an unrecognized acquirer ID and will be sent to you by . Acquirer setup may take 3 5 business days once the Acquirer Certificate Request is returned to Cardinal. Global Version June

65 Service Provider Merchant by Merchant Onboarding Steps Invite Service Provider to be Merchant s Developer Merchant Activity Invite Service Provider to be Merchant s Developer Merchant Activity The following process explains how to invite a service provider to be the merchant's developer. Procedure 1. Sign in to your merchant s account from the MasterPass Merchant Portal. 2. On the MasterPass Setup page, click the Start This Step button under the Add developers option. 3. Select A third party platform provider. Global Version June

66 Service Provider Merchant by Merchant Onboarding Steps Invite Service Provider to be Merchant s Developer Merchant Activity 4. Select the service provider from the vendor drop-down list. Results Service provider business owners will be notified as soon as the organization has been selected by a merchant. The service provider s developer will receive invitation s from MasterPass indicating that they have been selected to handle the technical integration of Global Version June

67 Service Provider Merchant by Merchant Onboarding Steps Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity MasterPass Services on behalf of the merchant. The integration guide will guide the developer through the integration process. Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity Developers invited to integrate MasterPass on behalf of a merchant will manage their integration activities through two portals. MasterPass Merchant Portal ( MasterCard Developer Zone ( NOTE: These are two different websites that use different login credentials. If you are a new developer for MasterPass, you must sign up for a new account on Developer Zone. MasterPass Merchant Portal Developer Account Developers will use the MasterPass Merchant Portal to request and access merchant-specific integration credentials (consumer keys and checkout identifiers), which will be used when interacting with the MasterPass web services. After the service provider invites you as a developer, you will receive your MasterPass Developer credentials in two s from MasterPass. along with instructions for creating your portal account and links to the MasterPass development documentation and resources. You do not need a Developer Zone Account to access and view this documentation. Create a MasterCard Developer Zone Account Developers invited to integrate MasterPass on behalf of a merchant will use MasterCard Developer Zone to view integration documentation and generate developer keys. Complete the following steps to create your MasterCard Developer Zone account and access these tools. Procedure 1. From the Manage Development page of the MasterPass Merchant Portal, click Start This Step under the Register on Developer Zone option. Global Version June

68 Service Provider Merchant by Merchant Onboarding Steps Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity If you do not have the MasterPass Merchant Portal open, simply go to developer.mastercard.com. 2. From the main page of the MasterCard Developer Zone, click Register. 3. Complete and submit the registration form. After submitting the form, you will receive a confirmation Activate your MasterCard Developer Zone profile by clicking on the link included in the confirmation . Global Version June

69 Service Provider Merchant by Merchant Onboarding Steps Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity Generate MasterCard Developer Zone API Keys After creating your account, you will need to generate two API keys: one for the sandbox environment and one for the production environment. Generate MasterCard Developer Zone API Key for Sandbox Environment To create an API key for the sandbox environment, complete the following steps. About this task To make keys easy to distinguish, it is recommended to prefix sandbox keys with "SBX_". Procedure 1. Click My Account, then My Dashboard. 2. On the My Dashboard page, select the My Keys tab and click on the Add a Key button. Global Version June

70 Service Provider Merchant by Merchant Onboarding Steps Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity 3. To get an API Key, you need to supply a PEM encoded Certificate Request File. You may use a tool of your choice, such as OpenSSL or Java Keytool to generate this CSR, or you may use the CSR generation tool. Click here to see instructions for using CSR generation tool. 4. Complete the form, select Sandbox for Environment, and click Submit. Results You will have a Sandbox Key ID at this point. Global Version June

71 Service Provider Merchant by Merchant Onboarding Steps Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity NOTE: Keys expire after one year before which they should be renewed by initiating the Developer Zone Key Renewal process. The Certificate Request File initially submitted for the key creation will be needed to renew the key. Notifications at 30, 15, and one day prior to key expiration will be sent to the address associated with the Developer Zone account. When the keys expire, the project will not work and the MasterPass transactions will fail. Therefore, the keys need to be renewed prior to expiration. Generate MasterCard Developer Zone API Key for Production Environment To create an API key for the production environment, complete the following steps. About this task To make keys easy to distinguish, it is recommended to prefix production keys with "PRD_". Procedure 1. Click My Account, then My Dashboard. Global Version June

72 Service Provider Merchant by Merchant Onboarding Steps Developer Registration, API Keys, Initiate Development, and Request Sandbox Approval Developer Activity 2. On the My Dashboard page, select the My Keys tab and click on the Add a Key button. 3. Complete the form, select Production for Environment, and click Submit. Results At this point, developers will have a Sandbox Key ID and a Production Key ID, which will be used when creating a checkout project in the MasterPass Merchant Portal. NOTE: Keys expire after one year before which they should be renewed by completing the Developer Zone Key Renewal process. The Certificate Request File initially submitted for the key creation will be needed to renew the key. Notifications at 30, 15, and one day prior to key expiration will be sent to the address associated with the Developer Zone account. When the keys expire, the checkout project will not work and the MasterPass transactions will fail. Therefore the keys need to be renewed prior to expiration. Initiate Development and MasterPass Implementation Once a developer has generated their MasterCard Developer Zone API keys, they can begin developing their own implementation. Sample Applications for C#.NET, Java, PHP, and Ruby will be made available for download from the Sample Code tab on the MasterCard Developer Zone. Contact MasterPass Support if the sample applications are not available in the language you need. Global Version June

73 Service Provider Merchant by Merchant Onboarding Steps Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) MasterPass follows the OAuth 1.0a specification. Any merchant or service provider integrating with MasterPass must strictly adhere to the OAuth specs for interacting with MasterPass through Open API Gateway. Failure to implement OAuth correctly may impact your integration and transactions with MasterPass. For more details, refer to the Authentication page on the Developer Zone. Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) Prior to allowing the developer s code to interact with the MasterPass service (on behalf of a merchant), the merchant administrator must approve a request to link the developer s API keys to create a credential called a consumer key created by the developer in the Developer Zone with the merchant identifier. About this task Typically, the developer will make two separate key approval requests: Request to generate a consumer key that will grant the developer access to the MasterPass sandbox environment on behalf of the merchant NOTE: The sandbox environment does not contain real consumer data. Request to generate a consumer key that will grant the developer access to the production environment to enable real transactions Developers will use the MasterPass Merchant Portal to request and access merchant-specific integration credentials which will be used when interacting with the MasterPass services. The consumer keys are generated by requesting key approval from the business owner in the Key Management module; the checkout identifiers are generated in the Digital Assets module. Procedure 1. To get started, sign into the MasterPass Merchant Portal. Under Manage Development, click Key Management to open an interface with MasterCard Developer Zone, enter your Developer Zone credentials, and click Sign In. Global Version June

74 Service Provider Merchant by Merchant Onboarding Steps Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) NOTE: If you have not already set up your Developer Zone account, click here. 2. After you have entered your Developer Zone information, to create a sandbox or production key, click Create Consumer Key. 3. Select the key type (i.e., sandbox or production), and then click Continue. 4. After clicking Browse Keys, a list of all the keys of the specified type you have in your Developer Zone account is displayed; select the key you want to associate with the merchant s Masterpass integration. Global Version June

75 Service Provider Merchant by Merchant Onboarding Steps Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) Click Submit for Approval; an will be sent to the merchant administrator for approval. Upon approval, a MasterPass consumer key will be generated for the selected environment and will be displayed on this page. These keys, along with the Checkout Identifier (refer to Digital Assets section below) are required to make MasterPass calls in sandbox and production environments. 5. Repeat the steps above as needed to generate additional keys. Typically, developers need at least one sandbox and one production key for each merchant integration. 6. To generate or view a checkout identifier, under Manage Development, click Digital Assets. If the merchant administrator has previously input data for the required fields for this module during registration, the checkout identifiers will be displayed on the main page. Global Version June

76 Service Provider Merchant by Merchant Onboarding Steps Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) To edit this information at any time, click the View link. If the merchant administrator has requested that the developer input this data on behalf of the merchant, click Add Assets, and enter the merchant display name, an alias identifying this set of digital assets (e.g. website or Android app ), and an optional description of the merchant s goods/services Global Version June

77 Service Provider Merchant by Merchant Onboarding Steps Review Key Request and Approve/Reject Merchant Activity NOTE: If no logo is provided, the merchant name will be displayed. Review Key Request and Approve/Reject Merchant Activity After the developer submits the request for sandbox or production credentials, the merchant will get an notification. Procedure 1. Upon receipt of the notification that a developer has submitted a key request for approval, log on to the portal and click Key Management. 2. Click the down arrow to the right of the developer s name to view the details of the request (environment, key alias, key status, date of expiration, and the consumer key). Global Version June

78 Service Provider Merchant by Merchant Onboarding Steps Review Key Request and Approve/Reject Merchant Activity 3. To approve the developer s request for a new key, click Approve, or to reject the request, click Deny. The key status will update on the portal UI for the administrator as well as for the requesting developer. An notification will also be sent to the requesting developer notifying him/her that the approval request has been completed. If the request was approved, the developer will also be able to see the system-generated consumer key that is needed to make calls to MasterPass services. Global Version June

79 Service Provider Merchant by Merchant Onboarding Steps Deploy Application Using Production Credentials Developer Activity 4. Make a note of the following values as they will be used in the code to integrate with MasterPass web services: Consumer Key (97 characters) Callback URL Checkout Identifier Keystore and Keystore Password Deploy Application Using Production Credentials Developer Activity Once the merchant has approved the checkout project, the developer will receive containing the merchant s production Consumer Key, production callback URL and the Checkout Identifier. Procedure 1. Prior to production deployment, ensure that (a) you have implemented the MasterPass button on your site or app and (b) your sandbox implementation passes all items in the QA checklist. 2. To move your code to production, update your code with the following: Global Version June

80 Service Provider Merchant by Merchant Onboarding Steps Deploy Application Using Production Credentials Developer Activity MasterPass production endpoint Merchant s production Consumer Key Production callback URL Keystore (if different than Sandbox) 3. The last step is to deploy your code to production. NOTE: For more details on the specific configuration parameters, refer to the FAQ section and look for the question, What are the various parameters I need to call MasterPass services, and where do I get them from? Global Version June

81 Integration Process Chapter 5 Integration Process This topic provides information on the MasterPass integration process. Lightbox Integration...82 Standard checkout...84 Standard Checkout Callback Redirect to Merchant Callback URL Parameters for Standard Checkout Checkout Callback Method Example...86 Implementing DSRP and Tokenization...86 DSRP Extension Points in the MasterPass Merchant API DSRP Extension Points in the MasterPass Checkout XML Tokenization Extension Points in the MasterPass Checkout XML...94 Split/Partial Shipments and Recurring Payment Transactions D Secure Considerations Testing DSRP Pairing with MasterPass Merchant outside of Checkout...97 Invoke MasterPass UI Return Checkout Callback Pairing with MasterPass Merchant During Checkout...99 Invoke MasterPass UI for Pairing During Checkout Return Checkout Callback Pairing during Checkout Callback Method Example Return Checkout (Checkout after Pairing) Invoke MasterPass UI for Connected Checkout Connected Checkout Callback MasterPass Service Descriptions Request Token Service Shopping Cart Service Merchant Initialization Service Access Token Service Retrieve Payment, Shipping Data, Rewards, and 3-D Secure Details Postback Service Android and ios App Integration Completing the Integration Global Version June

82 Integration Process Lightbox Integration For a step-by-step guide through integration and illustration of the various calls to MasterPass, download code samples available in various languages such as Java, C#, PHP, and Ruby. You can also access the sample code for correct implementation of signature base string and exchanges with MasterPass on the Merchant Checkout Services Sample Code page. Lightbox Integration Lightbox integration is required to launch the MasterPass user interface. Procedure 1. To invoke the Lightbox, merchants must include the following scripts to the page on which they are adding the Buy with MasterPass or Connect with MasterPass buttons. NOTE: Merchants invoking the Lightbox from an iframe must include both the sandbox and production scripts on the parent (outer) web page and the iframe source that is invoking MasterPass Lightbox. a. Add jquery. Include this jquery file from the public jquery repository: b. Add the MasterPass Integration Script to your checkout page. Sandbox MasterPass.client.js Production MasterPass.client.js 2. Add the MasterPass Checkout Button to your checkout page. NOTE: Be sure to change the image name to the image size and locale that you would like to use. For further details, refer to MasterPass Branding. 3. Launch MasterPass checkout on the click of the button. Global Version June

83 Integration Process Lightbox Integration Parameters for Invoking MasterPass Checkout Parameter Data Type Required Description requesttoken String Yes Your request token from the Standard Checkout flow callbackurl String Yes The URL to which the browser must redirect when checkout is complete NOTE: This is required even if you use callback functions. merchantcheckoutid String Yes Your unique checkout identifier from the MasterPass Merchant Portal allowedcardtypes String array No Card types accepted by merchant Version String No (default: v6) Masterpass API Version successcalback Function No The function that will be called if the MasterPass flow ends successfully failurecallback Function No The function that will be called if the MasterPass flow ends in a failure Global Version June

84 Integration Process Standard checkout Parameter Data Type Required Description cancelcallback Function No The function that will be called if the user cancels the MasterPass flow 4. Handle the callback on completion of checkout. On completion of checkout (success, failure or cancellation), the control will be transferred to your system either via the callback url or the callback functions. NOTE: If MasterPass is forced to go full screen, then you will not be able to call the JavaScript callback method and must use a merchant callback redirect. As a result, you must support always support the callback url redirect. Standard checkout The following steps are necessary to integrate a standard MasterPass checkout. For more details, click on each of the following steps: 1. Request Token Service 2. Shopping Cart Service 3. Merchant Initialization Service 4. Invoke MasterPass UI (Lightbox) for checkout 5. Standard Callback method and Redirect to callback URL 6. Access Token Service 7. Retrieve Payment, Shipping Data, Rewards, and 3DS Details 8. Authorize Payment through payment processor 9. Postback Service NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must use the Merchant Initialization service to send the Origin URL. Standard Checkout Callback Once a checkout is completed, MasterPass will return context to the merchant. This can be done via the following: NOTE: If MasterPass is forced to go full screen, then you will not be able to call the JavaScript callback method and must use a merchant callback redirect. As a result, you must support both the callback method and the redirect. A callback URL: MasterPass uses the callback URL ( callbackurl ) parameter passed when invoking lightbox or oauth_callback from the request token call to direct back to the merchant site when lightbox is rendered in full-screen mode. Global Version June

85 Integration Process Standard checkout A JavaScript callback method: Use the failurecallback and successcallback parameters to give control back to the page that initiated the Lightbox without any redirects. These parameters must be set when invoking the MasterPass lightbox user interface. Use the cancelcallback parameter to notify a MasterPass merchant that a consumer has canceled their transaction. Callback Parameters for Standard Checkout Parameter Data Type Required Description mpstatus String Success, Failure, Cancel Indicates whether the MasterPass flow was completed and results in success, failure or cancel oauth_token String Used in conjunction with oauth_verifier to retrieve the access token oauth_verifier String Used in conjunction with oauth_token to retrieve the access token checkout_resource_url String API URL to retrieve checkout information Example of Callback URL (Successful Transaction) mpstatus=success checkout_resource_url=https%3a%2f%2fapi.mastercard.com%2fmasterpass %2Fv6%2Fcheckout%2F17%3Fwallet %3Dphw& oauth_verifier=6c50838e31b7441e6eafa b13& oauth_token=d6fa aebb6183d44fb9688fb9dc8332dc Example of Callback URL (Cancelled Transaction) Example of Callback Function function handlecallbacksuccess (data) { callyourserverwith(data.oauth_token, data.oauth_verifier, data.checkout_resource_ur);} Redirect to Merchant Callback URL Parameters for Standard Checkout Merchants must use the following data parameters to complete the MasterPass Standard Checkout flow. mpstatus Success, failure, or cancel. Indicates whether MasterPass flow was completed. Global Version June

86 Integration Process Standard checkout oauth_token Used in concert with oauth_verifier to retrieve access token. oauth_verifier Used in concert with oauth_token to retrieve access token. checkout_resource_url API URL to retrieve checkout information. Following are examples of the redirect to merchant callback URLs when a transaction is successful or cancelled: Redirect to Merchant Callback URL Example for a Successful Transaction mpstatus=success&checkout_resource_url=https%3a%2f%2fsandbox.api.mastercard.com %2Fmasterpass %2Fv6%2Fcheckou t%2f %3fwallet %3Dphw&oauth_verifier=6c50838e31b7441e6eafa b13&oauth_token=d6fa aebb6183d44fb9688fb9dc8332dc Redirect to Merchant Callback URL Example for a Cancelled Transaction Checkout Callback Method Example The following is a sample of the checkout callback method. function onsuccessfulcheckout(data) { document.getelementbyid('oauthtoken').value=data.oauth_token; document.getelementbyid('oauthverifer').value=data.oauth_verifier; document.getelementbyid('checkouturl').value=data.checkout_resource_url; } Implementing DSRP and Tokenization A MasterPass transaction must meet the following conditions to be processed as a Digital Secure Remote Payment (DSRP) transaction. The merchant or service provider must have successfully implemented MasterPass Merchant API version 6, including the merchant initialization call and the new DSRP and tokenization extension points. The merchant or service provider must have successfully implemented MasterPass Merchant Mobile Checkout SDK that facilitates consumer transactions from the merchant Android application to an Android MasterPass wallet application (app-to-app). DSRP cryptograms can currently only be generated for transactions that occur for these Android app-to-app use cases. If Mobile Checkout is available in your country, refer to the MasterPass - Merchant Android SDK page on the MasterCard Developer Zone for more information. Systems must be in place to correctly identify authorizations for split/partial shipments and recurring payments so that the DSRP data is accurately processed for subsequent authorizations (for more information, refer to the section below). Global Version June

87 Integration Process Standard checkout The payment gateway and acquirer must have updated their Dual Message and Single Message System interfaces to pass and receive DSRP data elements (refer to the Digital Secure Remote Payment Acquirer Implementation Guide for more information). MasterPass recommends that merchants or service providers contact their payment gateway(s) and acquirer(s) to: Understand the changes the gateway and acquirer are making to support DSRP. Identify any corresponding work that the merchants or service providers must complete. The consumer s card issuer/wallet provider must have successfully updated their interfaces to pass and receive DSRP data elements. The consumer has elected to pay with a card that has been digitized (for MasterPass Mobile Checkout transactions, this will be a MasterCard Digital Enablement Services [MDES]-enabled MasterCard brand card). If any of these conditions has not been met, the transaction will be considered a standard MasterPass transaction. For MasterPass transactions that start on a merchant's Android application and complete on a consumer s Android MasterPass wallet application, a DSRP cryptogram will be generated. A DSRP cryptogram will be accompanied by a 16-digit token rather than the actual MasterCard card brand primary account number (PAN). Whenever a token is passed instead of the actual account number, the last four digits of the consumer s actual PAN will be passed in an extension point so that they can be displayed to the consumer if so desired. DSRP Extension Points in the MasterPass Merchant API Merchants and service providers must use the merchant initialization call and the Digital Secure Remote Payment (DSRP) extension points in the MasterPass Merchant API version 6 to pass and receive DSRP data elements and values. MerchantInitializationRequest with DSRP Extension Points V6 XML Details Element Description Type Min Max MerchantInitializationRe quest Root Element XML MerchantInitializationRe quest.oauthtoken Request Token (oauth_token) returned by call to the request_token API MerchantInitializationRe quest.originurl Identifies the URL of the page that initializes the lightbox string NA Global Version June

88 Integration Process Standard checkout Element Description Type Min Max MerchantInitializationRe quest.extensionpoint.ds RP.DSRPOptions.Option. BrandId MerchantInitializationRe quest.extensionpoint.ds RP.DSRPOptions.Option. AcceptanceType MerchantInitializationRe quest.extensionpoint.ds RP.UnpredictableNumbe r Required for DSRP transactions. Identifies the card brands for which DSRP is desired. The valid card IDs are master and maestro. Required for DSRP transactions. Indicates the type(s) of cryptograms the merchant or service provider can accept. Valid types are: UCAF and/or ICC (see descriptions that follow). MasterPass passes the most secure selection (ICC) if both acceptance types are indicated. Optional for DSRP transactions. EMVquality random number generated by the merchant, service provider, or if null by MasterPass and Base64 encoded string alpha 4-byte binary string 8 A cryptogram is the output of the process of transforming clear text into ciphertext for security or privacy. There are two forms in which the DSRP cryptograms may be generated and sent depending on the capabilities of the merchant, payment gateway, and acquirer systems: UCAF data: In this case, the EMV cryptogram and a subset of the EMV data are carried in the Universal Cardholder Authentication Field (UCAF) in data element (DE) 48, subelement 43. The UCAF cryptogram is Base64 encoded and is up to 32 characters in length and contains a subset of the EMV data including the application cryptogram, application transaction counter (ATC), unpredictable number, and cryptogram version. Global Version June

89 Integration Process Standard checkout Most merchant and acquirer systems are configured today to support UCAF data transmission. Full EMV data: In this case the full set of EMV data is carried in data element (DE) 55 Integrated Circuit Card (ICC) System-Related Data in transaction messages. The ICC cryptogram is Hex encoded and is up to 512 characters in length as it contains the full set of EMV data including all the data listed previously for UCAF plus other information such as issuer application data, terminal verification results, cryptogram information data (CID), cardholder verification method (CVM) results, authorized amount, other amount, transaction currency code, transaction date, transaction type, application primary account number (PAN), application expiration date, and terminal country code. While ICC is considered the more secure, recommended option, many merchant and acquirer systems today are not yet configured to support this data element. If the merchant and acquirer systems are enabled to send and receive the DSRP cryptogram data in both the UCAF and/or ICC (DE 55) forms, the merchant or service provider can specify both UCAF and ICC. In this instance, MasterPass passes the cryptogram with the highest level of security (ICC) if the consumer s wallet provider also supports ICC. If the consumer s wallet cannot support ICC, MasterPass passes the UCAF form of the cryptogram. The Unpredictable Number is four-byte binary data that is randomly generated (per the EMVCo Specification Bulletin No. 144) by either the merchant, service provider, or MasterPass (which is then passed back to the merchant or service provider at the end of the transaction). The presence of the Unpredictable Number provides an additional layer of security by providing an element that is unknowable and unique to a specific transaction. This prevents a cryptogram from being used for anything other than the transaction for which it was generated. MasterPass recommends that you do not populate the Unpredictable Number element; in such cases, MasterPass will generate the value on your behalf. However, if you want to generate your own random/unpredictable numbers in order to able to validate the transaction easily by comparing the number that you generated with what was returned to you refer to EMVCo s requirements for this value in the Random Number Generation section of the EMV Acquirer and Terminal Security Guidelines document. After generation, the value must then be Base64 encoded and passed in the Unpredictable Number extension point in the Merchant Initialization Request OpenAPI call. MerchantInitializationRequest with DSRP Extension Points Sample URL: NOTE: The following example illustrates a case in which a merchant has chosen to generate the unpredictable number; if the UnpredictableNumber field is left null, MasterPass will generate the value on behalf of the merchant. <MerchantInitializationRequest> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <OriginUrl> <ExtensionPoint> <DSRP> <DSRPOptions> Global Version June

90 Integration Process Standard checkout <Option> <BrandId>master</BrandId> <AcceptanceType>UCAF</AcceptanceType> </Option> </DSRPOptions> <UnpredictableNumber>413142==</UnpredictableNumber> </DSRP> </ExtensionPoint> </MerchantInitializationRequest> MerchantInitializationResponse Sample <MerchantInitializationResponse> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <ExtensionPoint> <UnpredictableNumber>413142==</UnpredictableNumber> </ExtensionPoint> <MerchantInitializationResponse> DSRP Extension Points in the MasterPass Checkout XML After a remote transaction has been facilitated and secured via Digital Secure Remote Payment (DSRP), the MasterPass wallet will generate a cryptogram that the merchant or service provider will receive in the Checkout XML. The "Checkout XML Sample with UCAF Cryptogram" illustrates a case in which a merchant or service provider has indicated that it can only receive a UCAF cryptogram. The "Checkout XML Sample with ICC Cryptogram" illustrates a case in which a merchant or service provider has indicated that it can receive (a) a UCAF or ICC or (b) an ICC crytogram. The elements shown in bold are elements that are impacted by the presence of a cryptogram. The AccountNumber element is a 16-digit, device-based token rather than the cardholder's actual card number. The ExpiryMonth and ExpiryYear elements indicate the expiration data of the provided token. The AuthenticateMethod element indicates that DSRP was the method utilized for this transaction. The DSRP ExtensionPoint elements are populated with the cryptogram, type, unpredictable number, and ECI flag. These extension points will usually be followed by token extension points described in more detail below. Checkout XML Sample with UCAF Cryptogram Received from URL: <Checkout> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <AccountNumber> </AccountNumber> <BillingAddress> <City>O fallon</city> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</line1> <Line2/> <Line3/> Global Version June

91 Integration Process Standard checkout <PostalCode>63368</PostalCode> </BillingAddress> <CardHolderName>Jane Doe</CardHolderName> <ExpiryMonth>6</ExpiryMonth> <ExpiryYear>2017</ExpiryYear> </Card> <TransactionId> </TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <PhoneNumber> </PhoneNumber> </Contact> <ShippingAddress> <City>O fallon</city> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</line1> <Line2/> <Line3/> <PostalCode>63368</PostalCode> <RecipientName>Jane Doe</RecipientName> <RecipientPhoneNumber>US </RecipientPhoneNumber> </ShippingAddress> <AuthenticationOptions> <AuthenticateMethod>DSRP</AuthenticateMethod> </AuthenticationOptions> <WalletID>208</WalletID> <PreCheckoutTransactionId>a4c411b-18h26t-icni2rol-1-ics6caee-123y</ PreCheckoutTransactionId> <ExtensionPoint> <DSRP> <DSRPData>Qwertyuio asdfghjklpois</DSRPData> <DSRPDataType>UCAF</DSRPDataType> <UnpredictableNumber>413142==</UnpredictableNumber> <Eci>02</Eci> </DSRP> </ExtensionPoint> Checkout XML Sample with ICC Cryptogram Received from URL: NOTE: US merchants will not receive the PreCheckoutTransactionId element in the following example. <Checkout> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <AccountNumber> </AccountNumber> <BillingAddress> <City>O fallon</city> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</line1> <Line2/> <Line3/> <PostalCode>63368</PostalCode> </BillingAddress> Global Version June

92 Integration Process Standard checkout <CardHolderName>Jane Doe</CardHolderName> <ExpiryMonth>6</ExpiryMonth> <ExpiryYear>2017</ExpiryYear> </Card> <TransactionId> </TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <PhoneNumber> </PhoneNumber> </Contact> <ShippingAddress> <City>O fallon</city> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</line1> <Line2/> <Line3/> <PostalCode>63368</PostalCode> <RecipientName>Jane Doe</RecipientName> <RecipientPhoneNumber>US </RecipientPhoneNumber> </ShippingAddress> <AuthenticationOptions> <AuthenticateMethod>DSRP</AuthenticateMethod> </AuthenticationOptions> <WalletID>208</WalletID> <PreCheckoutTransactionId>a4c411b-18h26t-icni2rol-1-ics6caee-123y</ PreCheckoutTransactionId> <ExtensionPoint> <DSRP> <DSRPData>Qwertyuio asdfghjklpoiuytrewq unhtsrebnkoiemskdh e9inyQwertyuio asdfghjklpoiuytrewq unhtsrebnkoiemskdh e9inyQwertyuio asdfghjklpoiuytrewq unhtsrebnkoiemskdh e 9inyQwertyuio asdfghjklpoiuytrewq unhtsrebnkoiemskdh e9i nyqwertyuio asdfghjklpoiuytrewq unhtsrebnkoiemskdh e9iny Qwertyuio asdfghjklpoiuytrewq unhtsrebnkoiemskdh e9inyqa zwsxedcrfvtgbyhnuj</dsrpdata> <DSRPDataType>ICC</DSRPDataType> <UnpredictableNumber>413142==</UnpredictableNumber> </DSRP> </ExtensionPoint> </Checkout> Checkout XML DSRP Details NOTE: For details on the remaining elements in XML, refer to the V6 Checkout XML Details table. Global Version June

93 Integration Process Standard checkout Element Description Type Min-Max Checkout.Card.Account Number Card number or primary account number (PAN) that identifies the consumer s card. For DSRP transactions the actual number is replaced with an MDES DSRP device-based or card on file token. Integer Checkout.Authenticatio noptions.authenticate Method The method used to authenticate the cardholder at checkout. Valid values are MERCHANT ONLY, 3DS and NO AUTHENTICATION, and DSRP. Alphanumeric NA Value equals DSRP for DSRP transactions. Checkout.ExtensionPoin t.dsrp.dsrpdata DSRP cryptogram generated by the consumer s MasterPass wallet Alphanumeric UCAF: Max 32 ICC: Max 512 Checkout.ExtensionPoin t.dsrp.dsrpdatatype Indicates the type of cryptogram generated by the consumer s MasterPass wallet. Alpha NA MasterPass passes the most secure selection (ICC) if the merchant or service provider has indicated they can accept both types (UCAF, ICC). Global Version June

94 Integration Process Standard checkout Element Description Type Min-Max Checkout.ExtensionPoin t.dsrp.unpredictablenu mber Checkout.ExtensionPoin t.dsrp.eci Encoded EMV-quality random number generated by either the merchant or MasterPass. Electronic commerce indicator (ECI) value (DE 48 SE 42 position 3). Present only when DSRP data type is UCAF. For MasterCard brand cards, value is: 02 Authenticated by ACS (Card Issuer Liability) 4-byte binary string 8 Numeric UCAF: 02 ICC: N/A NOTE: The Security Level Indicators (SLIs) found in Authorization DE 48 (Additional Data Private Data), subelement 42 (Electronic Commerce Indicators), subfield 1 (Electronic Commerce Security Level Indicator and UCAF Collection Indicator), positions 1 3 for a MasterPass DSRP transaction are 24X, where the positions 1 and 2 combination of 24 indicates a DSRP transaction and the position 3 value of X is the ECI value. Tokenization Extension Points in the MasterPass Checkout XML When MasterPass generates and replaces the primary account number (PAN) with a token (device-based or card-on-file), the Checkout XML that is returned to the merchant or service provider will include (a) a token in place of the actual account/card number in the AccountNumber element, (b) the expiry month and year of the token, and (c) values in the three tokenization-related extension points described in the Checkout XML Tokenization Details table. Merchants or service providers must parse the checkout XML to extract and utilize the values provided to: Display the last four digits of consumer s card number to facilitate the entry of the card security code or print on the order confirmation page and/or receipt. Identify and pass the identifier of the token requestor. Record the payment account reference (PAR) data element to link the current transaction to others made by the same consumer. Checkout XML Sample with Tokenization Extension Points NOTE: The elements shown in bold are affected by the presence of a token. Global Version June

95 Integration Process Standard checkout <Checkout> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <AccountNumber> </AccountNumber> <BillingAddress> <City>O fallon</city> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</line1> <Line2/> <Line3/> <PostalCode>63368</PostalCode> </BillingAddress> <CardHolderName>Jane Doe</CardHolderName> <ExpiryMonth>6</ExpiryMonth> <ExpiryYear>2017</ExpiryYear> </Card> <TransactionId> </TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <PhoneNumber> </PhoneNumber> </Contact> <ShippingAddress> <City>O fallon</city> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</line1> <Line2/> <Line3/> <PostalCode>63368</PostalCode> <RecipientName>Jane Doe</RecipientName> <RecipientPhoneNumber>US </RecipientPhoneNumber> </ShippingAddress> <AuthenticationOptions> <AuthenticateMethod>DSRP</AuthenticateMethod> </AuthenticationOptions> <WalletID>208</WalletID> <PreCheckoutTransactionId>a4c411b-18h26t-icni2rol-1-ics6caee-123y</ PreCheckoutTransactionId> <ExtensionPoint> <DSRP> <DSRPData>Qwertyuio asdfghjklpois</DSRPData> <DSRPDataType>UCAF</DSRPDataType> <UnpredictableNumber>413142==</UnpredictableNumber> <Eci>02</Eci> </DSRP> <Tokenization> <FPanSuffix>1234</FPanSuffix> <TokenRequestorId> </TokenRequestorId> </Tokenization> <PaymentAccountReference> abcdefghijkl9</ PaymentAccountReference> </ExtensionPoint> </Checkout> Global Version June

96 Integration Process Standard checkout Checkout XML Tokenization Details NOTE: For details on the remaining elements in XML, refer to the V6 Checkout XML Details table. Checkout XML Element Description Type Min Max Tokenization- Related Extension Points FPanSuffix Last digits of card number or primary account number that identifies the card. Also known as Funding Primary Account Number. Normally suffix is the last four digits. String 8 TokenRequestorId Identifier of the entity requesting the token, typically the wallet from which the transaction originated. For MasterPass transactions, this ID is that for MasterCard/ MasterPass or for the wallet provider. String 11 PaymentAccountR eference Data element that allows merchants/ service providers and acquirers to link all transactions for a single consumer even in the absence of the actual primary account number (PAN). Alphanumeric 24 For more information on the Payment Account Reference (PAR), refer to EMVCo Draft Specification Bulletin No Global Version June

97 Integration Process Standard checkout Split/Partial Shipments and Recurring Payment Transactions Split/partial shipments occur when an e-commerce merchant or service provider ships several items in separate consignments (for example, if a portion of the purchased items are out of stock or items are shipping from separate locations). Recurring payments occur when a cardholder has authorized a merchant to bill the cardholder s account on a recurring basis (for example, monthly or quarterly). The amount of each payment may or may not be the same. Only the first authorization for split/partial or recurring payments associated with a Digital Secure Remote Payment (DSRP) transaction may contain cryptographic data. Merchants or service providers must not include the cryptogram with each subsequent authorization request. They must indicate (in DE 48, SE 42, position 3), however, that the subsequent authorizations are associated with a previous authorization that was cryptographically authenticated (by coding a value of 07 in position 3 rather than a value of 02 as mentioned in the Eci row of the Checkout XML DSRP Details table in the DSRP Extension Points in the MasterPass Merchant API section). 3-D Secure Considerations It is important to note that the MasterPass Mobile Checkout product that facilitates merchant app-to-wallet app transactions automatically suppresses 3-D Secure for Digital Secure Remote Payment (DSRP) transactions when it is called from within the MasterPass wallet. Merchants should also suppress 3-D Secure for these transactions. For more information about the Mobile Checkout product, refer to the MasterPass - Merchant Android SDK page on the MasterCard Developer Zone. Testing DSRP For information on the tools that are currently available for testing Digital Secure Remote Payment (DSRP) implementation, send a message to the following address. merchant_testing_support@masterpass.com Pairing with MasterPass Merchant outside of Checkout The following steps are necessary to establish a connection to a consumer s wallet outside of checkout flow. NOTE: For Pairing to occur, the merchant must have a way of identifying consumers on the merchant site prior to requesting pairing. For more details, click on each of the following steps: 1. Authenticate user on merchant site 2. Request Token Service 3. Merchant Initialization Service 4. Invoke MasterPass UI (Lightbox) for Pairing 5. Pairing outside of Checkout Callback 6. Access Token Service Global Version June

98 Integration Process Standard checkout Invoke MasterPass UI Consumers can pair their MasterPass wallet with merchant outside of checkout by clicking the Connect with MasterPass button. Merchants can display this button anywhere on their site except on checkout pages or pages where payment is initiated to enable pairing outside of checkout, for example, Account Management. Within a script the merchant must invoke the connect method with the required parameters. Here is an example: <script type="text/javascript" language="javascript"> MasterPass.client.connect({ "pairingrequesttoken":"pairing_request_token_here", "callbackurl":" "merchantcheckoutid":"merchant_checkout_id_here", "requesteddatatypes":"[ REWARD_PROGRAM, ADDRESS, PROFILE, CARD]", "requestpairing":true, "version":"v6" }); </script> Required parameters are as follows: pairingrequesttoken Request token for pairing. callbackurl The URL to which the browser must redirect when checkout is complete. This is required unless the merchant prefers to use the callback method. If a merchant uses callback methods, and MasterPass is forced to go full screen, MasterPass will redirect to the URL sent in the request token call when the flow is complete. merchantcheckoutid The merchant s unique checkout identifier from the MasterPass Merchant Portal. requesteddatatypes An array of data types the merchant requests for pairing. Valid values are as follows: CARD PROFILE ADDRESS REWARD_PROGRAM requestpairing Value should be "true". version Checkout version (v6). Lightbox parameter details can be found here. Global Version June

99 Integration Process Standard checkout Return Checkout Callback Once a pairing flow completes, MasterPass will return context to the merchant. This can be done through a callback URL or a JavaScript callback method. If you want to use the callback method, failurecallback and successcallback parameters must be set when invoking MasterPass Lightbox. Merchants must use the following data parameters to complete the MasterPass pairing outside of checkout flow: mpstatus Success, failure, or cancel. Indicates whether MasterPass flow was completed. pairing_token Used in concert with pairing_verifier to retrieve long access token. pairing_verifier Used in concert with pairing_token to retrieve long access token. Callback Parameter Details ier=6c50838e31b7441e6eafa b13&pairing_token= bdb8cd83 deed1fbe73df b1f Pairing Callback Method Example function onsuccessfulpairing(data) { document.getelementbyid('pairingtoken').value=data.pairing_token; document.getelementbyid('pairingverifer').value=data.pairing_verifier; } Pairing with MasterPass Merchant During Checkout The following steps are necessary to establish a connection to a consumer s wallet during a checkout. For further information, click on each of the following steps: 1. Request Token Service to get Checkout request token 2. Request Token Service * to get pairing request token 3. Shopping Cart Service 4. Merchant Initialization Service * 5. Invoke MasterPass UI for Standard Checkout with Pairing 6. Pairing Callback Method or Redirect to Callback URL 7. Access Token Service to get Checkout access token 8. Access Token Service ** to get long access token 9. Retrieve Payment, Shipping Data, Rewards, and 3-D Secure Details * The request token service to get checkout request token and pairing request token is the same service call but needs to be differentiated by the merchant. ** The access token service will be called twice, one for long access token (used to retrieve precheckout data) and other to retrieve checkout data for current transaction. Global Version June

100 Integration Process Standard checkout 10. Authorize Payment through payment processor 11. Postback Service Invoke MasterPass UI for Pairing During Checkout Within a script tag the merchant must invoke the checkout method with the required parameters. Here is an example: <script type="text/javascript" language="javascript"> MasterPass.client.checkout({ "requesttoken":"request_token_here", "callbackurl":" "pairingrequesttoken":"pairing_request_token_here", "requesteddatatypes":"[ REWARD_PROGRAM, ADDRESS, PROFILE, CARD]", "merchantcheckoutid":"merchant_checkout_id_here", "allowedcardtypes":["master", "amex", "discover"], "requestpairing":true, "version":"v6" }); </script> Required parameters are as follows: requesttoken Request token used to get checkout access token. callbackurl The URL to which the browser must redirect when checkout is complete. This is required unless the merchant prefers to use the callback method. If a merchant uses callback methods, and MasterPass is forced to go full screen, MasterPass will redirect to the URL sent in the request token call when the flow is complete. pairingrequesttoken Request token used to get long access token. requesteddatatypes An array of data types the merchant requests for pairing. Valid values are as follows: CARD PROFILE ADDRESS REWARD_PROGRAM The values PROFILE and CARD are mandatory. merchantcheckoutid The merchant s unique checkout identifier from the MasterPass Merchant Portal. allowedcardtypes Card types accepted by merchant. requestpairing Value should be true. Global Version June

101 Integration Process Standard checkout version Checkout version (v6). Lightbox parameter details can be found here. Return Checkout Callback Once a checkout and pairing completes, MasterPass will return context to the merchant. This can be done via a callback URL or a JavaScript callback method. If you want to use the callback method, the failurecallback and successcallback parameters must be set when invoking MasterPass Lightbox. Merchants must use the following data parameters to complete the pairing during checkout flow: mpstatus Success, failure, or cancel. Indicates whether MasterPass flow was completed. oauth_token Used in concert with oauth_verifier to retrieve access token. oauth_verifier Used in concert with oauth_token to retrieve access token. checkout_resource_url API URL to retrieve checkout information. pairing_token Used in concert with pairing_verifier to retrieve long access token. pairing_verifier Used in concert with pairing_token to retrieve long access token. Redirect to Merchant Callback URL Example rce_url=https%3a%2f%2fstage.api.mastercard.com%2fmasterpass%2fv6%2fcheckout%2f %3Fwallet%3Dphw&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f8445 8&oauth_token=d9382e34e0721a68a cecdf89517e45498&pairing_verifier=6c5083 8e31b7441e6eafa b13&pairing_token=35b2a0cf87f8160fcb5d24996a12e db7cce4c530 Pairing during Checkout Callback Method Example Here is an example for the callback method. function onsuccessfulcheckout(data) { document.getelementbyid('oauthtoken').value=data.oauth_token; document.getelementbyid('oauthverifer').value=data.oauth_verifier; document.getelementbyid('checkouturl').value=data.checkout_resource_url; document.getelementbyid('pairingtoken').value=data.pairing_token; document.getelementbyid('pairingverifer').value=data.pairing_verifier; } Global Version June

102 Integration Process Standard checkout Return Checkout (Checkout after Pairing) The following steps provide information on how to integrate a connected checkout flow. For more details, click on each of the following steps: 1. Consumer logs onto Merchant site/app 2. Precheckout Data Service 3. Consumer makes card/shipping address selection and clicks on Buy with MasterPass 4. Request Token Service 5. Shopping Cart Service 6. Merchant Initialization Service 7. Invoke MasterPass UI for Connected Checkout 8. Return Checkout Callback 9. Access Token Service (Checkout) 10. Retrieve Payment, Shipping Data, Rewards, and 3-D Secure Details 11. Authorize Payment through payment processor 12. Postback Service NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must use the Merchant Initialization service to send the Origin URL. Invoke MasterPass UI for Connected Checkout Connected checkout can be used after a user has paired their wallet. The merchant will pass in selections based on the precheckout data for a streamlined checkout experience. Within a script tag the merchant must invoke the checkout method with the required parameters. Here is an example: <script type="text/javascript" language="javascript"> MasterPass.client.checkout({ "requesttoken":"request_token_here", "callbackurl":" "merchantcheckoutid":"merchant_checkout_id_here", "cardid":"card_id_here", "shippingid":"shipping_address_id_here", "precheckouttransactionid":"prechechout_txn_id_here", "walletname":"wallet_name_here", "consumerwalletid":"consumer_walletid_here", "version":"v6" }); </script> Required parameters are as follows: requesttoken The merchants request token from OpenAPI. callbackurl A URL to redirect the browser to when checkout is complete. This URL should match the domain specified when creating the checkout project. This is required unless the merchant prefers to use the callback method. If a merchant uses callback methods, and MasterPass Global Version June

103 Integration Process Standard checkout is forced to go full screen, MasterPass will redirect to the URL sent in the request token call when the flow is complete. merchantcheckoutid The merchant s unique checkout identifier from the MasterPass Merchant Portal. cardid The ID of the card the consumer selected. shippingid The ID of the shipping address the user selected. precheckouttransactionid Precheckout transaction ID from precheckout xml. walletname Wallet Name from precheckout xml. consumerwalletid Consumer Wallet ID from precheckout xml. version Checkout version (v6). Lightbox parameter details can be found here. Connected Checkout Callback Once a checkout completes, MasterPass will return context to the merchant. This can be done via a callback URL or a javascript callback method. If you want to use the callback method, the failurecallback and successcallback parameters must be set when invoking MasterPass Lightbox. Here are the examples: Redirect to Merchant Callback URL Example status=success&checkout_resource_url=https%3a%2f%2fstage.api.mastercard.com %2Fmasterpass%2Fv6%2Fcheckout%2F %3Fwallet %3Dphw&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458&oauth_token=d9382e3 4e0721a68a cecdf89517e45498 Callback method Example function onsuccessfulcheckout(data) { document.getelementbyid('oauthtoken').value=data.oauth_token; document.getelementbyid('oauthverifer').value=data.oauth_verifier; document.getelementbyid('checkouturl').value=data.checkout_resource_url; } Global Version June

104 Integration Process Standard checkout MasterPass Service Descriptions The following sections describe the different services offered by MasterPass. Request Token Service This must be executed when a consumer clicks the Buy with MasterPass or Connect with MasterPass buttons on your site/app. For Pairing during checkout, this service will need to be called twice: To exchange for a long access token which is used to retrieve precheckout data To exchange for an Access Token which is used to retrieve checkout data Request and response parameter details can be found here. Sandbox and Production Endpoints for the Request Token Service The endpoints to be used for the Request Token Service are as follows. Shopping Cart Service Merchants must call the Shopping Cart service before invoking the MasterPass UI for checkout. This enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. Request and response parameter details can be found here. NOTE: The product description needs to be HTML encoded and has a character limit of 100 characters. Global Version June

105 Integration Process Standard checkout Sandbox and Production Endpoints for the Shopping Cart Service The endpoints to be used for the Shopping Cart Service are as follows. Global Version June

106 Integration Process Standard checkout Merchant Initialization Service This service is used to pass the OriginURL field and to secure Lightbox connections between merchant and MasterPass. Merchant Initialization also has an optional SecondaryOriginUrl field if the service provider sets this. This is used only when the Lightbox will be invoked from a frame that is on a merchant site and when that frame is of a different domain than that of the merchant site, like for a service provider. This service requires a request token (OAuthToken). This service call should be used when shopping cart service is not called, for example, pairing outside of checkout flow. Request and response parameter details can be found here. Sandbox and Production Endpoints for the Merchant Initialization Service The endpoints to be used for the Merchant Initialization Service are as follows. Access Token Service The next step is to exchange a request token for a long access token from the MasterPass service. For Pairing during checkout, this service will need to be called twice: To request the checkout access token, which is used to retrieve checkout data To request the long access token, which is used to retrieve precheckout data You will need the Request Token (oauth_token) and Verifier (oauth_verifier) from the merchant callback to get an access token. Request and response parameter details can be found here. Sandbox and Production Endpoints for the Access Token Service The endpoints to be used for the Access Token Service are as follows. Retrieve Payment, Shipping Data, Rewards, and 3-D Secure Details Now you will use the Checkout Resource URL request parameter (checkout_resource_url) received from the callback URL to retrieve consumer s payment, shipping address, reward, and 3-D Secure information from MasterPass. The checkout resource URL supplied by MasterPass must be decoded and consumed by the merchant as provided by MasterPass. MasterPass may add or delete parameters in future. Below are two examples of callback URLs with the checkout_resource_url parameter in bold: 1. mpstatus=success&checkout_resource_url=https%3a%2f%2fapi.mastercard.com %2Fmasterpass%2Fv6%2Fcheckout Global Version June

107 Integration Process Standard checkout %2F &oauth_verifier=aa2ff8e8f1144f45c3b8fdc3d a49e387&oauth_t oken=b8361ad151af35f71df7b395e083befcaf8192dd Decoded checkout URL: checkout_resource_url= %2Fapi.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout %2F &checkoutId= &oauth_verifier=aa2ff8e8f1144f45c3b8fdc3d a49e387&oauth_token=b8361ad151af35f71df7b395e083befcaf8192dd Decoded checkout URL: checkout_resource_url= &checkoutId= Request and response parameter details can be found here. NOTE: MasterPass performs a CVC/CVV check at card enrollment. However, in accordance with PCI standards, CVC2/CVV2 data is not persisted, and will not be provided to the merchant. As the card data has been validated and securely stored by MasterPass, merchants must not require CVC/CVV entry from a consumer checking out with MasterPass. In cases where, prior to submitting their order, the cardholder chooses to replace the payment details provided by MasterPass with different, manually entered payment details, Merchants should ask the cardholder to enter CVV2/CVC2/CID as they would in the normal course and should not pass the wallet indicator flag to the acquirer. In this case, the transaction is no longer considered to be a MasterPass transaction. Checkout Postback is still required. It is recommended not to allow consumers to change their card details after returning from MasterPass. A three-byte wallet Indicator (WID) Flag (WalletID xml element in the checkout xml) will be part of the output returned by this request. This value must be passed to your acquiring bank, and will indicate that the customer s payment details were provided by the MasterPass service, rather than being manually entered. You may need to work with your payment provider (acquirer, payment gateway, and so on) to understand how best to handle this data element. In the event, your acquirer has not completed implementation of this element, your transactions will continue to process as-is. Contact customer support if you have any questions. The following message elements in the Dual Message System (Authorization and Clearing) and Single Message System carry this WID Flag: Dual Message System (Authorization) Data element (DE) 48 (Additional Data Private Data), subelement 26 (Wallet Program Data), subfield 1 (Wallet Identifier) Dual Message System (Clearing) PDS 0207 (Wallet Identifier) Single Message System DE 48 (Additional Data), subelement 26 (Wallet Program Data), subfield 1 (Wallet Identifier) Global Version June

108 Integration Process Standard checkout Postback Service The final step of a MasterPass transaction is a service call from the merchant to MasterPass, communicating the result of the transaction (success or failure). Abandoned transactions do not need to be reported. The <TransactionId> value should be the value from the <TransactionId> element of the Checkout XML returned in the Checkout request. Request and response parameter details can be found here. The following fields are passed in the postback service call: ConsumerKey: Consumer key from checkout project Currency: Currency for the transaction, for example, USD OrderAmount: Transaction order amount with no decimals, for example, 1500 (for USD 15 transaction amount) PurchaseDate: Date of Purchase ApprovalCode: Six-digit approval code returned by payment API. Global Version June

109 Integration Process Standard checkout TransactionId: Transaction ID from TransactionId element of the Checkout XML from the retrieve payment, shipping, rewards, and 3-D Secure data service call for example, TransactionStatus: Status of transaction. Valid values are: SUCCESS: For approved transaction FAILURE: For declined transaction PreCheckoutTransactionId: Comes from PrecheckoutTransactionId element of the PrecheckoutData XML. (This is not required for Standard Checkout) Sandbox and Production Endpoints for the Postback Service The endpoints to be used for the Postback Service are as follows. Android and ios App Integration In order to integrate the MasterPass web checkout experience into your Android or ios application, you must integrate with all of the MasterPass services described previously.. Mobile Browser Support Below is a list of mobile browsers supported by MasterPass Lightbox. Phone ios 8+ (Safari ) on iphone 6+ ios 8+ (Safari) on iphone 5+ Android 4.0+ (Chrome ) Android 4.0+ (Stock Browser) Tablet ios 8+ (Safari) Android 4.0+ (Chrome) Android 4.0+ (Stock Browser) Sample Integration In the merchant's application, the merchant must have a Buy with MasterPass or Connect with MasterPass button depending on the MasterPass checkout process. Please refer to Chapter 2 MasterPass Checkout Experiences section for more information on the various checkout process flows. Merchants should integrate MasterPass Lightbox by refering to the Lightbox Integration section. Once MasterPass Lightbox Integration is completed, upon the user s clicking ofbuy with MasterPass or Connect with MasterPass button, the merchant application must redirect the user to a mobile browser that launches the MasterPass experience. Global Version June

110 Integration Process Standard checkout NOTE: MasterPass does not support webview for in-app implementation due to security issues. A sample web page implementation is provided below. Open URL in Mobile Browser Sample ios Objective-C Code to Open URL [ [UIApplication sharedapplication ] openurl : [NSURL URLWithString ] ] ; Sample ios Swift Code to Open URL UIApplication. sharedapplication ( ). openurl ( NSURL (string : "url_to_merchant_web_page_that_launches_masterpass" )! ) Sample Android Code to Open URL Uri uri = Uri. parse ( "url_to_merchant_web_page_that_launches_masterpass" ) ; Intent intent = new Intent (Intent.ACTION_VIEW, uri ) ; startactivity (intent ) ; Sample Web Page That Launches MasterPass <html> <head> <!-- url to sandbox masterpass lightbox --> <script type="text/javascript" src=" lightbox/switch/integration/masterpass.client.js "></script> <!-- url to production masterpass lightbox --> <!-- <script type="text/javascript" src=" Switch/integration/MasterPass.client.js "></script> --> <!-- url to jquery > <script type="text/javascript" src=" jquery/1.10.2/jquery.min.js"></script> </head> <body> <script> <!-- see sample javascript to invoke MasterPass below--> </script> </body> </html> Sample JavaScript to Invoke MasterPass Checkout Below is a sample JavaScript to invoke MasterPass. You can also see Lightbox Integration - Standard checkout for more information. $ (document ). ready ( function ( ) { MasterPass.client. checkout ( { // from MasterPass Request Token Service "requesttoken" : "request_token", // redirect url after checkout is completed "callbackurl" : "merchant_callback_url", // checkout identifier from the MasterPass Merchant Portal "merchantcheckoutid" : "merchant_checkout_id", // Card types accepted by merchant "allowedcardtypes" : [ "master,amex,diners,discover,maestro,visa" ], Global Version June

111 Integration Process Standard checkout // version v6 "version" : "v6" } ) ; } ) ; Handling Callbacks from MasterPass In addition to invoking MasterPass, the merchant must implement callbacks from MasterPass on its backend system when a transaction is successful or cancelled. For Standard Checkout callback, please refer to Standard Checkout Callback. For Standard Checkout callback, please refer to Standard Checkout Callback For Pairing with MasterPass Merchant outside of Checkout, please refer to Pairing with MasterPass Merchant outside of Checkout - Callback Parameter Details - page 88 For Pairing with MasterPass Merchant during Checkout, please refer to Pairing with MasterPass Merchant during Checkout - Redirect to Merchant Callback URL Example - page 90 For Return Checkout (Checkout after Pairing), please refer to Return Checkout (Checkout after Pairing) - Redirect to Merchant Callback URL Example - page 92 Redirecting User Back to Merchant App After a checkout is completed, the merchant should implement its own mechanism to redirect users back to its mobile application. Android On Android, one of the ways to redirect users back to a native application from browser is to use an Intent. You can find more information by referring to Android's developer website. Helpful Links When coming from the Chrome mobile browser When using Android Intent ios On ios, some of the ways to redirect users back to a native application from browser are to use URL Schemes and Universal Links. You can find more information by refering to Apple's developer website. Helpful Links URL Schemes iphoneosprogrammingguide/inter-appcommunication/inter-appcommunication.html Universal Link Global Version June

112 Integration Process Completing the Integration UniversalLinks.html Completing the Integration By the end of the integration, your site or mobile app must be able to do the following: 1. Display Buy with MasterPass button and the Learn More link at the start of the checkout experience. 2. Invoke and display the MasterPass Lightbox. 3. Relay MasterPass checkout requests to the MasterPass service. 4. Receive consumer s billing, shipping address, and rewards data from MasterPass service. 5. Process card, shipping, and rewards information using existing checkout process. NOTE: Your implementation must satisfy all criteria in the Q/A Checklist. Global Version June

113 MasterPass Branding Chapter 6 MasterPass Branding This topic provides information on MasterPass branding. Displaying Buy with MasterPass Button and Acceptance Marks Buy With MasterPass Button Example MasterPass Checkout Images Displaying the Connect with MasterPass Button Connect with MasterPass Button Example Connect with MasterPass Image Files MasterPass Learn More Page Global Version June

114 MasterPass Branding Displaying Buy with MasterPass Button and Acceptance Marks Displaying Buy with MasterPass Button and Acceptance Marks The MasterPass acceptance mark and checkout button image URLs can be found here. To ensure the best consumer experience, the checkout button should be placed at the earliest possible entrypoint, prior to the collection of shipping and billing information. NOTE: Downloading and locally hosting the MasterPass acceptance-mark and checkoutbutton images is against MasterPass integration guidelines. To minimize the impact of future branding updates, use the country-specific link to the images on the checkout page. To successfully integrate with MasterPass and enable successful checkout by an end-user consumer via the service, the Buy with MasterPass checkout button must be integrated on the merchant website and displayed as noted in the MasterPass Merchant Branding Requirements document available on the Merchant Checkout Services - Documentation page of the MasterCard Developer Zone. For all production button URLs and "Learn More" links, refer to the MasterPass Digital Assets Buttons and Learn More Links document. The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO ), and Button file name as follows: Base URL/Language/Country/Image File Name Base URL: NOTE: The list of language/country folders can be found on the MasterPass - Merchant Checkout Services - FAQs page under the question, Which countries and locales are currently supported to host Buy with MasterPass images? Buy With MasterPass Button Example The following is an example of how a merchant can include the checkout button. <div class="masterpassbtnexample"> <a href="/exampleredirect"> <img src=" mcpp_wllt_btn_chk_147x034px.png" alt="checkout with MasterPass Button Example" /> </a> </div> Global Version June

115 MasterPass Branding Displaying Buy with MasterPass Button and Acceptance Marks MasterPass Checkout Images This topic provides information on MasterPass checkout images. PNG Checkout Buttons /mcpp_wllt_btn_chk_147x034px.png /mcpp_wllt_btn_chk_160x037px.png /mcpp_wllt_btn_chk_166x038px.png /mcpp_wllt_btn_chk_180x042px.png GIF Checkout Buttons /mcpp_wllt_btn_chk_147x034px.gif /mcpp_wllt_btn_chk_160x037px.gif /mcpp_wllt_btn_chk_166x038px.gif /mcpp_wllt_btn_chk_180x042px.gif GIF Acceptance Marks /mp_mc_acc_023px_gif.gif /mp_mc_acc_030px_gif.gif /mp_mc_acc_034px_gif.gif /mp_mc_acc_038px_gif.gif /mp_mc_acc_050px_gif.gif /mp_mc_acc_065px_gif.gif /mp_mc_acc_113px_gif.gif PNG Checkout Buttons High Resolution /mcpp_wllt_btn_chk_290x068px.png /mcpp_wllt_btn_chk_317x074px.png /mcpp_wllt_btn_chk_326x076px.png /mcpp_wllt_btn_chk_360x084px.png GIF Checkout Buttons High Resolution /mcpp_wllt_btn_chk_290x068px.gif /mcpp_wllt_btn_chk_317x074px.gif /mcpp_wllt_btn_chk_326x076px.gif /mcpp_wllt_btn_chk_360x084px.gif GIF Acceptance Marks High Resolution /mp_acc_046px_gif.gif /mp_acc_060px_gif.gif /mp_acc_068px_gif.gif /mp_acc_076px_gif.gif /mp_acc_100px_gif.gif /mp_acc_130px_gif.gif /mp_acc_226px_gif.gif Here are a few examples: U.S. English URL: Canada French URL: Global Version June

116 MasterPass Branding Displaying the Connect with MasterPass Button Displaying the Connect with MasterPass Button This button is used to initiate pairing outside of a checkout. The MasterPass Connect with MasterPass button image URLs may be found in the MasterPass Digital Assets Buttons and Learn More Links document available on Merchant Checkout Services - Documentation page of the MasterCard Developer Zone. To minimize the impact of future branding updates, use the country-specific link to the images on the checkout page rather than downloading them and hosting the images locally. In order to successfully integrate with MasterPass and enable successful connection by an end-user consumer via the service, the Connect with MasterPass button must be integrated on the merchant website and displayed as noted in the MasterPass Merchant Branding Requirements document available on Merchant Checkout Services - Documentation page of the MasterCard Developer Zone. The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO ), and Button file name as follows: Base URL/Language/Country/Image File Name Base URL: Here are a few examples: U.S. English URL Connect with MasterPass button: Canada French URL Connect with MasterPass button: NOTE: The list of language/country folders can be found on the MasterPass - Merchant Checkout Services - FAQs page under the question, Which countries and locales are currently supported to host Buy with MasterPass images? Connect with MasterPass Button Example The following is an example of how a merchant can include the Connect with MasterPass button. <div class="masterpassconnectbtnexample"> <a href="/exampleredirect"> <img src=" MasterPass.checkout.png" alt="connect with MasterPass" /> </a> </div> Global Version June

117 MasterPass Branding MasterPass Learn More Page Connect with MasterPass Image Files The image-file names of the Connect with MasterPass button are as follows. PNG Connect with Buttons /mp_connect_with_button_034px.png /mp_connect_with_button_037px.png /mp_connect_with_button_038px.png /mp_connect_with_button_042px.png /mp_connect_with_button_068px.png /mp_connect_with_button_074px.png /mp_connect_with_button_126px.png MasterPass Learn More Page In addition to the MasterPass checkout button and acceptance mark, MasterPass also requires merchants to provide a link to Learn More page which can be used by the consumers to get additional information about MasterPass. It is recommended that you place the link in close proximity to the Buy with MasterPass button. The Learn More page is available in multiple languages and can be accessed from the following link. For the list of all available languages, refer to the MasterPass Digital Assets Buttons and Learn More Links document. Global Version June

118 Testing Chapter 7 Testing This topic provides information on how to perform testing in the sandbox environment. MasterPass Sandbox Testing Sign up for a Test MasterPass Wallet Account during Checkout Q/A Checklist Checklist for MasterPass Asset Placement In-Wallet Experience Post-Wallet Experience Postback Checklist for the Connected Checkout Experience General Global Version June

119 Testing MasterPass Sandbox Testing MasterPass Sandbox Testing To access the necessary information to test in the sandbox environment, the developer must submit an approval request to the merchant and obtain a sandbox consumer key as explained earlier in the guide. The following pre-set MasterPass wallet accounts, which have previously been available for sandbox testing, are no longer available: joe.test@ .com joe.test3@ .com 3ds.masterpass+securecode@gmail.com 3ds.masterpass+verifiedbyvisa@gmail.com To conduct testing in the sandbox environment, you must first set up your own MasterPass test wallet account. Sign up for a Test MasterPass Wallet Account during Checkout To set up a MasterPass test wallet account during checkout, complete the following instructions. Procedure 1. Go to your merchant website in the test environment, add an item to the shopping cart, and click on the MasterPass checkout button. 2. In the Sign-in screen, click on the More Wallets drop-down menu at the top of the screen and ensure that you have selected country United Kingdom - English language. Global Version June

120 Testing MasterPass Sandbox Testing 3. Choose the MasterPass by MasterCard option from the selection of featured banks and providers. 4. In the United Kingdom MasterPass wallet sign-in screen, click on Sign up for a MasterPass. Global Version June

121 Testing MasterPass Sandbox Testing 5. Accept the MasterPass Terms and Conditions, the MasterPass Privacy Notice with Cookie Notice, and click Sign Up. 6. In the Tell us about yourself screen, enter your personal details and password. Ensure you use a real ID that you have access to (for example, your work address) and a valid phone number as prompted on the screen, such as Global Version June

122 Testing MasterPass Sandbox Testing 7. Choose a security question and provide an answer. 8. Add one of the test card numbers from the table below. Note that these are not real cards and cannot be used outside of the MasterPass testing environment. Category Test Card # CVC Expiration Date Billing Address MasterCard [any] [any] [any] MasterCard [any] [any] [any] MasterCard [any] [any] [any] MasterCard [any] [any] [any] Visa [any] [any] [any] Visa [any] [any] [any] Global Version June

123 Testing MasterPass Sandbox Testing Category Test Card # CVC Expiration Date Billing Address Visa [any] [any] [any] Visa [any] [any] [any] AMEX [any] [any] [any] AMEX [any] [any] [any] AMEX [any] [any] [any] AMEX [any] [any] [any] 9. Add a billing address (you can use 99 test street, London, UK, E145NP). 10. Add shipping addresses and click on Finish shopping. All of the transaction data will be sent to your test merchant site, and you will be redirected to your merchant test site (where you can submit/place the order). Global Version June

124 Testing Q/A Checklist NOTE: If you have a test payment gateway setup for this testing, you may need to replace the test card details provided above with your own test card data and send the transaction through to the gateway and MasterPass. Submit a postback, too, per MasterPass integration guidelines. Q/A Checklist This topic provides information on the Q/A checklist. Checklist for MasterPass Asset Placement The following is an checklist to follow for proper placement of MasterPass visual assets. Verify your adherence to the MasterPass Merchant Branding Requirements document found on the MasterPass - Merchant Checkout Services - Documentation page. Global Version June

125 Testing Q/A Checklist Verify that you are linking to all MasterPass visual assets (this includes the checkout button, acceptance marks, and Learn More link) and JavaScript library through provided URLs. Do not download and host these assets on your own side. Verify that the MasterPass checkout button is used appropriately on the checkout page to initiate the MasterPass experience. In-Wallet Experience The following is a checklist for the MasterPass in-wallet experience. Verify that the consumer can only select cards and addresses that are supported by the merchant. Verify that shopping cart information is sent to MasterPass and is displayed. Merchants requesting liability shift for MasterPass transactions should use Advanced Checkout/3-D Secure within MasterPass. Merchants must enable 3-D Secure such that it is invoked within the MasterPass wallet. Post-Wallet Experience The following is a checklist for post-wallet experience. After clicking the Finish Shopping button, verify the consumer is taken to a valid page. Verify that the MasterPass acceptance mark is displayed for all MasterPass transactions. Verify that MasterPass and issuer logo are displayed with precheckout data. As recommended by MasterPass, do not allow consumers to edit the payment information returned on the merchant site. Verify that any information provided by a consumer s MasterPass wallet (for example, payment, shipping, profile information, and so on) is used only for that transaction and is not stored for subsequent use. Verify that your code gracefully handles consumers returning without selecting a card and address (as a result of user choice or login failure). Verify that your code handles the return of a consumer with an expired request token. NOTE: The request token is valid for 15 minutes; therefore, if the process is not completed within the timeout, the request token will expire, and the checkout will need to be restarted. Verify that your code is able to parse and ingest the returned data. Verify that any post-masterpass wallet page has a clear call to action (for example, select preferred shipping method) versus simply having the consumer review the data they just selected in the wallet. Verify that the consumer is not required to enter CVC/CVV in order to complete the transaction. Verify that the card primary account number (PAN) has not been provided to any entity that does not have the appropriate security in place for storage and transmission of card data (per PCI guidelines). Verify that if merchants are provided with the PAN, this value is not displayed on screen. Global Version June

126 Testing Q/A Checklist Verify that your system can handle the PostalCode element of up to nine characters; this element is sent by MasterPass as part of the BillingAddress and the ShippingAddress elements in checkout XML. Postback The following is a checklist for postback: Ensure that you are submitting postback for all MasterPass transactions initiated with the consumer s click of the MasterPass checkout button (approved, declined, or abandoned). Verify that the transaction ID submitted as part of a postback was sourced from the associated MasterPass transaction. Verify that the transaction result (postback) is reported immediately. Checklist for the Connected Checkout Experience The following is a checklist for the connected checkout experience. Verify that the consumer is logged into merchant site before offering connected checkout. For pairing, you must request at least Card and Profile data elements. If a precheckout call gets rejected by MasterPass (merchant requests data that the consumer did not originally consent to, if the pairing has been deleted by the user, if the long access token has expired, and so on), the merchant has to request pairing again. Verify that pairing is offered during checkout or outside of checkout (for example, account management). General The following is a general checklist. Ensure that you are coding to DNS and not to IP addresses for our URLs and endpoints. Verify that your implementation follows the standard process and utilizes all calls (to the MasterPass wallet, complete postback, and so on) for each and every transaction initiated by a consumer s click of the MasterPass checkout button. Verify that you are accepting and passing the wallet identifier (WID) when present for MasterPass transactions. Global Version June

127 Troubleshooting Chapter 8 Troubleshooting This topic provides information on troubleshooting. Common Errors Support Global Version June

128 Troubleshooting Common Errors Common Errors The following are the procedures to troubleshoot the most common errors that you may encounter. If you get Error 400 when calling MasterPass web services: Verify Authorization header is not missing from the request. Verify Authorization header has the following: Signature Consumer Key (exists and correct length) Nonce Signature Method Timestamp Callback URL (Request Token call only) oauth_verifier (Access Token call only) oauth_token (Access Token call only) If you get Error 401 when calling MasterPass web services: Verify that you are passing the Access Token in the get CheckoutXML call. If you get Error Forbidden when calling MasterPass services: Verify correct credentials or correct environment (that is, sandbox credentials with the prod URL). Verify timestamp. If you get Error 500 when calling MasterPass web services: Verify oauth_body_hash exists and is correct (Post Transaction call only). Verify Content-Type HTTP header is being sent. Verify correct private key. Verify signature is readable (for example, encoded incorrectly). Support This topic provides information on how to get additional support. Refer to the FAQs at +Merchant+Checkout+-+FAQs. If you have any questions or comments relating to MasterPass merchant testing, contact the implementation manager assigned to work with you on this implementation. If you don t have an assigned implementation manager, send an with the following information (as applicable) to merchant_testing_support@masterpass.com: Merchant/Service Provider Name Global Version June

129 Troubleshooting Support Address Country/Region Onboarding Model (Direct Merchant, Service Provider Merchant-by-Merchant or Service Provider File and API Onboarding) Environment of Integration (Sandbox or Production) Checkout Version and Checkout Identifier Consumer Key Postback Details (Amount, Date and Time of recent Checkout) Detailed description of the issue, including expected and actual test results (if applicable) Error Message(s) Screenshot(s) Exact Timestamp Global Version June

130 Appendix Appendix Appendix A Appendix This appendix provides additional information related to MasterPass integration process. Lightbox Parameters OAuth Samples Request Token Merchant Initialization Service Shopping Cart Service Access Token Service Checkout Resource Pre-Checkout Resource Postback Service Renew Your Developer Zone Key Developer Zone Key Tool Utility D Secure Overview D Secure Service Description General Overview of MasterCard SecureCode and Verified by Visa Transaction Authentication Important Merchant Information Global Version June

131 Appendix Lightbox Parameters Lightbox Parameters This section provides descriptions of the MasterPass Lightbox parameters. Lightbox parameters invoked on clicking the Buy with MasterPass or Connect with MasterPass button O = Optional; R = Required; A = Automatically populated Parameter name Data type Card Security Checkout Description allowedcardtypes string[] O This parameter restricts the payment methods that may be selected based on card brand. Omit this parameter to allow all payment methods. Here are the valid values for different card types MasterCard: master Maestro: maestro American Express: amex Discover: discover Diners: diners Visa: visa JCB: jcb callbackurl string O O This defines the base URL to which the browser is redirected to upon successful or failed completion of the flow if there is no appropriate callback function available. cancelcallback functio n O O This defines the function to be called when the flow is cancelled by the consumer prior to completing checkout. cardid string O Required for connected checkout. Set to a valid payment card ID. Global Version June

132 Appendix Lightbox Parameters Parameter name Data type Card Security Checkout Description consumerwalletid string Required for connected checkout to uniquely identify consumer. failurecallback functio n O O This defines the function to be called when the flow ends in failure. Refer SDK for more examples. loyaltyenabled boolean O This parameter defines if the merchant is requesting consumer s loyalty details from MasterPass for the transaction. Valid values are True or False. loyaltyid string O Optional for connected checkout. Set to a valid loyalty card ID. merchantcheckoutid string R R This is the checkout identifier which is used to identify the merchant and their checkout branding. pairingrequesttoken string O This is an OAuth token. precheckouttransactionid string R Helps the wallet identify the wallet account for which precheckout data is provided. MasterPass includes this parameter in the checkout xml for connected checkout. requestbasiccheckout boolean O Set to "true" to disable step-up authentication (advanced checkout) during any checkout flow. The default is "false". Global Version June

133 Appendix Lightbox Parameters Parameter name Data type Card Security Checkout Description requesteddatatypes string[] O This indicates the types of data being requested for pairing. Possible values include "PROFILE", "CARD", "ADDRESS", and "REWARD_PROGRAM". "PROFILE" and CARD are mandatory data types. Refer to precheckout data xml to get details of these data types. This parameter is required when requestpairing is "true". requestpairing boolean O This indicates that the user is being asked to enable pairing. It is automatically set to "true" for the "Connected" flow. The default for other flows is "false". requesttoken string R R This is an OAuth token. shippingid string O Optional for connected checkout. Set to a valid shipping destination ID. shippinglocationprofile comma separat ed string O This parameter defines Merchant s Shipping Profile(s) for the transaction that they set in their account. Multiple values may be passed via comma separation (as in, no spaces within a profile name). For example, "CHEERIO,AUONLY,NAmerica". successcallback functio n O O This defines the function to be called when the flow ends in success. Global Version June

134 Appendix OAuth Samples Parameter name Data type Card Security Checkout Description suppressshippingaddressenable boolean O When set to true, the consumer placing the order through MasterPass Wallet will not provide a shipping address (for example, when the consumer purchases digital goods). When set to false, the consumer placing the order through MasterPass Wallet must provide a shipping address. walletname string Required for connected checkout to uniquely identify wallet name. OAuth Samples This topic provides information on OAuth samples. Request Token This section describes the Request Token parameters. Request Token Parameters request_token Request request_token Response oauth_callback oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm X X X X X X X X oauth_token oauth_callback_confirmed X X Global Version June

135 Appendix OAuth Samples request_token Request request_token Response oauth_expires_in oauth_token_secret xoauth_request_auth_url X X X Request Parameter Details Request Token Request Description Possible Values Signature Base String Authorization Header oauth_callback Endpoint that will handle the transition from the wallet site to the merchant checkout page Variable oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version oauth version 1.0 oauth_nonce oauth_signature_m ethod oauth_consumer_ke y Unique alphanumeric string generated from code oauth signature method. Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable RSA-SHA1 Variable oauth_timestamp Current timestamp Variable realm Used to differentiate between our mobile and full site. Currently not used. ewallet Request Token Response Description Possible Values Oauth Token oauth_token oauth_token is sent in the signature base string, authorization header and redirect URL Variable Request Token oauth_callback_con firmed Variable Global Version June

136 Appendix OAuth Samples Request Token Response Description Possible Values oauth_expires_in Time the Request Token expires in seconds Variable oauth_token_secret Oauth Secret Variable xoauth_request_aut h_url Authorize URL Variable Signature Base String Example POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Freque st_token&oauth_callback%3dhttp%253a%252f%252fprojectabc.com%252fmerchant%252f Callback.jsp%26oauth_consumer_key%3DZGho8Df8vqW- IpGCIu559HYriL093IBXdJeKavp4dce9db2a% b616c a413d3d%26oauth_nonce%3D %26oauth_signature_method%3DRSA- SHA1%26oauth_timestamp%3D %26oauth_version%3D1.0 HTTP Request Example POST /oauth/consumer/v1/request_token HTTP/1.1 Authorization: OAuth oauth_callback="http%3a%2f%2fprojectabc.com%2fmerchant%2fcallback.jsp",oauth_ signature="pznoggtgshe16%2fwhp4cstrxkgj1mv%2fkm6do5zvi6dokzajz0m8qqhieri5lrup hdyukhw8lkdul1tetpdxm32vtr%2bqgf6n6ibjr8dgcyymfalyayvhf%2fx5oqhudvpdxic10dj0m iuwzpbj1qopn3ibeozvgnxheihykvnpvyehc%3d",oauth_version="1.0",oauth_nonce=" ",oauth_signature_method="RSA- SHA1",oauth_consumer_key="ZGho8Df8vqW- IpGCIu559HYriL093IBXdJeKavp4dce9db2a% b616c a413d3d",oauth_timestamp=" ",realm="eWallet" HTTP Response Example oauth_callback_confirmed=true&oauth_expires_in=900&oauth_token=a02c5c5c1a128c2 cebc650ea9aa3dfb7&oauth_token_secret=c2daaf d82bd bee91f&xoauth_r equest_auth_url=https%3a%2f%2fsandbox.masterpass.com%2fonline%2fcheckout%2faut horize Merchant Initialization Service This section describes the Merchant Initialization parameters. Merchant Initialization Parameters Merchant Initialization resource Request Merchant Initialization Resource Response oauth_signature oauth_version oauth_nonce X X X Global Version June

137 Appendix OAuth Samples Merchant Initialization resource Request Merchant Initialization Resource Response oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_body_hash oauth_token Merchant Initialization Request XML X X X X X X X Merchant Initialization Response XML X Merchant Initialization Request Parameter Details Merchant Initialization Resource Request Description Possible Values Signature Base String Authorization Header oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version. 1.0 oauth_nonce oauth_signature_m ethod oauth_consumer_ke y Unique alphanumeric string generated from code oauth signature method. Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable RSA-SHA1 Variable oauth_timestamp Current timestamp Variable oauth_token Request token Variable Merchant Initialization Request XML MerchantInitializatio nrequest XML Merchant Initialization details Global Version June

138 Appendix OAuth Samples Merchant Initialization Resource Response Description Possible Values Oauth Token oauth_token oauth_token is sent in the request Variable PreCheckout TransactionID PreCheckout TransactionID PreCheckoutTransactionID sent in the request only for connected checkout. Variable Signature Base String Example POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%merchantinitial ization&oauth_body_hash%3d8k9uhvezjvdzw8aiyixpr70kctk%253d%26oauth_consumer_key %3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c% f c4a366c726a b d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4- B4263CB5A305%26oauth_signature_method%3DRSA- SHA1%26oauth_timestamp%3D %26oauth_version%3D1.0 HTTP Request Example POST /masterpass/v6/merchant-initialization HTTP/1.1 Authorization: OAuth realm="ewallet",oauth_consumer_key="clb0tkkejhgtitp_6ltdiibo5wgbx4rildexm_jrd4b 0476c%21414f c4a366c726a b d",oauth_signature_metho d="rsa-sha1",oauth_nonce="deaeb1cd-ca03-405d-a7b4- B4263CB5A305",oauth_timestamp=" ",oauth_version="1.0",oauth_body_hash= "8K9uhveZjVdZW8AIYiXpR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C 8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zrav b02oqtrvqh3zlx5fi4o0u2xxqrdwhzvbhjpgwbybrme%2fotw2l9h%2fznsn45xcs1ejpa%2fgi%3d" XML V6/merchant-initialization XML Schema Request <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="merchantinitializationrequest" type="merchantinitializationrequest" /> <xs:complextype name="merchantinitializationrequest"> <xs:sequence> <xs:element name="oauthtoken" type="xs:string" /> <xs:element name="precheckouttransactionid" type="xs:string" maxoccurs="1" minoccurs="0" /> <xs:element name="originurl" type="xs:string" /> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0" /> </xs:sequence> </xs:complextype> <xs:element name="merchantinitializationextension" type="merchantinitializationextension"/> <xs:complextype name="merchantinitializationextension"> <xs:sequence> <xs:element name="secondaryoriginurl" type="xs:string" minoccurs="0"/> </xs:sequence> </xs:complextype> Global Version June

139 Appendix OAuth Samples URL: Sample Request <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantInitializationRequest> <OAuthToken>oauth_demo_token4sj4x6f1eqka2ib2f1nzd1ib2ivvjx16a</OAuthToken> <OriginUrl> <ExtensionPoint> <SecondaryOriginUrl> </ExtensionPoint> </MerchantInitializationRequest> V6/merchant-initialization XML Schema Response <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="merchantinitializationresponse" type="merchantinitializationresponse"/> <xs:complextype name="merchantinitializationresponse"> <xs:sequence> <xs:element name="oauthtoken" type="xs:string"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any" /> </xs:sequence> <xs:anyattribute /> </xs:complextype> </xs:schema> V6/ MerchantInitialization Sample Response <MerchantInitializationResponse> <OAuthToken>4c7b34cc63a68282bba77a4b34f0192fcb2268fb</OAuthToken> </MerchantInitializationResponse> V6 MerchantInitializationRequest XML Details MerchantInitialization Request XML Element Description Type Min Max MerchantInitializationRe quest Root Element XML - Global Version June

140 Appendix OAuth Samples MerchantInitialization Request XML Element Description Type Min Max MerchantInitializationRe quest OAuthToken Request Token (oauth_token) returned by call to the request_token API - OriginUrl Identifies the URL of the page that will initialize the Lightbox. string NA ExtensionPoint Reserved for future enhancement. Optional Any SecondaryOriginUrl Identifies the domain URL of the outer/parent web page. This optional field should only be used when the Lightbox will be invoked from a frame that s on a merchant site, and when that frame is of a different domain than that of the merchant site, like for a service provider. string NA MerchantInitialization Response XML Element Description Type Min Max OAuthToken ExtensionPoint Request Token (oauth_token) returned by call to the request_token API Reserved for future enhancement. Optional XML - Any - ExtensionPoint Elements Starting with API v6, all schema container elements contain a new optional element named ExtensionPoint. These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of xs:any, meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an Global Version June

141 Appendix OAuth Samples ExtensionPoint element, beyond any that may be defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further, only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be dropped by MasterPass. ExtensionPoint Sample <ExtensionPoint> <s:sampleextension xmlns:s= ns > <s:samplefield>sample Value</s:SampleField> </s:sampleextension> <f:anotherexampleextension xmlns:f= example2/ns > <f:samplecontainer> <f:anothersamplefield>sample Value</f:AnotherSampleField> </f:samplecontainer> </f:anotherexampleextension> </ExtensionPoint> Shopping Cart Service This section provides description on the Shopping Cart parameters. Shopping Cart Parameters Shopping Cart Request Shopping Cart Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp oauth_body_hash X X X X X X X oauth_token X X Shopping Cart Request XML X Shopping Cart Response XML X Shopping Cart Parameter Details Shopping Cart Request Description Possible Values Global Version June

142 Appendix OAuth Samples Signature Base String Authorization Header oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version 1.0 oauth_nonce oauth_signature_m ethod oauth_consumer_ke y Unique alphanumeric string generated from code oauth signature method Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable RSA-SHA1 Variable oauth_timestamp Current timestamp Variable oauth_body_hash SHA1 hash of the message body Variable Oauth Token oauth_token oauth_token is sent in the signature base string, authorization header and redirect URL Variable Transfer XML Strings Shopping Cart Request XML Merchant Shopping Cart details Shopping Cart Response Description Possible Values Oauth Token oauth_token oauth_token is sent in the signature base string, authorization header and redirect URL Variable Transfer XML Strings Shopping Cart Response XML Signature Base String Example POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fshopping-cart &oauth_body_hash%3d8k9uhvezjvdzw8aiyixpr70kctk%253d%26oauth_consumer_key% 3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c % f c4a366c726a b d% 26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4-B4263CB5A305%26oauth_signature_method %3DRSA-SHA1%26oauth_timestamp% 3D %26oauth_version%3D1.0 Global Version June

143 Appendix OAuth Samples HTTP Request Example POST /masterpass/v6/shopping-cart HTTP/1.1 Authorization: OAuth realm="ewallet",oauth_consumer_key="clb0tkkejhgtitp_6ltdiibo5wgbx4rildexm_jrd4b047 6c% 21414f c4a366c726a b d",oauth_signature_method="RSA- SHA1",oauth_nonce="DEAEB1CD- CA03-405D-A7B4- B4263CB5A305",oauth_timestamp=" ",oauth_version="1.0",oauth_body_hash="8K 9uhveZjVdZW8AIYiXpR70KCtk% 3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C8t6PlW8xTrDob0WzWJ5% 2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQH3Zlx5fi4o0u2x xqrdwhzvbhjpgwbybrme% 2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D" Shopping Cart V6 XML Schema <xs:complextype name="shoppingcart"> <xs:sequence> <xs:element name="currencycode" type="xs:string"/> <xs:element name="subtotal" type="xs:long"/> <xs:element name="shoppingcartitem" type="shoppingcartitem" minoccurs="0" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="shoppingcartitem"> <xs:sequence> <xs:element name="description" type="xs:string"/> <xs:element name="quantity" type="xs:long"/> <xs:element name="value" type="xs:long"/> <xs:element name="imageurl" type="xs:string" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="shoppingcartrequest"> <xs:sequence> <xs:element name="oauthtoken" type="xs:string"/> <xs:element name="shoppingcart" type="shoppingcart"/> <xs:element name="extensionpoint" type="shoppingcartrequestextensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="shoppingcartrequestextensionpoint" type="shoppingcartrequestextensionpoint"/> <xs:complextype name="shoppingcartrequestextensionpoint"> <xs:sequence> <xs:element name="secondaryoriginurl" type="xs:string" minoccurs="0"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> <xs:element name="extensionpoint" type="extensionpoint"/> <xs:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> Global Version June

144 Appendix OAuth Samples Shopping Cart V6 XML Details ShoppingCartRequest Element Description Type Min Max OAuthToken Request Token (oauth_token) returned by call to the request_token API String Variable ShoppingCart ExtensionPoint Merchant Shopping Cart details Reserved for future enhancement. Optional XML - Any - ExtensionPoint SecondaryOriginUrl Identifies the domain URL of the outer/parent web page. This optional field should only be used when the Lightbox will be invoked from a frame, that is, on a merchant site and when that frame is of a different domain than that of the merchant site, like for a service provider. String NA ShoppingCart CurrencyCode Defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars. All MonetaryValues will be modified by the CurrencyCode. Alpha 3 Subtotal ShoppingCartItem Total sum of all the items in the cart excluding shipping, handling and tax. Integer without the decimal, for example, USD will be Details of a single shopping cart item. Integer 1 12 XML - ShoppingCartItem Description Describes a single shopping cart item. String Global Version June

145 Appendix OAuth Samples Quantity Value ImageURL ExtensionPoint Number of a single shopping cart item. Price or monetary value of a single shopping cart item. Cost * Quantity. Integer without decimal, for example, USD is Link to shopping cart item image. URLs must be HTTPS and not HTTP. Reserved for future enhancement. Optional Integer 1 12 Integer 1 12 String Any - ShoppingCartRespons e Element Description Type Min Max OAuthToken Request Token (oauth_token) returned by call to the request_token API String Variable ExtensionPoint Reserved for future enhancement. Optional Any - ShoppingCartRequest XML Sample <?xml version="1.0"?> <ShoppingCartRequest> <OAuthToken>f7f16d8462a afade20caaa</OAuthToken> <ShoppingCart> <CurrencyCode>USD</CurrencyCode> <Subtotal>11900</Subtotal> <ShoppingCartItem> <Description>This is one item</description> <Quantity>1</Quantity> <Value>1900</Value> </ShoppingCartItem> <ShoppingCartItem> <Description>Five items</description> <Quantity>5</Quantity> <Value>10000</Value> <ImageURL> </ShoppingCartItem> </ShoppingCart> </ShoppingCartRequest> ShoppingCartRequest with Optional SecondaryOriginUrl Field XML Sample <?xml version="1.0"?> <ShoppingCartRequest> <OAuthToken>oauth_demo_token4sj4x6f1eqka2ib2f1nzd1ib2imvce151</OAuthToken> Global Version June

146 Appendix OAuth Samples <ShoppingCart> <CurrencyCode>USD</CurrencyCode> <Subtotal>2500</Subtotal> <ShoppingCartItem> <Description>Apple MacBook Pro MD101LL/A 13.3-Inch Laptop</ Description> <Quantity>1</Quantity> <Value>2500</Value> <ImageURL> 41t0EjbJXYL._SL500_SS100_.jpg</ImageUIm> </ShoppingCartItem> </ShoppingCart> <ExtensionPoint> <SecondaryOriginUrl> </ExtensionPoint> </ShoppingCartRequest> ShoppingCartResponse XML Sample <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ShoppingCartResponse> <OAuthToken>a747f7e7c2e0c f640b92806c8</OAuthToken> </ShoppingCartResponse> ShoppingCartResponse XML Schema <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="shoppingcartresponse" type="shoppingcartresponse"/> <xs:complextype name="shoppingcartresponse"> <xs:sequence> <xs:element name="oauthtoken" type="xs:string" /> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0" /> </xs:sequence> </xs:complextype> <xs:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any" /> </xs:sequence> <xs:anyattribute /> </xs:complextype> </xs:schema> HTTP Response Example <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ShoppingCartResponse> <OAuthToken>93dcec2e58e1bee050301bb2ee7d9331</OAuthToken> </ShoppingCartResponse> Global Version June

147 Appendix OAuth Samples Access Token Service This section describes the Access Token parameters. Access Token Parameters access_token Request access_token Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm X X X X X X X oauth_token X X oauth_token_secret X oauth_verifier X Access Token Parameter Details Access Token Request Description Possible Values Signature Base String Authorization Header oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version. 1.0 oauth_nonce oauth_signature_m ethod oauth_consumer_ke y Unique alphanumeric string generated from code oauth signature method Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable RSA-SHA1 Variable oauth_timestamp Current timestamp Variable Global Version June

148 Appendix OAuth Samples Access Token Request Description Possible Values realm oauth_verifier oauth_token Used to differentiate between our mobile and full site. Currently not used. Verifier is returned on the callback and used in the access token request oauth token obtained from request token call ewallet Variable Access Token Response Description Possible Values Access Token oauth_token oauth_token that needs to be sent in the signature base string and authorization header for checkout resource call Variable Oauth_Token_Secret oauth_token_secret Oauth Secret Variable Signature Base String Example POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer %2Fv1%2Faccess_token&oauth_consumer_key %3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c %21414f c4a366c726a b d%26oauth_nonce%3DXgqPqENy %26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D %26oauth_token %3Df263a7383ce705fdf17dc163a33c00c5d49bea4e%26oauth_verifier %3Daa73f a36b6ba8fe5e938367a8f0f5d9%26oauth_version%3D1.0 HTTP Request Example Authorization: OAuth oauth_consumer_key="clb0tkkejhgtitp_6ltdiibo5wgbx4rildexm_jrd4b0476c %21414f c4a366c726a b d",oauth_nonce="XgqPqENy",oauth_ signature="jimdswuf1aw %2FeAjsXwwgAEeKsEZ0qJiRH39jar3BtZdA6Ccc2zbx4nhDRWm7QNmEgfkruVFbLFkdckix8ZABNW8e %2Fte0mapbCeI0ldkWPb3Bc2z9qvu8uoHpUU9t8Un6k0bbI %2BAswSA30VCcUKtcy2crA2plkAoU52SOq1Cyqdk%3D",oauth_signature_method="RSA- SHA1",oauth_timestamp=" ",oauth_token="f263a7383ce705fdf17dc163a33c00c5d4 9bea4e",oauth_verifier="aa73f a36b6ba8fe5e938367a8f0f5d9",oauth_version="1.0",realm="eWallet" HTTP Response Example oauth_token=9429f23bd08f992c41fb5ddabcc03ecd&oauth_token_secret=cd1ab178419c2111 fb f5dc8d9 Global Version June

149 Appendix OAuth Samples Checkout Resource This topic provides details of the Checkout parameters and XML. Checkout Parameters Checkout resource Request Checkout Resource Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_token checkout_resource_url X X X X X X X X Used as endpoint Checkout XML X Checkout Parameter Details Checkout Resource Request Description Possible Values Signature Base String Authorization Header oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version. 1.0 oauth_nonce oauth_signature_m ethod oauth_consumer_ke y Unique alphanumeric string generated from code oauth signature method. Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable RSA-SHA1 Variable oauth_timestamp Current timestamp Variable Global Version June

150 Appendix OAuth Samples Checkout Resource Request Description Possible Values realm oauth_token checkout_resource_ url Used to differentiate between our mobile and full site. Currently not used. Access token that is returned in the access token response needs to be sent in the signature base string, authorization header for checkout resource call Endpoint used to request the users billing and shipping information from MasterPass ewallet Variable Checkout Resource Response Description Possible Values Transfer XML Strings Checkout XML Refer to the V6 Checkout XML Details table in this section. Signature Base String Example GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout %2F &oauth_consumer_key%3DcLb0tKkEJhG====_6ltDIibO5Wgbx4rIl====_jRd4b0476c %21414f c4a366c726a b353049====%26oauth_nonce %3D8yNKr7i3%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp %3D %26oauth_token%3Dd475e1a692b7bfed07b492dd845b7f43190becad %26oauth_version%3D1.0 HTTP Request Example GET /masterpass/v6/checkout/4400 HTTP/1.1 Authorization:OAuth oauth_consumer_key="clb0tkkejhgtitp_6ltdiibo5wgbx4rildexm_jrd4b0476c %21414f c4a366c726a b d",oauth_nonce="8yNKr7i3",oauth_ signature="g95ku%2blpj%2blt %2FIOCGYj5a3H1OB7LNltBrw7Hq7%2BhrTtXoiAMRp56obJYlkX10LS2lNugBPKq %2FU8YyJ8Tt8wDDsRCLFbS1XT4xi%2FzKsXk%2B7LRXN3YwLTi8exDI4rAan %2B02YYOpMyOk4uX6KDb9ue6Lu%2FxAfQ0lqB2zK7mT24TwHs%3D",oauth_signature_method="RSA- SHA1",oauth_timestamp=" ",oauth_token="d475e1a692b7bfed07b492dd845b7f4319 0becad",oauth_version="1.0",realm="eWallet" V6/Checkout-XML Schema URL: The checkout resource url supplied by MasterPass should be decoded and consumed by the merchant as provided by MasterPass. MasterPass may add or delete parameters in future. The following are examples of decoded URL: Global Version June

151 Appendix OAuth Samples checkout_resource_url= &checkoutId= checkout_resource_url= <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="checkout" type="checkout"/> <xs:complextype name="checkout"> <xs:sequence> <xs:element name="card" type="card"/> <xs:element name="transactionid" type="xs:string"/> <xs:element name="contact" type="contact"/> <xs:element name="shippingaddress" type="shippingaddress" minoccurs="0"/> <xs:element name="authenticationoptions" type="authenticationoptions" minoccurs="0"/> <xs:element name="rewardprogram" type="rewardprogram" minoccurs="0"/> <xs:element name="walletid" type="xs:string"/> <xs:element name="precheckouttransactionid" type="xs:string" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="authenticationoptions"> <xs:sequence> <xs:element name="authenticatemethod" type="xs:string" minoccurs="0"/> <xs:element name="cardenrollmentmethod" type="xs:string" minoccurs="0"/> <xs:element name="cavv" type="xs:string" minoccurs="0"/> <xs:element name="eciflag" type="xs:string" minoccurs="0"/> <xs:element name="mastercardassignedid" type="xs:string" minoccurs="0"/> <xs:element name="paresstatus" type="xs:string" minoccurs="0"/> <xs:element name="scenrollmentstatus" type="xs:string" minoccurs="0"/> <xs:element name="signatureverification" type="xs:string" minoccurs="0"/> <xs:element name="xid" type="xs:string" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="card"> <xs:sequence> <xs:element name="brandid" type="nonemptystring"/> <xs:element name="brandname" type="nonemptystring"/> <xs:element name="accountnumber" type="nonemptystring"/> <xs:element name="billingaddress" type="address"/> <xs:element name="cardholdername" type="nonemptystring"/> <xs:element name="expirymonth" type="month" minoccurs="0"/> <xs:element name="expiryyear" type="year" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="address"> <xs:sequence> <xs:element name="city" type="nonemptystring"/> <xs:element name="country" type="country"/> <xs:element name="countrysubdivision" type="nonemptystring" minoccurs="0"/> Global Version June

152 Appendix OAuth Samples <xs:element name="line1" type="nonemptystring"/> <xs:element name="line2" type="nonemptystring" minoccurs="0"/> <xs:element name="line3" type="nonemptystring" minoccurs="0"/> <xs:element name="postalcode" type="nonemptystring" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="contact"> <xs:sequence> <xs:element name="firstname" type="nonemptystring"/> <xs:element name="middlename" minoccurs="0"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:minlength value="1"/> <xs:maxlength value="150"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="lastname" type="nonemptystring"/> <xs:element name="gender" type="gender" minoccurs="0"/> <xs:element name="dateofbirth" type="dateofbirth" minoccurs="0"/> <xs:element name="nationalid" minoccurs="0"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:minlength value="1"/> <xs:maxlength value="150"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="country" type="country"/> <xs:element name=" address" type=" address"/> <xs:element name="phonenumber" type="xs:string"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="dateofbirth"> <xs:sequence> <xs:element name="year"> <xs:simpletype> <xs:restriction base="xs:int"> <xs:mininclusive value="1900"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="month" type="month"/> <xs:element name="day"> <xs:simpletype> <xs:restriction base="xs:int"> <xs:mininclusive value="1"/> <xs:maxinclusive value="31"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:simpletype name="gender"> <xs:restriction base="xs:token"> <xs:enumeration value="m"/> <xs:enumeration value="f"/> Global Version June

153 Appendix OAuth Samples </xs:restriction> </xs:simpletype> <xs:complextype name="shippingaddress"> <xs:complexcontent> <xs:extension base="address"> <xs:sequence> <xs:element name="recipientname" type="nonemptystring"/> <xs:element name="recipientphonenumber" type="xs:string"/> </xs:sequence> </xs:extension> </xs:complexcontent> </xs:complextype> <xs:complextype name="rewardprogram"> <xs:sequence> <xs:element name="rewardnumber" type="xs:string"/> <xs:element name="rewardid" type="xs:string"/> <xs:element name="rewardname" type="xs:string" minoccurs="0"/> <xs:element name="expirymonth" type="month" minoccurs="0"/> <xs:element name="expiryyear" type="year" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:simpletype name="nonemptystring"> <xs:restriction base="xs:string"> <xs:minlength value="1"/> <xs:whitespace value="collapse"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="country"> <xs:restriction base="xs:string"> <xs:pattern value="[a-z]{2}"/> </xs:restriction> </xs:simpletype> <xs:simpletype name=" address"> <xs:restriction base="xs:string"> <xs:pattern value="[a-za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[a-za-z0-9! \-/=\?\^_`\{-~]+)*"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="month"> <xs:restriction base="xs:int"> <xs:mininclusive value="1"/> <xs:maxinclusive value="12"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="year"> <xs:restriction base="xs:int"> <xs:mininclusive value="2013"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpletype> <xs:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> </xs:schema> Global Version June

154 Appendix OAuth Samples V6/Checkout Sample Response URL: <Checkout> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <AccountNumber> </AccountNumber> <BillingAddress> <City>Anytown</City> <Country>US</Country> <Line1>100 Not A Real Street</Line1> <PostalCode>63011</PostalCode> </BillingAddress> <CardHolderName>Joe Test</CardHolderName> <ExpiryMonth>02</ExpiryMonth> <ExpiryYear>2016</ExpiryYear> </Card> <TransactionId>72525</TransactionId> <Contact> <FirstName>Joe</FirstName> <MiddleName>M</MiddleName> <LastName>Test</LastName> <Gender>M</Gender> <DateOfBirth> <Year>1975</Year> <Month>03</Month> <Day>28</Day> </DateOfBirth> <NationalID> </NationalID> <Country>US</Country> < Address>joe.test@ .com</ Address> <PhoneNumber> </PhoneNumber> </Contact> <ShippingAddress> <City>O Fallon</City> <Country>US</Country> <CountrySubdivision>US-AK</CountrySubdivision> <Line1>1 main street</line1> <PostalCode>63368</PostalCode> <RecipientName>Joe Test</RecipientName> <RecipientPhoneNumber> </RecipientPhoneNumber> </ShippingAddress> <WalletID>101</WalletID> <RewardProgram> <RewardNumber>123</RewardNumber> <RewardId>1234</RewardId> <RewardName>ABC Rewards</RewardName> <ExpiryMonth>02</ExpiryMonth> <ExpiryYear>2015</ExpiryYear> </RewardProgram> </Checkout> V6 Checkout XML Details CheckoutXML Element Description Type Min Max Checkout Root Element XML - Global Version June

155 Appendix OAuth Samples CheckoutXML Element Description Type Min Max Checkout Card Child Element XML - Card BrandId Identifies the card brand id, for example, master for MasterCard. Alpha Numeric 0 8 BrandName AccountNumber BillingAddress Identifies the card brand name, for example, MasterCard Card number or primary account number that identifies the card Billing Address for the card holder. String Integer XML - CardHolderName Cardholder name String ExpiryMonth Expiration month displayed on the payment card. Date XML format ExpiryYear Expiration year displayed on the payment card. Date XML format ExtensionPoint Reserved for future enhancement. Optional Any - Checkout TransactionID Child Element String Checkout Contact Child Element XML Contact FirstName Contact First Name String Optional MiddleName Contact Middle Name or Initial String LastName Contact Surname String Global Version June

156 Appendix OAuth Samples CheckoutXML Element Description Type Min Max Optional * Gender Contact Gender (M or F) M or F [SB1] NOTE: This field may only be requested from a MasterPass wallet if it is required by law in a region. Merchants and service providers seeking to use this field must work with the local MasterPass representative to get the necessary clearances before requesting these data elements. Optional * DateOfBirth Contact DOB YYYY/MM/DD NOTE: This field may only be requested from a MasterPass wallet if it is required by law in a region. Merchants and service providers seeking to use this field must work with the local MasterPass representative to get the necessary clearances before requesting these data elements. Sequence: Year (Int); Month (Int) Day (Int) Y (4) M (2) D (2) * Only when legally required and enabled by MasterPass Global Version June

157 Appendix OAuth Samples CheckoutXML Element Description Type Min Max Optional (dependent on merchant country of incorporation and the consumer country of residence) NationalID Contact National Identification NOTE: This field may only be requested from a MasterPass wallet if it is required by law in a region. Merchants and service providers seeking to use this field must work with the local MasterPass representative to get the necessary clearances before requesting these data elements. String Optional Country Contact Country of Residence String 0 2 Address Contact Address String PhoneNumber Contact Phone String 3 20 DateOfBirth Contact DOB Year Contact DOB Year Integer 4 Month Contact DOB Month Integer 1 2 Day Contact DOB Day Integer 1 2 ExtensionPoint Reserved for future enhancement. Optional Any - Checkout ShippingAddress Child Element XML - ShippingAddress Address Child Element XML - Address City Cardholder s city String 0 25 Global Version June

158 Appendix OAuth Samples CheckoutXML Element Description Type Min Max Country CountrySubdivision Line 1 Line 2 Line 3 PostalCode ExtensionPoint Cardholder s country. Defined by ISO alpha-2 digit country codes, for example, US is United States, AU is Australia, CA is Canada, GB is United Kingdom, and so on. Cardholder s country subdivision. Defined by ISO alpha-2 digit code, for example, US-VA is Virginia, US-OH is Ohio Address line 1 used for Street number and Street Name. Address line 2 used for Apt Number, Suite Number, and so on. Address line 3 used to enter remaining address information if it does not fit in Line 1 and Line 2 Postal Code or Zip Code appended to mailing address for the purpose of sorting mail. Reserved for future enhancement. Optional String 2 String 5 String 1 40 String 0 40 String String 0 20 Any - ShippingAddress RecipientName Name of person set to receive the shipped order. String Global Version June

159 Appendix OAuth Samples CheckoutXML Element Description Type Min Max ShippingAddress RecipientPhoneNumb er Phone of the person set to receive the shipped order. String 3 20 Checkout AuthenticationOption s Child Element XML - Checkout WalletID Helps identify origin wallet String 3 AuthenticationOptions AuthenticateMethod Method used to authenticate the cardholder at checkout. Valid values are MERCHANT ONLY, 3DS and No Authentication. Alpha NA CardEnrollmentMeth od Method by which the card was added to the wallet. Valid values are: Alpha NA Manual Direct Provisioned 3DS Manual NFC Tap CAvv (CAVV) Cardholder Authentication Verification Value generated by card issuer upon successful authentication of the cardholder. This must be passed in the authorization message Alpha Numeric NA Global Version June

160 Appendix OAuth Samples CheckoutXML Element Description Type Min Max EciFlag Electronic commerce indicator (ECI) flag. Possible values are as follows: MasterCard: 00 No Authentication 01 Attempts (Card Issuer Liability) 02 Authenticated by ACS (Card Issuer Liability) 03 Maestro (MARP) 05 Risk Based Authentication (Issuer, not in use) 06 Risk Based Authentication (Merchant, not in use) Visa: 05 Authenticated (Card Issuer Liability) 06 Attempts (Card Issuer Liability) 07 No 3DS Authentication (Merchant Liability) Alphanume ric NA MasterCardAssignedI D This value is assigned by MasterCard and represents programs associated directly with Maestro cards. This field should be supplied in the authorization request by the merchant. Alpha Numeric NA Global Version June

161 Appendix OAuth Samples CheckoutXML Element Description Type Min Max PaResStatus A message formatted, digitally signed, and sent from the ACS (issuer) to the MPI providing the results of the issuer s MasterCard SecureCode/Verified by Visa cardholder authentication. Possible values are: Alpha NA Y The card was successfully authenticated via 3-D Secure N Authentication failed A signifies that either (a) the transaction was successfully authenticated via a 3- D Secure attempts transaction or (b)the cardholder was prompted to activate 3-D Secure during shopping but declined (Visa). U Authentication results were unavailable Global Version June

162 Appendix OAuth Samples CheckoutXML Element Description Type Min Max SCEnrollmentStatus MasterCard SecureCode Enrollment Status: Indicates if the issuer of the card supports payer authentication for this card. Possible values are as follows: Alpha NA Y The card is eligible for 3-D Secure authentication. N The card is not eligible for 3-D Secure authentication. U Lookup of the card's 3-D Secure eligibility status was either unavailable, or the card is inapplicable (for example, prepaid cards). SignatureVerification: Signature Verification. Possible values are as follows: Alpha NA Y Indicates that the signature of the PaRes has been validated successfully and the message contents can be trusted. N Indicates that for a variety of reasons (tampering, certificate expiration, and so on) the PaRes could not be validated, and the result should not be trusted. Global Version June

163 Appendix OAuth Samples CheckoutXML Element Description Type Min Max XID Transaction identifier resulting from authentication processing. Alpha Numeric NA ExtensionPoint Reserved for future enhancement. Optional Any Checkout Reward Program Child Element XML Reward Program RewardNumber Consumer s reward number associated with the reward program Reward Program RewardId ID associated with the reward program Alphanume ric Alphanume ric RewardName Name of reward program Alphanume ric ExpiryMonth Month the reward program expires Alphanume ric ExpiryYear Year the reward program expires Alphanume ric ExtensionPoint Reserved for future enhancement. Optional Any - PreCheckoutTransactionId Pre Checkout Transaction ID ID associated with the PreCheckout Transaction Alphanume ric Pre-Checkout Resource This topic provides information on the Pre-Checkout parameters. Pre-Checkout Parameters Checkout resource Request Checkout Resource Response oauth_signature X Global Version June

164 Appendix OAuth Samples Checkout resource Request Checkout Resource Response oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_token PreCheckout Data Request XML X X X X X X X X PreCheckout Data Response XML X Pre-Checkout Parameter Details PreCheckout Resource Request Description Possible Values Signature Base String Authorization Header oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version. 1.0 oauth_nonce oauth_signature_m ethod oauth_consumer_ke y Unique alphanumeric string generated from code oauth signature method. Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable RSA-SHA1 Variable oauth_timestamp Current timestamp Variable oauth_token realm Long access token used to retrieve precheckout data Used to differentiate between our mobile and full site. Currently not used. Variable ewallet Global Version June

165 Appendix OAuth Samples PreCheckout Resource Request Description Possible Values Transfer XML Strings PreCheckout Data Request XML Details of the PreCheckout Request PreCheckout Resource Response Description Possible Values Transfer XML Strings Pre-Checkout XML Refer to the V6/ PreCheckoutData Sample Response and V6 PreCheckoutData Response XML Details sections. Signature Base String Example GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F &oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c% f c4a366c726a b d%26oauth_nonce%3d %26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D %26oauth_token%3Dc531cce64ca2d88ecb223a8a37afe98e%26oauth_version%3D1.0 HTTP Request Example POST /masterpass/v6/precheckout/4400 HTTP/1.1 Authorization: OAuth oauth_signature="cks9xjehksuvnkotsrmoog0rwmveoc2dtqnnw8iwlszeg1znkvrpstjde32ybndhr 7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhXGWRrRpjh3ZhHLDOdSxtxjSCJaHF QkfGyq%2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce=" ",oauth_signature_method="rsa- SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f c4a366c726a b d",oauth_token="c531cce64ca2d88ecb223a 8a37afe98e",oauth_timestamp=" ",realm="eWallet" V6/PreCheckoutDataRequest XML Schema URL: <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="precheckoutdatarequest" type="precheckoutdatarequest"/> <xs:complextype name="precheckoutdatarequest"> <xs:sequence> <xs:element name="pairingdatatypes" type="pairingdatatypes"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="pairingdatatype" type="pairingdatatype"/> <xs:complextype name="pairingdatatype"> <xs:sequence> <xs:element name="type"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:enumeration value="card"/> <xs:enumeration value="address"/> <xs:enumeration value="reward_program"/> <xs:enumeration value="profile"/> Global Version June

166 Appendix OAuth Samples </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="pairingdatatypes" type="pairingdatatypes"/> <xs:complextype name="pairingdatatypes"> <xs:sequence> <xs:element name="pairingdatatype" type="pairingdatatype" minoccurs="1" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> </xs:schema> V6/PreCheckoutData Sample Request URL: <PrecheckoutDataRequest> <PairingDataTypes> <PairingDataType> <Type>CARD</Type> </PairingDataType> <PairingDataType> <Type>ADDRESS</Type> </PairingDataType> <PairingDataType> <Type>PROFILE</Type> </PairingDataType> <PairingDataType> <Type>REWARD_PROGRAM</Type> </PairingDataType> </PairingDataTypes> </PrecheckoutDataRequest> V6 PreCheckoutData XML Details PreCheckoutXML Element Description Type Min Max PrecheckoutDataRequest Root Element XML - PrecheckoutDataRequest PairingDataTypes Child Element XML - ExtensionPoint Reserved for future enhancement. Optional Any - PairingDataType Child Element XML - Global Version June

167 Appendix OAuth Samples PreCheckoutXML Element Description Type Min Max ExtensionPoint Reserved for future enhancement. Optional Any - PairingDataType PairingDataType Child Element XML - PairingDataType PairingDataType Card, ShippingAddress, Reward_Program, Profile String - ExtensionPoint Reserved for future enhancement. Optional Any - V6/PreCheckoutDataResponse XML Schema <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="precheckoutdataresponse" type="precheckoutdataresponse"/> <xs:complextype name="precheckoutdataresponse"> <xs:sequence> <xs:element name="precheckoutdata" type="precheckoutdata"/> <xs:element name="walletpartnerlogourl" type="xs:anyuri"/> <xs:element name="masterpasslogourl" type="xs:anyuri"/> <xs:element name="longaccesstoken" type="xs:string" minoccurs="1"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="precheckoutdata" type="precheckoutdata"/> <xs:complextype name="precheckoutdata"> <xs:sequence> <xs:element name="cards" type="precheckoutcards"/> <xs:element name="contact" type="contact" minoccurs="0"/> <xs:element name="shippingaddresses" type="precheckoutshippingaddresses"/> <xs:element name="rewardprograms" type="precheckoutrewardprograms"/> <xs:element name="walletname" type="xs:string" minoccurs="1"/> <xs:element name="precheckouttransactionid" type="xs:string" /> <xs:element name="consumerwalletid" type="xs:string" minoccurs="1"/> <xs:element name="errors" type="errors" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="precheckoutcards" type="precheckoutcards"/> <xs:complextype name="precheckoutcards"> <xs:sequence> <xs:element name="card" type="precheckoutcard" minoccurs="0" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="precheckoutcard" type="precheckoutcard"/> <xs:complextype name="precheckoutcard"> <xs:sequence> <xs:element name="brandid" type="xs:string" /> <xs:element name="brandname" type="xs:string" /> <xs:element name="billingaddress" type="address" /> Global Version June

168 Appendix OAuth Samples <xs:element name="cardholdername" type="xs:string" /> <xs:element name="expirymonth" type="month" minoccurs="0"/> <xs:element name="expiryyear" type="year" minoccurs="0"/> <xs:element name="cardid" type="xs:string"></xs:element> <xs:element name="lastfour" type="xs:string" /> <xs:element name="cardalias" type="xs:string" /> <xs:element name="selectedasdefault" type="xs:boolean" /> <xs:element name="bnbunverified" type="xs:boolean" /> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="contact"> <xs:sequence> <xs:element name="firstname" type="nonemptystring"/> <xs:element name="middlename" minoccurs="0"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:minlength value="1"/> <xs:maxlength value="150"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="lastname" type="nonemptystring"/> <xs:element name="gender" type="gender" minoccurs="0"/> <xs:element name="dateofbirth" type="dateofbirth" minoccurs="0"/> <xs:element name="nationalid" minoccurs="0"> <xs:simpletype> <xs:restriction base="xs:string"> <xs:minlength value="1"/> <xs:maxlength value="150"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="country" type="country"/> <xs:element name=" address" type=" address"/> <xs:element name="phonenumber" type="xs:string"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:simpletype name="nonemptystring"> <xs:restriction base="xs:string"> <xs:minlength value="1"/> <xs:whitespace value="collapse"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="gender"> <xs:restriction base="xs:token"> <xs:enumeration value="m"/> <xs:enumeration value="f"/> </xs:restriction> </xs:simpletype> <xs:complextype name="dateofbirth"> <xs:sequence> <xs:element name="year"> <xs:simpletype> <xs:restriction base="xs:int"> <xs:mininclusive value="1900"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="month" type="month"/> Global Version June

169 Appendix OAuth Samples <xs:element name="day"> <xs:simpletype> <xs:restriction base="xs:int"> <xs:mininclusive value="1"/> <xs:maxinclusive value="31"/> </xs:restriction> </xs:simpletype> </xs:element> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:simpletype name="month"> <xs:restriction base="xs:int"> <xs:mininclusive value="1"/> <xs:maxinclusive value="12"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="year"> <xs:restriction base="xs:int"> <xs:mininclusive value="2013"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="country"> <xs:restriction base="xs:string"> <xs:pattern value="[a-z]{2}"/> </xs:restriction> </xs:simpletype> <xs:simpletype name=" address"> <xs:restriction base="xs:string"> <xs:pattern value="[a-za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[a-za-z0-9! /=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*"/> </xs:restriction> </xs:simpletype> <xs:element name="precheckoutshippingaddresses" type="precheckoutshippingaddresses"/> <xs:complextype name="precheckoutshippingaddresses"> <xs:sequence> <xs:element name="shippingaddress" type="precheckoutshippingaddress" minoccurs="0" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="precheckoutshippingaddress" type="precheckoutshippingaddress"/> <xs:complextype name="precheckoutshippingaddress"> <xs:complexcontent> <xs:extension base="address"> <xs:sequence> <xs:element name="recipientname" type="xs:string" /> <xs:element name="recipientphonenumber" type="xs:string" /> <xs:element name="addressid" type="xs:string"/> <xs:element name="selectedasdefault" type="xs:boolean" /> <xs:element name="shippingalias" type="xs:string" /> </xs:sequence> </xs:extension> </xs:complexcontent> </xs:complextype> <xs:complextype name="address"> <xs:sequence> <xs:element name="city" type="nonemptystring"/> Global Version June

170 Appendix OAuth Samples <xs:element name="country" type="country"/> <xs:element name="countrysubdivision" type="nonemptystring" minoccurs="0"/> <xs:element name="line1" type="nonemptystring"/> <xs:element name="line2" type="nonemptystring" minoccurs="0"/> <xs:element name="line3" type="nonemptystring" minoccurs="0"/> <xs:element name="postalcode" type="nonemptystring" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="precheckoutrewardprograms" type="precheckoutrewardprograms"/> <xs:complextype name="precheckoutrewardprograms"> <xs:sequence> <xs:element name="rewardprogram" type="precheckoutrewardprogram" minoccurs="0" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="precheckoutrewardprogram" type="precheckoutrewardprogram"/> <xs:complextype name="precheckoutrewardprogram"> <xs:sequence> <xs:element name="rewardnumber" type="xs:string"/> <xs:element name="rewardid" type="xs:string"/> <xs:element name="rewardname" type="xs:string" minoccurs="0"/> <xs:element name="expirymonth" type="month" minoccurs="0"/> <xs:element name="expiryyear" type="year" minoccurs="0"/> <xs:element name="rewardprogramid" type="xs:string"/> <xs:element name="rewardlogourl" type="xs:string" /> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="error"> <xs:sequence> <xs:element name="description" type="xs:string" minoccurs="0"/> <xs:element name="reasoncode" type="xs:string"/> <xs:element name="recoverable" type="xs:boolean"/> <xs:element name="source" type="xs:string"/> <xs:element name="details" type="details" minoccurs="0" maxoccurs="1"/> </xs:sequence> </xs:complextype> <xs:complextype name="errors"> <xs:sequence> <xs:element name="error" type="error" minoccurs="0" maxoccurs="unbounded"/> </xs:sequence> </xs:complextype> <xs:complextype name="details"> <xs:sequence> <xs:element name="detail" type="detail" minoccurs="0" maxoccurs="unbounded"/> </xs:sequence> </xs:complextype> <xs:complextype name="detail"> <xs:sequence> <xs:element name="name" type="xs:string"/> <xs:element name="value" type="xs:string"/> </xs:sequence> </xs:complextype> <xs:complextype name="extensionpoint"> Global Version June

171 Appendix OAuth Samples <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> </xs:schema> V6/PreCheckoutData Sample Response <PrecheckoutDataResponse> <PrecheckoutData> <Cards> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <CardHolderName>Joe Cardholder</CardHolderName> <ExpiryMonth>2</ExpiryMonth> <ExpiryYear>2016</ExpiryYear> <CardId> </CardId> <LastFour>2149</LastFour> <CardAlias>Rewards Card</CardAlias> <SelectedAsDefault>false</SelectedAsDefault> </Card> <Card> <BrandId>master</BrandId> <BrandName>MasterCard</BrandName> <CardHolderName>Joe Cardholder</CardHolderName> <ExpiryMonth>2</ExpiryMonth> <ExpiryYear>2016</ExpiryYear> <CardId> </CardId> <LastFour>0144</LastFour> <SelectedAsDefault>true</SelectedAsDefault> </Card> </Cards> <Contact> <FirstName>Joe</FirstName> <LastName>Cardholder</LastName> <Country>US</Country> <PhoneNumber> </PhoneNumber> </Contact> <ShippingAddresses> <ShippingAddress> <City>chesterfield</City> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>123 main st</line1> <Line2/> <Line3/> <PostalCode>63017</PostalCode> <RecipientName>Joe Cardholder</RecipientName> <RecipientPhoneNumber> </RecipientPhoneNumber> <AddressId> </AddressId> <SelectedAsDefault>true</SelectedAsDefault> </ShippingAddress> <ShippingAddress> <City>St Louis</City> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>11642 Frontier Dr</Line1> <Line2/> <Line3/> Global Version June

172 Appendix OAuth Samples <PostalCode>63146</PostalCode> <RecipientName>Joe Cardholder</RecipientName> <RecipientPhoneNumber> </RecipientPhoneNumber> <AddressId> </AddressId> <SelectedAsDefault>false</SelectedAsDefault> </ShippingAddress> </ShippingAddresses> <WalletName>Mobile</WalletName> <PrecheckoutTransactionId>a4d6x6s-55pqrj-hyko44a5-1-hyq76c51-a4a</ PrecheckoutTransactionId> <ConsumerWalletId> </ConsumerWalletId> </PrecheckoutData> <WalletPartnerLogoUrl> </ WalletPartnerLogoUrl> <MasterpassLogoUrl> </ MasterpassLogoUrl> <LongAccessToken>a2abae6b0b21be8fc23113bf8477a7dd1f0f4041</LongAccessToken> </PrecheckoutDataResponse> V6 PreCheckoutData Response XML Details PreCheckoutData XML Element Description Type Min Max PrecheckoutData Root Element XML - PrecheckoutData Cards Child Element PrecheckoutCard - Contact Child Element Contact - ShippingAddresses Child Element PrecheckoutShippi ngaddress - WalletName Child Element String - RewardPrograms Child Element PrecheckoutRewar dprogram - PrecheckoutTransa ctionid Child Element String - ConsumerWalletId Child Element String - WalletPartnerLogo Url Child Element String - MasterpassLogoUrl Child Element String LongAccessToken Child Element String Errors Child Element String - PrecheckoutCard Root Element String - CardId Child Element String - BrandId Child Element String - Global Version June

173 Appendix OAuth Samples PreCheckoutData XML Element Description Type Min Max BrandName Child Element String - BillingAddress Child Element Address - CardHolderName Child Element String - LastFour Child Element String - CardAlias Child Element String - ExpiryMonth Child Element String 0 9, 2 ExpiryYear Child Element String 0 9, 4 SelectedAsDefault Child Element Boolean - ExtensionPoint Any - Contact Root Element String - Contact FirstName Child Element String - MiddleName Child Element String LastName Child Element String - Gender* Child Element String M/F DateOfBirth Child Element String - DateOfBirth Year Child Element Integer 1900, 4 Month Child Element Integer 1 12 Day Child Element Integer 1 31 ExtensionPoint Any - Contact NationalId* Child Element String Country Child Element Country - Address Child Element Address - PhoneNumber Child Element String - ExtensionPoint Any - PrecheckoutShippi ngaddress Root Element String - PrecheckoutShippi ngaddress Address Child Element String - * Only when legally required and enabled by MasterPass. Global Version June

174 Appendix OAuth Samples PreCheckoutData XML Element Description Type Min Max Address AddressId Child Element String - RecipientName Child Element String - RecipientPhoneNu mber Child Element String - SelectedAsDefault Child Element Boolean - ShippingAlias Child Element String - ExtensionPoint Any - PrecheckoutRewar dprogram Root Element String - PrecheckoutRewar dprogram RewardProgramId Child Element String - RewardNumber Child Element String - RewardId Child Element String - RewardName Child Element String - ExpiryMonth Child Element String 0 9, 2 ExpiryYear Child Element String 0 9, 4 RewardLogo Child Element Logo - ExtensionPoint Any - Address Root Element String - Address Line1 Child Element String 1 40 Line2 Child Element String 0 40 Line3 Child Element String City Child Element String 1 25 CountrySubdivision Child Element String PostalCode Child Element String 0 10 Country Child Element String ExtensionPoint Any - Country Root Element String - Country Code Child Element String A Z, 3 Name Child Element String - Global Version June

175 Appendix OAuth Samples PreCheckoutData XML Element Description Type Min Max CallingCode Child Element String - Locale Child Element String - Address Root Element String - Logo Root Element String - Logo Ref Child Element String - Height Child Element String - Width Child Element String - BackgroundColor Child Element String - Url Child Element String - LongDescription Child Element String - Errors Root Element Error - Errors Error Child Element String - Error Description Child Element String - ReasonCode Child Element String - Recoverable Child Element Boolean - Source Child Element String - ExtensionPoint Elements Starting with API v6, all schema container elements contain a new optional element named ExtensionPoint. These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of xs:any, meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an ExtensionPoint element, beyond any that may be defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further, only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be dropped by MasterPass. ExtensionPoint Sample <ExtensionPoint> <s:sampleextension xmlns:s= ns > <s:samplefield>sample Value</s:SampleField> </s:sampleextension> <f:anotherexampleextension xmlns:f= Global Version June

176 Appendix OAuth Samples example2/ns > <f:samplecontainer> <f:anothersamplefield>sample Value</f:AnotherSampleField> </f:samplecontainer> </f:anotherexampleextension> </ExtensionPoint> Postback Service This topic provides information on the Postback parameters. Postback Parameters Post Transaction Request Post Transaction Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp oauth_body_hash X X X X X X X MerchantTransactions XML X X Postback Parameter Details Post Transaction Request Description Possible Values Signature Base String Authorization Header oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version. 1.0 oauth_nonce oauth_signature_m ethod Unique alphanumeric string generated from code oauth signature method. Variable RSA-SHA1 Global Version June

177 Appendix OAuth Samples Post Transaction Request Description Possible Values oauth_consumer_ke y Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable oauth_timestamp Current timestamp Variable oauth_body_hash SHA1 hash of the message body Variable Transfer XML Strings Merchant Transactions XML Transaction details Post Transaction Response Description Possible Values Transfer XML Strings Merchant Transactions XML Transaction details Signature Base String Example POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Ftransaction &oauth_body_hash%3dycnt7a676vey7i0skyymkorihcg%253d%26oauth_consumer_key%3dclb0 tkkejhgtitp_6ltdiibo5wgbx4rildexm_jrd4b0476c% f c4a366c726a b d%26oauth_nonce%3D %26oauth_signature_method%3DRS A-SHA1%26oauth_timestamp%3D %26oauth_version%3D1.0 HTTP Request Example POST /masterpass/v6/transaction HTTP/1.1 Authorization: OAuth oauth_signature="aom0wfgfi7ityv1izfn125bod6jgftdx15dq8xbjvmggkgktj5awv7wsmgwucc eglpl52hfs%2b%2boqzvrcdxuidvgekox1nhdfhns0l1yiaqgdkjqyr%2bcqgu1qo7xvjvztqpxulrc 2uzVCjyLoQEroIWv5cAOj5l4aBxDopz7OKQA%3D",oauth_body_hash="ycNt7A676VEY7i0SkyymK orihcg%3d",oauth_version="1.0",oauth_nonce=" ",oauth_signature_met hod="rsa- SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2141 4f c4a366c726a b d",oauth_timestamp=" " MerchantTransactions Request Schema <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="merchanttransactions" type="merchanttransactions"/> <xs:complextype name="merchanttransactions"> <xs:sequence> <xs:element name="merchanttransactions" type="merchanttransaction" minoccurs="0" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="merchanttransaction"> <xs:sequence> <xs:element name="transactionid" type="xs:string"/> Global Version June

178 Appendix OAuth Samples <xs:element name="consumerkey" type="xs:string" minoccurs="0"/> <xs:element name="currency" type="xs:string"/> <xs:element name="orderamount" type="xs:long"/> <xs:element name="purchasedate" type="xs:datetime"/> <xs:element name="transactionstatus" type="transactionstatus"/> <xs:element name="approvalcode" type="xs:string"/> <xs:element name="precheckouttransactionid" type="xs:string" minoccurs="0"/> <xs:element name="expresscheckoutindicator" type="xs:boolean" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:simpletype name="transactionstatus"> <xs:restriction base="xs:string"> <xs:enumeration value="success"/> <xs:enumeration value="failure"/> </xs:restriction> </xs:simpletype> <xs:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> </xs:schema> HTTP Request Example <MerchantTransactions> <MerchantTransactions> <TransactionId> </TransactionId> <ConsumerKey>0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4! 414b b b d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate> T14:52: :00</PurchaseDate> <TransactionStatus>Success</TransactionStatus> <ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947</ PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> <MerchantTransactions> </MerchantTransactions> MerchantTransactionsResponse Schema <?xml version-/="1.0" encoding-/="utf-8" standalone-/="yes"?> <xs:schema version-/="1.0" xmlns:xs-/=" <xs:element name-/="merchanttransactions" type-/="merchanttransactions"/> <xs:complextype name-/="merchanttransactions"> <xs:sequence> <xs:element name-/="merchanttransactions" type-/ ="MerchantTransaction" minoccurs-/="0" maxoccurs-/="unbounded"/> <xs:element name-/="extensionpoint" type-/="extensionpoint" minoccurs-/="0"/> </xs:sequence> </xs:complextype> <xs:complextype name-/="merchanttransaction"> <xs:sequence> <xs:element name-/="transactionid" type-/="xs:string"/> Global Version June

179 Appendix OAuth Samples <xs:element name-/="consumerkey" type-/="xs:string" minoccurs-/="0"/> <xs:element name-/="currency" type-/="xs:string"/> <xs:element name-/="orderamount" type-/="xs:long"/> <xs:element name-/="purchasedate" type-/="xs:datetime"/> <xs:element name-/="transactionstatus" type-/="transactionstatus"/> <xs:element name-/="approvalcode" type-/="xs:string"/> <xs:element name-/="precheckouttransactionid" type-/="xs:string" minoccurs-/="0"/> <xs:element name-/="expresscheckoutindicator" type-/="xs:boolean" minoccurs-/="0"/> <xs:element name-/="extensionpoint" type-/="extensionpoint" minoccurs-/="0"/> </xs:sequence> </xs:complextype> <xs:simpletype name-/="transactionstatus"> <xs:restriction base-/="xs:string"> <xs:enumeration value-/="success"/> <xs:enumeration value-/="failure"/> </xs:restriction> </xs:simpletype> <xs:complextype name-/="extensionpoint"> <xs:sequence> <xs:any maxoccurs-/="unbounded" processcontents-/="lax" namespace-/ ="##any"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> </xs:schema> HTTP Response Example (response will be identical to the XML sent if call was successful) <MerchantTransactions> <MerchantTransactions> <TransactionId> </TransactionId> <ConsumerKey>0zMKpm0nFtUv8lLXT97jDRo2b d0zMKpm0nFt9682b b d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate> T14:52: :00</PurchaseDate> <TransactionStatus>Success</TransactionStatus> <ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-9477</ PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> </MerchantTransactions> </MerchantTransactions> MerchantTransactionsXML Details MerchantTransactio nsrequest Element Description Type Min - Max MerchantTransactions MerchantTransactions XML - Global Version June

180 Appendix OAuth Samples MerchantTransactio nsrequest Element Description Type Min - Max ExtensionPoint Reserved for future enhancement. Optional Any - MerchantTransactions TransactionID Uses the TransactionID element of the Checkout XML String ConsumerKey Currency OrderAmount Automatically generated when creating a checkout project on MasterPass Merchant portal. Currency of the transaction. Defined by ISO 4217 to be exactly three characters, such as, USD for U.S. Dollars. (Integer) Transaction order amount without decimal, for example, String 97 String 3 Integer 1 12 PurchaseDate Date and Time of the shopping cart purchase. Date XML format TransactionStatus ApprovalCode PreCheckoutTransactio nid ExpressCheckoutIndicat or ExtensionPoint State of the transaction. Indicates whether successful. Valid values are Success or Failure. Approval code returned to merchant from merchant's payment API with payment gateway or service provider. Value returned from the PrecheckoutData call. True or False. Set to false for connected checkout Reserved for future enhancement. Optional String 7 String 6 String Boolean Any - MerchantTransactio nsresponse Element Description Type Min - Max MerchantTransactions Global Version June

181 Appendix OAuth Samples MerchantTransactio nsresponse Element Description Type Min - Max MerchantTransactions Root Element XML - ExtensionPoint Reserved for future enhancement. Optional Any - MerchantTransactions TransactionID Uses the TransactionID element of the Checkout XML String ConsumerKey Currency OrderAmount Automatically generated when creating a checkout project on MasterPass Merchant portal. Currency of the transaction. Defined by ISO 4217 to be exactly three characters, such as, USD for U.S. Dollars. Integer Transaction order amount without decimal, for example, String 97 String 3 Integer 1 12 PurchaseDate Date and Time of the shopping cart purchase, for example, T15:12: :00 Date XML format TransactionStatus ApprovalCode PreCheckoutTransactio nid ExpressCheckoutIndicat or ExtensionPoint State of the transaction. Indicates whether successful. Valid values are Success or Failure. Approval code returned to merchant from merchant's payment API with payment gateway or service provider. Value returned from the PrecheckoutData call. True or False. Set to false for connected checkout. Reserved for future enhancement. Optional String 7 String 6 String Boolean Any - Global Version June

182 Appendix Renew Your Developer Zone Key ExtensionPoint Elements Starting with API v6, all schema container elements contain a new optional element named ExtensionPoint. These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of xs:any, meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an ExtensionPoint element, beyond any that may be defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further, only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be dropped by MasterPass. ExtensionPoint Sample <ExtensionPoint> <s:sampleextension xmlns:s= > <s:samplefield>sample Value</s:SampleField> </s:sampleextension> <f:anotherexampleextension xmlns:f= > <f:samplecontainer> <f:anothersamplefield>sample Value</f:AnotherSampleField> </f:samplecontainer> </f:anotherexampleextension> </ExtensionPoint> Renew Your Developer Zone Key This section provides information on how to complete the key-renewal process on the MasterCard Developer Zone. Procedure 1. Login to MasterCard s Developer Zone ( 2. Click My Account, then My Dashboard. Global Version June

183 Appendix Renew Your Developer Zone Key 3. On the My Dashboard page, click My Keys button, select the key you want to renew and then click on Renew Key button. 4. Supply a PEM encoded Certificate Request File. Choose the file and click the Submit button. Global Version June

184 Appendix Renew Your Developer Zone Key Global Version June

185 Appendix Renew Your Developer Zone Key Notice the updated Key ID expiry date. Global Version June

186 Appendix Developer Zone Key Tool Utility NOTE: If the CSR file is different than the CSR that was originally submitted when you created the key, make sure that your application is using the correct key store (.p12 file); otherwise calls to MasterPass services will fail. Developer Zone Key Tool Utility This topic provides information on developer zone key tool utility. Procedure 1. From the Add A Key screen, click Click Here to launch the Key Tool utility. Global Version June

187 Appendix Developer Zone Key Tool Utility 2. Click on the Generate Keys and CSR button and then Save to Files. 3. In the Keystore Password screen, enter your password. Global Version June