MASTERPASS MERCHANT ONBOARDING & INTEGRATION GUIDE

Transcription

1 MASTERPASS MERCHANT ONBOARDING & INTEGRATION GUIDE VERSION 6.1, AS OF DECEMBER 5, 2014

2 Notices Proprietary Rights The information contained in this document is proprietary and confidential to MasterCard International Incorporated, one or more of its affiliated entities (collectively MasterCard ), or both. This material may not be duplicated, published, or disclosed, in whole or in part, without the prior written permission of MasterCard. Trademarks Trademark notices and symbols used in this document reflect the registration status of MasterCard trademarks in the United States. Please consult with the Customer Operations Services team or the MasterCard Law Department for the registration status of particular product, program, or service names outside the United States. All third-party product and service names are trademarks or registered trademarks of their respective owners. Translation A translation of any MasterCard manual, bulletin, release, or other MasterCard document into a language other than English is intended solely as a convenience to MasterCard members and other customers. MasterCard provides any translated document to its members and other customers AS IS and makes no representations or warranties of any kind with respect to the translated document, including, but not limited to, its accuracy or reliability. In no event shall MasterCard be liable for any damages resulting from members and other customers reliance on any translated document. The English version of any MasterCard document will take precedence over any translated version in any legal proceeding. Content Disclaimer No assurances are given that the information provided herein is error-free. You acknowledge and agree that inaccuracies may be present. The information is provided to you on an "AS IS" basis for use at your own risk. MasterCard will not be responsible for any action you take as a result of this document. Publication Code MWMI 2

3 Table of Contents Notices... 2 Proprietary Rights... 2 Trademarks... 2 Translation... 2 Content Disclaimer... 2 Publication Code... 2 Release Notes... 5 Overview... 6 How does MasterPass work?... 6 MasterPass User Interface... 6 Standard Lightbox Display (desktop and laptop)... 6 Standard Mobile Display (.mobi)... 7 Standard Full Screen Display... 8 MasterPass Checkout Experiences... 9 Overview... 9 MasterPass Merchant Standard Checkout process flow MasterPass Connected Checkout Experience Pairing of wallet Return Checkout Unpairing Direct Merchant Onboarding I. Incorporating MasterPass into your site or app Direct Merchant Onboarding - Steps Merchant Registration and Setup Merchant Activity Add Developer Accounts to Merchant Profile Merchant Activity Developer Registration, API Keys, Initiate Development & Request Approval Developer Activity26 MasterPass Developer Account MasterCard Developer Zone Account Generate MasterCard Developer Zone Developer API Keys Initiate Development Request Access to Merchant s Sandbox Details Review Integration Project & Approval/Reject Merchant Activity Access Sandbox Credentials, Complete Development and Test Developer Activity Access Merchant Sandbox details Request Production Credentials Developer Activity Approve Production Credential Request Merchant Activity Deploy application using Production Credentials Developer Activity Integration Process Lightbox Integration Standard Checkout Invoke MasterPass UI (Lightbox) Standard Checkout Callback a. Redirect to Merchant Callback URL Example b. Checkout Callback method Example Pairing with MasterPass Wallet without Checkout

4 Invoke MasterPass UI Pairing without checkout Callback Pairing with MasterPass Wallet during Checkout Invoke MasterPass UI for Pairing during Checkout Pairing during Checkout Callback Return Checkout (Checkout after Wallet Pairing) Invoke MasterPass UI for Connected Checkout Connected Checkout Callback Service Descriptions: Request Token Service Sandbox and Production Endpoints Shopping Cart Service Sandbox and Production Endpoints Merchant Initialization Service Sandbox and Production Endpoints Access Token Service Sandbox and Production Endpoints Pre-Checkout Data Service Sandbox and Production Endpoints Retrieve Payment, Shipping Data, Rewards and 3DS Details Postback Service Sandbox and Production Endpoints Android and ios App Integration MasterPass Branding Displaying Buy with MasterPass Button and Acceptance Marks Displaying Connect with MasterPass Button MasterPass Learn More page Testing MasterPass Sandbox Testing Q/A Checklist Asset Placement In-Wallet Experience Post Wallet Experience Postback Connected Checkout Experience Troubleshooting Troubleshooting Support Appendix Lightbox Parameters OAuth Samples Request Token Merchant Initialization Service Shopping Cart Service Redirect & Callback Access Token Service Checkout Resource Pre-Checkout Service Postback Service

5 Developer Zone Key Renewal Process Developer Zone Key Tool Utility DS Overview Service Description General Overview of Transaction Authentication Important Merchant InformationL Document Version Notes Document Version Date /01/ /19/ /26/2013 Updates Updated Connected checkout table (p 9) Added user flows for Standard, Paired, and Returned Checkout (p 12, 14, 15, 17) Updated information about unpairing (p 17) Added note not uploading test loyalty card numbers (p 22) Added further information about OAuth (p 30) Added note about key renewal requirements (p 30) Clarified production deployment instructions (p 37) Added note about new SDK/sample code availability (p 39) Clarified checkout resource URL information (p 46 & 72) Updated ECI Values (p 79) Added note about liability shift and Advanced Checkout (p 53) Added sandbox JavaScript URL (p 38) Highlighted WalletID in checkout ML (p 79) Noted inclusion of JCB as an allowed card type (p 56) Added Lightbox UI experience (p 6) Added New Checkout experience: Connected checkout details (p 12) Merchant Initialization Service - version V6 (p44, 58) Shopping Cart Service - version V6 (p43, 62) Checkout version - version V6 (p45, 69) Precheckout Service - version v6 (p 44, 78) Postback Service - version V6 (p46, 90) Updated QA Checklist (p 52) Lightbox Parameters (p 55) 3DS No Authentication value High resolution image links MasterPass Learn More link Checkout version v5 schema and xml Instructions to use Developer Zone Key Tool Utility 5

6 Overview This document is intended to orient Merchants and their developers seeking to integrate MasterPass as a checkout option on their website and mobile application. How does MasterPass work? MasterPass is a service that enables consumers to store, manage and securely share their payment, shipping 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. Shop on merchant site Click Buy with MasterPass at checkout Sign into MasterPass -enabled Wallet Select card, shipping address and loyalty Select shipping method Review and confirm transaction 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. 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 display Standard full screen display Standard Lightbox Display (desktop and laptop) At full screen, where the browser is set to 100% height and width, the overall Lightbox dimensions are 740 pixels (height) by 700 pixels (width). This is inclusive of the Lightbox header and footer. The interior Lightbox dimensions are 590 pixels (height) by 680 pixels (width). If the height of the browser is reduced so that the entire Lightbox has a height of 740 pixels and the width is maintained, the content container has the following dimensions: 530 pixels (height) by 680 pixels (width). If the browser is set to 100% maximum width, but is less than 530 pixels in height (for the content container), vertical scrolling will appear. If the browser is set to less than 680 pixels in width the Lightbox layout will change to accommodate small screen formats (i.e. phone, smaller tablets). There is a 320 pixel width threshold for the content container. 6

7 Standard Mobile Display (.mobi) Within the.mobi experience, the header and footer are approximately 70 pixels high except for the iphone 5/5S, which has a header and footer which 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. 7

8 Standard Full Screen Display Under certain conditions, such as when the consumer s browser does not support the Lightbox display (older browser), or if the merchant has not yet made coding changes to invoke the Lightbox display, or if the URL requesting the Lightbox display is different from the merchant specified origin URL, then MasterPass will render the wallet experience in full screen. This full screen wallet experience supports all functionality and design as that of the Lightbox display. 8

9 Overview MasterPass Checkout Experiences MasterPass is introducing new checkout options that offer merchants greater flexibility and control over the MasterPass checkout experience. Merchant MasterPass Merchant Experience Merchant identifies consumer Consumer Clicks Signs into Wallet Finalizes Payment Method/ Address Reviews/ Submits Order Confirms Order Receipt/ Thank You Page Standard Checkout Buy with MasterPass Connected Checkout Checkout * *If applicable, advanced authentication, will be invoked after this step. 9

10 MasterPass Merchant Standard Checkout process flow The flows below depict the Standard MasterPass Checkout flow with the Lightbox MasterPass UI. Merchants should use this flow for a non-recognized (guest) user. Merchant Site/App MasterPass Lightbox 13 8 Display Buy with MasterPass at start of checkout Invoke MasterPass Lightbox UI Calculate final price based on shipping and taxes and user confirms purchase Display purchase confirmation page Display Sign-in page 9 1 Merchant Back-End 6 7 Return Origin URL Capture Checkout Resource URL Request Token and Verifier Return Checkout Resource URL, request token and Verifier to site/app 12 Consumer Sign-in 10 Select Card/ Shipping Address/Loyalty details Retrieve credentials - Checkout Identifier, Consumer Key & Callback URL 2 Get Request Token 4 Use Request Token to call Shopping Cart Service with origin URL Use Request Token and Verifier to retrieve Access Token 16 Retrieve purchase data by sending Access Token to Checkout Resource URL Submit transaction to payment gateway/ acquier Review Your Order MasterPass Services Return Request Token and Authorize URL Receive Shopping Cart data Return Access Token Return Payment Method, Loyalty and Shipping Address Receive postback data 10

