MasterPass Service Provider Onboarding & Integration Guide Fileand API-Based Merchant Onboarding Version 6.10

Transcription

1 MasterPass Service Provider Onboarding & Integration Guide Fileand API-Based Merchant Onboarding Version January 2016 SPBM

2 Summary of Changes, 7 January 2016 Summary of Changes, 7 January 2016 This document reflects changes made since the previous publication. To locate these changes online, click the hyperlinks in the following table. Description of Change Updated the MerchantInitializationRequest with DSRP Extension Points V6 XML Details table to indicate that the UnpredictableNumber element contains a maximum of eight characters. Updated the Checkout XML DSRP Details table to indicate that the UnpredictableNumber element contains a maximum of eight characters. Removed the first two paragraphs from the 3-D Secure Considerations section. Updated the Mobile Checkout subsection of the Further Information Related to DSRP section to indicate that the MasterPass Mobile Checkout product is currently available only in certain countries. Where to Look DSRP Extension Points in the MasterPass Merchant API DSRP Extension Points in the MasterPass Checkout XML 3-D Secure Considerations MasterPass Mobile Checkout Onboarding Version January

3 Contents Contents Summary of Changes, 7 January Chapter 1: Overview... 6 MasterPass File-Based Onboarding... 7 MasterPass API-Based Onboarding... 7 How does MasterPass Work?... 7 MasterPass User Interface... 7 Chapter 2: MasterPass Checkout Experiences...12 Overview...13 MasterPass Standard Checkout Process Flow Chapter 3: Service Provider File- and API-Based Onboarding Models...20 Incorporating MasterPass into Your Site or App Service Providers New to MasterPass: Start Here Service Providers with an Existing MasterPass Relationship Open Feed to Production Checkout Project...24 Chapter 4: Service Provider File-Based and API-Based Onboarding Steps Service Provider Registration and Setup Service Provider Activity Auto Approval Add Developer to Service Provider Profile Service Provider Activity Developer Registration Developer Activity MasterPass Merchant Portal and Developer Account...35 MasterCard Developer Zone Account...36 Generate MasterCard Developer Zone API Keys Initiate Development Request Sandbox Credentials Developer Activity Create Checkout Project File-Based Onboarding...43 Generate Merchant Files...44 How to Validate Merchant Files before Submitting...44 How to Upload Merchant Files to Production Submit Checkout Project for Sandbox Approval Review Integration Project and Sandbox Approval Service Provider Activity Onboarding Version January

4 Contents 6. Access Sandbox Credentials, Complete Development and Test Developer Activity Access Sandbox Details Request Production Credentials Developer Activity Review Integration Project and Production Approval Service Provider Activity Deploy Application Using Production Credentials Developer Activity Single-Merchant API Setup Set Auto Approval Service Provider Activity Use Open Feed to Production Checkout Project Service Provider Activity Upload Merchant Record to Open Feed Checkout Project System Activity Validate Merchant API Service...60 Chapter 5: Integration Process...61 Lightbox Integration...62 MasterPass Lightbox Callback Values...62 Standard checkout Invoke MasterPass UI (Lightbox)...63 Standard Checkout Callback...64 DSRP and Tokenization MasterPass Service Descriptions Android and ios App Integration...82 Chapter 6: MasterPass Branding...84 Displaying Buy with MasterPass Button and Acceptance Marks Buy With MasterPass Button Example MasterPass Checkout Images...86 Displaying the Connect with MasterPass Button Connect with MasterPass Button Example Connect with MasterPass Image Files...88 MasterPass Learn More Page...88 Chapter 7: Testing...89 MasterPass Sandbox Testing Q/A Checklist Checklist for MasterPass Asset Placement In-Wallet Experience Post Wallet Experience...94 Postback...95 General Onboarding Version January

5 Contents Chapter 8: Troubleshooting...96 Common Errors...97 Support...97 Appendix A: Appendix...99 Lightbox Parameters OAuth Samples Request Token Merchant Initialization Service Shopping Cart Service Access Token Service Checkout Resource Postback Service File-Based Merchant Onboarding Merchant Upload Schema Merchant Download Schema MasterCard Open API Gateway Service API-Based Merchant Onboarding Single-Merchant API Service Overview D Secure Status Renew Your Developer Zone Key Developer Zone Key Tool Utility D Secure Overview D Secure Service Description General Overview of MasterCard SecureCode and Verified by Visa Transaction Authentication Important Merchant Information Validation Error Messages Notices Onboarding Version January

6 Overview Chapter 1 Overview This guide is intended for service providers who would like to use the MasterPass File-Based Onboarding or MasterPass API-Based Onboarding methods. MasterPass File-Based Onboarding... 7 MasterPass API-Based Onboarding... 7 How does MasterPass Work?... 7 MasterPass User Interface...7 Standard Lightbox Display (desktop and laptop)...8 Standard Mobile Display (.mobi)... 9 Standard Full Screen Display...10 Onboarding Version January

7 Overview MasterPass File-Based Onboarding MasterPass File-Based Onboarding This onboarding method allows the service providers to upload a file with merchant records through the MasterPass Merchant and Service Provider portal. Service providers can use this onboarding mechanism to add merchants, update merchants, or delete merchant records on the MasterPass platform. Once the file is successfully processed by MasterPass, the result file is available for the service provider to download. MasterPass API-Based Onboarding At this time, a Single-Merchant API is available for merchant onboarding. This onboarding method allows to onboard a single merchant to MasterPass in real time. This API can be used to complete the following tasks: Add an individual merchant to MasterPass. Update an individual, existing MasterPass merchant record. Delete an individual merchant record from MasterPass. MasterPass then provides a real-time response to the API. How does MasterPass Work? MasterPass is a service that enables consumers to store, manage and securely share their payment information, shipping information, billing address, and rewards information with the websites and mobile apps they transact with. MasterPass supports checkout on full and mobile websites, as well as in-app purchases on Android and ios apps. MasterPass User Interface The MasterPass user interface, or Lightbox, floats the MasterPass wallet interface on top of the merchant s web page through illuminated overlays, and backgrounds dimmed to 0.7 opacity. This modern method allows a consumer to interact with their MasterPass digital wallet without having to leave the merchant s page. The MasterPass Lightbox is built in a Onboarding Version January

8 Overview How does MasterPass Work? responsive design style allowing it to respond dynamically to the various screen sizes and orientations. MasterPass supports the following displays: Standard Lightbox Standard Full Screen Standard Lightbox Display (desktop and laptop) At full screen, where the browser is set to 100% height and width, the overall Lightbox dimensions are 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 (for example, phones and smaller tablets). There is a 320 pixel width threshold for the content container. Onboarding Version January

9 Overview How does MasterPass Work? 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. The mobile interface fills the screen and does not use modal windows such as the Lightbox display. Onboarding Version January

10 Overview How does MasterPass Work? Standard Full Screen Display Under certain conditions (such as [a] when the consumer s browser does not support the Lightbox display [older browser], [b] if the merchant has not yet made coding changes to invoke the Lightbox display, or [c] if the URL requesting the Lightbox display is different from the merchant-specified origin URL), 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. Onboarding Version January

11 Overview How does MasterPass Work? Onboarding Version January

12 MasterPass Checkout Experiences Chapter 2 MasterPass Checkout Experiences This section provides information on the MasterPass checkout experiences. Overview MasterPass Standard Checkout Process Flow...13 Onboarding Version January

13 MasterPass Checkout Experiences Overview Overview The following table depicts the steps involved in the standard MasterPass checkout experience. MasterPass Standard Checkout Process Flow This topic provides information on the standard checkout process flow using the MasterPass user interface or Lightbox where the merchant integrates with MasterPass through the service provider. Merchant initiates the MasterPass user interface but does not receive consumer s PAN. The merchant must use this process flow for a non-registered (guest) user. Standard Checkout User Flow The following steps explain the standard MasterPass checkout process flow that the merchant must use for a non-registered (guest) user on their site: NOTE: The product images in the following screenshots are blurred for trademark reasons. 1. The consumer clicks the Buy with MasterPass button. Onboarding Version January

14 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow 2. The consumer logs in to their wallet. Onboarding Version January

15 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow 3. The consumer selects their payment method and shipping address. Onboarding Version January

16 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow 4. The consumer reviews and submits the order. Onboarding Version January

17 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow 5. The merchant confirms the order. Onboarding Version January

18 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow The following diagram illustrates the MasterPass merchants standard checkout process flow for registered users: Onboarding Version January

19 MasterPass Checkout Experiences MasterPass Standard Checkout Process Flow Onboarding Version January

20 Service Provider File- and API-Based Onboarding Models Chapter 3 Service Provider File- and API-Based Onboarding Models This section provides information on the File- and API-Based Onboarding models that are available to service providers. Incorporating MasterPass into Your Site or App...21 Service Providers New to MasterPass: Start Here Service Providers with an Existing MasterPass Relationship...24 Open Feed to Production Checkout Project...24 Onboarding Version January

21 Service Provider File- and API-Based Onboarding Models Incorporating MasterPass into Your Site or App Incorporating MasterPass into Your Site or App Enabling checkout with MasterPass on behalf of your merchant site or mobile app is straightforward here are the required activities for service providers who would like to use the File-based or API-based methods for onboarding merchants. File-Based Onboarding Under this onboarding method, service providers upload a file with merchant profile records through the MasterPass Merchant Portal. Service providers can onboard merchants by uploading file(s) containing multiple merchant records. Service providers will access the MasterPass Merchant Portal to enroll and provision their merchants to MasterPass. The File-based onboarding method must be used by service providers who will be onboarding a large number of merchants and can generate XML formatted files(s) with the required information for multiple merchants. This process allows multiple merchant profiles to be set up at the same time rather than manually creating a MasterPass account for each merchant. No Merchant interaction with MasterPass is required in this onboarding method. Service provider's developers will create checkout projects and the service provider approves the checkout projects. Service providers can also enable Auto Approval for each developer to avoid having to approve each and every checkout project by that developer. Service providers can use File-based onboarding method to add merchants, update merchants, or delete merchant records on the MasterPass platform. Once the file is successfully processed by MasterPass, the result file is available for the service provider to download. API-Based Onboarding MasterPass service providers may use a Single-Merchant API to onboard merchant records to MasterPass. Single-Merchant API Service The Single-Merchant API can be used by service providers to onboard merchant records one at a time, in real time, to MasterPass. This method is best suited for service providers that want to onboard merchants in real time from their system to MasterPass without any manual intervention. No merchant interaction with MasterPass is required in this onboarding method. By using the API, service provider developers do not have to create multiple checkout projects for onboarding merchants. An Open Feed checkout project is available for service providers using the API that can be used for ongoing submission of merchant records to MasterPass. Benefits of the Single-Merchant API Service Service providers may onboard merchants one at a time through the web service in a request/response model. Onboarding Version January

22 Service Provider File- and API-Based Onboarding Models Incorporating MasterPass into Your Site or App Service providers may retrieve a real-time status of their onboarding request through the web service. Service Providers New to MasterPass: Start Here This section explains on how the new service providers can create their realationship with MasterPass. All new service providers that have not onboarded merchants, using either File- or API-based onboarding, must complete steps 1 9 that are summarized in the table below. By completing these steps, you create your relationship with MasterPass and have onboarded an initial set of merchants. Detailed instructions for steps 1 9 can be found here, or click on the links within the table below. At the successful completion of step 9, you will have a Checkout Project that has been approved for production and at least one merchant in the MasterPass system. At this point, the Service Provider is considered existing in the MasterPass system. Activity Actor Steps Environment 1. Service Provider Registration and Setup Service Provider Create Service Provider account and create shipping profile MasterPass Merchant Portal Onboarding Version January

23 Service Provider File- and API-Based Onboarding Models Incorporating MasterPass into Your Site or App Activity Actor Steps Environment 2. Add Developer to Service Provider Profile 3. Developer Registration 4. Request Sandbox Credentials 5. Review Integration Project & Approval 6. Access Sandbox Credentials 7. Request Production Credentials 8. Review Integration Project & Approval Service Provider Developer Developer Service Provider Business Owner Developer Developer Service Provider Business Owner Add Developer to Service Provider Profile Create MasterPass Developer account Create Developer Zone account Generate developer s sandbox and production keys Review sample code/sdk and design services integration MasterPass Merchant Portal MasterPass Merchant Portal MasterCard Developer Zone Create Checkout Project MasterPass Merchant Portal Obtain details for merchant(s) and generate merchant upload file(s). Select merchant file(s), Upload and Review results from the Download Merchant File. Submit Checkout Project for sandbox approval. Approve sandbox credentials. Obtain checkout IDs for each successfully provisioned merchant. Map each checkout Id to the correct merchant. Test against MasterPass sandbox environment Submit Checkout Project for production approval Approve production credentials Service Provider Engineering Environment MasterPass Merchant Portal MasterPass Merchant Portal MasterPass Merchant Portal MasterPass Merchant Portal Service Provider Engineering Environment MasterPass Merchant Portal MasterPass Merchant Portal Onboarding Version January

24 Service Provider File- and API-Based Onboarding Models Incorporating MasterPass into Your Site or App Activity Actor Steps Environment 9. Production Migration Developer Update MasterPass API endpoints, Consumer key, Callback URL and Private Key (.p12 file), if different than Sandbox. Service Provider Production Environment Service Providers with an Existing MasterPass Relationship This section explains on how the existing service providers can change the merchant onboarding mechanism. Existing service providers that are using the File-Based Onboarding method and would like to use the Single-Merchant API may skip to the Single-Merchant API Service section. Existing service providers have two options for adding, updating and deleting Merchants in the MasterPass system: Use File-Based Onboarding via the MasterPass Merchant Portal user interface to upload XML file(s). In other words, you can always choose to simply follow steps 4 9 in the preceding table to add, update, or delete merchants. Use Single-Merchant API service to upload the XML file containing a single merchant record, which is explained in the following section. Follow steps to set up the Single- Merchant API service for your account. Once a service provider has at least one checkout project approved to production (step 8), they may choose to activate the Single-Merchant API service. Open Feed to Production Checkout Project Service providers using the Single-Merchant API service can use the Open Feed to Production Checkout Project to submit merchant records to MasterPass. The Open Feed to Production Checkout Project has the advantage over a standard checkout project which allows continuous submissions of merchant records for the desired action (add/update/delete) directly to the production environment. To create the Open Feed to Production Checkout Project, complete the following steps: Activity Actor Steps Environment 10. Set Auto Approval Service Provider Business Owner Check Enable Auto Approval Checkbox MasterPass Merchant Portal 11. Use Open Feed to Production Checkout Project Service Provider Business Owner Check Use Open Feed to Production Checkout Project (Auto Approval must be enabled, step 10) MasterPass Merchant Portal Onboarding Version January

25 Service Provider File- and API-Based Onboarding Models Incorporating MasterPass into Your Site or App Activity Actor Steps Environment 12. Send XML to Open Feed Project Developer Send a single merchant record in XML format via the Single-Merchant API service using the Checkout Project ID of the Open Feed Project and the production consumer key, which can be obtained from one of the previous production approved checkout projects on the Merchant Portal. Upload XML via API XML flows automatically to Approved for Production, step 9. Service Provider 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 Service Provider business owner. This ID should be used to login at masterpass.com/sp/merchant/ Home Go here to create Service Provider account, invite developers, create shipping profiles, approve checkout projects, and so on. Userid: Onboarding Version January