11 Standard Checkout User Flow Standard Checkout MasterPass Merchant Consumer Consumer clicks Buy with MasterPass Get Checkout Request Token Request Token Service Use checkout request token and origin URL to make shopping cart call Shopping Cart Service Initiate lightbox Consumer log-in and make card / shipping / rewards selection Displays log-in and checkout options Return Checkout verifier and Checkout resource URL Use checkout verifier and checkout request token to get checkout Access Token Access token service Display order confirmation Use checkout access token to get checkout data Checkout Service Postback Service 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 pre-checkout data (shipping, and other wallet information, without the actual card number without the consumer having to log 11

12 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 the wallet password). Data shared in connection with the Connected Checkout can only be used to implement checkout and must be deleted immediately following the check-out experience. No data shared during the Connected Checkout experience may be retained after the checkout is completed. Adherence to MasterPass branding requirements is required. (For display of Wallet Partner logo and MasterPass logo near the pre-checkout information). Connected checkout is supported by 3 components. Pairing of wallet The consumer consents to pair their wallet account with their account on the merchant side (consumer s merchant account), by agreeing to Connected Checkout. Pairing can happen during Checkout or outside of checkout on the merchant site/app. Pairing enables the consumers MasterPass wallet data to be shared with the merchant during current and/or future visits to merchant app/site. This is accomplished by passing a Long Access token to the merchant. No cardholder data should be retained by the Merchant or Service Provider in between checkouts. NOTE: 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. Pair with MasterPass Wallet during Checkout In this experience, a 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 pre-checkout data will be available 12

13 to the merchant during the subsequent checkouts without the consumer having to log in to their wallet. When checkout is completed, the consumer data must be immediately deleted. Pairing During Checkout User Flow Pair with MasterPass Wallet during Checkout MasterPass Merchant Consumer Consumer signs onto merchant site and Clicks Buy with MasterPass Get Checkout Request Token Request Token Service Get Pairing Request Token Request Token Service Use checkout request token and origin URL to make shopping cart call Shopping Cart Service Initiate lightbox Consumer selects wallet, logs-in, select card/ shipping, and consents to pairing Displays wallet selector, log-in, checkout and pairing consent screens Return pairing verifie & token, Checkout verifier & token and Checkout resource URL Use pairing verifier and pairing request token to get Long Access Token Access token service Use checkout verifier and checkout request token to get checkout Access Token Access token service Display order confirmation and pairing Use checkout access token to get checkout data Checkout Service Postback Service 13

14 Pair with MasterPass Wallet outside of a Checkout In this experience, a consumer pairs their wallet with a merchant while not performing checkout e.g. account management. The pairing process starts when a consumer clicks the Connect 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 pre-checkout 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 data must be immediately deleted. Pairing Outside of Checkout User Flow 14

15 Pair with MasterPass Wallet outside of a Checkout MasterPass Merchant Consumer Consumer signs onto merchant site and Clicks Connect with MasterPass Get Request Token Request Token Service Call Merchant initialization with Origin url Merchant Initialization Service Initiate lightbox Consumer logs in Display wallet selector and prompts consumer signin Consumer consents to pairing Prompts consumer to pair Return Verifier and request token Display pairing confirmation screen to the consumer Use verifier and request token to get Long Access Token Access token service Store long access token and associate with user account Return Checkout Once the consumer has paired their wallet account with merchant account, when the consumer returns to the merchant site/app and logs in to their merchant account, the Merchant submits the token to MasterPass to retrieve the consumer s up to date wallet information (card details without card number, addresses etc.). The merchant can then present this information to the consumer as part of their own experience, with the ability to streamline/personalize the consumer s experience during Pre-checkout. Consumers can then checkout easily. The actual PAN will be provided to the merchant only after the consumer logs in to their wallet (by entering the wallet password). Data shared in connection with the Return/Connected Checkout can only be used for the express 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. 15

16 Return Checkout User Flow Return Checkout MasterPass Merchant Consumer Consumer signs onto merchant site Uses long access token to call precheckout service PreCheckout Service Receive Pre-Checkout Data & Precheckout Transaction ID and new long access token Displays Pre-Checkout data to consumer. Consumer makes card / shipping address selection and clicks Buy withmasterpass Get Request Token Request Token Service Shopping cart call Shopping Cart Service Initializes LB Consumer Logs-in and confirms order Displays login page Return Verifier, request token & checkout url Use request token and verifier to get access token Access token service Displays Order Confirmation Use access token to get checkout data Checkout service Postback service 16

17 Unpairing A consumer can unpair their pairing consent for the merchant at any time, using MasterPass account management. When this happens the precheckout call from the merchant to MasterPass will be rejected. In such situations, merchant can proceed with standard checkout. The merchant can also request pairing with this consumer again. 17

18 I. Incorporating MasterPass into your site or app Direct Merchant Onboarding Enabling checkout with MasterPass on your site or mobile app is straightforward here is an overview of the required activities. Activity Actor Steps Environment 1. Merchant Registration & Setup Merchant Create Merchant account, set shipping profile, rewards and advanced authentication MasterPass Merchant Portal 2. Add Developer Accounts to Merchant Profile 3. Developer Registration and Setup 4. Review Integration Project & Approval 5. Access Sandbox Credentials 6. Request Production Credentials 7. Review Integration Project & Approval 8. Production Migration Merchant Developer Merchant Developer Developer Merchant Developer Invite developers to manage integration Create MasterPass Developer account Create Developer Zone account Generate developer s sandbox and production keys Review sample code/sdk & design services integration Request access to merchant s sandbox credentials Approve and grant access to merchant s sandbox key Use merchant s sandbox key to test against MasterPass sandbox environment Request access to merchant s production credentials Approve and grant access to merchant s production key Update MasterPass API endpoints, Consumer key, Callback URL and Private Key (p12), if different than Sandbox MasterPass Merchant Portal MasterPass Merchant Portal MasterCard Developer Zone Merchant Engineering Environment MasterPass Merchant Portal MasterPass Merchant Portal Merchant Engineering Environment MasterPass Merchant Portal MasterPass Merchant Portal Merchant Production Environment The following accounts will be created during this onboarding process. Use the following table to record the account information for future reference. Account Type Details Account Info Merchant Portal - Merchant account Created by merchant business owner. This id should be used to login at Go here to create merchant account, invite developers, create shipping profiles, rewards, approve checkout projects etc. Userid: Merchant Portal - Developer Account(s) Created when a merchant invites a developer. It s a system generated user id. This id should be used to login at Go here to create checkout project, get checkout project details etc. Userid: 18

19 Developer Zone - Developer Account(s) Created by developer and is used for key exchange. This id should be used to login at Go here to perform key exchange, download Sample Applications, integration guide etc. Userid: By the end of the integration, your site or mobile app should be able to: 1. Display Buy with MasterPass button at the start of the checkout experience. 2. Display Connect with MasterPass button. 3. Invoke and display the MasterPass Lightbox. 4. Relay MasterPass checkout requests to the MasterPass service. 5. Get Precheckout data for consumers that have consented to pair their wallets 6. Receive consumer s billing, shipping address, and rewards data from MasterPass service. 7. Process card, shipping and rewards information using existing process. Note that your implementation must satisfy all criteria in the Q/A checklist. 19

20 Direct Merchant Onboarding - Steps 1. Merchant Registration and Setup Merchant Activity From the MasterPass Merchant Portal, select the country language from the dropdown and click the Create an Account button to start the registration process. You will be presented with a modal window, into which you will enter the invitation code. Please reach out to your MasterCard representative to obtain an invitation code that will grant you access and allow you to register within the merchant portal. After entering the invitation code, you will be presented with the option to select the registration type. Select Merchant to continue with the registration process as shown in screen shots below. If you need to register as a Service Provider, please access the Service Provider Integration Guide(s). Create an Account Enter Invitation Code Select Merchant 20

21 After the merchant account has been created, select Shipping Locations to manage your shipping options. Merchants can have multiple shipping profiles and can also set a preferred shipping profile option. 21

22 Select Rewards Program to enter details about your reward/loyalty program. The name of the Reward Program and Logo provided will be displayed to the consumer during checkout. Here are the field details Reward Program Name: Unique, Min 1- Max 30 characters, String Reward Program ID: Required, Unique, Min 1- Max 10 char, Alphanumeric, Non-Editable Logo: Required, Logo size 65 x 60 pix NOTE: Test reward or loyalty programs must not be entered, as any programs added will be visible to consumers in Production. Any test reward programs uploaded may be deleted by MasterPass Support without prior notice. If available, select Authentication Settings to enable 3DS Authentication. Where available, 3DS may be opted into for MasterCard, Maestro, and Visa only. 22

23 If 3DS is available to your country, you may enable it by completing the Authentication Settings section. If 3DS is not available to you, you will not see the Authentication Settings tab. Select Advanced Checkout on the Authentication Settings page, which means that 3DS will run for all checkout transactions for the appropriate card brand. To enable 3DS for your transactions, you will need to supply the details of your 3DS-enabled Acquirer accounts. To add accounts, click Manage Accounts and then click Add Merchant Acquirer. 23

24 Provide the details requested for each of your MasterCard, Maestro, and/or Visa accounts. If you enable your account for 3DS, you will have the option to downgrade the transaction to Basic Authentication during checkout. 24

25 2. Add Developer Accounts to Merchant Profile Merchant Activity The first step in setting up MasterPass for your business is to add the developers who will integrate MasterPass into your checkout flow. From the landing page, you will add developers to the merchant profile. These developers will handle the technical implementation of MasterPass for your site/app. To get started, click the Start This Step button from the MasterPass Setup page. You will need to indicate who will perform the technical integration. 25

26 Merchants who have an internal or contracted engineering team should select Internal or Contracted Developer, and provide contact information for each developer he/she wishes to invite. Please forward this integration guide to each invited developer. Each developer will receive invitation s from MasterPass, indicating that he/she has been invited to handle the technical integration of MasterPass on-behalf of your company. This integration guide will guide the developer through the integration process. 3. Developer Registration, API Keys, Initiate Development & Request Approval Developer Activity Developers invited to integrate MasterPass on behalf of a merchant will manage their integration activities through two portals: 1. MasterPass Merchant Portal ( 2. MasterCard Developer Zone ( MasterPass Developer Account Developers will use the MasterPass Merchant Portal to request, and access merchant-specific integration credentials, which will be used when interacting with the MasterPass web services. After the merchant invites you as a developer, you should have received your MasterPass Developer credentials in two s from MasterPass. Follow the instructions in the s to create your developer account. 26

27 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. To create a Developer Zone account, visit Developer Zone and click Register. After submitting the form, be sure to activate the account using the confirmation . Generate MasterCard Developer Zone Developer API Keys After creating your account, you will need to generate two sets of API keys (one each for the sandbox and production environments). To make keys easy to distinguish, it s recommended to prefix sandbox keys "SB_" and production keys with "PRD_". Create Sandbox Key To create a Sandbox key, click My Account, then My Dashboard. 27

28 On the My Dashboard page, click My Keys button and then click on Add a Key button. In order 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's "keytool" to generate this CSR, or you may use the CSR generation tool on the developer zone portal. Click here to see instructions for using CSR generation tool. Complete the form, select Sandbox for Environment, and click Submit. You will have Sandbox Key ID at this point. 28

29 Create Production Key To create a Production API key, return to My Dashboard and click on My Keys. Then click on Add a Key and make sure you select Production environment. Complete the form and click Submit. At this point, developers will have Sandbox and Production Key ID. These IDs will be used when submitting a checkout project to the merchant for approval. Note: Keys expire after 1 year before which they should be renewed by initiating the Developer Zone Key Renewal process. Notifications at 30, 15 and 1 day prior to key expiration will be sent to the address associated with the Developer Zone account. Your integration will stop working if the keys are expired. 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 At this point, developers should begin developing their own implementation. Sample Applications for.net (C#), Java, PHP and Ruby will be made available for download from Developer Zone. Please contact MasterPass Support if the sample applications are not available in the language you need them in. 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. Further information can be found here: 29

30 Request Access to Merchant s Sandbox Details Prior to allowing the developer s code to interact with the MasterPass service (on-behalf of a merchant) the merchant must approve the checkout project created by the developer. The developer will make two separate approval requests. The first request is to grant the developer access to credentials that will enable his/her code to transact with the MasterPass sandbox environment on-behalf of the merchant. The sandbox environment does not contain real consumer data. The second request is for production credentials, which will enable real transactions. Developers will use MasterPass Merchant Portal to request, and access merchant-specific integration credentials, which will be used when interacting with the MasterPass services. The credentials are requested by submitting a checkout project. To get started, sign into the MasterPass Merchant Portal. Under Manage Development, click Checkout Projects -> Create New Project and complete the New Project creation wizard. 30

31 Select Commerce Channel Enter Project Name, Project Description Enter branding elements for the merchant (Merchant Name, Logo), domain-level URL that the MasterPass consumers will be launched from in the sandbox and production environments. Merchant Name will be displayed if no logo is provided. The recommended logo dimensions for a website project are 100x60 pixels; the recommended logo dimensions for a mobile project is 8030 pixels. 31

32 Enter the sandbox and production Key IDs that were created on MasterCard Developer Zone. Create Checkout Project Developer Zone Production Key ID Developer Zone Sandbox Key ID To submit the project for sandbox approval, click Submit. 32

33 4. Review Integration Project & Approval/Reject Merchant Activity After the Developer submits the request for sandbox credentials, the Merchant will get an notification. The Merchant will log on to the MasterPass Merchant Portal, review the branding and provide approval. After clicking Approval Requests on the navigation bar, the user will see a list of open requests. Click View Details. Merchant must click View details of the checkout project to approve it. Please note that the consumer facing UI will be the new MasterPass Lightbox user interface, and the branding shown will be different in the end user experience. The MasterPass interface in this step is illustrative only and not representative of actual end consumer user interface. 33

34 The user will be presented with the option to either Approve or Reject the project. If rejected, a reason must be provided, and the developer will be allowed to modify the entry and resubmit. 5. Access Sandbox Credentials, Complete Development and Test Developer Activity Access Merchant Sandbox details After approval has been granted by the Merchant, the Developer will receive an notification that changes have been approved. The Developer will sign into the MasterPass Merchant Portal and will note the Sandbox Consumer Key associated with the checkout project. Click the View Branding link to view the Checkout Identifier. Please note MasterPass UI is illustrative only. Please refer to MasterCard Developer Zone for sample code and SDKs. 34

35 (Please note MasterPass UI is illustrative only and is not representative of actual consumer UI). 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 35

36 6. Request Production Credentials Developer Activity Once the application has been tested against sandbox, the developer will request merchant s production credential. This is done by submitting the checkout project created in Step 3 to the merchant for approval. 7. Approve Production Credential Request Merchant Activity After developer submits request for production credentials, merchant will get an notification. Merchant will log on to MasterPass Merchant Portal, click on Approval Requests and provide approval (similar to step 4). 36

37 8. 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. Prior to production deployment: - Ensure that you have implemented the MasterPass button on your site or app - Your sandbox implementation passes all items in the QA checklist To move your code to production, update your code with the MasterPass production endpoint, merchant s production Consumer Key, production callback URL and the keystore if different than Sandbox. The last step is to deploy your code to production. You re all done creating your checkout project! Note: For more details on the specific configuration parameters, please refer to the FAQ section at and look for the question, What are the various parameters I need, to call MasterPass services and where do I get them from? 37

38 Integration Process For a step by step guide through integration and illustration of the various calls to MasterPass, you can download the example of our code 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. Lightbox Integration Lightbox integration is required to launch MasterPass user interface. In order to invoke the Lightbox, merchants will need to include the following scripts on the page they implementing Buy with MasterPass or Connect with MasterPass buttons: 1. It is recommended to pull the jquery file from the public jquery repository 2. MasterPass Script a. Production - b. Sandbox - Standard Checkout The following steps are necessary to integrate a standard MasterPass checkout. For further information, click on each step of the process. 1. Request Token Service 2. Shopping Cart Service 3. Merchant Initialization Service (Optional based on Shopping Cart parameters) 4. Invoke MasterPass UI(Lightbox) for checkout 5. Standard Callback method or 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 Invoke MasterPass UI (Lightbox) Within a script tag the merchant must invoke the checkoutbutton method with the required parameters. Here is an example <script type="text/javascript" language="javascript"> MasterPass.client.checkout({ "requesttoken":"insert_request_token_here", "callbackurl":" "merchantcheckoutid":"insert_checkout_id_here", "allowedcardtypes":["master,amex,diners,discover,maestro,visa"], "version":"v6" }); </script> 38

39 Required parameters are:» requesttoken- The merchants request token from OpenAPI.» callbackurl- A URL to redirect the browser to when checkout is complete. Required unless you use the callback method.» merchantcheckoutid- The merchant s unique checkout id.» allowedcardtypes Card types accepted by merchant» accepted by merchant» version checkout version (v6) Lightbox parameter details can be found here. Standard Checkout Callback Once a checkout completes, MasterPass will return context to the merchant. This can be done via: a. callback URL or b. A javascript call back method. If you wish to use the callback method, failurecallback and successcallback parameters must be set when invoking MasterPass Lightbox UI. a. Redirect to Merchant Callback URL Example ource_url=https%3a%2f%2fstage.api.mastercard.com%2fmasterpass%2fv6%2fcheckou t%2f %3fwallet%3dphw&oauth_verifier=6c50838e31b7441e6eafa b13&oauth_token=d6fa aebb6183d44fb9688fb9dc8332dc b. Checkout 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; } Pairing with MasterPass Wallet without Checkout Note: For Pairing to occur, the merchant must have a way of identifying consumers on the merchant site prior to requesting pairing The following steps are necessary to establish a connection to a consumer s wallet outside of checkout flow. For further information, click on each step of the process. 1. Authenticate user on merchant site 2. Request Token Service 3. Merchant Initialization Service 4. Invoke MasterPass UI(Lightbox) for Pairing 5. Pairing Callback method or Redirect to callback URL 6. Access Token Service 39

40 Invoke MasterPass UI Consumers can pair their MasterPass wallet with merchant outside of checkout by clicking on Connect With MasterPass button. Merchants can display the Connect with MasterPass button anywhere on their site except on checkout pages or pages where payment is initiated to enable pairing outside of checkout e.g. 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":"de7647ac630b50f32f5c9addac122614a727ba52f", "callbackurl":" "merchantcheckoutid":"insert_checkout_id_here", "requesteddatatypes":"[reward_program, ADDRESS, PROFILE, CARD]", "requestpairing":true, "version":"v6" }); </script> Required parameters are:» pairingrequesttoken- Request token for pairing» callbackurl- A URL to redirect the browser to when pairing is complete. Required unless you use the callback method.» merchantcheckoutid- The merchant s unique checkout identifier.» requesteddatatypes- an array of data types the merchant wants paired for. Valid values are CARD, PROFILE, ADDRESS and REWARD_PROGRAM.» requestpairing- value should be true» version checkout version (v6) Lightbox parameter details can be found here Pairing without checkout Callback Once a pairing flow completes, MasterPass will return context to the merchant. This can be done via a callback URL or a javascript call back method. If you wish to use the callback method, failurecallback and successcallback parameters must be set when invoking MasterPass lightbox. 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; } 40

41 Pairing with MasterPass Wallet 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 step of the process. 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 (Optional based on Shopping Cart parameters) 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 3DS Details 10. Authorize Payment through payment processor 11. Postback Service *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. 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":"de4847ac630b50f32f5c9ddac122614a727ba52f", "callbackurl":" "pairingrequesttoken":"de7647ac630b50f32f5c9addac122614a727ba52f", "requesteddatatypes":"[reward_program, ADDRESS, PROFILE, CARD]", "merchantcheckoutid":"a4d6x6r6zhak9hvkkkl091hvofxxmat4y", "allowedcardtypes":["master", "amex", "discover"], "requestpairing":true, "version":"v6" }); </script> Required parameters are:» requesttoken- Request token used to get checkout access token.» callbackurl- A URL to redirect the browser to when checkout is complete. Required unless you use the callback method.» pairingrequesttoken Request token used to get long access token» requesteddatatypes- an array of data types the merchant wants paired for. Valid values are CARD, PROFILE, ADDRESS and REWARD_PROGRAM. PROFILE and CARD are mandatory.» merchantcheckoutid- The merchant s unique checkout id. 41