26 Service Provider File- and API-Based Onboarding Models Incorporating MasterPass into Your Site or App Account Type Details Account Info Merchant Portal - Developer Account(s) Developer Zone - Developer Account(s) Created when a service provider invites a developer. It is a system generated user ID. This ID should be used to login at masterpass.com/sp/merchant/ Home Go here to create checkout project, upload merchant files, get checkout project details, and so on. Created by developer and is used for key exchange. This ID should be used to login at developer.mastercard.com Go here to perform key exchange, download SDKs and Sample Application, Integration Guides and to access FAQs, and so on. Userid: Userid: By the end of the integration, your site or mobile app must be able to: 1. Display Buy with MasterPass button and the Learn More link at the start of the checkout experience. 2. Invoke and display the MasterPass Lightbox. 3. Relay MasterPass checkout requests to the MasterPass service. 4. Receive consumer s billing, shipping address, and rewards data from MasterPass service. 5. Process card, shipping, and rewards information using existing checkout process. NOTE: Your implementation must satisfy all criteria in the Q/A Checklist. Onboarding Version January

27 Service Provider File-Based and API-Based Onboarding Steps Chapter 4 Service Provider File-Based and API-Based Onboarding Steps This topic provides information on the service provider File-based and API-based onboarding steps to be followed. 1. Service Provider Registration and Setup Service Provider Activity Auto Approval Add Developer to Service Provider Profile Service Provider Activity Developer Registration Developer Activity...35 MasterPass Merchant Portal and Developer Account MasterCard Developer Zone Account Generate MasterCard Developer Zone API Keys...37 Generate MasterCard Developer Zone API Key for Sandbox Environment...37 Generate MasterCard Developer Zone API Key for Production Environment Initiate Development Request Sandbox Credentials Developer Activity...42 Create Checkout Project...42 File-Based Onboarding Generate Merchant Files...44 How to Validate Merchant Files before Submitting...44 How to Upload Merchant Files to Production...47 Submit Checkout Project for Sandbox Approval Review Integration Project and Sandbox Approval Service Provider Activity Access Sandbox Credentials, Complete Development and Test Developer Activity...51 Access Sandbox Details Request Production Credentials Developer Activity Review Integration Project and Production Approval Service Provider Activity Deploy Application Using Production Credentials Developer Activity Single-Merchant API Setup Set Auto Approval Service Provider Activity Use Open Feed to Production Checkout Project Service Provider Activity Upload Merchant Record to Open Feed Checkout Project System Activity...59 Validate Merchant API Service Onboarding Version January

28 Service Provider File-Based and API-Based Onboarding Steps 1. Service Provider Registration and Setup Service Provider Activity 1. Service Provider Registration and Setup Service Provider Activity Before beginning this process, request an invitation code from your MasterCard representative; this will grant you access and allow you to register as a service provider within the merchant portal. About this task Procedure 1. From the MasterPass Merchant Portal, select the country language from the dropdown and click the Create an Account button. You will be presented with a modal window, into which you will enter the invitation code. NOTE: Service provider invitation codes should begin with the prefix SP. You will be presented with a modal window. 2. Enter the invitation code into the Create A MasterPass Account window. NOTE: Service provider invitation codes should begin with the prefix SP. Onboarding Version January

29 Service Provider File-Based and API-Based Onboarding Steps 1. Service Provider Registration and Setup Service Provider Activity After entering the invitation code, you will be presented with the option to select the registration type. 3. Select Service Provider and click the Continue button. If you need to register as a merchant, access the MasterPass Merchant Onboarding & Integration Guide. 4. Complete all of the required fields in the Enter Account Information screen. Onboarding Version January

30 Service Provider File-Based and API-Based Onboarding Steps 1. Service Provider Registration and Setup Service Provider Activity 5. In the Enter Security Information screen, choose your security questions and enter the answers. 6. Complete all of the required fields in the Enter Business Information screen. Onboarding Version January

31 Service Provider File-Based and API-Based Onboarding Steps 1. Service Provider Registration and Setup Service Provider Activity At this point, you will have created a service provider account. 7. After your account is created, select Shipping Profiles to manage shipping for your merchants. Service providers that have onboarded at least one merchant must have at least one shipping profile (and no more than 25). NOTE: The following module will appear with a different graphical design than others, as the Masterpass merchant portal is being redesigned on a module-by-module basis. Onboarding Version January

32 Service Provider File-Based and API-Based Onboarding Steps 1. Service Provider Registration and Setup Service Provider Activity 8. Service providers may set a default shipping profile for their merchants. Onboarding Version January

33 Service Provider File-Based and API-Based Onboarding Steps 2. Add Developer to Service Provider Profile Service Provider Activity Auto Approval The Service provider business owner has an option to Enable Auto Approval of checkout projects. This feature allows service providers to determine if they wish to have a checkpoint/audit step prior to having merchants setup in sandbox and production or not. Once enabled, subsequent projects submitted by the developer using the same credentials do not need business owner approval prior to sandbox and production deployment. Any changes made to the project are effective immediately. To enable Auto Approval, click Account Settings from the top navigation bar and click on the Enable Auto Approval checkbox. 2. Add Developer to Service Provider Profile Service Provider Activity The next step is to add developers who will integrate MasterPass into the checkout flow. About this task From the landing page, you will add developers to the service provider profile. These developers will handle the technical implementation of MasterPass. Onboarding Version January

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