42 » allowedcardtypes Card types accepted by merchant» requestpairing- value should be true.» version checkout version (v6) Lightbox parameter details can be found here Pairing during 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 call back method. If you wish to use the callback method, failurecallback and successcallback parameters must be set when invoking MasterPass lightbox. Parameter Details 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 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; document.getelementbyid('pairingtoken').value=data.pairing_token; document.getelementbyid('pairingverifer').value=data.pairing_verifi er; } Return Checkout (Checkout after Wallet Pairing) The following steps are necessary to integrate a connected checkout flow. For further information, click on each step of the process. 1. Consumer logs onto Merchant site/app 2. Pre-Checkout 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 (Optional based on Shopping Cart parameters) 7. Invoke MasterPass UI for Connected Checkout 8. Callback method or Redirect to callback URL 9. Access Token Service (Checkout) 10. Retrieve Payment, Shipping Data, Rewards and 3DS Details 11. Authorize Payment through payment processor 12. Postback Service 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. 42

43 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.checkoutButton({ "requesttoken":"insert_request_token_here", "callbackurl":" "merchantcheckoutid":"insert_checkout_id_here", "cardid":"insert_card_id_here", "shippingid":"insert_shipping_address_id_here", "precheckouttransactionid":"insert_prechechout_txn_id_here", "walletname":"insert_wallet_name_here", "consumerwalletid":"insert_consumer_walletid_here", "version":"v6" }); </script> Required parameters are:» 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. Required unless you use the callback method.» merchantcheckoutid- The merchant s unique checkout id.» cardid- The id of the card the user selected.» shippingid- The id of the shipping address the user selected» precheckouttransactionid Pre checkout transaction ID from precheckout xml» walletname Wallet Name from precheckout xml» consumerwalletid Consumer Wallet ID 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 call back method. If you wish to use the callback method, failurecallback and successcallback parameters must be set when invoking MasterPass lightbox. Here are the examples 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 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; } 43

44 Service Descriptions: Request Token Service This should be executed when a consumer clicks Buy with MasterPass button or Connect with MasterPass button on your site/app. For Pairing during checkout, this service will need to be called twice: once to exchange for a Long Access Token which is used to retrieve precheckout data and once 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 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. Shopping cart request has an optional OriginUrl field, if the merchant sets this, it will remove the need to call the merchant initialization service before displaying the Lightbox. Request and response parameter details can be found here. Note: The product description needs to be HTML encoded. 44

45 Sandbox and Production Endpoints Merchant Initialization Service This service is used to secure Lightbox connections between merchant and MasterPass This service requires a request token (OAuthToken); This service call should be used when shopping cart service is not called e.g. pairing during non-checkout flow. Request and response parameter details can be found here. Sandbox and Production Endpoints Access Token Service Next step is to exchange a Request token for an Access token from the MasterPass service. For Pairing during checkout, this service will need to be called twice: once for requesting the checkout access token which is used to retrieve checkout data; and one for requesting the long access token which is used to retrieve pre-checkout data. You will use 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 Pre-Checkout Data Service MasterPass provides merchants with the ability to request paired consumer s data (card alias, shipping addresses, loyalty program, and profile information) prior to the actual MasterPass checkout. This gives the merchant the ability to provide the consumer the opportunity to pre-select their checkout options before completing the checkout. If for any reason the precheckout call gets rejected at 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, etc.) the merchant has to request pairing again. Note: This is not required for standard checkout. Request and response parameter details can be found here. Sandbox and Production Endpoints

46 Retrieve Payment, Shipping Data, Rewards and 3DS 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 3DS information from MasterPass. 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. Example: Below are two example callback urls with the checkout_resource_url parameter highlighted: 1) %2Fapi.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F &oauth_verifier=aa2ff8e8f11 44f45c3b8fdc3d a49e387&oauth_token=b8361ad151af35f71df7b395e083befcaf8192dd Decoded checkout url: checkout_resource_url= 2) com%2fmasterpass%2fv6%2fcheckout%2f &checkoutid= &oauth_verifier=aa2ff8e 8f1144f45c3b8fdc3d a49e387&oauth_token=b8361ad151af35f71df7b395e083befcaf8192dd Decoded checkout url: checkout_resource_url= Request and response parameter details can be found here. Please note that 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. Note: 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. In accordance with MasterCard bulletin Global 550 Identification of PayPass Transactions, a 3-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, rather than being manually entered. You many need to work with your payment provider (acquirer, payment gateway, etc.) to understand how best to handle this data element. In the event, your acquirer has not completed implementation of this bulletin, your transactions will continue to process as-is. Please contact your MasterCard representative to get the bulletin. This project created the following new message elements in Dual Message Authorization, Dual Message Clearing, and the Single Message System to carry this identifier: 46

47 Dual Message System (Authorization) Data element (DE) 48 (Additional Data Private Data), sub element 26 (Wallet Program Data), subfield 1 (Wallet Identifier) Dual Message System (Clearing) PDS 0207 (Wallet Identifier) Single Message System DE 48 (Additional Data), sub element 26 (Wallet Program Data), subfield 1 (Wallet Identifier) Postback Service Note: This is a mandatory step. 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. Please note that the <TransactionId> value should be the value from the <TransactionId> element of the Checkout ML 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 e.g. USD OrderAmount: Transaction Order Amount e.g., 1500 (for $15 transaction amount) PurchaseDate: Date of Purchase ApprovalCode: 6-digit approval code returned by payment API. TransactionId: Transaction ID from TransactionId element of the Checkout ML from the retrieve payment, shipping, rewards and 3DS data service call for example, TransactionStatus: Status of transaction. Valid values are o SUCCESS: For approved transaction o FAILURE: For declined transaction PreCheckoutTransactionId: Comes from PrecheckoutTransactionId element of the PrecheckoutData ML. (this is not required for Standard Checkout) 47

48 Sandbox and Production Endpoints Android and ios App Integration Your Android or ios application should invoke a backend service to initiate the OAuth authorization. On the native application side, most of the work involves connecting to your backend services. The basic process is as follows: 1. Perform a POST to ${server}/apptowallet/initialize with the shopping cart data in the POST message a) The server will request the Request Token, pairing, and precheckout data, post the shopping cart data to MasterPass services and generate the Redirect URL. b) The server will pass the Redirect URL and the Callback URL back to the mobile application. 2. On a 200 response, save the Callback URL, and use the user Redirect URL to open a Web View 3. Watch the Web View for navigation to the Callback URL. 4. On navigation to the Callback URL, a) If the query parameter section of the Callback URL only contains the oauth_token, the user did not complete selection in MasterPass. Return the user to the cart view, or wherever your particular requirements dictate. b) If the query parameter of the Callback URL section contains information, parse out the oauth_token, oauth_verifier, and checkout_resource parameter values, perform a string replacement on the checkout_resource value to replace / with. and use these to perform a GET to${server}/apptowallet/checkoutinformation/${oauth_token}/${oauth_verifier}/${checkout_resource} c) Note: Do not send the full PAN to the mobile device. This information should be stored on the server similarly to the server/browser implementation. 5. On a 200 response, use the returned information to produce a summary view for the user to give final approval to the transaction (pursuant to your specific requirements.) 6. After the consumer completes the transaction, the server should submit postback to MasterPass. MasterPass Branding Displaying Buy with MasterPass Button and Acceptance Marks The MasterPass acceptance mark and checkout button image URLs can be found below. To ensure the best consumer experience, the checkout button should be placed at the beginning of the checkout experience, prior to the collection of shipping and billing information. 48

49 To minimize the impact of future branding updates, please 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 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 Branding Requirements document available on MasterCard developer zone. The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO and Button as shown below: Base URL/Language/Country/Image File Name Base URL: Note: The list of language/country folders can be found at under the question, Which countries and locales are currently supported to link 'Buy with MasterPass' images? Buy with MasterPass button Example: Below is an example of how a Merchant can include the checkout button. <div class="masterpassbtnexample"> <a href="/exampleredirect"> <img src=" 034px.png" alt="checkout with MasterPass Button Example" /> </a> </div> 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 49

50 /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 US English URL: Canada French URL: Displaying Connect with MasterPass Button This button is used to initiate Pairing outside of a checkout. The MasterPass Connect with MasterPass button image URLs can be found below. To minimize the impact of future branding updates, please 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 Branding Requirements document available on MasterCard developer zone. The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO and Button as shown below: Base URL/Language/Country/Image File Name Base URL: Here are a few examples US English URL Connect with MasterPass Button: Canada French URL Connect with MasterPass Button: Note: The list of language/country folders can be found at under 50

51 the question, Which countries and locales are currently supported to link 'Connect with MasterPass' images? Connect with MasterPass button Example: Below is an example of how a Merchant can include the Connect with MasterPass button. <div class="masterpassconnectbtnexample"> <a href="/exampleredirect"> <img src=" " alt="connect with MasterPass" /> </a> </div> Connect with MasterPass Images 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. Learn More page is available in multiple languages and can be accessed from the following link. For the list of all available languages, please refer to FAQs on developer zone. English - Swedish - French - Italian - Spanish - Please refer to the FAQs for a list of all available countries at under the question, Which languages are currently available for use with the MasterPass Learn More page? Testing 51

52 MasterPass Sandbox Testing In order to access the necessary information to test in the sandbox environment, you must submit an approval request to the merchant as explained earlier in the guide. Testing can be conducted in the sandbox environment, using the test consumer account. Your code must gracefully handle the error states and scenarios listed below. Note: You cannot add cards to a sandbox account. Only shipping addresses can be added to sandbox accounts. Consumer Account (Sandbox) Do not modify this shared account Test Account 1 Login Joe.test@ .com Password abc123 Answer to Security Question Pets Name: fido Test Account 2 Login Joe.test3@ .com Password abc123 Answer to Security Question Pets Name: fido Use the remember me and remember this device options when testing so that you don t have to rekey the entire test account information every time you login to MasterPass. Once you are redirected to the sandbox environment, select MasterPass wallet to sign-in to Sandbox Consumer Wallet Account. Below is a quick walkthrough of the Wallet experience. (Select) MasterPass Wallet Sign-in & Verify Your ID (Login for Sandbox) 52

53 Select Payment & Shipping Q/A Checklist Asset Placement» Verify your adherence to the MasterPass Branding Requirements document.» Verify that you are linking to (versus hosting your own) MasterPass visual assets 53

54 In-Wallet Experience» Verify that the consumer can only select card/addresses/rewards that are supported by the merchant» Verify shopping cart information is sent to MasterPass and is displayed.» Merchants requesting liability shift for MasterPass transactions should use Advanced Checkout within MasterPass Post Wallet Experience» After clicking the Finish Shopping button, verify the consumer is taken to a valid page.» Verify that MasterPass acceptance mark is displayed for all MasterPass transactions» Verify that MasterPass and issuer logo are displayed with pre-checkout data (for connected checkout)» It s recommended to not allow consumers to edit the payment information returned by MasterPass.» 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-wallet page has a clear call to action (e.g. select preferred shipping method), versus simply having the consumer review the data they just selected in the Wallet» Verify that consumer is not required to enter CVC/CVV in order to complete the transaction» Verify that non-pci compliant merchants do not receive the card PAN» Verify that if merchants are provided with the PAN, this value is not displayed on-screen Postback» 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 after card authorization Connected Checkout Experience» Verify that consumer is logged into Merchant site before offering Connected Checkout» For Pairing, you must request at least Card and Profile data elements» If 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, etc.) the merchant has to request pairing again.» Verify that pairing is offered during checkout or outside of checkout (e.g. account management) General» Ensure that you are coding to DNS and not to IP addresses for our urls and endpoints Troubleshooting 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 Troubleshooting 54