35 Service Provider File-Based and API-Based Onboarding Steps 3. Developer Registration Developer Activity Results MasterPass will send two separate s to each newly added developer indicating that he/she has been invited to handle the technical integration of MasterPass on-behalf of your company. These s will contain the username and password to log in to the MasterPass Merchant Portal. Invitation s sent to the developer will contain links to the MasterPass integration guides that developers can use to get started with MasterPass integration. 3. Developer Registration Developer Activity Developers invited to integrate MasterPass on behalf of a service provider will manage their integration activities through following portals. MasterPass Merchant Portal ( MasterCard Developer Zone ( NOTE: These are two different websites that use different login credentials. If you are a new developer for MasterPass, you must sign up for a new account on Developer Zone. MasterPass Merchant Portal and 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 service provider 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. You will find links to the MasterPass integration documentation in the invitation s you receive from MasterPass and on the landing page once you sign in to your Developer account on the MasterPass Merchant Portal. You do not need a Developer Zone Account to access and view this documentation. Onboarding Version January

36 Service Provider File-Based and API-Based Onboarding Steps 3. Developer Registration Developer Activity MasterCard Developer Zone Account Developers invited to integrate MasterPass on behalf of a service provider will use MasterCard Developer Zone to view integration documentation and generate developer keys. Click on Start This Step to go to the Developer Zone. If you do not have the MasterPass Merchant Portal open, simply go to To create a Developer Zone account, click Register. Complete and submit the registration form. Onboarding Version January

37 Service Provider File-Based and API-Based Onboarding Steps 3. Developer Registration Developer Activity After submitting the form, you will receive a confirmation . Activate the account using this confirmation . Generate MasterCard Developer Zone API Keys After creating your account, you will need to generate two API keys: one for the sandbox environment and one for the production environment. Generate MasterCard Developer Zone API Key for Sandbox Environment To create an API key for the sandbox environment, complete the following steps. About this task To make keys easy to distinguish, it is recommended to prefix sandbox keys with "SBX_". Procedure 1. Click My Account, then My Dashboard. Onboarding Version January

38 Service Provider File-Based and API-Based Onboarding Steps 3. Developer Registration Developer Activity 2. On the My Dashboard page, select the My Keys tab and click on the Add a Key button. 3. To get an API Key, you need to supply a PEM encoded Certificate Request File. You may use a tool of your choice, such as "openssl" or Java's "keytool" to generate this CSR, or you may use the CSR generation tool. Click here to see instructions for using CSR generation tool. 4. Complete the form, select Sandbox for Environment, and click Submit. Onboarding Version January

39 Service Provider File-Based and API-Based Onboarding Steps 3. Developer Registration Developer Activity Results You will have a Sandbox Key ID at this point. Onboarding Version January

40 Service Provider File-Based and API-Based Onboarding Steps 3. Developer Registration Developer Activity NOTE: Keys expire after one year before which they should be renewed by initiating the Developer Zone Key Renewal process. The Certificate Request File initially submitted for the key creation will be needed to renew the key. Notifications at 30, 15, and one day prior to key expiration will be sent to the address associated with the Developer Zone account. 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. Generate MasterCard Developer Zone API Key for Production Environment To create an API key for the production environment, complete the following steps. About this task To make keys easy to distinguish, it is recommended to prefix production keys with "PRD_". Procedure 1. Click My Account, then My Dashboard. 2. On the My Dashboard page, select the My Keys tab and click on the Add a Key button. 3. Complete the form, select Production for Environment, and click Submit. Results At this point, developers will have a Sandbox Key ID and a Production Key ID, which will be used when creating a checkout project in the MasterPass Merchant Portal. Onboarding Version January

41 Service Provider File-Based and API-Based Onboarding Steps 3. Developer Registration Developer Activity NOTE: Keys expire after one year before which they should be renewed by initiating the Developer Zone Key Renewal process. The Certificate Request File initially submitted for the key creation will be needed to renew the key. Notifications at 30, 15, and one day prior to key expiration will be sent to the address associated with the Developer Zone account. 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 C#.NET, Java, PHP, and Ruby will be made available for download from the Sample Code tab in the Developer Zone. Contact MasterPass Support if the sample applications are not available in the language you need. MasterPass follows the OAuth 1.0a specification. Any merchant or Service Provider integrating with MasterPass must strictly adhere to the OAuth specs for interacting with MasterPass through Open API Gateway. Failure to implement OAuth correctly may impact your integration and transactions with MasterPass. For more details, refer to the Authentication page on the Developer Zone. Onboarding Version January

42 Service Provider File-Based and API-Based Onboarding Steps 4. Request Sandbox Credentials Developer Activity 4. Request Sandbox Credentials Developer Activity Prior to allowing the developer s code to interact with MasterPass, the project must be approved by the service provider business owner. The developer will submit the following requests: Request to grant the developer with access to credentials that will enable his/her code to transact with the MasterPass sandbox environment on behalf of the merchant. NOTE: The sandbox environment does not contain real consumer data. Request 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. Create Checkout Project The following process explains on how to create checkout projects. Procedure 1. To get started, sign into the MasterPass Merchant Portal. 2. Under Manage Development, click Checkout Projects and click the Create New Project button. 3. Complete the New Project creation wizard. 4. If you are a service provider developer uploading the files containing several merchant records, choose the File or API based Merchant Onboarding option in the Create Checkout Project window. 5. Enter the Project Name and Project Description. Enter the sandbox and production Key IDs that were created from MasterCard Developer Zone. Onboarding Version January

43 Service Provider File-Based and API-Based Onboarding Steps 4. Request Sandbox Credentials Developer Activity Results File-Based Onboarding Service providers can associate multiple merchant profiles to a checkout project all at once using a merchant upload file. The first step in this process is to obtain the Merchant Upload File template referenced in the Appendix. Service providers must gather the details for each merchant. Onboarding Version January

44 Service Provider File-Based and API-Based Onboarding Steps 4. Request Sandbox Credentials Developer Activity Generate Merchant Files Once the merchant details are available, the developer must create the file(s) to upload. The size of the file being upload cannot be more than 10 MB. For best results, try not to exceed 1,000 merchant records in a file. If you want to upload more than 1,000 merchants, consider creating multiple files to upload at the same time or as part of a new checkout project. How to Validate Merchant Files before Submitting Complete these steps to verify your file submission for schema and business rules validation before uploading. Procedure 1. Go to the Checkout Projects page and click the Validate File button. 2. Click the Choose File button. Onboarding Version January

45 Service Provider File-Based and API-Based Onboarding Steps 4. Request Sandbox Credentials Developer Activity 3. Select the file you want to validate and click the Validate Now button. The system will validate your file against business and XML schema rules. If your file does not meet either one of these sets of rules, you will receive an error message (as in the screenshot below) and must repair the error. To see the cause of the validation error, click the Download Result File button. Onboarding Version January

46 Service Provider File-Based and API-Based Onboarding Steps 4. Request Sandbox Credentials Developer Activity The XML file you download will contain the error message. Once your file meets both the XML schema and business rules, you (a) will receive a result file with an ErrorText status of Successful (as in the following screenshot) and (b) are ready to upload the file to MasterPass. The following is a sample of a successful XML validation. Onboarding Version January

47 Service Provider File-Based and API-Based Onboarding Steps 4. Request Sandbox Credentials Developer Activity How to Upload Merchant Files to Production Once the merchant files have been generated and the merchant is ready to upload files to MasterPass, complete the following steps to initiate the File-Based Onboarding process. Procedure 1. Click the Upload button. 2. Click the Choose File button to select the merchant files. 3. Enter a description of the merchant file and click the Upload button. Onboarding Version January

48 Service Provider File-Based and API-Based Onboarding Steps 4. Request Sandbox Credentials Developer Activity A message will display indicating the processing has finished and the number of records processed successes and failures. The service provider account owner will still need to approve the successfully processed merchants before they will be able to process transactions. You will also get an when the file processing is complete. 4. Once the processing is complete, click the Download Result File button to view the results of the upload process. Onboarding Version January

49 Service Provider File-Based and API-Based Onboarding Steps 4. Request Sandbox Credentials Developer Activity Any merchant records that fail processing will need to be reviewed, corrected, and submitted for processing. A sample Download Result File is available in the appendix. Submit Checkout Project for Sandbox Approval After creating the checkout project but before submission, the developer can edit the file to modify previously-entered information. To submit the project for sandbox approval, click Submit. This will kick-off the Checkout Project Approval Process. NOTE: Once the checkout project is submitted/approved, it cannot be deleted. Onboarding Version January

50 Service Provider File-Based and API-Based Onboarding Steps 5. Review Integration Project and Sandbox Approval Service Provider Activity NOTE: If Auto Approval has been enabled by the business owner for a developer, sandbox and production credentials will be generated at this time and steps 5 8 will be skipped. Once Auto Approval has been enabled for a developer, subsequent projects that they submit using the same credentials do not need business owner approval prior to sandbox and production deployment. Any changes made to the project are effective immediately. 5. Review Integration Project and Sandbox Approval Service Provider Activity After the Developer submits the request for sandbox credentials, the Service Provider Business Owner will get an notification. NOTE: Skip if Auto Approval is enabled. The Service Provider Business Owner logs on to the MasterPass Merchant Portal, reviews and provides approval. After clicking Approval Requests on the navigation bar, the user will see a list of open requests. The user will be presented with the option to either Approve or Reject the project. Users can also view processing results by clicking on Download Result File button or download the uploaded file by clicking on Download Merchant File. If rejected, a reason must be provided, and the developer will be allowed to modify the entry and resubmit. Onboarding Version January

51 Service Provider File-Based and API-Based Onboarding Steps 6. Access Sandbox Credentials, Complete Development and Test Developer Activity Upon approval, the developer will receive an containing the Consumer Key for the sandbox environment. Developers will be able to sign into the MasterPass Merchant Portal and access credentials necessary to develop and test their MasterPass implementation in the sandbox environment. 6. Access Sandbox Credentials, Complete Development and Test Developer Activity This section explains the developer's activity to access sandbox credentials, complete development, and test. NOTE: Skip if Auto Approval is enabled. Access Sandbox Details After signing into the portal, the developer will click the Action Required button associated with the entry, and note the Sandbox Consumer Key. For each successfully uploaded merchant, developers will obtain the checkout identifiers from the result file and map to the correct merchant. These will be used in the code to call MasterPass web services. Refer to MasterCard Developer Zone for sample code and SDKs. Onboarding Version January

52 Service Provider File-Based and API-Based Onboarding Steps 7. Request Production Credentials Developer Activity 7. Request Production Credentials Developer Activity Once the application has been tested against sandbox, the developer requests the production credential. NOTE: Skip if Auto Approval is enabled. This is done by submitting the checkout project created in Step 4 and submitting it again for approval. Onboarding Version January

53 Service Provider File-Based and API-Based Onboarding Steps 7. Request Production Credentials Developer Activity Onboarding Version January

54 Service Provider File-Based and API-Based Onboarding Steps 8. Review Integration Project and Production Approval Service Provider Activity 8. Review Integration Project and Production Approval Service Provider Activity After the developer submits request for production credentials, the service provider business owner will get an notification. NOTE: Skip if Auto Approval is enabled. The business owner logs on to the MasterPass Merchant Portal, reviews and provides approval (similar to step 5). The user will be presented with the option to either Approve or Reject the project. Users can also view processing results by clicking on Download Result File button. If rejected, a reason must be provided, and the developer will be allowed to modify the entry and resubmit. Onboarding Version January

55 Service Provider File-Based and API-Based Onboarding Steps 9. Deploy Application Using Production Credentials Developer Activity 9. Deploy Application Using Production Credentials Developer Activity Once the application has been approved, the developer will receive an containing the production Consumer Key and will enable the Service Provider platform to transact with the MasterPass Services on-behalf of the Merchant. 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 API production endpoint, Consumer Key, Checkout Identifier and the private key if different than Sandbox. The last step is to deploy your code to production and you are done creating your checkout project. Onboarding Version January

56 Service Provider File-Based and API-Based Onboarding Steps Single-Merchant API Setup Single-Merchant API Setup Follow steps to setup the Single-Merchant API service. 10. Set Auto Approval Service Provider Activity Once the first checkout project has been completely approved for production, the Enable Auto Approval checkbox will be available in the Account Settings. About this task The Service Provider business owner has an option to enable auto approval of checkout projects, which must be done to use the API-based onboarding method. This feature allows service providers to determine if they wish to have a checkpoint/audit step prior to having merchants setup in sandbox and production or not. When auto approval is enabled, the system will automatically approve any submitted merchant profiles for both Sandbox and Production credentials. This is applicable to all developers associated with the account, and changes are effective immediately. Onboarding Version January

57 Service Provider File-Based and API-Based Onboarding Steps 10. Set Auto Approval Service Provider Activity Procedure 1. To enable auto approval, click Account Settings from the top navigation bar and click on the Enable Auto Approval check box. When the Enable Auto Approval checkbox is checked, the Use Open Feed to Production Checkout Project checkbox will be enabled. 2. Click Agree when prompted. Onboarding Version January

58 Service Provider File-Based and API-Based Onboarding Steps 11. Use Open Feed to Production Checkout Project Service Provider Activity 11. Use Open Feed to Production Checkout Project Service Provider Activity Service providers that want to use the Single-Merchant API service will need to create the Open Feed to Production checkout project by selecting the Use Open Feed to Production Checkout Project checkbox is selected for the first time. Procedure 1. To create the Open Feed to Production checkout project, click Account Settings from the top navigation bar and select the Use Open Feed to Production Checkout Project checkbox. 2. To view the newly created Open Feed to Production project, click Checkout Projects. Onboarding Version January

59 Service Provider File-Based and API-Based Onboarding Steps 12. Upload Merchant Record to Open Feed Checkout Project System Activity When the Use Open Feed to Production Checkout Project checkbox is unchecked, the Open Feed to Production project gets hidden in the user interface from the user, and any calls made to that project gets rejected. Selecting the Use Open Feed to Production Checkout Project checkbox again will unhide the Open Feed to Production project. 12. Upload Merchant Record to Open Feed Checkout Project System Activity The Open Feed to Production Project can only be used for onboarding via the API. NOTE: The Single-Merchant API has a size limit of 399K (409,600 bytes) and must be used for one merchant record at a time. The service provider system must be designed to send the XML containing details for a single merchant record, the Checkout Project ID and approved consumer key*, to the Open Feed to Production project through the Single-Merchant API service call. This will auto submit and push merchant adds/updates/deletes directly to Production. Refer to Single-Merchant API Upload for parameter details. *If you are a new service provider, then you first need to get a project approved all the way to production (steps 1 8 in the onboarding table) and you can use consumer keys of the first production approved checkout project. If you are an existing service provider, who has used the File-based onboarding, you can use the consumer key that is associated with any checkout project approved all the way to production that you have used onboard merchants using the File-based onboarding method. The API call to upload each merchant must be made using a production consumer key and the associated production developer Key ID credentials. The checkout project ID of the Open Feed project needs to be used in the API request URL. NOTE: Once MasterPass successfully processes the merchant record, the API will provide a response with the checkout identifier for the merchant. Onboarding Version January

60 Service Provider File-Based and API-Based Onboarding Steps 12. Upload Merchant Record to Open Feed Checkout Project System Activity Validate Merchant API Service Service providers may use an API service to verify their submission for schema and business rules validation before uploading merchant records to MasterPass via the onboarding API. To start the validation process via the Validation API service, the developer must call the API and send the XML containing the merchant record. If there are schema errors, the system indicates them. The errors must be corrected before the xml can be validated against the business rules. Once validation is complete if there are any errors, the API response indicate them, and if the XML contains no errors the API will provide a success response. The results of the validation are not stored by MasterPass and will not be available to service providers when they return, so they must save the results of the API response on their end which can be used to correct any errors with their submission. There are no limits on the number of times the validation API can be called for validating an XML. The validation API supports the same size of the onboarding API (399 KB), and only one merchant record may be submitted at a time via the validation API. The Validation API system will display an error message if the file is invalid. Refer to the Validation Error Messages section of the Appendix for a list and descriptions of the validation error messages. If the XML file is valid, the Validation API system sends a confirmation response indicating that the XML file was loaded successfully. Onboarding Version January

61 Integration Process Chapter 5 Integration Process This topic provides information on the MasterPass integration process. Lightbox Integration...62 MasterPass Lightbox Callback Values...62 Standard checkout...63 Invoke MasterPass UI (Lightbox)...63 Standard Checkout Callback Redirect to Merchant Callback URL Parameters for Standard Checkout Checkout Callback Method Example...65 DSRP and Tokenization Implementing DSRP Split/Partial Shipments and Recurring Payment Transactions D Secure Considerations...76 Testing DSRP...76 MasterPass Mobile Checkout MasterPass Service Descriptions...77 Request Token Service...77 Shopping Cart Service...77 Merchant Initialization Service...79 Access Token Service...79 Retrieve Payment, Shipping Data, Rewards and 3-D Secure Details...79 Postback Service Android and ios App Integration Onboarding Version January

62 Integration Process Lightbox Integration For a step-by-step guide through integration and illustration of the various calls to MasterPass, download code samples available in various languages such as Java, C#, PHP, and Ruby. You can also access the sample code for correct implementation of signature base string and exchanges with MasterPass on the Merchant Checkout Services Sample Code page. Lightbox Integration Lightbox integration is required to launch MasterPass user interface. To invoke the Lightbox, merchants must include the following scripts to the page on which they are adding the Buy with MasterPass or Connect with MasterPass buttons: It is recommended to pull the jquery file from the public jquery repository: ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js MasterPass Script NOTE: Only merchants invoking the Lightbox from an iframe must include the following scripts on the parent (outer) frame in addition to the iframe source that is invoking MasterPass Lightbox: Production: MasterPass.client.js Sandbox: MasterPass.client.js MasterPass Lightbox Callback Values MasterPass indicates to merchants the status of a flow through either a callback URL or javascript callback method. The available callback parameters are as follows. successcallback This parameter (a) defines the function to be called when the flow ends in success and (b) requires the failurecallback parameter to function. failurecallback This parameter (a) defines the function to be called when the flow ends in failure and (b) requires the successcallback parameter to function. cancelcallback This parameter (a) alerts a MasterPass merchant that a consumer has canceled their transaction and (b) is a standalone function that the merchant may optionally integrate. Onboarding Version January

63 Integration Process Standard checkout Standard checkout The following steps are necessary to integrate a standard MasterPass checkout. For more details, click on each of the following steps: 1. Request Token Service 2. Shopping Cart Service 3. Merchant Initialization Service (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 checkout 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":"merchant_checkout_id_here", "allowedcardtypes":["master,amex,diners,discover,maestro,visa"], "version":"v6" }); </script> The required parameters are as follows: requesttoken The merchant s request token from OpenAPI callbackurl The URL to which the browser must redirect when checkout is complete. This is required unless the merchant prefers to use the callback method. If a merchant uses callback methods, and MasterPass is forced to go fullscreen, MasterPass will redirect to the URL sent in the request token call when the flow is complete. merchantcheckoutid The merchant s unique checkout identifier from the MasterPass Merchant Portal allowedcardtypes Card types accepted by merchant version Checkout version (v6). Onboarding Version January

64 Integration Process Standard checkout Lightbox parameter details can be found here. Standard Checkout Callback Once a checkout is completed, MasterPass will return context to the merchant. This can be done via one of the following options: A callback URL: MasterPass uses the callback URL (oauth_callback) from the request token call to direct back to the merchant site when Lightbox is rendered in full screen mode. A javascript callback method: Use failurecallback and successcallback parameters to give control back to the page that initiated the Lightbox without any redirects. These parameters must be set when invoking MasterPass Lightbox UI. Use cancelcallback to notify a MasterPass merchant that a consumer has canceled their transaction. NOTE: If MasterPass is forced to go full screen, then you will not be able to call the javascript callback method and must use a merchant callback redirect. As a result, you must support both the callback method and the redirect. Javascript Callback Method Sample (with successcallback parameter) <script type="text/javascript" language="javascript"> MasterPass.client.checkout({ "requesttoken":"request_token_here", "callbackurl":" "successcallback": handlecallbacksuccess, "merchantcheckoutid":"merchant_checkout_id_here", "allowedcardtypes":["master,amex,diners,discover,maestro,visa"], "version":"v6" }); </script> Javascript Callback Method Sample (with failurecallback parameter) <script type="text/javascript" language="javascript"> MasterPass.client.checkout({ "requesttoken":"request_token_here", "callbackurl":" "failurecallback": handlecallbackfailure, "merchantcheckoutid":"merchant_checkout_id_here", "allowedcardtypes":["master,amex,diners,discover,maestro,visa"], "version":"v6" }); </script> Javascript Callback Method Sample (with cancelcallback parameter) <script type="text/javascript" language="javascript"> MasterPass.client.checkout({ "requesttoken":"request_token_here", "callbackurl":" "cancelcallback": handlecallbackcancel, "merchantcheckoutid":"merchant_checkout_id_here", "allowedcardtypes":["master,amex,diners,discover,maestro,visa"], "version":"v6" }); </script> Onboarding Version January

65 Integration Process Standard checkout Redirect to Merchant Callback URL Parameters for Standard Checkout Merchants must use the following data parameters to complete the MasterPass Standard Checkout flow. mpstatus Success, failure, or cancel. Indicates whether MasterPass flow was completed. oauth_token Used in concert with oauth_verifier to retrieve access token. oauth_verifier Used in concert with oauth_token to retrieve access token. checkout_resource_url API URL to retrieve checkout information. Following are examples of the redirect to merchant callback URLs when a transaction is successful or cancelled: Redirect to Merchant Callback URL Example for a Successful Transaction mpstatus=success&checkout_resource_url=https%3a%2f%2fsandbox.api.mastercard.com %2Fmasterpass %2Fv6%2Fcheckou t%2f %3fwallet %3Dphw&oauth_verifier=6c50838e31b7441e6eafa b13&oauth_token=d6fa aebb6183d44fb9688fb9dc8332dc Redirect to Merchant Callback URL Example for a Cancelled Transaction Checkout Callback Method Example The following is a sample of the checkout callback method. function onsuccessfulcheckout(data) { document.getelementbyid('oauthtoken').value=data.oauth_token; document.getelementbyid('oauthverifer').value=data.oauth_verifier; document.getelementbyid('checkouturl').value=data.checkout_resource_url; } DSRP and Tokenization MasterCard Cloud-Based Payments (MCBP), a software-based alternative to Secure Element (SE), was initially built to facilitate and secure face-to-face (contactless) transactions, and has been extended to facilitate and secure remote transactions via Digital Secure Remote Payment (DSRP). Upon successful cardholder verification, a DSRP-enabled wallet generates a cryptogram for the DSRP transaction and passes it to the merchant or service provider. The merchant or service provider submits the cryptogram with the authorization request to the issuer, which then validates the cryptogram to confirm that the request originated from a valid payment application for a verified cardholder. Onboarding Version January

66 Integration Process Standard checkout A DSRP cryptogram will be accompanied by a 16-digit token rather than the actual MasterCard card brand primary account number (PAN). For example, the MasterPass Mobile Checkout product will, in the case of a merchant app-to-wallet app or web-to-wallet app transaction, pass a MasterCard Digital Enablement Services (MDES) device-based token along with the DSRP cryptographic data in the checkout resources. In some cases in which a devicebased token is not generated, an MDES card-on-file token will be passed. Whenever a token is passed instead of the actual account number, the last four digits of the consumer s actual PAN will be passed in an extension point so that they can be displayed to the consumer if so desired. Implementing DSRP A MasterPass transaction must meet the following conditions to be processed as a Digital Secure Remote Payment (DSRP) transaction. The merchant or service provider must have successfully implemented MasterPass Merchant API version 6, including the merchant initialization call and the new DSRP and tokenization extension points. Systems must be in place to correctly identify authorizations for split/partial shipments and recurring payments so that the DSRP data is accurately processed for subsequent authorizations (for more information, refer to the section below). The payment gateway and acquirer must have successfully updated their interfaces to pass and receive DSRP data elements. MasterPass recommends that merchants or service providers contact their payment gateway(s) and acquirer(s) to: Understand the changes the acquirer is making to support DSRP. Identify any corresponding work that the merchants or service providers must complete. The consumer s card issuer/wallet provider must have successfully updated their interfaces to pass and receive DSRP data elements. The consumer has elected to pay with a card that has been digitized (for MasterPass Mobile Checkout transactions, this will be a MasterCard Digital Enablement Services [MDES]-enabled MasterCard brand card). If any of these conditions has not been met, the transaction will be considered a standard MasterPass transaction. DSRP Extension Points in the MasterPass Merchant API Merchants and service providers must use the merchant initialization call and the Digital Secure Remote Payment (DSRP) extension points in the MasterPass Merchant API version 6 to pass and receive DSRP data elements and values. MerchantInitializationRequest with DSRP Extension Points V6 XML Details Element Description Type Min Max MerchantInitializationRe quest Root Element XML Onboarding Version January

67 Integration Process Standard checkout Element Description Type Min Max MerchantInitializationRe quest.oauthtoken Request Token (oauth_token) returned by call to the request_token API MerchantInitializationRe quest.originurl Identifies the URL of the page that initializes the lightbox string NA MerchantInitializationRe quest.extensionpoint.ds RP.DSRPOptions.Option. BrandId MerchantInitializationRe quest.extensionpoint.ds RP.DSRPOptions.Option. AcceptanceType MerchantInitializationRe quest.extensionpoint.ds RP.UnpredictableNumbe r Required for DSRP transactions. Identifies the card brands for which DSRP is desired. Currently, the only valid card ID is: master Required for DSRP transactions. Indicates the type(s) of cryptograms the merchant or service provider can accept. Valid types are: UCAF and/or ICC (see descriptions that follow). MasterPass passes the most secure selection (ICC) if both acceptance types are indicated. Optional for DSRP transactions. EMVquality random number generated by the merchant, service provider, or if null by MasterPass and Base64 encoded string alpha 4-byte binary string 8 A cryptogram is the output of the process of transforming clear text into ciphertext for security or privacy. There are two forms in which the DSRP cryptograms may be generated and sent depending on the capabilities of the merchant, payment gateway, and acquirer systems: Onboarding Version January

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

69 Integration Process Standard checkout NOTE: The following example illustrates a case in which a merchant has chosen to generate the unpredictable number; if the UnpredictableNumber field is left null, MasterPass will generate the value on behalf of the merchant. <MerchantInitializationRequest> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <OriginUrl> <ExtensionPoint> <DSRP> <DSRPOptions> <Option> <BrandId>master</BrandId> <AcceptanceType>UCAF</AcceptanceType> </Option> </DSRPOptions> <UnpredictableNumber>413142==</UnpredictableNumber> </DSRP> </ExtensionPoint> </MerchantInitializationRequest> MerchantInitializationResponse Sample <MerchantInitializationResponse> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <ExtensionPoint> <UnpredictableNumber>413142==</UnpredictableNumber> </ExtensionPoint> <MerchantInitializationResponse> DSRP Extension Points in the MasterPass Checkout XML After a remote transaction has been facilitated and secured via Digital Secure Remote Payment (DSRP), the MasterPass wallet will generate a cryptogram that the merchant or service provider will receive in the Checkout XML. The "Checkout XML Sample with UCAF Cryptogram" illustrates a case in which a merchant or service provider has indicated that it can only receive a UCAF cryptogram. The "Checkout XML Sample with ICC Cryptogram" illustrates a case in which a merchant or service provider has indicated that it can receive (a) a UCAF or ICC or (b) an ICC crytogram. The elements shown in bold are elements that are impacted by the presence of a cryptogram. The AccountNumber element is a 16-digit, device-based token rather than the cardholder's actual card number. The ExpiryMonth and ExpiryYear elements indicate the expiration data of the provided token. The AuthenticateMethod element indicates that DSRP was the method utilized for this transaction. The DSRP ExtensionPoint elements are populated with the cryptogram, type, unpredictable number, and ECI flag. These extension points will usually be followed by token extension points described in more detail below. Checkout XML Sample with UCAF Cryptogram Received from URL: Onboarding Version January

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

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

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

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

74 Integration Process Standard checkout <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</line1> <Line2/> <Line3/> <PostalCode>63368</PostalCode> </BillingAddress> <CardHolderName>Jane Doe</CardHolderName> <ExpiryMonth>6</ExpiryMonth> <ExpiryYear>2017</ExpiryYear> </Card> <TransactionId> </TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <PhoneNumber> </PhoneNumber> </Contact> <ShippingAddress> <City>O fallon</city> <Country>US</Country> <CountrySubdivision>US-MO</CountrySubdivision> <Line1>4305 applerock dr</line1> <Line2/> <Line3/> <PostalCode>63368</PostalCode> <RecipientName>Jane Doe</RecipientName> <RecipientPhoneNumber>US </RecipientPhoneNumber> </ShippingAddress> <AuthenticationOptions> <AuthenticateMethod>DSRP</AuthenticateMethod> </AuthenticationOptions> <WalletID>208</WalletID> <PreCheckoutTransactionId>a4c411b-18h26t-icni2rol-1-ics6caee-123y</ PreCheckoutTransactionId> <ExtensionPoint> <DSRP> <DSRPData>Qwertyuio asdfghjklpois</DSRPData> <DSRPDataType>UCAF</DSRPDataType> <UnpredictableNumber>413142==</UnpredictableNumber> <Eci>02</Eci> </DSRP> <Tokenization> <FPanSuffix>1234</FPanSuffix> <TokenRequestorId> </TokenRequestorId> </Tokenization> <PaymentAccountReference> abcdefghijkl9</ PaymentAccountReference> </ExtensionPoint> </Checkout> Checkout XML Tokenization Details NOTE: For details on the remaining elements in XML, refer to the V6 Checkout XML Details table. Onboarding Version January

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

76 Integration Process Standard checkout Split/Partial Shipments and Recurring Payment Transactions Split/partial shipments occur when an e-commerce merchant or service provider ships several items in separate consignments (for example, if a portion of the purchased items are out of stock or items are shipping from separate locations). Recurring payments occur when a cardholder has authorized a merchant to bill the cardholder s account on a recurring basis (for example, monthly or quarterly). The amount of each payment may or may not be the same. Only the first authorization for split/partial or recurring payments associated with a Digital Secure Remote Payment (DSRP) transaction may contain cryptographic data. Merchants or service providers must not include the cryptogram with each subsequent authorization request. They must indicate (in DE 48, SE 42, position 3), however, that the subsequent authorizations are associated with a previous authorization that was cryptographically authenticated (by coding a value of 07 in position 3 rather than a value of 02 as mentioned in the Eci row of the Checkout XML DSRP Details table in the DSRP Extension Points in the MasterPass Merchant API section). 3-D Secure Considerations It is important to note that the MasterPass Mobile Checkout product that facilitates merchant app-to-wallet app transactions automatically suppresses 3-D Secure for Digital Secure Remote Payment (DSRP) transactions when it is called from within the MasterPass wallet. For more information about the Mobile Checkout product, refer to the MasterPass Mobile Checkout section. Testing DSRP For information on the tools that are currently available for testing Digital Secure Remote Payment (DSRP) implementation, send a message to the following address. merchant_testing_support@masterpass.com MasterPass Mobile Checkout In 2015, MasterCard extended the Digital Secure Remote Payment (DSRP) capability to support MasterPass through the Mobile Checkout product in certain countries to secure the purchases of goods and services from a merchant's Android app via a direct connection to a consumer's Android MasterPass wallet app. In the future, MasterPass plans to extend: Mobile Checkout to additional countries DSRP support to app-to-app transactions for ios devices and other payment scenarios such as website-to-mobile app wallet, mobile app-to-web wallet, and website-to-web wallet (as in, standard, browser-based MasterPass transactions) If Mobile Checkout is available in your country, refer to the Mobile Checkout Merchant Integration Guide and SDK found on the MasterPass - Merchant Android SDK page of the MasterCard Developer Zone. Onboarding Version January

77 Integration Process Standard checkout MasterPass Service Descriptions The following sections describe the different services offered by MasterPass. Request Token Service This must be executed when a consumer clicks Buy with MasterPass or Connect with MasterPass buttons on your site/app. For Pairing during checkout, this service will need to be called twice: To exchange for a long access token which is used to retrieve precheckout data To exchange for an Access Token which is used to retrieve checkout data Request and response parameter details can be found here. Sandbox and Production Endpoints for the Request Token Service The endpoints to be used for the Request Token Service are as follows. Shopping Cart Service Merchants must call the Shopping Cart service before invoking the MasterPass UI for checkout. This enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout. 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. Shopping cart request has an optional SecondaryOriginUrl field, if the merchant sets this. It is used only when the Lightbox will be invoked from a frame that is on a merchant site and when that frame is of a different domain than that of the merchant site, like for a service provider. NOTE: The product description needs to be HTML encoded and has a character limit of 100 characters. Onboarding Version January

78 Integration Process Standard checkout Sandbox and Production Endpoints for the Shopping Cart Service The endpoints to be used for the Shopping Cart Service are as follows. Onboarding Version January

79 Integration Process Standard checkout 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. Request and response parameter details can be found here. Sandbox and Production Endpoints for the Merchant Initialization Service The endpoints to be used for the Merchant Initialization Service are as follows. Access Token Service The next step is to exchange a request token for a long access token from the MasterPass service. You will need the Request Token (oauth_token) and Verifier (oauth_verifier) from the merchant callback to get an access token. Request and response parameter details can be found here. Sandbox and Production Endpoints for the Access Token Service The endpoints to be used for the Access Token Service are as follows. Retrieve Payment, Shipping Data, Rewards and 3-D Secure Details Now you will use the Checkout Resource URL request parameter (checkout_resource_url) received from the callback URL to retrieve consumer s payment, shipping address, reward and 3-D Secure information from MasterPass. The checkout resource URL supplied by MasterPass must be decoded and consumed by the merchant as provided by MasterPass. MasterPass may add or delete parameters in future. Below are two examples of callback URLs with the checkout_resource_url parameter in bold: 1. mpstatus=success&checkout_resource_url=https%3a%2f%2fapi.mastercard.com %2Fmasterpass%2Fv6%2Fcheckout %2F &oauth_verifier=aa2ff8e8f1144f45c3b8fdc3d a49e387&oauth_t oken=b8361ad151af35f71df7b395e083befcaf8192dd Decoded checkout url: checkout_resource_url= %2Fapi.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout %2F &checkoutId= &oauth_verifier=aa2ff8e8f1144f45c3b8fdc3d a49e387&oauth_token=b8361ad151af35f71df7b395e083befcaf8192dd Onboarding Version January

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

81 Integration Process Standard checkout Postback Service The final step of a MasterPass transaction is a service call from the merchant to MasterPass, communicating the result of the transaction (success or failure). NOTE: This is a mandatory step. Abandoned transactions do not need to be reported. The <TransactionId> value should be the value from the <TransactionId> element of the Checkout XML returned in the Checkout request. Request and response parameter details can be found here. The following fields are passed in the postback service call: ConsumerKey: Consumer key from checkout project Currency: Currency for the transaction, for example, USD OrderAmount: Transaction Order Amount, for example, 1500 (for USD 15 transaction amount) Onboarding Version January

82 Integration Process Standard checkout PurchaseDate: Date of Purchase ApprovalCode: Six-digit approval code returned by payment API. TransactionId: Transaction ID from TransactionId element of the Checkout XML from the retrieve payment, shipping, rewards and 3-D Secure data service call for example, TransactionStatus: Status of transaction. Valid values are: SUCCESS: For approved transaction FAILURE: For declined transaction PreCheckoutTransactionId: Comes from PrecheckoutTransactionId element of the PrecheckoutData XML. (This is not required for Standard Checkout) Sandbox and Production Endpoints for the Postback Service The endpoints to be used for the Postback Service are as follows. Android and ios App Integration 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. Before you begin If you are integrating MasterPass for Android devices, set the android:targetsdkversion value in your application to 19 or higher. There will be significant MasterPass user interface usability issues for users with the latest devices and Android releases if this version is not declared. For more information on Android SDK targets, refer to the <uses-sdk> page on the Android Developers site. To maintain your application along with each Android release, you must increase the value of this attribute to match the latest API level. The basic process is as follows: Procedure 1. Perform a POST to ${server}/apptowallet/initialize with the shopping cart data in the POST message. The server will request the Request Token, pairing, and precheckout data, post the shopping cart data to MasterPass services and generate the Redirect URL. 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: Onboarding Version January

83 Integration Process Standard checkout 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. 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}. 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). Results After the consumer completes the transaction, the server should submit postback to MasterPass. Onboarding Version January

84 MasterPass Branding Chapter 6 MasterPass Branding This topic provides information on MasterPass branding. Displaying Buy with MasterPass Button and Acceptance Marks Buy With MasterPass Button Example...85 MasterPass Checkout Images Displaying the Connect with MasterPass Button...87 Connect with MasterPass Button Example Connect with MasterPass Image Files MasterPass Learn More Page...88 Onboarding Version January

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

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

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

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

89 Testing Chapter 7 Testing This topic provides information on how to perform testing in the sandbox environment. MasterPass Sandbox Testing...90 Q/A Checklist...94 Checklist for MasterPass Asset Placement...94 In-Wallet Experience...94 Post Wallet Experience...94 Postback General Onboarding Version January

90 Testing MasterPass Sandbox Testing 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 and obtain a sandbox consumer key 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 here. NOTE: You cannot add cards to a sandbox account. Only shipping addresses can be added to sandbox accounts. The accounts in the following table are shared by many sandbox testers. If you experience difficulty using these accounts, wait at least 30 minutes and try again. Sandbox Consumer Account Login Password Test Account 1 Test Account 2 Joe.test@ .co m Joe.test3@ .co m Security Question abc123 Pet s Name fido abc123 Pet s Name fido Security Answer Select the Remember me and Remember this device options when testing so that you do not 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. The following is a quick walkthrough of the Wallet experience. Onboarding Version January

91 Testing MasterPass Sandbox Testing (Select) MasterPass Wallet Onboarding Version January

92 Testing MasterPass Sandbox Testing Sign-in & Verify Your ID (Login for Sandbox) Onboarding Version January

93 Testing MasterPass Sandbox Testing Select Payment & Shipping Onboarding Version January

94 Testing Q/A Checklist Q/A Checklist This topic provides information on the Q/A checklist. Checklist for MasterPass Asset Placement The following is an checklist to follow for proper placement of MasterPass visual assets. Verify your adherence to the MasterPass Merchant Branding Requirements document found on the MasterPass - Merchant Checkout Services - Documentation page. Verify that you are linking to MasterPass visual assets rather than hosting your own. In-Wallet Experience The following is an checklist for 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 The following is an checklist for 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 precheckout data (for connected checkout). It is 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 (for example, 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 the card PAN has not been provided to any entity that does not have the appropriate security in place for storage and transmission of card data (per PCI guidelines). Verify that if merchants are provided with the PAN, this value is not displayed on screen. Onboarding Version January

95 Testing Q/A Checklist Verify that your system can handle the PostalCode element of up to nine characters; this element is sent by MasterPass as part of the BillingAddress and the ShippingAddress elements in checkout XML. Postback The following is a checklist for postback: 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. General The following is a general checklist. Ensure that you are coding to DNS and not to IP addresses for our URLs and endpoints. Onboarding Version January

96 Troubleshooting Chapter 8 Troubleshooting This topic provides information on troubleshooting. Common Errors Support Onboarding Version January

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

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

99 Appendix Appendix Appendix A Appendix This appendix provides additional information related to MasterPass integration process. Lightbox Parameters OAuth Samples Request Token Merchant Initialization Service Shopping Cart Service Access Token Service Checkout Resource Postback Service File-Based Merchant Onboarding Merchant Upload Schema Merchant Download Schema MasterCard Open API Gateway Service API-Based Merchant Onboarding Single-Merchant API Service Overview Single-Merchant API Upload Method Single-Merchant API Validation Method Single-Merchant API Upload Schema Single-Merchant API Upload Sample Messages Single-Merchant API Download Schema Single-Merchant API Download Sample Messages D Secure Status Renew Your Developer Zone Key Developer Zone Key Tool Utility D Secure Overview D Secure Service Description General Overview of MasterCard SecureCode and Verified by Visa Transaction Authentication Important Merchant Information Validation Error Messages Onboarding Version January

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

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

102 Appendix Lightbox Parameters Parameter name Data type Card Security Checko ut Connect Description 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. requestpairing boolea n Refer to precheckout data xml to get details of these data types. This parameter is required when requestpairing is "true". 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. shippingid string O Optional for connected checkout. Set to a valid shipping destination ID. shippinglocationprofile successcallback comm a separa ted string functio n O This parameter defines Merchant s Shipping Profile(s) for the transaction that they set in their account. Multiple values may be passed via comma separation (as in, no spaces within a profile name). For example, "CHEERIO,AUONLY,NAmeri ca". O O O This defines the function to be called when the flow ends in success. Onboarding Version January

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

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

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

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

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

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

109 Appendix OAuth Samples MerchantInitialization Request XML Element Description Type Min Max MerchantInitializationRe quest OAuthToken Request Token (oauth_token) returned by call to the request_token API - PreCheckoutTransactionI D 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 ExtensionPoint SecondaryOriginUrl Identifies the domain URL of the outer/parent web page. This optional field should only be used when the Lightbox will be invoked from a frame that s on a merchant site, and when that frame is of a different domain than that of the merchant site, like for a service provider. string NA MerchantInitialization Response XML Element Description Type Min Max OAuthToken ExtensionPoint Request Token (oauth_token) returned by call to the request_token API Reserved for future enhancement. Optional XML - Any - Onboarding Version January

110 Appendix OAuth Samples ExtensionPoint Elements Starting with API v6, all schema container elements contain a new optional element named ExtensionPoint. These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of xs:any, meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an ExtensionPoint element, beyond any that may be defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further, only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be dropped by MasterPass. ExtensionPoint Sample <ExtensionPoint> <s:sampleextension xmlns:s= ns > <s:samplefield>sample Value</s:SampleField> </s:sampleextension> <f:anotherexampleextension xmlns:f= example2/ns> <f:samplecontainer> <f:anothersamplefield>sample Value</f:AnotherSampleField> </f:samplecontainer> </f:anotherexampleextension> </ExtensionPoint> Shopping Cart Service This section provides description on the Shopping Cart parameters. Shopping Cart Parameters Shopping Cart Request Shopping Cart Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp oauth_body_hash X X X X X X X oauth_token X X Shopping Cart Request XML X Shopping Cart Response XML X Onboarding Version January

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

112 Appendix OAuth Samples %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_6ltdiibo5wgbx4rildexm_jrd4b047 6c% 21414f c4a366c726a b d",oauth_signature_method="RSA- SHA1",oauth_nonce="DEAEB1CD- CA03-405D-A7B4- B4263CB5A305",oauth_timestamp=" ",oauth_version="1.0",oauth_body_hash="8K 9uhveZjVdZW8AIYiXpR70KCtk% 3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C8t6PlW8xTrDob0WzWJ5% 2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQH3Zlx5fi4o0u2x xqrdwhzvbhjpgwbybrme% 2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D" Shopping Cart V6 XML Schema <xs:complextype name="shoppingcart"> <xs:sequence> <xs:element name="currencycode" type="xs:string"/> <xs:element name="subtotal" type="xs:long"/> <xs:element name="shoppingcartitem" type="shoppingcartitem" minoccurs="0" maxoccurs="unbounded"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="shoppingcartitem"> <xs:sequence> <xs:element name="description" type="xs:string"/> <xs:element name="quantity" type="xs:long"/> <xs:element name="value" type="xs:long"/> <xs:element name="imageurl" type="xs:string" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="shoppingcartrequest"> <xs:sequence> <xs:element name="oauthtoken" type="xs:string"/> <xs:element name="shoppingcart" type="shoppingcart"/> <xs:element name="originurl" type="xs:string" minoccurs="0"/> <xs:element name="extensionpoint" type="shoppingcartrequestextensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:element name="shoppingcartrequestextensionpoint" type="shoppingcartrequestextensionpoint"/> <xs:complextype name="shoppingcartrequestextensionpoint"> <xs:sequence> <xs:element name="secondaryoriginurl" type="xs:string" minoccurs="0"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> <xs:element name="extensionpoint" type="extensionpoint"/> <xs:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any"/> </xs:sequence> <xs:anyattribute/> </xs:complextype> Onboarding Version January

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

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

115 Appendix OAuth Samples Shopping Cart Request XML with Optional SecondaryOriginUrl Field Sample <?xml version="1.0"?> <ShoppingCartRequest> <OAuthToken>oauth_demo_token4sj4x6f1eqka2ib2f1nzd1ib2imvce151</OAuthToken> <ShoppingCart> <CurrencyCode>USD</CurrencyCode> <Subtotal>2500</Subtotal> <ShoppingCartItem> <Description>Apple MacBook Pro MD101LL/A 13.3-Inch Laptop</ Description> <Quantity>1</Quantity> <Value>2500</Value> <ImageURL> 41t0EjbJXYL._SL500_SS100_.jpg</ImageUIm> </ShoppingCartItem> </ShoppingCart> <OriginUrl> <ExtensionPoint> <SecondaryOriginUrl> </ExtensionPoint> </ShoppingCartRequest> Shopping Cart Response XML Sample <?xml version="1.0" encoding="utf-8" standalone="yes"?> <ShoppingCartResponse> <OAuthToken>a747f7e7c2e0c f640b92806c8</OAuthToken> </ShoppingCartResponse> Shopping Cart XML 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> Onboarding Version January

116 Appendix OAuth Samples Access Token Service This section describes the Access Token parameters. Access Token Parameters access_token Request access_token Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm X X X X X X X oauth_token X X oauth_expires_in oauth_token_secret xoauth_request_auth_url X X X oauth_verifier X Access Token Parameter Details Access Token Request Description Possible Values Signature Base String Authorization Header oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version. 1.0 oauth_nonce oauth_signature_m ethod Unique alphanumeric string generated from code oauth signature method Variable RSA-SHA1 Onboarding Version January

117 Appendix OAuth Samples Access Token Request Description Possible Values oauth_consumer_ke y Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable oauth_timestamp Current timestamp Variable realm oauth_verifier oauth_token Used to differentiate between our mobile and full site. Currently not used. Verifier is returned on the callback and used in the access token request oauth token obtained from request token call ewallet Variable Access Token Response Description Possible Values Oauth Token oauth_token oauth_token is sent in the signature base string, authorization header and redirect URL Request Token oauth_expires_in Time the Request Token expires in seconds Variable 900 oauth_token_secret Oauth Secret Variable 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- IpGCIu559HYriL093IBXdJeKavp4dce9db2a% 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%2FXI08DS0BZ0XMZZIkhY5Dcg775U3Re4GRN4xa9vm bztobd%2bkknyfiw35to22n1zuhrypi%3d",oauth_version="1.0",oauth_nonce=" ",oauth_signature_method="RSA-SHA1",oauth_consumer_key="ZGho8Df8vqW- IpGCIu559HYriL093IBXdJeKavp4dce9db2a% b616c a413d3d",oauth_token="a02c5c5c1a128c2cebc650ea9aa3dfb7",oauth_verifier=" ce6289d0faf45be777d2d86f",oauth_timestamp=" ",realm="ewallet" Onboarding Version January

118 Appendix OAuth Samples HTTP Response Example oauth_token=9429f23bd08f992c41fb5ddabcc03ecd&oauth_token_secret=cd1ab178419c2111 fb f5dc8d9 Checkout Resource This topic provides details of the Checkout parameters and XML. Checkout Parameters Checkout resource Request Checkout Resource Response oauth_signature oauth_version oauth_nonce oauth_signature_method oauth_consumer_key oauth_timestamp realm oauth_token checkout_resource_url X X X X X X X X Used as endpoint Checkout XML X Checkout Parameter Details Checkout Resource Request Description Possible Values Signature Base String Authorization Header oauth_signature RSA/SHA1 signature generated from the signature base string Variable oauth_version Oauth version. 1.0 oauth_nonce oauth_signature_m ethod Unique alphanumeric string generated from code oauth signature method. Variable RSA-SHA1 Onboarding Version January

119 Appendix OAuth Samples Checkout Resource Request Description Possible Values oauth_consumer_ke y Consumer Key generated when creating a checkout project on MasterPass Merchant portal Variable oauth_timestamp Current timestamp Variable realm oauth_verifier Used to differentiate between our mobile and full site. Currently not used. Verifier is returned on the callback and used in the access token request ewallet Checkout Resource Response Description Possible Values Oauth Token Access Token Access Token is sent in the signature base string, authorization header and redirect URL. Variable Transfer XML Strings Checkout XML Details of the Checkout Signature Base String Example GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout %2F349484&oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c % f c4a366c726a b d%26oauth_nonce %3D %26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D %26oauth_token%3Dc531cce64ca2d88ecb223a8a37afe98e%26oauth_version%3D1.0 HTTP Request Example GET /masterpass/v6/checkout/4400 HTTP/1.1 Authorization: OAuth oauth_signature="cks9xjehksuvnkotsrmoog0rwmveoc2dtqnnw8iwlszeg1znkvrpstjde32ybndhr 7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhXGWRrRpjh3ZhHLDOdSxtxjSCJaHFQ kfgyq %2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce=" ",oauth _signature_method="rsa- SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c %21414f c4a366c726a b d",oauth_token="c531cce64ca2d88e cb223a8a37afe98e",oauth_timestamp=" ",realm="ewallet" V6/Checkout-XML Schema URL: Onboarding Version January

120 Appendix OAuth Samples The checkout resource URL supplied by MasterPass should be decoded and consumed by the merchant as provided by MasterPass. MasterPass may add or delete parameters in future. The following are examples of decoded URL: checkout_resource_url= &checkoutId= checkout_resource_url= <?xml version="1.0" encoding="utf-8" standalone="yes"?> <xs:schema version="1.0" xmlns:xs=" <xs:element name="checkout" type="checkout"/> <xs:complextype name="checkout"> <xs:sequence> <xs:element name="card" type="card"/> <xs:element name="transactionid" type="xs:string"/> <xs:element name="contact" type="contact"/> <xs:element name="shippingaddress" type="shippingaddress" minoccurs="0"/> <xs:element name="authenticationoptions" type="authenticationoptions" minoccurs="0"/> <xs:element name="rewardprogram" type="rewardprogram" minoccurs="0"/> <xs:element name="walletid" type="xs:string"/> <xs:element name="precheckouttransactionid" type="xs:string" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="authenticationoptions"> <xs:sequence> <xs:element name="authenticatemethod" type="xs:string" minoccurs="0"/> <xs:element name="cardenrollmentmethod" type="xs:string" minoccurs="0"/> <xs:element name="cavv" type="xs:string" minoccurs="0"/> <xs:element name="eciflag" type="xs:string" minoccurs="0"/> <xs:element name="mastercardassignedid" type="xs:string" minoccurs="0"/> <xs:element name="paresstatus" type="xs:string" minoccurs="0"/> <xs:element name="scenrollmentstatus" type="xs:string" minoccurs="0"/> <xs:element name="signatureverification" type="xs:string" minoccurs="0"/> <xs:element name="xid" type="xs:string" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="card"> <xs:sequence> <xs:element name="brandid" type="nonemptystring"/> <xs:element name="brandname" type="nonemptystring"/> <xs:element name="accountnumber" type="nonemptystring"/> <xs:element name="billingaddress" type="address"/> <xs:element name="cardholdername" type="nonemptystring"/> <xs:element name="expirymonth" type="month" minoccurs="0"/> <xs:element name="expiryyear" type="year" minoccurs="0"/> <xs:element name="extensionpoint" type="extensionpoint" minoccurs="0"/> </xs:sequence> </xs:complextype> <xs:complextype name="address"> <xs:sequence> Onboarding Version January

121 Appendix OAuth Samples <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> <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> Onboarding Version January

122 Appendix OAuth Samples <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"/> <xs:whitespace value="collapse"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="country"> <xs:restriction base="xs:string"> <xs:pattern value="[a-z]{2}"/> </xs:restriction> </xs:simpletype> <xs:simpletype name=" address"> <xs:restriction base="xs:string"> <xs:pattern value="[a-za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[a-za-z0-9! \-/=\?\^_`\{-~]+)*"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="month"> <xs:restriction base="xs:int"> <xs:mininclusive value="1"/> <xs:maxinclusive value="12"/> </xs:restriction> </xs:simpletype> <xs:simpletype name="year"> <xs:restriction base="xs:int"> <xs:mininclusive value="2013"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpletype> <xs:complextype name="extensionpoint"> <xs:sequence> <xs:any maxoccurs="unbounded" processcontents="lax" namespace="##any"/> </xs:sequence> <xs:anyattribute/> Onboarding Version January

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

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

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

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

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

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

129 Appendix OAuth Samples CheckoutXML Element Description Type Min Max EciFlag Electronic commerce indicator (ECI) flag. Possible values are as follows: Alpha Numeric NA 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) MasterCardAssignedI D This value is assigned by MasterCard and represents programs associated directly with Maestro cards. This field should be supplied in the authorization request by the merchant. Alpha Numeric NA Onboarding Version January

130 Appendix OAuth Samples CheckoutXML Element Description Type Min Max PaResStatus A message formatted, digitally signed, and sent from the ACS (issuer) to the MPI providing the results of the issuer s SecureCode/Verified by Visa cardholder authentication. Possible values are: Alpha NA 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 Onboarding Version January

131 Appendix OAuth Samples CheckoutXML Element Description Type Min Max SCEnrollmentStatus SecureCode Enrollment Status: Indicates if the issuer of the card supports payer authentication for this card. Possible values are; Alpha NA 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 (for example, prepaid cards). SignatureVerification: Signature Verification. Possible values are: Alpha NA Y- Indicates that the signature of the PaRes has been validated successfully and the message contents can be trusted. N-Indicates that for a variety of reasons (tampering, certificate expiration, and so on) the PaRes could not be validated, and the result should not be trusted. Onboarding Version January

132 Appendix OAuth Samples CheckoutXML Element Description Type Min Max XID Transaction identifier resulting from authentication processing. Alpha Numeric NA ExtensionPoint Reserved for future enhancement. Optional Any Checkout Reward Program Child Element XML Reward Program RewardNumber Consumer s reward number associated with the reward program Reward Program RewardId ID associated with the reward program Alphanume ric Alphanume ric RewardName ExpiryMonth ExpiryYear ExtensionPoint Name of reward program Month the reward program expires Year the reward program expires Reserved for future enhancement. Optional Alphanume ric Alphanume ric Alphanume ric Any - ExtensionPoint Elements Starting with API v6, all schema container elements contain a new optional element named ExtensionPoint. These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of xs:any, meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an 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= Onboarding Version January

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

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

135 Appendix OAuth Samples </xs:complextype> <xs:complextype name="merchanttransaction"> <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>0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4! 414b b b d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate> T14:52: :00</PurchaseDate> <TransactionStatus>Success</TransactionStatus> <ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947</ PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> <MerchantTransactions> </MerchantTransactions> MerchantTransactionsResponse Schema <?xml version-/="1.0" encoding-/="utf-8" standalone-/="yes"?> <xs:schema version-/="1.0" xmlns:xs-/=" <xs:element name-/="merchanttransactions" type-/="merchanttransactions"/> <xs:complextype name-/="merchanttransactions"> <xs:sequence> <xs:element name-/="merchanttransactions" type-/ ="MerchantTransaction" minoccurs-/="0" maxoccurs-/="unbounded"/> <xs:element name-/="extensionpoint" type-/="extensionpoint" minoccurs-/="0"/> </xs:sequence> Onboarding Version January

136 Appendix OAuth Samples </xs:complextype> <xs:complextype name-/="merchanttransaction"> <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 Response Example (response will be identical to the XML sent if call was successful) <MerchantTransactions> <MerchantTransactions> <TransactionId> </TransactionId> <ConsumerKey>0zMKpm0nFtUv8lLXT97jDRo2b d0zMKpm0nFt9682b b d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate> T14:52: :00</PurchaseDate> <TransactionStatus>Success</TransactionStatus> <ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-9477</ PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> </MerchantTransactions> </MerchantTransactions> MerchantTransactionsXML Details MerchantTransacti onsrequest Element Description Type Min - Max MerchantTransactions Onboarding Version January

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

138 Appendix OAuth Samples MerchantTransactio nsresponse Element Description Type Min - Max MerchantTransactions TransactionID Uses the TransactionID element of the Checkout XML String ConsumerKey Currency OrderAmount Automatically generated when creating a checkout project on MasterPass Merchant portal. Currency of the transaction. Defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars. Integer Transaction order amount without decimal, for example, String 97 String 3 Integer 1-12 PurchaseDate Date and Time of the shopping cart purchase, for example, T15:12: :00 Date XML format TransactionStatus ApprovalCode ExtensionPoint State of the transaction. Indicates whether successful. Valid values are Success or Failure. Approval code returned to merchant from merchant's payment API with payment gateway or service provider. Reserved for future enhancement. Optional String 7 String 6 Any - ExtensionPoint Elements Starting with API v6, all schema container elements contain a new optional element named ExtensionPoint. These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of xs:any, meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an 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 Onboarding Version January

139 Appendix File-Based Merchant Onboarding 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> File-Based Merchant Onboarding This topic provides information File-based merchant onboarding mechanism. Merchant Upload Schema This section provides information on the merchant upload schema. The file schema can be downloaded from the MasterPass - Merchant Checkout - Documentation page on Developer Zone. NOTE: For information on how to specify a reward program for a merchant in the Merchant Upload file, contact Merchant Testing Support. Merchant Upload Schema Details MerchantUplo ad Element Description Type Mandato ry/ Optional Min Max Comment Merchant Merchant Details Element M Variable Merchant SPMerchantId Service Provider Issued Merchant ID. This should be unique per Service Provider String M Variable For example, Onboarding Version January

140 Appendix File-Based Merchant Onboarding MerchantUplo ad Element Description Type Mandato ry/ Optional Min Max Comment Action Merchant Action String M 1 1 Valid values are C (Create), U (Update) and D (Delete) Profile Merchant Profile Child Mandator y for Create and Update. Not used for Delete. 1 1 Mandatory for Create (Action=C) and Update (Action=U) CheckoutBrand Branding Information Child Mandator y for Create, Optional for Update and Delete At least one CheckoutBran d element MUST be present for merchant creation. AuthOption Authentication Options Child Variable per Merchant MerchantAcqui rer MerchantAcqui rer Child Profile Name Merchant Name String M For example, XYZ Pizza DoingBusAs FedTaxId Url BusinessCateg ory Doing Business As - Alias Merchant s Federal Tax ID Merchant s Website URL Merchant s business type String M For example, XYZ Pizza Inc. String O For example, String M For example, String O For example, Restaurant Onboarding Version January

141 Appendix File-Based Merchant Onboarding MerchantUplo ad Element Description Type Mandato ry/ Optional Min Max Comment Address Merchant s Address Child Phone Merchant s Phone Child s Merchant s address String O Acquirer Merchant s Acquirer Child O Address City Merchant s City M 1 25 For example, New York Country Country Subdivision Line1 Line2 Line3 PostalCode Merchant s Country Merchant s Country Subdivision. Defined by ISO alpha-2 digit code. For example, US- VA is Virginia, US-OH is Ohio Merchant s Address Line 1 Merchant s Address Line 2 Merchant s Address Line 3 Merchant s Postal Code M 2 2 Standard 2- letter ISO 3166 country codes. For example, US O If defined choose string (1-100) or defined enumerator. For example, US-NY M 1 40 For example, 1 Main Street O 1 40 O 1 40 M 1 10 For example, Phone CountryCode Merchant s phone country code M 1 10 For example, 75 Onboarding Version January

142 Appendix File-Based Merchant Onboarding MerchantUplo ad Element Description Type Mandato ry/ Optional Min Max Comment Number Merchant s phone Number M 3 20 For example, s Address Merchant's address Acquirer Action Merchant Acquirer action String O For example, @master pass.com String O 1 1 Valid values are C (Create), U (Update), and D (Delete) Id Name AssignedMerch antid Password Merchant s Acquirer Id Merchant s Acquirer Name Acquirer assigned merchant ID Acquirer Password for 3DS setup M 1 15 For example, M For example, Test Acquirer. 3DS merchants must reduce their character limit to 250 to meet Cardinal Commerce s API specifications. M For example, 435t6543 O 1 8 For example, Visa. 3DS merchants must reduce their character limit to 8 to meet Cardinal Commerce s API specifications Onboarding Version January

143 Appendix File-Based Merchant Onboarding MerchantUplo ad Element Description Type Mandato ry/ Optional Min Max Comment CheckoutBrand CheckoutId Name If the checkout brand exists for update action, then the checkout ID is mandatory. Name displayed on MasterPass site during checkout when no logo is provided O For example, a4c411by7lob 4i81xb6r41i8 20mw3n151 M For example, XYZ Pizza DisplayName Display Name M For example, XYZ Pizza ProductionUrl SandboxUrl LogoUrl Production checkout URL Sandbox checkout URL Merchant logo displayed on MasterPass site during checkout. If not specified, the Name is displayed M For example, xyzpizza.com M For example, test.xyzpizza.c om O For example, xyzpizza.com/ logo.jpg AuthOption CardBrand Card brands enrolled for advanced authentication M NA NA Refer to the schema to get valid values. For example, for MasterCard, use "MASTER". Onboarding Version January

144 Appendix File-Based Merchant Onboarding MerchantUplo ad Element Description Type Mandato ry/ Optional Min Max Comment Type Authentication type M NA NA Refer to the schema to get valid values. MerchantAcqui rer Action Action Child O 0 C, U, or D Acquirer Acquirer Child M Used to create (C), update (U) or delete (D) Visa Password MerchantAcqui rerbrand Merchant Acquirer Brand Child MerchantAcqui rerbrand CardBrand Card Brand M NA NA Refer to the schema to get valid values. For example, for MasterCard, use "MASTER". Currency Currency O 3 3 ISO 4217 standard 3- letter currency code. Refer to the schema to get valid values. NOTE: If this field is left blank, then all currency codes will be enabled. Merchant Upload Sample Create <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> <Merchant> Onboarding Version January

145 Appendix File-Based Merchant Onboarding <SPMerchantId>SPMerch58401</SPMerchantId> <Action>C</Action> <Profile> <Name>SPMerch58401</Name> <DoingBusAs>SPMerch58401</DoingBusAs> <FedTaxId> </FedTaxId> <Url> <BusinessCategory>test</BusinessCategory> <Address> <City>SPMerch58401</City> <Country>US</Country> <Line1>898 SPMerch58401</Line1> <PostalCode>78090</PostalCode> </Address> <Phone> <CountryCode>1</CountryCode> <Number> </Number> </Phone> < s> </ s> <Acquirer> <Id> </Id> <Name>QATESTACQ</Name> <AssignedMerchantId>MCQA1</AssignedMerchantId> </Acquirer> </Profile> <CheckoutBrand> <Name>SPMerch58401</Name> <DisplayName>SPMerch58401</DisplayName> <ProductionUrl> <SandboxUrl> SandboxUrl> <LogoUrl> navl_logo_mastemasterca.png</logourl> </CheckoutBrand> </Merchant> </MerchantUpload> Merchant Upload Sample Create with Advanced Authentication Settings (3DS) for MasterCard <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload xmlns:xsi=" <Merchant> <SPMerchantId>022416_TESTMERCH</SPMerchantId> <Action>C</Action> <Profile> <Name>022416_TESTMERCH</Name> <DoingBusAs>022415testmerchant</DoingBusAs> <Url> <Address> <City>Padova</City> <Country>IT</Country> <Line1>Boettgerstr</Line1> <PostalCode>35129</PostalCode> </Address> <Phone> <CountryCode>39</CountryCode> <Number> </Number> </Phone> < s> Onboarding Version January

146 Appendix File-Based Merchant Onboarding </ s> </Profile> <CheckoutBrand> <Name>022416_TESTMERCH</Name> <DisplayName>022416_TESTMERCH</DisplayName> <ProductionUrl> <SandboxUrl> </CheckoutBrand> <AuthOption> <CardBrand>MASTER_CARD</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <MerchantAcquirer> <Acquirer> <Id>523078</Id> <Name>CartaSI</Name> <AssignedMerchantId>001</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>MASTER_CARD</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> </Merchant> </MerchantUpload> Merchant Upload Sample Create with Advanced Authentication Settings (3DS) for Visa <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> <Merchant> <SPMerchantId>SPMerchantId1</SPMerchantId> <Action>C</Action> <Profile> <Name>XYZ Pizza</Name> <DoingBusAs>XYZ Pizza</DoingBusAs> <FedTaxId> </FedTaxId> <Url> <BusinessCategory>Restaurant</BusinessCategory> <Address> <City>Springfield</City> <Country>US</Country> <Line1>1234 Main Street</Line1> <PostalCode>12345</PostalCode> </Address> <Phone> <CountryCode>1</CountryCode> <Number> </Number> </Phone> < s> </ s> </Profile> <CheckoutBrand> <Name>XYZ Pizza</Name> <DisplayName>XYZ Pizza</DisplayName> <ProductionUrl> <SandboxUrl> <LogoUrl> </CheckoutBrand> <AuthOption> <CardBrand>VISA</CardBrand> Onboarding Version January

147 Appendix File-Based Merchant Onboarding <Type>ALL_TRANSACTIONS</Type> </AuthOption> <MerchantAcquirer> <Action>C</Action> <Acquirer> <Id> </Id> <Name>CRDNLDEMO4</Name> <AssignedMerchantId> </AssignedMerchantId> <Password>tester456</Password> </Acquirer> <MerchantAcquirerBrand> <CardBrand>VISA</CardBrand> <Currency>USD</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> </Merchant> </MerchantUpload> Merchant Upload Sample Update NOTE: If the checkout brand exists for the update action, then the checkout ID is mandatory. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> <Merchant> <SPMerchantId>SPMerchantId1</SPMerchantId> <Action>U</Action> <Profile> <Name>XYZ Pizza Co</Name> <DoingBusAs>XYZ Pizza</DoingBusAs> <FedTaxId> </FedTaxId> <Url> <BusinessCategory>Restaurant</BusinessCategory> <Address> <City>Springfield</City> <Country>US</Country> <Line1>1 Main Street</Line1> <PostalCode>12345</PostalCode> </Address> <Phone> <CountryCode>1</CountryCode> <Number> </Number> </Phone> < s> </ s> </Profile> <CheckoutBrand> <CheckoutId> a466w1sj09wfehqqy3xxl12</checkoutid> <Name>XYZ Pizza</Name> <DisplayName>XYZ Pizza Co</DisplayName> <ProductionUrl> <SandboxUrl> <LogoUrl> </CheckoutBrand> </Merchant> </MerchantUpload> Merchant Upload Sample Update <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> Onboarding Version January

148 Appendix File-Based Merchant Onboarding <Merchant> <SPMerchantId>SPMerch58401</SPMerchantId> <Action>U</Action> <Profile> <Name>SPMerch58401</Name> <DoingBusAs>SPMerch58401</DoingBusAs> <FedTaxId> </FedTaxId> <Url> <BusinessCategory>test</BusinessCategory> <Address> <City>SPMerch58401</City> <Country>US</Country> <Line1>898 SPMerch58401</Line1> <PostalCode>78090</PostalCode> </Address> <Phone> <CountryCode>1</CountryCode> <Number> </Number> </Phone> < s> </ s> <Acquirer> <Id> </Id> <Name>QATESTACQ</Name> <AssignedMerchantId>MCQA1</AssignedMerchantId> </Acquirer> </Profile> <CheckoutBrand> <Name>SPMerch58401</Name> <DisplayName>SPMerch58401</DisplayName> <ProductionUrl> <SandboxUrl> <LogoUrl> </CheckoutBrand> </Merchant> </MerchantUpload> Merchant Upload Sample with Advanced Authentication Settings (3DS) Update <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload xmlns:xsi=" <Merchant> <SPMerchantId>022416_TESTMERCH</SPMerchantId> <Action>U</Action> <Profile> <Name>022416_TESTMERCH</Name> <DoingBusAs>022415testmerchant</DoingBusAs> <Url> <Address> <City>Padova</City> <Country>IT</Country> <Line1>Boettgerstr</Line1> <PostalCode>35129</PostalCode> </Address> <Phone> <CountryCode>39</CountryCode> <Number> </Number> </Phone> < s> </ s> </Profile> Onboarding Version January

149 Appendix File-Based Merchant Onboarding <CheckoutBrand> <CheckoutId>a4a6w4vr8jzii6j0wk2e1i6kx962m2gle</CheckoutId> <Name>022416_TESTMERCH</Name> <DisplayName>022416_TESTMERCH</DisplayName> <ProductionUrl> <SandboxUrl> </CheckoutBrand> <AuthOption> <CardBrand>MASTER_CARD</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <AuthOption> <CardBrand>VISA</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <MerchantAcquirer> <Acquirer> <Id>523078</Id> <Name>CartaSI</Name> <AssignedMerchantId>001</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>MASTER_CARD</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> <MerchantAcquirer> <Acquirer> <Id>453997</Id> <Name>CartaSI</Name> <AssignedMerchantId>011</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>VISA</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> </Merchant> </MerchantUpload> Merchant Upload Sample Delete <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> <Merchant> <SPMerchantId>SPMerchantId1</SPMerchantId> <Action>D</Action> </Merchant> </MerchantUpload> Merchant Upload Sample Delete <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> <Merchant> <SPMerchantId>SPMerch58401</SPMerchan <Action>D</Action> <Profile> <Name>SPMerch58401</Name> <DoingBusAs>SPMerch58401</DoingBusAs> <FedTaxId> </FedTaxId> <Url> <BusinessCategory>test</BusinessCategory> Onboarding Version January

150 Appendix File-Based Merchant Onboarding <Address> <City>SPMerch58401</City> <Country>US</Country> <Line1>898 SPMerch58401</Line1> <PostalCode>78090</PostalCode> </Address> <Phone> <CountryCode>1</CountryCode> <Number> </Number> </Phone> < s> </ s> <Acquirer> <Id> </Id> <Name>QATESTACQ</Name> <AssignedMerchantId>MCQA1</AssignedMerchantId> </Acquirer> </Profile> <CheckoutBrand> <Name>SPMerch58401</Name> <DisplayName>SPMerch58401</DisplayName> <ProductionUrl> <SandboxUrl> <LogoUrl> navl_logl_mastercardcom.png</logourl> </CheckoutBrand> </Merchant> </MerchantUpload> Merchant Upload Sample with Advanced Authentication Settings (3DS) Delete <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload xmlns:xsi=" <Merchant> <SPMerchantId>022416_TESTMERCH</SPMerchantId> <Action>D</Action> <Profile> <Name>022416_TESTMERCH</Name> <DoingBusAs>022415testmerchant</DoingBusAs> <Url> <Address> <City>Padova</City> <Country>IT</Country> <Line1>Boettgerstr</Line1> <PostalCode>35129</PostalCode> </Address> <Phone> <CountryCode>39</CountryCode> <Number> </Number> </Phone> < s> </ s> </Profile> <CheckoutBrand> <CheckoutId>a4a6w4vr8jzii6j0wk2e1i6kx962m2gle</CheckoutId> <Name>022416_TESTMERCH</Name> <DisplayName>022416_TESTMERCH</DisplayName> <ProductionUrl> <SandboxUrl> </CheckoutBrand> <AuthOption> Onboarding Version January

151 Appendix File-Based Merchant Onboarding <CardBrand>MASTER_CARD</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <AuthOption> <CardBrand>VISA</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <MerchantAcquirer> <Acquirer> <Id>523078</Id> <Name>CartaSI</Name> <AssignedMerchantId>001</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>MASTER_CARD</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> <MerchantAcquirer> <Acquirer> <Id>453997</Id> <Name>CartaSI</Name> <AssignedMerchantId>011</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>VISA</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> </Merchant> </MerchantUpload> Please refer to the FAQs for additional sample scenarios for using Create, Update, and Delete at +FAQs. Merchant Upload Validate Response Schema Details ValidateFil erespons e Element Descriptio n Type Mandator y / Optional Min Max Comment ValidatedM erchant Validation Details of a Merchant Element M Variable Validated Merchant MerchantId Identifier of the merchant defined by the Service Provider String M 1 1 For example, STGQA09 Onboarding Version January

152 Appendix File-Based Merchant Onboarding ErrorText Description of validation error String M 0 unbounde d VBMU014 0: merchantid already exists for serviceprovi derid= and spmerchan tid=stgqa 09 ExtensionP oint Reserved for future enhancem ent. Any Optional 0 unbounde d Extension Point Name Merchant Name String M For example, XYZ Pizza Merchant Download Schema This section provides information on the merchant download schema. The file schema can be downloaded from the MasterPass - Merchant Checkout - Documentation page on Developer Zone. Merchant Download Schema Details Merchant Download Element Descriptio n Type Mandator y/ Optional Min Max Comment Merchant Download Summary Summary of the Upload Element M - - MerchantR esponsere cord List of merchants uploaded/ edited Element Summary BatchId System assigned Batch ID Integer M Variable For example, Onboarding Version January

153 Appendix File-Based Merchant Onboarding Description Description provided during file upload String M 1 50 For example, Merchant file upload UploadTim estamp UploadFile Name SuccessCo unt FailureCou nt ErrorText SandboxKe y Upload Time Stamp Upload File Name Number of successfully uploaded Merchant Brandings Number of unsuccessf ully uploaded Merchant Brandings Description of errors resulting upload failures Developer s sandbox API key Date/Time M DateTime field. For example, T11:45: :0 0 String M For example, merchant.x ml Integer M NA NA For example, 490 Integer M NA NA For example, 10 String O For example, Invalid Format String 1 50 For example, 245d5a53 7a457c2f2 b55644b b5 6673d9d Onboarding Version January

154 Appendix File-Based Merchant Onboarding Production Key Developer s production key String 1 50 For example, 245d5a53 7a457c2f2 b55644b b5 6673d9d Merchant Response Record SPMerchan tid Merchant identifier for a specific Service provider String M Variable For example, CheckoutB rand Checkout Branding Child Choice (ErrorText or CheckoutB rand) ErrorText Error description for failure O For example, Invalid rewards logo URL Checkout Brand Name Checkout Brand Name String M For example, XYZ Pizza CheckoutId entifier Checkout identifier generated by MasterPass String M For example, a4a6x3oeh b3fzhgu2e Production Url Production Checkout Branding URL String M For example, xyzpizza.co m Onboarding Version January

155 Appendix File-Based Merchant Onboarding SandboxUrl Sandbox Checkout Branding URL String M For example, test.xyzpizz a.com Merchant Download Sample <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantDownload> <Summary> <BatchId>277800</BatchId> <Description>Merchant Upload</Description> <UploadTimestamp> T11:45: :00</UploadTimestamp> <UploadFileName>merchant_1.xml</UploadFileName> <SuccessCount>1</SuccessCount> <FailureCount>0</FailureCount> <ProjectKeys> <SandboxKey>41496b7a452f35764d b f3d</ SandboxKey> <ProductionKey>41496b7a452f35764d b f3d</ ProductionKey> </ProjectKeys> </Summary> <MerchantResponseRecord> <SPMerchantId>SPMerchantId1</SPMerchantId> <CheckoutBrand> <Name>XYZ Pizza</Name> <CheckoutIdentifier>a4a6x3oehb3fzh</CheckoutIdentifier> <ProductionUrl> <SandboxUrl> </CheckoutBrand> </MerchantResponseRecord> </MerchantDownload> Merchant Download Sample with Advanced Authentication Settings (3DS) <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantDownload Version="1.1"> <Summary> <BatchId> </BatchId> <Description>1P_Upload_MC_3DS.xml</Description> <UploadTimestamp> T15:00: :00</UploadTimestamp> <UploadFileName>1P_Upload_MC_3DS (1).xml</UploadFileName> <SuccessCount>1</SuccessCount> <FailureCount>0</FailureCount> <ProjectKeys> <SandboxKey>456d5a537a346c2f2b55644b b56673d3d</ SandboxKey> <ProductionKey>456d5a537a346c2f2b55644b b56673d3d</ ProductionKey> </ProjectKeys> </Summary> <MerchantResponseRecord> <SPMerchantId>022416_RAMA</SPMerchantId> <CheckoutBrand> <Name>022416_RAMA</Name> <CheckoutIdentifier>a4c411by7lob4i81xb6r41i820mw3n151</ CheckoutIdentifier> Onboarding Version January

156 Appendix MasterCard Open API Gateway Service <ProductionUrl> <SandboxUrl> </CheckoutBrand> <MerchantAcquirer> <ID>523078</ID> <Name>CartaSI</Name> <AssignedMerchantID>001</AssignedMerchantID> <DSStatus>Not Submitted</DSStatus> </MerchantAcquirer> </MerchantResponseRecord> </MerchantDownload> MasterCard Open API Gateway Service The MasterCard Open API Gateway is a fully managed service that makes it easy to create, publish, maintain, monitor, and secure APIs at any scale that are exposed to third-party developers. The MasterCard Open API Gateway handles all tasks involving the acceptance and processing of up to hundreds of thousands of concurrent API request calls, including traffic management, authorization and access control, monitoring, and API version management. API-Based Merchant Onboarding This topic provides information Single-Merchant API service. Single-Merchant API Service Overview The Single-Merchant API can be used by service providers to onboard merchant records one at a time, in real time, to MasterPass. Single-Merchant API Upload Method Details of the Single-Merchant API upload method, including the URL, HTTP method, and URL parameter definition, are as follows. Description: Returns a MerchantDownload payload that will contain records of merchants that have, or have not, enabled 3-D Secure. URL: HTTP Method: POST URL Parameter(s) Definition: URL Parameter Name Description Type Format projectid Identifier of Open Feed Project created in the Merchant Portal Number [0-9]+ Request Body Definition: Refer to the Single-Merchant API Upload Schema Response Body Definition: Refer to the Single-Merchant API Download Schema Onboarding Version January

157 Appendix API-Based Merchant Onboarding Single-Merchant API Validation Method Details of the Single-Merchant API validation method, including the URL, HTTP method, and URL parameter definition, are as follows. Description: Returns a ValidateFileResponse payload that will contain records of merchants that have, or have not, enabled 3-D Secure. URL: validation HTTP Method: POST URL Parameter(s) Definition: URL Parameter Name Description Type Format projectid Identifier of Open Feed Project created in the Merchant Portal Number [0-9]+ Response Body Definition: Refer to the Validate File Response Schema Single-Merchant API Upload Schema The Single-Merchant API is used by service providers to onboard merchant information one at a time to MasterPass through the Open Feed Project. The XML schema for the Single-Merchant API is the same as that used for the File-based merchant onboarding via the merchant and service provider portal. For more details, refer to Merchant Upload Schema and Merchant Download Schema. Merchant Upload Schema Details Child Node: Merchant[1...1] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.SPM erchantid Service Provider Issued Merchant ID. This should be unique per Service Provider String M 1 1 undefi ned undefi ned SPMerchantId 123. Need to verify 25 character constraint Onboarding Version January

158 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Actio n Merchant Action Code for the type of onboarding request Enum M Valid values: C (Create) U (Update) D (Delete) Child Node: Profile[0...1] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Profil e.name Merchant.Profil e.doingbusas Merchant.Profil e.fedtaxid Merchant.Profil e.url Merchant.Profil e.businesscate gory Merchant Name Merchant Doing Business As Merchant Federal Tax ID Merchant Website URL Merchant business type String M For example, MerchantNam e123 String M For example, MerchantDoin gbusinessas1 23 String O For example, String O For example, com String O For example, Electronics Merchant.Profil e.address[1...1].city Merchant City Address String M For example, New York Onboarding Version January

159 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Profil e.address[1...1].country Merchant Country (twocharacter country code) Enum String (two charact ers) M This code list module defines the enumerated types of standard twoletter ISO 3166 country codes. For example, "AU" for Austraila List of all countries with their 2 digit codes (ISO ) Merchant.Profil e.address[1...1].countrysubdiv ison Merchant.Profil e.address[1...1].line1 Merchant.Profil e.address[1...1].line2 Merchant.Profil e.address[1...1].line3 Merchant.Profil e.address[1...1].postalcode Country Subdivision Merchant Address Line 1 Merchant Address Line 2 Merchant Address Line 3 Merchant Postal Code String O For example, US-NY String M For example, Main Street String O For example, Main Street String O For example, Main Street String O For example, Onboarding Version January

160 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Profil e.address[1...1].extensionpoint Data Element to support unique use cases for Merchant OnBoarding Generic Object O 0 1 N/A N/A N/A Merchant.Profil e.phone[1...1]. CountryCode Merchant.Profil e.phone[1...1]. Number Merchant phone country code Merchant phone Number String M For example, 75 String M For example, Merchant.Profil e.phone[1...1].e xtensionpoint Data Element to support unique use cases for Merchant OnBoarding Object O 0 1 N/A N/A N/A Merchant.Profil e. s[0...1].e mailaddress Merchant address String O 0 undefi ned undefi ned undefi ned For example, samplemercha nt@sample.co m Child Node: RewardProgram[0...1] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Rewa rdprogram.na me Merchant.Rewa rdprogram.id Name of Reward Program ID of Reward Program String M For example, RewardProgra m String M RP12345 Pattern Value: [a-za-zàÿ0-9œæ]* Onboarding Version January

161 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Rewa rdprogram.log ourl Merchant.Rewa rdprogram.exte nsionpoint Url of Reward Program Data element to support unique use cases for merchant onboarding String O For example, abc123.com/ images/ logo.png Object O 0 1 N/A N/A N/A Child Node: CheckoutBrand[0...*] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Chec koutbrand.che ckoutid Identifier for CheckoutBrand element String O For example, Merchant.Chec koutbrand.nam e Merchant.Chec koutbrand.disp layname Merchant.Chec koutbrand.prod uctionurl Name for CheckoutBrand element Display name for CheckoutBrand element Production checkout URL String M For example, MerchantChe ckoutbrandna me String M MerchantChe ckoutbranddis playname String M xyzpizza.com Merchant.Chec koutbrand.san dboxurl Sandbox URL string String M test.xyzpizza.c om Onboarding Version January

162 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Chec koutbrand.log ourl Merchant.Chec koutbrand.exte nsionpoint Logo Url for CheckoutBrand element Data element to support unique use cases for merchant onboarding String O abc123.com/ images/ logo.png Object O 0 1 N/A N/A N/A Child Node: AuthOption[0...*] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Auth Option.CardBra nd Card Brand enrolled for advanced authentication (3-D Secure) via Cardinal Commerce Enum M 1 1 N/A N/A Valid values are as follows: MASTER_ CARD VISA AMERICA N_EXPRES S DISCOVER JCB MAESTRO Merchant.Auth Option.Type Authentication type for the specified card brand Enum M 1 1 N/A N/A Valid values are as follows: BASIC ALL_TRAN SACTIONS VERIFIED Onboarding Version January

163 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Auth Option.Extensio npoint Data element to support unique use cases for merchant onboarding Object O 0 1 N/A N/A N/A Child Node: Merchant Acquirer[0...*] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Merc hantacquirer.a ction Merchant.Merc hantacquirer.a cquirer[1...1].id Merchant.Merc hantacquirer.a cquirer[1...1].n ame Merchant.Merc hantacquirer.a cquirer[1...1].a ssignedmercha ntid Action Code for Merchant Acquirer Identifier for Merchant Acquirer Name of Merchant Acquirer Acquirer assigned merchant ID String O Valid values are as follows: C (Create) U (Update) D (Delete) String M For example, SP String M For example, SPMerchantA cquirer123 String M For example, 435t6543 Merchant.Merc hantacquirer.a cquirer[1...1].ex tensionpoint Data element to support unique use cases for merchant onboarding Object O 0 1 N/A N/A N/A Onboarding Version January

164 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Merc hantacquirer.m erchantacquire rbrand[1...1].c ardbrand Card Brand Enum M 1 1 N/A N/A Valid values are as follows: MASTER_ CARD VISA AMERICA N_EXPRES S DISCOVER JCB MAESTRO Merchant.Merc hantacquirer.m erchantacquire rbrand[1...1].c urrency ISO 4217 standard threeletter currency code Enum O 0 unbou nded N/A N/A For example, USD ISO 4217 Currency Codes Merchant.Merc hantacquirer.m erchantacquire rbrand[1...1].ex tensionpoint Data element to support unique use cases for merchant onboarding Object O 0 1 N/A N/A N/A Child Node: CheckoutLevel Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Merchant.Chec koutlevel Checkout Type Enum O 0 1 N/A N/A Valid values are as follows: STANDAR D EXPRESS Onboarding Version January

165 Appendix API-Based Merchant Onboarding Single-Merchant API Upload Sample Messages The Single-Merchant API is used by service providers to onboard merchant information one at a time to MasterPass through the Open Feed Project. Payload samples of the Single- Merchant API Upload onboarding requests are as follows. Merchant Upload Sample Message Create non-3-d Secure <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> <Merchant> <SPMerchantId>SPMerch58401</SPMerchantId> <Action>C</Action> <Profile> <Name>SPMerch58401</Name> <DoingBusAs>SPMerch58401</DoingBusAs> <FedTaxId> </FedTaxId> <Url> <BusinessCategory>test</BusinessCategory> <Address> <City>SPMerch58401</City> <Country>US</Country> <Line1>898 SPMerch58401</Line1> <PostalCode>78090</PostalCode> </Address> <Phone> <CountryCode>1</CountryCode> <Number> </Number> </Phone> < s> < Address> @masterpass.com</ Address> </ s> <Acquirer> <Id> </Id> <Name>QATESTACQ</Name> <AssignedMerchantId>MCQA1</AssignedMerchantId> </Acquirer> </Profile> <CheckoutBrand> <Name>SPMerch58401</Name> <DisplayName>SPMerch58401</DisplayName> <ProductionUrl> <SandboxUrl> <LogoUrl> navl_logo_mastemasterca.png</logourl> </CheckoutBrand> </Merchant> </MerchantUpload> Merchant Upload Sample Message Create MasterCard 3-D Secure <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload xmlns:xsi=" <Merchant> <SPMerchantId>022416_TESTMERCH</SPMerchantId> <Action>C</Action> <Profile> <Name>022416_TESTMERCH</Name> <DoingBusAs>022415testmerchant</DoingBusAs> <Url> <Address> <City>Padova</City> Onboarding Version January

166 Appendix API-Based Merchant Onboarding <Country>IT</Country> <Line1>Boettgerstr</Line1> <PostalCode>35129</PostalCode> </Address> <Phone> <CountryCode>39</CountryCode> <Number> </Number> </Phone> < s> </ s> </Profile> <CheckoutBrand> <Name>022416_TESTMERCH</Name> <DisplayName>022416_TESTMERCH</DisplayName> <ProductionUrl> <SandboxUrl> </CheckoutBrand> <AuthOption> <CardBrand>MASTER_CARD</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <MerchantAcquirer> <Acquirer> <Id>523078</Id> <Name>CartaSI</Name> <AssignedMerchantId>001</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>MASTER_CARD</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> </Merchant> </MerchantUpload> Merchant Upload Sample Message Update non-3-d Secure NOTE: If the checkout brand exists for the update action, then the checkout ID is mandatory. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> <Merchant> <SPMerchantId>SPMerchantId1</SPMerchantId> <Action>U</Action> <Profile> <Name>XYZ Pizza Co</Name> <DoingBusAs>XYZ Pizza</DoingBusAs> <FedTaxId> </FedTaxId> <Url> <BusinessCategory>Restaurant</BusinessCategory> <Address> <City>Springfield</City> <Country>US</Country> <Line1>1 Main Street</Line1> <PostalCode>12345</PostalCode> </Address> <Phone> <CountryCode>1</CountryCode> <Number> </Number> </Phone> < s> Onboarding Version January

167 Appendix API-Based Merchant Onboarding </ s> </Profile> <CheckoutBrand> <CheckoutId> a466w1sj09wfehqqy3xxl12</checkoutid> <Name>XYZ Pizza</Name> <DisplayName>XYZ Pizza Co</DisplayName> <ProductionUrl> <SandboxUrl> <LogoUrl> </CheckoutBrand> </Merchant> </MerchantUpload> Merchant Upload Sample Message Update 3-D Secure MasterCard and Visa NOTE: If the checkout brand exists for the update action, then the checkout ID is mandatory. <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload xmlns:xsi=" <Merchant> <SPMerchantId>022416_TESTMERCH</SPMerchantId> <Action>U</Action> <Profile> <Name>022416_TESTMERCH</Name> <DoingBusAs>022415testmerchant</DoingBusAs> <Url> <Address> <City>Padova</City> <Country>IT</Country> <Line1>Boettgerstr</Line1> <PostalCode>35129</PostalCode> </Address> <Phone> <CountryCode>39</CountryCode> <Number> </Number> </Phone> < s> </ s> </Profile> <CheckoutBrand> <CheckoutId>a4a6w4vr8jzii6j0wk2e1i6kx962m2gle</CheckoutId> <Name>022416_TESTMERCH</Name> <DisplayName>022416_TESTMERCH</DisplayName> <ProductionUrl> <SandboxUrl> </CheckoutBrand> <AuthOption> <CardBrand>MASTER_CARD</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <AuthOption> <CardBrand>VISA</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <MerchantAcquirer> <Acquirer> <Id>523078</Id> <Name>CartaSI</Name> <AssignedMerchantId>001</AssignedMerchantId> </Acquirer> Onboarding Version January

168 Appendix API-Based Merchant Onboarding <MerchantAcquirerBrand> <CardBrand>MASTER_CARD</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> <MerchantAcquirer> <Acquirer> <Id>453997</Id> <Name>CartaSI</Name> <AssignedMerchantId>011</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>VISA</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> </Merchant> </MerchantUpload> Merchant Upload Sample Message Delete non-3-d Secure <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload> <Merchant> <SPMerchantId>SPMerchantId1</SPMerchantId> <Action>D</Action> </Merchant> </MerchantUpload> Merchant Upload Sample Message Delete 3-D Secure <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantUpload xmlns:xsi=" <Merchant> <SPMerchantId>022416_TESTMERCH</SPMerchantId> <Action>D</Action> <Profile> <Name>022416_TESTMERCH</Name> <DoingBusAs>022415testmerchant</DoingBusAs> <Url> <Address> <City>Padova</City> <Country>IT</Country> <Line1>Boettgerstr</Line1> <PostalCode>35129</PostalCode> </Address> <Phone> <CountryCode>39</CountryCode> <Number> </Number> </Phone> < s> </ s> </Profile> <CheckoutBrand> <CheckoutId>a4a6w4vr8jzii6j0wk2e1i6kx962m2gle</CheckoutId> <Name>022416_TESTMERCH</Name> <DisplayName>022416_TESTMERCH</DisplayName> <ProductionUrl> <SandboxUrl> </CheckoutBrand> <AuthOption> <CardBrand>MASTER_CARD</CardBrand> Onboarding Version January

169 Appendix API-Based Merchant Onboarding <Type>ALL_TRANSACTIONS</Type> </AuthOption> <AuthOption> <CardBrand>VISA</CardBrand> <Type>ALL_TRANSACTIONS</Type> </AuthOption> <MerchantAcquirer> <Acquirer> <Id>523078</Id> <Name>CartaSI</Name> <AssignedMerchantId>001</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>MASTER_CARD</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> <MerchantAcquirer> <Acquirer> <Id>453997</Id> <Name>CartaSI</Name> <AssignedMerchantId>011</AssignedMerchantId> </Acquirer> <MerchantAcquirerBrand> <CardBrand>VISA</CardBrand> <Currency>EUR</Currency> </MerchantAcquirerBrand> </MerchantAcquirer> </Merchant> </MerchantUpload> Single-Merchant API Download Schema The Single-Merchant API is used by service providers to onboard merchant information one at a time to MasterPass through the Open Feed Project. The XML schema for the Single-Merchant API is the same as that used for the File-based merchant onboarding via the merchant and service provider portal. For more details, refer to Merchant Upload Schema and Merchant Download Schema. Child Node: Summary[1...1] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Summary.Batch Id Identifier for merchant onboarding request Integer M Summary.Descr iption Description to Onboarding request summary String M undefi ned undefi ned 1 50 Merchant File Upload Onboarding Version January

170 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Comment Summary.Uploa dtimestamp Upload Timestamp DateTi me M undefi ned undefi ned N/A N/A T11:45: :0 0 Summary.Uploa dfilename Upload File Name String M undefi ned undefi ned Summary.Succe sscount Success count of requested merchants to be onboarded Integer M undefi ned undefi ned N/A N/A 12 Summary.Failur ecount Failure Count of requested merchants to be onboarded Integer M undefi ned undefi ned N/A N/A 24 Summary.ErrorT ext Summary.Projec tkeys[1..1].san dboxkey Error text for the onboarding request Sandbox ConsumerKey of API client String O Invalid Format String M a78366f4 46c4a4b466e 4b c6b d Summary.Projec tkeys[1..1].prod uctionkey Production ConsumerKey of API client String M d f d9d Child Node: MerchantResponseRecord[0...*] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Example MerchantRespo nserecord.spm erchantid Merchant Identifier provided by the Service Provider String M 1 1 undefi ned undefi ned SPMerchantId 123 Onboarding Version January

171 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Example MerchantRespo nserecord.error Text MerchantRespo nserecord.che ckoutbrand[ 1...*].Name MerchantRespo nserecord.che ckoutbrand[1... * ].CheckoutId entifier MerchantRespo nserecord.che ckoutbrand[1... * ].ProductionU rl MerchantRespo nserecord.che ckoutbrand[1... * ].SandboxUrl MerchantRespo nserecord.che ckoutbrand[1... * ].ExtensionPoi nt Response Text from merchant onboarding request Name of the CheckoutBrand of the merchant Checkout identifierof the CheckoutBrand of the merchant Production checkout branding URL Sandbox checkout branding URL Data element to support unique use cases for merchant onboarding String M Error boarding merchant into 3-D Secure: Completed with errors String M TestCheckout Brand String M TestCheckoutI d String M xyzpizza.com String M test.xyzpizza.c om Object O 0 1 N/A N/A N/A MerchantRespo nserecord.mer chantacquirer[ 0..* ].ID MerchantRespo nserecord.mer chantacquirer[ 0..* ].Name ID of merchant acquirer for the specified card brand Name of merchant acquirer for the specified card brand String M String M TESTACQUIRE R Onboarding Version January

172 Appendix API-Based Merchant Onboarding Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Example MerchantRespo nserecord.mer chantacquirer[ 0..* ].Assigned MerchantID MerchantRespo nserecord.mer chantacquirer[ 0..* ].DSStatus ID of merchant acquirer for the specified card brand Status code of the merchant 3-D Secure setup on the Cardinal Directory Server String M TESTACQUIRE R String M SUBMITTED Child Node: ExtensionPoint[0...1] Data Field Name Description Type Mandato ry/ Optional Min Occur rence Max Occur rence Min Lengt h Max Lengt h Example MerchantRespo nserecord.exte nsionpoint Data element to support unique use cases for merchant onboarding Object O 0 1 N/A N/A N/A Single-Merchant API Download Sample Messages The Single-Merchant API is used by service providers to onboard merchant information one at a time to MasterPass through the Open Feed Project. Payload samples of the Single- Merchant API Download onboarding requests are as follows. Merchant Download Response Sample Message non-3-d Secure <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantDownload> <Summary> <BatchId>277800</BatchId> <Description>Merchant Upload</Description> <UploadTimestamp> T11:45: :00</UploadTimestamp> <UploadFileName>merchant_1.xml</UploadFileName> <SuccessCount>1</SuccessCount> <FailureCount>0</FailureCount> <ProjectKeys> Onboarding Version January

173 Appendix API-Based Merchant Onboarding <SandboxKey>41496b7a452f35764d b f3d</ SandboxKey> <ProductionKey>41496b7a452f35764d b f3d</ ProductionKey> </ProjectKeys> </Summary> <MerchantResponseRecord> <SPMerchantId>SPMerchantId1</SPMerchantId> <CheckoutBrand> <Name>XYZ Pizza</Name> <CheckoutIdentifier>a4a6x3oehb3fzh</CheckoutIdentifier> <ProductionUrl> <SandboxUrl> </CheckoutBrand> </MerchantResponseRecord> </MerchantDownload> Merchant Download Response Sample Message 3-D Secure <?xml version="1.0" encoding="utf-8" standalone="yes"?> <MerchantDownload Version="1.1"> <Summary> <BatchId> </BatchId> <Description>1P_Upload_MC_3DS.xml</Description> <UploadTimestamp> T15:00: :00</UploadTimestamp> <UploadFileName>1P_Upload_MC_3DS (1).xml</UploadFileName> <SuccessCount>1</SuccessCount> <FailureCount>0</FailureCount> <ProjectKeys> <SandboxKey>456d5a537a346c2f2b55644b b56673d3d</ SandboxKey> <ProductionKey>456d5a537a346c2f2b55644b b56673d3d</ ProductionKey> </ProjectKeys> </Summary> <MerchantResponseRecord> <SPMerchantId>022416_RAMA</SPMerchantId> <CheckoutBrand> <Name>022416_RAMA</Name> <CheckoutIdentifier>a4c411by7lob4i81xb6r41i820mw3n151</ CheckoutIdentifier> <ProductionUrl> <SandboxUrl> </CheckoutBrand> <MerchantAcquirer> <ID>523078</ID> <Name>CartaSI</Name> <AssignedMerchantID>001</AssignedMerchantID> <DSStatus>Not Submitted</DSStatus> </MerchantAcquirer> </MerchantResponseRecord> </MerchantDownload> Onboarding Version January

174 Appendix 3-D Secure Status 3-D Secure Status Service providers can include Advanced Authentication information as an XML element during the File-based and API-based merchant onboarding processes. This is done using the MerchantAcquirer element. For a description of the MerchantAcquirer element, refer to the Merchant Upload Schema Details. MasterCard uses a third party, Cardinal Commerce, to act as a Merchant Plug In (MPI) for the 3-D Secure step-up process. When used, 3-D Secure runs for all checkout transactions for the appropriate card brand. Where available, 3-D Secure may be opted into for MasterCard, Maestro, and Visa only. Once the File-based or API-based merchant onboarding process has been completed for a merchant, the service provider can check on the 3-D Secure status of the uploaded merchant. The possible 3-D Secure statuses are as follows: NOTSUBMITTED: Merchant s acquirer information has not been submitted to Cardinal Commerce SUBMITTED: Merchant s acquirer information has been submitted to Cardinal Commerce ACTIVE: The Merchant has been successfully registered in the Cardinal Commerce system, and the acquirer is participating. You are ready to process 3-D Secure production transactions ACQUIRERNOTPARTICIPATING: The acquirer ID (BIN) used in the merchant registration is not valid. Upon receiving this message, contact the implementation manager assigned to work with you on this implementation. If you don t have an assigned implementation manager, send an with the information listed in the Support section to merchant_testing_support@masterpass.com An uploaded Merchant 3-D Secure status can be checked using either of the following ways: 1. The Service Provider developer can click on the Download Result File button located with the Checkout Project used to upload the Merchant. Onboarding Version January

175 Appendix 3-D Secure Status The result file shows the current status of each Acquirer for the Merchant that was uploaded: 2. The Service Provider developer can use the Search button available at the top of the Checkout Project page: Onboarding Version January

176 Appendix 3-D Secure Status When the search bar pops up, enter the SPMerchantID of the uploaded merchant: The search output displays the current 3-D Secure status for the Merchant: Onboarding Version January

177 Appendix Renew Your Developer Zone Key Renew Your Developer Zone Key This section provides information on how to complete the key-renewal process on the MasterCard Developer Zone. Procedure 1. Login to MasterCard s Developer Zone ( 2. Click My Account, then My Dashboard. Onboarding Version January

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

179 Appendix Renew Your Developer Zone Key Notice the updated Key ID expiry date. Onboarding Version January

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