55 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 CheckoutML call. If you get Error Forbidden when calling MasterPass services» Verify correct credentials or correct environment (i.e., 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 (example, encoded incorrectly) Support Please refer to the FAQs at +Merchant+Checkout+-+FAQs. If you have any questions or comments relating to MasterPass integration, please contact us at merchant_support@masterpass.com. 55

56 Data type Card security Checkout Connect MasterPass Merchant Onboarding & Integration Guide Appendix Lightbox Parameters Lightbox Parameters invoked on clicking Buy with MasterPass or Connect with MasterPass button. O = Optional; R = Required; A = Automatically populated Parameter name 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 (*) *JCB is supported in select markets only. Please contact your local MasterCard representative to learn if it is supported in your markets loyaltyenabled bool O This parameter defines if the merchant is requesting consumer s loyalty details from MasterPass for the transaction. Valid values are true / false shippinglocationprofile string[] O This parameter defines Merchant s Shipping Profile(s) for the transaction that they set in their account. 56

57 callbackurl string O 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. cardid string O Required for connected checkout. Set to a valid payment card ID. failurecallback function O O O This defines the function to be called when the flow ends in failure. Refer SDK for more examples loyaltyid string O Optional for connected checkout. Set to a valid loyalty card ID. merchantcheckoutid string R R R This is the checkout identifier which is used to identify the merchant and their checkout branding. 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 bool O Set to "true" to disable step-up authentication (advanced checkout) during any checkout flow. The default is "false". requesteddatatypes string[] O R 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 bool O A 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 R This is an OAuth token. pairingrequesttoken string O R This is an OAuth token. 57

58 suppressshippingaddressenable Bool O When set to True shipping address screen is not displayed to consumer. When set to false, shipping address is displayed and consumer can select. shippingid string O Optional for connected checkout. Set to a valid shipping destination ID. walletname string R Required for connected checkout to uniquely identify wallet name consumerwalletid string R Required for connected checkout to uniquely identify consumer successcallback function O O O This defines the function to be called when the flow ends in success. OAuth Samples Request Token Request Token Parameters oauth_callback oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_token oauth_callback_confirmed oauth_expires_in oauth_token_secret xoauth_request_auth_url request_token Request request_token Response Request Parameter Details Signature Base String Authorization Header Request Token Request oauth_callback oauth_signature Description Endpoint that will handle the transition from the wallet site to the merchant checkout page RSA/SHA1 signature generated from the signature base string Possible Values Variable Variable 58

59 Oauth Token Request Token oauth_version oauth version 1.0 oauth_nonce oauth_signature_method oauth_consumer_key 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 Request Token Response oauth_token Signature Base String Example oauth_callback_confirmed Used to differentiate between our mobile and full site. Currently not used. Description oauth_token is sent in the signature base string, authorization header and redirect URL ewallet Possible Values Variable Variable oauth_expires_in Time the Request Token expires in seconds Variable oauth_token_secret Oauth Secret Variable xoauth_request_auth_url Authorize URL Variable 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- IpGCIu559HYriL093IBdJeKavp4dce9db2a% 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%2fwhp4cstrkgj1mv%2fkm6do5zvi6dokzajz0m8qqhieri5lrup hdyukhw8lkdul1tetpdxm32vtr%2bqgf6n6ibjr8dgcyymfalyayvhf%2fx5oqhudvpdic10dj0m iuwzpbj1qopn3ibeozvgnxheihykvnpvyehc%3d",oauth_version="1.0",oauth_nonce=" ",oauth_signature_method="RSA- SHA1",oauth_consumer_key="ZGho8Df8vqW- IpGCIu559HYriL093IBdJeKavp4dce9db2a% 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 59

60 Merchant Initialization Service Merchant Initialization Parameters oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_body_hash oauth_token Merchant Initialization Merchant Initialization resource Request Merchant Initialization Resource Response 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 oauth_version Oauth version. 1.0 oauth_nonce Unique alphanumeric string generated from code Variable Variable oauth_signature_method oauth_consumer_key oauth signature method. Consumer Key generated when creating a checkout project on MasterPass Merchant portal RSA- SHA1 Variable oauth_timestamp Current timestamp Variable oauth_token Request token Variable Merchant_Initialization _origin_url Merchant Initialization Resource Response URL of the page that will initialize the lightbox 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 60

61 Signature Base String Example POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%merchantinitial ization&oauth_body_hash%3d8k9uhvezjvdzw8aiyipr70kctk%253d%26oauth_consumer_key %3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeM_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_6ltdiibo5wgbx4rildem_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= "8K9uhveZjVdZW8AIYipR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAK%2FYvuJ2BtO4C 8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITt3HT3zrav b02oqtrvqh3zlx5fi4o0u2xxqrdwhzvbhjpgwbybrme%2fotw2l9h%2fznsn45xcs1ejpa%2fgi%3d" ML V6/merchant-initialization -ML 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:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any" /> </xs:sequence> <xs:anyattribute /> </xs:complextype> </xs:schema> URL: - Sample Request <MerchantInitializationRequest> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> 61

62 <OriginUrl> </MerchantInitializationRequest> V6/merchant-initialization -ML 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 ML Details MerchantInitializationRequest ML Element Description Type Min Max MerchantInitializationRequest Root Element ML - OAuthToken Request Token (oauth_token) returned by call to the request_token API - MerchantInitializationRequest PreCheckoutTransactionID Identifies pre-checkout transaction. Returned from get pre-checkout data call; Optional string NA OriginUrl Identifies the URL of the page that will initialize the lightbox. string NA ExtensionPoint Reserved for future enhancement. Optional Any 62

63 MerchantInitializationResponse ML Element Description Type Min Max OAuthToken ExtensionPoint Request Token (oauth_token) returned by call to the request_token API Reserved for future enhancement. Optional ML - 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 ML 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> Shopping Cart Service Shopping Cart Parameters oauth_signature oauth_version oauth_nonce Shopping Cart Request Shopping Cart Response 63

64 oauth_signature_method oauth_consumer_key oauth_timestamp oauth_body_hash oauth_token Shopping Cart Request ML Shopping Cart Response ML Shopping Cart Parameter Details Signature Base String Authorization Header Oauth Token Shopping Cart Request oauth_signature Description RSA/SHA1 signature generated from the signature base string oauth_version Oauth version 1.0 oauth_nonce oauth_signature_method oauth_consumer_key Unique alphanumeric string generated from code oauth signature method Consumer Key generated when creating a checkout project on MasterPass Merchant portal Possible Values Variable Variable RSA- SHA1 Variable oauth_timestamp Current timestamp Variable oauth_body_hash SHA1 hash of the message body Variable oauth_token oauth_token is sent in the signature base string, authorization header and redirect URL Transfer ML Strings Shopping Cart Request ML Merchant Shopping Cart details Oauth Token Transfer ML Strings Shopping Cart Response oauth_token Signature Base String Example Shopping Cart Response ML Description oauth_token is sent in the signature base string, authorization header and redirect URL Variable Possible Values Variable POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fshopping-cart &oauth_body_hash%3d8k9uhvezjvdzw8aiyipr70kctk%253d%26oauth_consumer_key%3dclb0 tkkejhgtitp_6ltdiibo5wgbx4rildem_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/shopping-cart HTTP/1.1 Authorization: OAuth realm="ewallet",oauth_consumer_key="clb0tkkejhgtitp_6ltdiibo5wgbx4rildem_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= "8K9uhveZjVdZW8AIYipR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAK%2FYvuJ2BtO4C 64

65 8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITt3HT3zrav b02oqtrvqh3zlx5fi4o0u2xxqrdwhzvbhjpgwbybrme%2fotw2l9h%2fznsn45xcs1ejpa%2fgi%3d" Shopping Cart V6-ML Schema <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="shoppingcartrequest" type="shoppingcartrequest" /> <xs:complextype name="shoppingcartrequest"> <xs:sequence> <xs:element name="oauthtoken" type="xs:string" /> <xs:element name="shoppingcart" type="shoppingcart" /> <xs:element name="originurl" type="xs:string" minoccurs="0" /> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0" /> </xs:sequence> </xs:complextype> <xs:complextype name="shoppingcart"> <xs:sequence> <!-- CurrencyCode is defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars. All Monetary Values will be modified by the CurrencyCode. For example a Monetary Value of combined with a CurrencyCode of USD will be handled at $ > <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="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any" /> </xs:sequence> <xs:anyattribute/> </xs:complextype> </xs:schema> Shopping Cart V6 ML Details ShoppingCartRequest Element Description Type OAuthToken Min Max Request Token (oauth_token) returned by call to the request_token API String Variable ShoppingCart Merchant Shopping Cart details. ML - OriginUrl Identifies the URL of the page that will String Variable 65

66 ShoppingCart initialize the lightbox. ExtensionPoint Reserved for future enhancement. Optional Any - CurrencyCode Subtotal 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 Total sum of all the items in the cart excluding shipping, handling and tax. Integer without the decimal e.g. $ USD will be Integer 1-12 ShoppingCartItem Details of a single shopping cart item. ML - ExtensionPoint Reserved for future enhancement. Optional Any - ShoppingCartItem Description Describes a single shopping cart item. String Quantity Number of a single shopping cart item. Integer 1-12 Value ImageURL Price or monetary value of a single shopping cart item. Cost * Quantity. Integer without decimal e.g., $ is Integer 1-12 Link to shopping cart item image. URLs must be HTTPS, and not HTTP. String ExtensionPoint Reserved for future enhancement. Optional Any - ShoppingCartResponse Element Description Type OAuthToken Min Max Request Token (oauth_token) returned by call to the request_token API String Variable ExtensionPoint Reserved for future enhancement. Optional Any - Shopping Cart Request ML 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> <OriginUrl> </ShoppingCartRequest> Shopping Cart Response ML Sample <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ShoppingCartResponse> <OAuthToken>a747f7e7c2e0c f640b92806c8</OAuthToken> 66

67 </ShoppingCartResponse> Shopping Cart-ML Response 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> Redirect & Callback Redirect & Callback Parameters Redirect to MasterPass Callback from MasterPass oauth_token oauth_verifier checkout_resource_url acceptable_cards checkout_identifier version suppress_shipping_address auth_basic accept_reward_program shipping_location_profile 67

68 Redirect & Callback Parameter Details Oauth Token Redirect URL Parameters Oauth Token Access Token Redirect to MasterPass oauth_token acceptable_cards checkout_identifier version suppress_shipping_address auth_level accept_reward_program Description oauth_token is sent in the signature base string, authorization header and redirect URL Comma delimited list of accepted cards. Checkout identifier generated when creating a checkout project on MasterPass Merchant portal Attribute to indicate which Checkout ML version to return. Flag to suppress the shipping options presented to the user. This parameter is optional and will default to false. Flag to reduce the 3DS authentication from advanced to basic on per transaction basis. Note: the 3DS level must be set to advance on the merchant profile to be reduced to basic with this flag. Possible value = basic. This parameter is optional and only used when 3DS authentication is used. Optional flag to specify if you want MasterPass to return consumer s reward program Possible Values Variable master, amex, diners, discover, maestro, visa Variable v6 true false basic true / false shipping_location_profile ID of shipping location profile variable Callback from MasterPass oauth_token oauth_verifier checkout_resource_url Description oauth_token is sent in the signature base string, authorization header and redirect URL Verifier is returned on the callback and used in the access token request Endpoint used to request the users billing and shipping information from MasterPass Possible Values Variable Variable Variable Redirect to MasterPass Example a85d95f8c f&acceptable_cards=master,amex,diners,discover,maestro,visa&c heckout_identifier=a4a6x1ywxlkxzhensyvad1hepuouaesuv&version=v6&suppress_ship ping_address=false&accept_reward_program=false Redirect to Merchant Callback URL Example urce_url=https%3a%2f%2fstage.api.mastercard.com%2fmasterpass%2fv6%2fcheckout% 2F %3Fwallet%3Dphw&oauth_verifier=6c50838e31b7441e6eafa b13&oauth_token=d6fa aebb6183d44fb9688fb9dc8332dc Note: the checkout_resource_url field must be URL decoded. 68

69 Access Token Service Access Token Parameters access_token Request access_token Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_token oauth_expires_in oauth_token_secret xoauth_request_auth_url oauth_verifier Access Token Parameter Details Access Token Request Description Possible Values oauth_signature RSA/SHA1 signature generated from the Variable signature base string oauth_version Oauth version. 1.0 Signature Base String Unique alphanumeric string generated Authorization Header oauth_nonce from code Variable oauth_signature_method oauth signature method RSA- SHA1 Consumer Key generated when creating a Variable oauth_consumer_key checkout project on MasterPass Merchant portal oauth_timestamp Current timestamp Variable realm Used to differentiate between our mobile ewallet and full site. Currently not used. oauth_verifier Verifier is returned on the callback and used in the access token request oauth_token oauth token obtained from request token Variable call Access Token Response Description Possible Values Oauth Token oauth_token is sent in the signature base Variable oauth_token string, authorization header and redirect URL Request Token oauth_expires_in Time the Request Token expires in 900 seconds oauth_token_secret Oauth Secret Variable 69

70 Signature Base String Example POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Faccess_t oken&oauth_callback%3dhttp%253a%252f%252fprojectabc.com%252fmerchant%252fcallbac k.jsp%26oauth_consumer_key%3dzgho8df8vqw- IpGCIu559HYriL093IBdJeKavp4dce9db2a% b616c a413d3d%26oauth_nonce%3D %26oauth_signature_method%3DRSA- SHA1%26oauth_timestamp%3D %26oauth_token%3Da02c5c5c1a128c2cebc650ea9aa3 dfb7%26oauth_verifier%3d ce6289d0faf45be777d2d86f%26oauth_version%3d1.0 HTTP Request Example POST /oauth/consumer/v1/access_token HTTP/1.1 Authorization: OAuth oauth_callback="http%3a%2f%2fprojectabc.com%2fmerchant%2fcallback.jsp",oauth_sig nature="okcp2kmzuer8kqs%2f7m2epv6uj30n786anz0kvjsngv4q8%2fp3%2bs7lqv7yik0yb2h0fu TC7gSHsfJwmCCk4ES%2FlWVIpSRmVxotgLacxj%2FI08DS0BZ0MZZIkhY5Dcg775U3Re4GRN4xa9vm bztobd%2bkknyfiw35to22n1zuhrypi%3d",oauth_version="1.0",oauth_nonce=" ",oauth_signature_method="RSA-SHA1",oauth_consumer_key="ZGho8Df8vqW- IpGCIu559HYriL093IBdJeKavp4dce9db2a% b616c a413d3d",oauth_token="a02c5c5c1a128c2cebc650ea9aa3dfb7",oauth_verifier=" ce6289d0faf45be777d2d86f",oauth_timestamp=" ",realm="ewallet" HTTP Response Example oauth_token=9429f23bd08f992c41fb5ddabcc03ecd&oauth_token_secret=cd1ab178419c2111 fb f5dc8d9 Checkout Resource Checkout Parameters oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_token checkout_resource_url Checkout ML Checkout resource Request Used as endpoint Checkout Resource Response Checkout Parameter Details Possible Checkout Resource Request Description Values Signature Base String oauth_signature RSA/SHA1 signature generated from the Variable 70

71 Authorization Header signature base string oauth_version Oauth version. 1.0 oauth_nonce Unique alphanumeric string generated from code Variable oauth_signature_method oauth signature method. RSA- SHA1 oauth_consumer_key Consumer Key generated when creating a checkout project on MasterPass Merchant Variable portal oauth_timestamp Current timestamp Variable realm Used to differentiate between our mobile and full site. Currently not used. ewallet oauth_verifier Verifier is returned on the callback and used in the access token request Checkout Resource Response Description Possible Values Oauth Token oauth_token is sent in the signature base oauth_token string, authorization header and redirect Variable URL Access Token Endpoint used to request the users billing checkout_resource_url and shipping information from MasterPass Variable Transfer ML Strings Checkout ML Details of the Checkout Signature Base String Example GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F &oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeM_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 GET /masterpass/v6/checkout/4400 HTTP/1.1 Authorization: OAuth oauth_signature="cks9xjehksuvnkotsrmoog0rwmveoc2dtqnnw8iwlszeg1znkvrpstjde32ybndhr 7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhGWRrRpjh3ZhHLDOdSxtxjSCJaHF QkfGyq%2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce=" ",oau th_signature_method="rsa- SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeM_jRd4b0476c%21414f c4a366c726a b d",oauth_token="c531cce64ca2d88ecb223a 8a37afe98e",oauth_timestamp=" ",realm="eWallet" Checkout ML V6/Checkout-ML 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 Examples of decoded url: checkout_resource_url=

72 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="id" 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"/> 72

73 <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"/> <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> 73

74 <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"/> </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"/> 74

75 <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 </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> V6/Checkout -Sample Response <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> 75

76 </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> <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 ML Details CheckoutML Element Description Type Checkout Root Element ML - Checkout Card Child Element ML - Card BrandId Identifies the card brand id e.g. Alpha master for MasterCard. Numeric 0-8 BrandName Identifies the card brand name e.g. MasterCard String AccountNumber Card number or primary account number that identifies Integer Min Max 76

77 CheckoutML Element Description Type Min Max the card BillingAddress Billing Address for the card holder. ML - CardHolderName Cardholder name String ExpiryMonth Expiration month displayed on ML Date the payment card. format ExpiryYear Expiration year displayed on ML Date the payment card. format ExtensionPoint Reserved for future enhancement. Optional Any - Checkout TransactionID Child Element String Checkout Contact Child Element ML Contact (V5 Updates) FirstName Contact First Name String 1-20 Optional MiddleName Contact Middle Name or Initial String 1-20 LastName Contact Surname String 1-20 Optional* Gender Contact Gender (M or F) M or F Optional * DateOfBirth Contact DOB YYYY/MM/DD Sequence: Y (4) Year (Int); M (2) Month (Int) D (2) Day (Int) Optional* (dependent on merchant country of incorporation and the NationalID Contact National Identification String consumer country of residence) 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 ML - ShippingAddress Address Child Element ML - Address City Cardholder s city String 0-25 Country Cardholder s country. Defined by ISO alpha-2 digit country codes e.g. US is United States, AU is Australia, String 2 CA is Canada, GB is United Kingdom, etc. CountrySubdivision Cardholder s country subdivision. Defined by ISO alpha-2 digit code e.g. String 5 US-VA is Virginia, US-OH is Ohio Line 1 Address line 1 used for Street number and Street Name. String 1-40 Line 2 Address line 2 used for Apt Number, Suite Number,etc. String 0-40 Line 3 Address line 3 used to enter remaining address information if it does not fit in Line 1 and String Line 2 PostalCode Postal Code or Zip Code String

78 CheckoutML Element Description Type Min Max appended to mailing address for the purpose of sorting mail. ExtensionPoint Reserved for future enhancement. Optional Any - ShippingAddress RecipientName Name of person set to receive the shipped order. String ShippingAddress RecipientPhoneNumber Phone of the person set to receive the shipped order. String 3-20 Checkout AuthenticationOptions Child Element ML - Checkout WalletID Helps identify origin wallet String 3 AuthenticationOptions AuthenticateMethod Method used to authenticate the cardholder at checkout. Valid values are MERCHANT Alpha NA ONLY, 3DS and No Authentication. CardEnrollmentMethod Method by which the card was added to the wallet. Valid values are: Manual Alpha NA Direct Provisioned 3DS Manual NFC Tap (CAVV) Cardholder Authentication Verification Value generated by card issuer CAvv upon successful authentication Alpha of the cardholder and which Numeric NA should be. This should be passed in the authorization message EciFlag: MasterCardAssignedID Electronic commerce indicator (ECI) flag. Present when the PaRes value is "Y" or "A." Possible values are; 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) 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 Alpha Numeric PaResStatus A message formatted, digitally Alpha NA NA NA 78

79 CheckoutML Element Description Type SCEnrollmentStatus SignatureVerification: ID ExtensionPoint signed, and sent from the ACS (issuer) to the MPI providing the results of the issuer s SecureCode/Verified by Visa cardholder authentication. Possible values are: Y-the card was successfully authenticated via 3DS A-signifies that either; 1) the transaction was successfully authenticated via a 3DS attempts transaction; or 2)The cardholder was prompted to activate 3DS during shopping but declined (Visa). U-Authentication results were unavailable SecureCode Enrollment Status: Indicates if the issuer of the card supports payer authentication for this card. Possible values are; Y-The card is eligible for 3DS authentication. N-The card is not eligible for 3DS authentication. U-Lookup of the card's 3DS eligibility status was either unavailable, or the card is inapplicable (i.e. prepaid cards). Signature Verification. Possible values are: 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, etc.) the PaRes could not be validated, and the result should not be trusted. Transaction identifier resulting from authentication processing. Reserved for future enhancement. Optional Alpha Alpha Alpha Numeric Any - Checkout Reward Program Child Element ML Reward Program RewardNumber Consumer s reward number Alpha associated with the reward Numeric program RewardId ID associated with the reward Alpha program Numeric RewardName Name of reward program Alpha Numeric Reward Program Month the reward program Alpha ExpiryMonth expires Numeric ExpiryYear Year the reward program Alpha expires Numeric ExtensionPoint Reserved for future enhancement. Optional Any - Min Max NA NA NA 79

80 CheckoutML Element Description Type Pre Checkout ID associated with the PreCheckoutTransactionId Transaction ID PreCheckout Transaction * Only when legally required and enabled by MasterPass Alpha Numeric Min Max Pre-Checkout Service Pre-Checkout Parameters oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_token PreCheckout Data Request ML PreCheckout Data Response ML Checkout resource Request Checkout Resource Response Pre Checkout Parameter Details PreCheckout Resource Request Description Possible Values oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version. 1.0 oauth_nonce Unique alphanumeric string generated from code Variable Signature Base String Authorization Header Transfer ML Strings oauth_signature_method oauth signature method. RSA- SHA1 oauth_consumer_key Consumer Key generated when creating a checkout project on MasterPass Merchant Variable portal oauth_timestamp Current timestamp Variable oauth_token Long Access token used to retrieve precheckout data variable realm Used to differentiate between our mobile and full site. Currently not used. ewallet PreCheckout Data Request ML Details of the PreCheckout Request Description Possible Values PreCheckout Resource Response Transfer ML Strings Checkout ML Details of the Checkout 80

81 Signature Base String Example GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F &oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeM_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 7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhGWRrRpjh3ZhHLDOdSxtxjSCJaHF QkfGyq%2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce=" ",oau th_signature_method="rsa- SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeM_jRd4b0476c%21414f c4a366c726a b d",oauth_token="c531cce64ca2d88ecb223a 8a37afe98e",oauth_timestamp=" ",realm="eWallet" V6/PreCheckoutDataRequest-ML 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"/> </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> 81

82 <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 ML Details PreCheckoutML Element Description Type PrecheckoutDataRequest Root Element ML - PrecheckoutDataRequest PairingDataTypes Child Element ML - ExtensionPoint Reserved for future enhancement. Optional Any - PairingDataType Child Element ML - ExtensionPoint Reserved for future enhancement. Optional Any - PairingDataType PairingDataType Child Element ML - PairingDataType PairingDataType ExtensionPoint Card, ShippingAddress, Reward_Program, Profile Reserved for future enhancement. Optional String - Any - Min Max 82

83 V6/PreCheckoutDataResponse-ML 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" /> <xs:element name="cardholdername" type="xs:string" /> <xs:element name="expirymonth" type="month" minoccurs="0"/> 83

84 <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> 84

85 <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="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!#-'\*\+\-/=\?\^_`\{-~]+)*"/> </xs:restriction> </xs:simpletype> <xs:element name="precheckoutshippingaddresses" type="precheckoutshippingaddresses"/> <xs:complextype name="precheckoutshippingaddresses"> <xs:sequence> <xs:element name="shippingaddress" 85

86 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"/> <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> 86

87 <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"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> </xs:schema> 87

88 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> 88

89 <Line1>11642 Frontier Dr</Line1> <Line2/> <Line3/> <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 ML Details PreCheckoutDataML Element Description Type PrecheckoutData Root Element ML - PrecheckoutData Cards Child Element PrecheckoutCard - Contact Child Element Contact - ShippingAddresses Child Element PrecheckoutShipping Address - WalletName Child Element String - RewardPrograms Child Element PrecheckoutRewardPr ogram - PrecheckoutTransactionId Child Element String - ConsumerWalletId Child Element String - WalletPartnerLogoUrl 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 - 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 - Min Max 89

90 PreCheckoutDataML Element Description Type Min Max 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 - PrecheckoutShippingAddress Root Element String - PrecheckoutShippingAddress Address Child Element String - Address AddressId Child Element String - RecipientName Child Element String - RecipientPhoneNumber Child Element String - SelectedAsDefault Child Element Boolean - ShippingAlias Child Element String - ExtensionPoint Any - PrecheckoutRewardProgram Root Element String - PrecheckoutRewardProgram 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 - 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 - 90

91 PreCheckoutDataML Element Description Type Min Max 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 - *Only when legally required and enabled by MasterPass 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 ML 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> Postback Service Postback Parameters Post Transaction Request Post Transaction Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key 91

92 oauth_timestamp oauth_body_hash MerchantTransactions ML Postback Parameter Details Post Transaction Request Description Possible Values oauth_signature RSA/SHA1 signature generated from the signature base string Variable Signature Base oauth_version Oauth version. 1.0 String Authorization oauth_nonce Unique alphanumeric string generated from code Variable Header oauth_signature_method oauth signature method. RSA-SHA1 oauth_consumer_key Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable oauth_timestamp Current timestamp Variable Transfer ML Strings Transfer ML Strings oauth_body_hash SHA1 hash of the message body Variable Merchant Transactions ML Post Transaction Response Merchant Transactions ML Signature Base String Example Transaction details Transaction details Description Possible Values POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Ftransaction &oauth_body_hash%3dycnt7a676vey7i0skyymkorihcg%253d%26oauth_consumer_key%3dclb0 tkkejhgtitp_6ltdiibo5wgbx4rildem_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="aom0wfgfi7ityv1izfn125bod6jgftd15dq8bjvmggkgktj5awv7wsmgwucc eglpl52hfs%2b%2boqzvrcduidvgeko1nhdfhns0l1yiaqgdkjqyr%2bcqgu1qo7xvjvztqpulrc 2uzVCjyLoQEroIWv6cAOj5l4aBxDopz7OKQA%3D",oauth_body_hash="ycNt7A676VEY7i0SkyymK orihcg%3d",oauth_version="1.0",oauth_nonce=" ",oauth_signature_met hod="rsa- SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeM_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="merchanttransactions" minoccurs="0" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> 92

93 </xs:sequence> </xs:complextype> <xs:complextype name="merchanttransactions"> <xs:sequence> <xs:element name="transactionid" type="xs:string"/> <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>0zMKpm0nFtUv8lLT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!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> 93

94 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="merchanttransactions" minoccurs="0" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="merchanttransactions"> <xs:sequence> <xs:element name="transactionid" type="xs:string"/> <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> 94

95 HTTP Response Example (response will be identical to the ML sent if call was successful) <MerchantTransactions> <MerchantTransactions> <TransactionId> </TransactionId> <ConsumerKey>0zMKpm0nFt9682b b d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate> T14:52: :00</PurchaseDate> <TransactionStatus>Success</TransactionStatus> <ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-7</PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> </MerchantTransactions> </MerchantTransactions> MerchantTransactionsML Details MerchantTransactionsRequest Element Description Type MerchantTransactions MerchantTransactions MerchantTransactions ML - ExtensionPoint TransactionID ConsumerKey Currency OrderAmount PurchaseDate TransactionStatus ApprovalCode PreCheckoutTransactionId ExpressCheckoutIndicator ExtensionPoint Reserved for future enhancement. Optional Uses the TransactionID element of the Checkout ML 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 US Dollars. (Integer) Transaction order amount without decimal e.g Date and Time of the shopping cart purchase. State of the transaction. Indicates whether successful. Valid values are Success or Failure. Approval code returned by payment API. Value returned from the PrecheckoutData call. True or False. Set to false for connected checkout Reserved for future enhancement. Optional Any - Min - Max String String 97 String 3 Integer 1-12 Date String 7 String 6 String Boolean Any - ML format MerchantTransactionsResponse Element Description Type Min - Max 95

96 MerchantTransactions MerchantTransactions Root Element ML - MerchantTransactions ExtensionPoint TransactionID ConsumerKey Currency OrderAmount PurchaseDate TransactionStatus ApprovalCode PreCheckoutTransactionId ExpressCheckoutIndicator ExtensionPoint Reserved for future enhancement. Optional Uses the TransactionID element of the Checkout ML 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 US Dollars. Integer Transaction order amount without decimal e.g Date and Time of the shopping cart purchase e.g T15:12: :00 State of the transaction. Indicates whether successful. Valid values are Success or Failure. Approval code returned by payment API. Value returned from the PrecheckoutData call. True or False. Set to false for connected checkout Reserved for future enhancement. Optional Any - String String 97 String 3 Integer 1-12 Date String 7 String 6 String Boolean Any - ML format 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 ML 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> 96

97 <f:anothersamplefield>sample Value</f:AnotherSampleField> </f:samplecontainer> </f:anotherexampleextension> </ExtensionPoint> Developer Zone Key Renewal Process Login to MasterCard s Developer Zone ( click My Account, then My Dashboard. On the My Dashboard page, click My Keys button, select the key you want to renew and then click on Renew Key button. In order to renew the API Key, you need to supply a PEM encoded Certificate Request File. Choose the file, and click Submit. Notice the updated Key ID expiry date. 97

98 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), otherwise calls to MasterPass services will fail. Developer Zone Key Tool Utility From the Add a Key screen, click Click Here, to launch the Key Tool utility. Click on Generate Keys and CSR and then click on Save to Files. Next screen will prompt you to select the password. 98