Masterpass Merchant Onboarding & Integration Guide · 2016. 9. 13. · Masterpass Merchant Onboarding & Integration Guide— U.S. Version 6.17 • 14 September 2016 2. ... Merchant

Masterpass MerchantOnboarding & Integration

GuideU.S. Version 6.17

14 September 2016

MTIG

Summary of Changes, 14 September 2016

This document reflects changes made since the previous publication. To locate these changesonline, click the hyperlinks in the following table.

Change Date Description of Change Where to Look

14 September 2016 Updated graphics and screenshotsof Masterpass user experiences toreflect the new Masterpass brandidentity.

Throughout document

10 August 2016 Replaced all references to the“Mastercard Developer Zone” with“Mastercard Developers” to reflectthe renaming of the site thatprovides services to developersseeking to add Mastercardcapabilities to their ownapplication(s); Mastercardreplatformed the site on 10 August2016.

Throughout document

10 August 2016 Revised the following sections toaccount for the replatform of thesite formerly known as MastercardDeveloper Zone:

• Create a Mastercard DevelopersAccount

• Generate Mastercard DevelopersAPI Key

• Renew a Mastercard DevelopersAPI Key

Create a MastercardDevelopers Account

Generate MastercardDevelopers API Key

Renew a MastercardDevelopers API Key

29 July 2016 Added a new section to makemerchants aware that some issuerstokenize their consumers’ paymentcredentials, how this might confusethe consumer and a merchant’sstaff, and what a merchant can doto help avoid this confusion.

Unique Masterpass WebTokenization Use Cases

29 July 2016 Added a note to the “Displaying the‘Masterpass Checkout’ Button andAcceptance Marks” and“Masterpass ‘Learn More’ Page”sections stating that Masterpass hasredesigned many digital assets withthe July 2016 Release.

Displaying the “MasterpassCheckout” Button andAcceptance Marks

Masterpass “Learn More”Page


©2014–2016 Mastercard. Proprietary. All rights reserved.Masterpass Merchant Onboarding & Integration Guide— U.S. Version 6.17 • 14 September 2016 2


29 July 2016 Revised the “Renew YourMastercard Developers Key” sectionto:

• Indicate that the MastercardDevelopers portal no longersupports the creation or renewalof keys using certificate signingrequest (CSR) files generatedwith MD5 digest.

• Provide troubleshootinginstructions for users who receivean error message when they tryto upload a CSR file.

Renew a MastercardDevelopers API Key

24 June 2016 Updated the Lightbox dimensionsprovided in the “Standard ‘LightboxDisplay’ (desktop and laptop)”section.

Standard “Lightbox Display”(desktop and laptop)

24 June 2016 Made the following updates to the“Standard Mobile Display (.mobi)”section:

• Updated height of the headerand footer of the mobileexperience.

• Inserted language indicating thatthere will be a landscape view formobile.

Standard Mobile Display(.mobi)

24 June 2016 Updated the “Standard Full-ScreenDisplay” section to indicate that thefull-screen view will always be usedfor Account Management (non-checkout) flows.

Standard Full-Screen Display

24 June 2016 Updated the “Sample Integration”subsection of the “Android and iOSApp Integration” section to indicatethat upon the user’s clicking ofMasterpass Checkout, the merchantapplication must redirect the user toa mobile browser that launches theMasterpass experience, and thatMasterpass does not supportwebview for in-app implementation.

Android and iOS AppIntegration




24 June 2016 Updated the “Masterpass SandboxTesting” section to indicate thatMasterpass has eliminated thefollowing pre-set Masterpass walletaccounts from use in the sandboxenvironment:

• [email protected]• [email protected]• 3ds.masterpass

[email protected]• 3ds.masterpass

[email protected]

Masterpass Sandbox Testing

24 June 2016 Added two new procedures thatU.S. merchants and service providersmust follow to conduct testing inthe sandbox environment.

• “Sign up for a Test MasterpassWallet Account during Checkoutand Test the UnrecognizedExperience”

• “Sign in to a Test MasterpassWallet Account during Checkoutand Test the RecognizedExperience”

Sign up for a Test MasterpassWallet Account duringCheckout and Test theUnrecognized Experience

Sign in to a Test MasterpassWallet Account duringCheckout and Test theRecognized Experience

24 June 2016 Replaced the test cases for bothMastercard SecureCode and Verifiedby Visa in the “3-D Secure TestCases” section.

3-D Secure Test Cases

24 June 2016 Added the following bullet to the“Checklist for Masterpass AssetPlacement”:

• Verify that the Masterpasscheckout button is usedappropriately on the checkoutpage to initiate the Masterpassexperience.

Checklist for Masterpass AssetPlacement




24 June 2016 Updated the following bullet in the“In-Wallet Experience” checklist toaccount for the required enablementof 3-D Secure for the Masterpasswallet:

• Merchants requesting liabilityshift for Masterpass transactionsshould use AdvancedCheckout/3-D Secure withinMasterpass. Merchants mustenable 3-D Secure such that it isinvoked within the Masterpasswallet.

In-Wallet Experience

24 June 2016 Added the following bullet to the“Post-Wallet Experience” checklist:

• Verify that any informationprovided by a consumer’sMasterpass wallet (for example,payment, shipping, profileinformation, and so on) is usedonly for that transaction and isnot stored for subsequent use.

Post-Wallet Experience

24 June 2016 Added the following bullet to the“Postback” checklist:

• Ensure that you are submittingpostback for all Masterpasstransactions initiated with theconsumer’s click of theMasterpass checkout button(approved, declined, orabandoned).

Postback




24 June 2016 Added the following bullet to the“General” checklist:

• Verify that your implementationfollows the standard process andutilizes all calls (to the Masterpasswallet, complete postback, andso on) for each and everytransaction initiated by aconsumer’s click of theMasterpass checkout button.

• Verify that you are accepting andpassing the wallet identifier(WID) when present forMasterpass transactions.

General

11 May 2016 Added onboarding content to reflectchanges to the Merchant Portal,including updates to theAuthentication Settings page andnew logic related to AdvancedCheckout.

Added and updated integrationcontent to reflect changes to 3-DSecure authentication.

Updated the EciFlag andPaResStatus elements in the

Checkout Resource section of theAppendix to reflect 3-D Secureupdates.

Merchant Registration andSetup—Merchant Activity


3-D Secure Overview

Checkout Resource

12 April 2016 Further updates to integrationcontent throughout the guide toreflect changes that applyspecifically to U.S. merchants.

Added content to the integrationsteps to reflect updates to theLightbox integration andAndroid/iOS integration.

Overview MasterpassCheckout Experiences

Direct Merchant Onboarding

Direct Merchant Onboarding -Steps

Integration Process

Android and iOS AppIntegration

Masterpass Branding

Appendix




15 March 2016 Updated integration contentthroughout the guide to reflectchanges that apply specifically toU.S. merchants. Updatedonboarding content to reflect a newand improved workflow within themerchant portal.

Overview MasterpassCheckout Experiences


Direct Merchant Onboarding -Steps

Integration Process

Masterpass Branding

Appendix



Contents

Summary of Changes, 14 September 2016.....................................................2

Chapter 1: Overview................................................................................................ 11Reflecting 2016 U.S. Masterpass Enhancements in This Guide..........................................12How does Masterpass Work?........................................................................................... 12

Masterpass User Interface............................................................................................12

Chapter 2: Masterpass Checkout Experiences............................................ 16Masterpass Merchant Standard Checkout Process Flow.................................................... 17Android Merchant App-to-Wallet App Checkout..............................................................23

Chapter 3: Direct Merchant Onboarding....................................................... 24Incorporating Masterpass into Your Site or App................................................................25

Chapter 4: Direct Merchant Onboarding - Steps........................................28Merchant Registration and Setup—Merchant Activity.......................................................29Add Developer to Merchant Profile—Merchant Activity.................................................... 41Developer Registration, API Keys, Initiate Development—Developer Activity..................... 43

Masterpass Merchant Portal Developer Account.......................................................... 43Create a Mastercard Developers Account.....................................................................44Generate Mastercard Developers API Key.....................................................................45Initiate Development and Masterpass Implementation................................................. 48Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) ..............48

Review Key Request and Approve/Deny—Merchant Activity............................................. 52Deploy Application Using Production Credentials—Developer Activity.............................. 54

Chapter 5: Integration Process............................................................................56Lightbox Integration.........................................................................................................57Standard checkout........................................................................................................... 59

Standard Checkout Callback........................................................................................59Implementing DSRP..................................................................................................... 60Split/Partial Shipments and Recurring Payment Transactions......................................... 733-D Secure Considerations...........................................................................................73Testing DSRP................................................................................................................73Masterpass Service Descriptions...................................................................................73Android and iOS App Integration ................................................................................77

Completing the Integration.............................................................................................. 80

Contents


Chapter 6: Masterpass Branding........................................................................81Displaying the “Masterpass Checkout” Button and Acceptance Marks.............................82

Masterpass Checkout Button Example......................................................................... 83Dynamic Checkout Button...........................................................................................84

Masterpass “Learn More” Page........................................................................................84

Chapter 7: Testing......................................................................................................85Masterpass Sandbox Testing.............................................................................................86

Sign up for a Test Masterpass Wallet Account during Checkout and Test theUnrecognized Experience.............................................................................................86Sign in to a Test Masterpass Wallet Account during Checkout and Test theRecognized Experience................................................................................................ 88

3-D Secure Test Cases...................................................................................................... 89Q/A Checklist................................................................................................................... 92

Checklist for Masterpass Asset Placement....................................................................92In-Wallet Experience.................................................................................................... 92Post-Wallet Experience.................................................................................................92Postback......................................................................................................................93General....................................................................................................................... 93

Chapter 8: Troubleshooting..................................................................................94Common Errors................................................................................................................95Support............................................................................................................................95

Appendix A: Appendix............................................................................................97Lightbox Parameters.........................................................................................................98OAuth Samples.............................................................................................................. 100

Request Token........................................................................................................... 100Merchant Initialization Service....................................................................................102Shopping Cart Service Parameters............................................................................. 106Access Token Service................................................................................................. 111Checkout Resource....................................................................................................113Postback Service........................................................................................................ 127

Renew a Mastercard Developers API Key........................................................................ 136Mastercard Developers Key Tool Utility........................................................................... 1403-D Secure Overview......................................................................................................141

3-D Secure Service Description...................................................................................141General Overview of Mastercard SecureCode and Verified by Visa TransactionAuthentication.......................................................................................................... 142

Contents


Important Merchant Information............................................................................... 143

Notices...........................................................................................................................145

Contents


Chapter 1 OverviewThis document is intended to orient merchants and their developers seeking to integrateMasterpass™ as a checkout option on their website and mobile application.

Reflecting 2016 U.S. Masterpass Enhancements in This Guide.......................................................12How does Masterpass Work?........................................................................................................12

Masterpass User Interface.........................................................................................................12Standard “Lightbox Display” (desktop and laptop)...............................................................13Standard Mobile Display (.mobi).......................................................................................... 14Standard Full-Screen Display................................................................................................ 14

Overview


Reflecting 2016 U.S. Masterpass Enhancements in This Guide

With Masterpass’s focus on continuous product improvement and user experienceoptimization, we have identified key enhancement opportunities that will be launched in Q22016. Therefore, this guide is specifically targeted to U.S. merchants and serviceproviders that will be implementing Masterpass in/after Q2 2016. For additional details,work with your regional Masterpass representative or Implementation Manager.

NOTE: This is a preliminary version of the document and may undergo revisions.

How does Masterpass Work?

Masterpass™ is a wallet service that enables consumers to store, manage and securely sharetheir payment information, shipping information, and billing address with the websites andmobile apps they transact with. Masterpass supports checkout on full and mobile websites, aswell as in-app purchases on Android™ and iOS™ apps. In addition, Masterpass recently addedthe ability to quickly implement native, app-to-app checkout experiences with EMV-likesecurity within Android smartphone applications.

NOTE: In Q2 2016 , Masterpass is bringing a highly enhanced consumer experience and we areworking towards a full product redesign to support that. As part of the redesign, Masterpasswill be updating core wallet features, as well as intelligent wallet routing and securityfeatures to deliver a more seamless user experience that enables fast checkout. We are alsointroducing a new checkout button design, along with an ability to display a personalizeddynamic checkout button based on consumers past wallet usage. The dynamic checkoutbutton capability is currently available to select wallet providers. We are also reassessingcertain features, such as loyalty/rewards, pairing, the shopping cart experience, andConnected checkout. As a result, these features will be unavailable to U.S. merchants/serviceproviders.

Masterpass User InterfaceThe Masterpass™ user interface, or Lightbox, floats the Masterpass wallet interface on top ofthe merchant’s web page through illuminated overlays, and backgrounds dimmed to 0.7opacity. This modern method allows a consumer to interact with their Masterpass digitalwallet without having to leave the merchant’s page. The Masterpass Lightbox is built in aresponsive design style allowing it to respond dynamically to the various screen sizes andorientations.

Masterpass supports the following displays:

OverviewReflecting 2016 U.S. Masterpass Enhancements in This Guide


• 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 Lightboxdimensions are 730 pixels (height) by 680 pixels (width). This is inclusive of the height of theLightbox header (60 pixels) and footer (30 pixels). The interior Lightbox dimensions are 640pixels (height) by 680 pixels (width).

If the height of the browser is reduced to 800 pixels or less and the width is maintained atgreater than 680 pixels, the entire Lightbox has an outer frame height of 620 pixels. TheLightbox header and footer heights are maintained at 60 pixels and 30 pixels, respectively, butthe content container (wallet frame) has dimensions of 530 pixels (height) by 680 pixels(width).

If the browser is set to 100% maximum width but is less than 620 pixels in height, verticalscrolling will appear.

If the browser is set to less than 680 pixels in width the Lightbox layout will change toaccommodate small screen formats (for example, phones and smaller tablets). There is a 320pixel width threshold for the content container.

OverviewHow does Masterpass Work?


Standard Mobile Display (.mobi)Within the .mobi experience, the height of the header and footer are 50 pixels and 23 pixels,respectively.

The interior content area for mobile devices is content-dependent. The initial view of contentis based on the overall screen sizes. Content that does not fit within the initial view of contentcan be accessed by scrolling. There will be a landscape view for mobile.The mobile interfacefills the screen and does not use modal windows such as the Lightbox display.

Standard Full-Screen DisplaySpecial conditions apply to the standard full-screen display.

Under certain conditions, such as the following:

1. The consumer’s browser does not support the Lightbox display (older browser)2. The merchant has not yet made coding changes to invoke the Lightbox display3. The URL requesting the Lightbox display is different from the merchant-specified origin

URL4. Third-party cookies are blocked by the browser (currently Safari® versions 8 and higher)5. The consumer is managing their wallet account (non-checkout/masterpass.com).

Masterpass will render the wallet experience in full screen as our Lightbox experience requiresMasterpass cookies to be dropped in the browser. In the case of scenario four above, we areable to drop cookies during the full-screen redirect experience, and subsequent Masterpasscheckouts on that browser will show the Lightbox experience. For Account Management(non-checkout) flows, the full-screen view will always be used.





Chapter 2 Masterpass Checkout ExperiencesThis section provides information on the Masterpass™ checkout experiences.

Masterpass Merchant Standard Checkout Process Flow.................................................................17Android Merchant App-to-Wallet App Checkout...........................................................................23

Masterpass Checkout Experiences


Masterpass Merchant Standard Checkout Process Flow

The Masterpass checkout flow is triggered when the consumer clicks the MasterpassCheckout button.

The following diagram illustrates the standard Masterpass™ checkout process flow with theMasterpass Lightbox UI. The merchant must use this process flow for a non-registered (guest)user.

NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must usethe Merchant Initialization service to send the Origin URL.

Masterpass Checkout ExperiencesMasterpass Merchant Standard Checkout Process Flow


The following steps explain the standard Masterpass checkout process flow:

NOTE: The product images in the following graphics are blurred for trademark reasons.

1. The consumer clicks the Masterpass Checkout button.



2. The consumer logs in to their wallet.



3. The consumer selects their payment method and shipping address.

4. The consumer reviews and submits the order.



5. The merchant confirms the order.



The following diagram illustrates the standard checkout process flow:

NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchants must usethe Merchant Initialization service to send the Origin URL.



Android Merchant App-to-Wallet App Checkout

Starting in 2016, Masterpass™ is introducing a multi-channel checkout solution that allowsmerchants to integrate Masterpass as a secure checkout experience within their nativeAndroid™ applications.

This checkout solution provides merchants with (a) a simplified, unified checkout experienceacross all merchant channels, including in-store contactless and in-app, and (b) the ability togenerate transactions that are secured with Digital Secure Remote Payment (DSRP).

DSRP is a Mastercard payment solution through which card-not-present merchants benefitfrom the dynamic secure data generated by contactless M/Chip applications. DSRPtransactions contain dynamic data (cryptograms) generated by a payment application usingEMV-based cryptography.

Currently, DSRP cryptograms can only be generated for transactions initiated on an Androidmobile app or mobile browser that has incorporated the Masterpass Mobile Checkout SDK,and transactions completed on a Masterpass Android wallet application (this will be availablefor other types of transactions later this year). If Mobile Checkout is available in your country,refer to the Masterpass Android Checkout Sample App page on GitHub.

Masterpass Checkout ExperiencesAndroid Merchant App-to-Wallet App Checkout


https://github.com/MasterCard/masterpass-android-sample-app

Chapter 3 Direct Merchant OnboardingThis topic provides information about the direct merchant onboarding process.

Incorporating Masterpass into Your Site or App.............................................................................25



Incorporating Masterpass into Your Site or App

Enabling checkout with Masterpass™ on your site or mobile app is straightforward; here is anoverview of the required activities.

Direct Merchant OnboardingIncorporating Masterpass into Your Site or App


Activity Actor Steps Environment

1. MerchantRegistration & Setup

Merchant Create Merchantaccount, set shippingprofile, and advancedauthentication

Masterpass MerchantPortal

2. Add Developer toMerchant Profile

Merchant Invite developers tomanage integration


3. DeveloperRegistration

Developer Log in to MasterpassDeveloper account thatis created upon invite


Create consumer keyrequests and submit toservice provider businessowner

Create MastercardDevelopers account

Mastercard Developers

Generate developer’ssandbox and productionkeys

Review samplecode/SDK and designservices integration

4. Review and approvesandbox and/orproduction consumerkey approval request

Merchant BusinessOwner

Approve consumer keyrequest(s)


5. Test Integration inSandbox

Developer Obtain checkout IDs foreach successfullyprovisioned merchantfrom results file. Mapeach checkout ID to thecorrect merchant.


Test against Masterpasssandbox environment

Service ProviderEngineeringEnvironment

6. Access SandboxCredentials

Developer Use merchant’s sandboxconsumer key to testagainst Masterpasssandbox environment

Merchant EngineeringEnvironment



https://masterpass.com/SP/Merchant/Home






https://developer.mastercard.com





Activity Actor Steps Environment

7. Production Migration Developer Update Masterpass APIendpoints, consumerkey, callback URL andprivate key (p12), ifdifferent than Sandbox

Merchant

Production Environment

The following accounts will be created during this onboarding process. Use the followingtable to record the account information for future reference.

Account Type Details Account Info

Merchant Portal - Merchantaccount

Created by merchant businessowner. This will be

used to login at https://masterpass.com/SP/Merchant/Home

Go here to create merchantaccount, invite developers,create shipping profiles, approveconsumer keys, and so on.

Userid: __________

Email: ___________

Merchant Portal - DeveloperAccount(s)

A system-generated ID createdwhen a merchant invites adeveloper. This ID will be used tologin at https://masterpass.com/SP/Merchant/Home

Go here to submit and view keyapprovals, retrieve consumerkeys, and checkout identifier(s).

Userid: __________

Email: ___________

Mastercard Developers -Developer Account(s)

Created by developer and is usedfor developer API keygeneration. This ID will be usedto login at https://developer.mastercard.com

Go here to generate developerAPI keys and download sampleapplications and other resourcesand documentation.

Userid: __________

Email: ___________











Chapter 4 Direct Merchant Onboarding - StepsThis section provides instructions that merchants and their developers must complete to integrateMasterpass™ as a checkout option on their website and mobile application.

Merchant Registration and Setup—Merchant Activity....................................................................29Add Developer to Merchant Profile—Merchant Activity.................................................................41Developer Registration, API Keys, Initiate Development—Developer Activity.................................. 43

Masterpass Merchant Portal Developer Account....................................................................... 43Create a Mastercard Developers Account................................................................................. 44Generate Mastercard Developers API Key................................................................................. 45Initiate Development and Masterpass Implementation.............................................................. 48Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers) ...........................48

Review Key Request and Approve/Deny—Merchant Activity..........................................................52Deploy Application Using Production Credentials—Developer Activity........................................... 54

Direct Merchant Onboarding - Steps


Merchant Registration and Setup—Merchant Activity

Before beginning this process, request an invitation code from your Mastercard representative;this will grant you access and allow you to register within the merchant portal.

About this taskDevelopers invited to integrate Masterpass on behalf of a service provider will manage theirintegration activities through following portals.

• Masterpass Merchant Portal (https://masterpass.com/SP/Merchant/Home)• Mastercard Developers (http://developer.mastercard.com)

Procedure

1. From the Masterpass Merchant Portal, select the country – language from the dropdownand click the Create an Account button to start the registration process.

2. You will be presented with a modal window, into which you will enter the invitation code

and click the Continue button.

NOTE: Merchant invitation codes should begin with the prefix MT. Please verify that youhave the invitation code with the correct prefix.

Direct Merchant Onboarding - StepsMerchant Registration and Setup—Merchant Activity



http://developer.mastercard.com


After entering the invitation code, you will be presented with the option to select theregistration type.

3. Select Merchant to continue with the registration process. If you need to register as aService Provider, access the Service Provider Integration Guide(s).

4. Complete all of the required fields in the Enter Account Information screen.

5. From the Enter Security Information screen, choose your security questions and enter

the answers.



6. Complete all of the required fields on the Enter Business Information screen.

7. To enter the merchant assets (for example, name, logo) that will be displayed to

consumers in their Masterpass wallets during checkout, click Digital Assets.

Enter merchant display name, domain-level URL, an alias identifying this set of digitalassets (for example, website or Android app ), an optional description of the merchant’sgoods/services. If no logo is provided, only the merchant name will be displayed in theconsumers’ Masterpass wallets during registration and checkout.



NOTE:

– Merchants doing business in the U.S. only should enter the display name and an alias,(but not the display logo).

– The Masterpass Merchant Portal is currently being redesigned, and parts of theinterface may vary during the transition to the new experience.

Once this information has been entered, a checkout identifier will be generated for thedeveloper to use during the integration process.



To edit this information at any time, click the View link.

NOTE: Merchant administrators and/or developers can enter and edit this information.

8. After the merchant account has been created and the digital assets provided, selectShipping Profiles to indicate the countries to which your company ships your goods.

NOTE: The Masterpass Merchant Portal is currently being redesigned, and parts of theinterface may vary during the transition to the new experience.



Merchants must have at least one shipping profile (and no more than 25).9. Merchants may set a default shipping profile by clicking the box next to Save as Default.




NOTE: U.S. merchants—Please do not enter loyalty information in the loyalty/rewardsmodule you see in the portal. This functionality is no longer available to U.S. merchantsand is being reassessed for future use.

10. If 3-D Secure is not available to you, you will not see the Authentication Settings

option. If the option is available in your country, select Authentication Settings toenable 3-D Secure Authentication. Where available, 3-D Secure can be enabled forMastercard (which includes Maestro) and Visa cards. 3-D Secure authentication allowsmerchants to gain liability shift on fraudulent ecommerce transactions.

You will first need to supply the details of your merchant acquirer accounts



11. To add an acquirer, select Add Acquirers. Complete the form, including acquirer name and

ID number, your assigned merchant ID, and supported currencies under that acquirer.

NOTE: Mastercard SecureCode is used to set up acquirers for both Mastercard andMaestro transactions.



Once saved, successfully added acquirer profiles will appear on the page by card brand. Tocomplete the setup for 3-D Secure, select the Advanced Checkout check box for eachcard brand to enable 3-D Secure for that brand.

NOTE: If you enable your account for 3-D Secure, you will have the option to out of 3-DSecure checkout by clearing the Advanced Checkout check box on this page.



Results

Mastercard uses a third party, Cardinal Commerce, to act as a Merchant Plug In (MPI) for the3-D Secure step-up process. When set up, the 3-D Secure user interface will be involved for allcheckout transactions for the selected card brand.

The 3-D Secure onboarding status for an acquiring account will be provided in the acquirer listunder each card brand.



The possible merchant 3-D Secure statuses are as follows:

• SUBMITTED: The merchant's acquirer information has been submitted to CardinalCommerce.

• ACQUIRER PENDING: Cardinal Commerce is in the process of onboarding the merchantto its system, and the merchant’s acquirer information has been sent to the card brandcompany and is waiting completion.

• ACTIVE: The merchant has been successfully registered in the Cardinal Commerce system,and the acquirer is participating. You are ready to process 3-D Secure productiontransactions.

• ACQUIRER NOT SUPPORTED: The acquirer ID (BIN) used in the merchant registration isnot valid. Upon receiving this message, you will receive an email from MasterpassMerchant support team attached with an unknown acquirer form.



When adding your acquirer accounts, it is possible that your acquirer has not previously beenonboarded to Cardinal’s system. In this case, you will need to download and complete theAcquirer Certificate Request and submit it to Cardinal Commerce for processing. The formwill be available in the portal upon submission of an unrecognized acquirer ID and will be sentto you by email. Acquirer setup may take 3–5 business days once the Acquirer CertificateRequest is returned to Cardinal.



Add Developer to Merchant Profile—Merchant Activity

The next step in setting up Masterpass™ for your business is to add the developers who willintegrate Masterpass into your checkout flow.

About this task

From the landing page, you will add developers to the merchant profile. These developers willhandle the technical implementation of Masterpass for your site/app.

Procedure

1. To get started, click the Start This Step button under the 2. Add developers option onthe Masterpass Setup page.

2. You will need to indicate who will perform the technical integration. On the Developers

page, click on the Add a Developer button.

Direct Merchant Onboarding - StepsAdd Developer to Merchant Profile—Merchant Activity


3. Merchants that have an internal or contracted engineering team should select An

internal or contracted developer.

4. Provide contact information for each developer you want to invite and click Complete.

Direct Merchant Onboarding - StepsAdd Developer to Merchant Profile—Merchant Activity


ResultsMasterpass will send two separate emails to each newly added developer indicating thathe/she has been invited to handle the technical integration of Masterpass on behalf of yourcompany. These emails will contain the username and password to log in to the MasterpassMerchant Portal, along with links to the Masterpass integration guides that developers canuse to get started with Masterpass integration.

Developer Registration, API Keys, Initiate Development—DeveloperActivity

Developers invited to integrate Masterpass on behalf of a merchant will manage theirintegration activities through two portals.

• Masterpass Merchant Portal (https://masterpass.com/SP/Merchant/Home)• Mastercard Developers (http://developer.mastercard.com)

NOTE: These are two different websites that use different login credentials. If you are a newdeveloper for Masterpass, you must sign up for a Mastercard Developers account.

Masterpass Merchant Portal Developer AccountDevelopers will use the Masterpass™ merchant portal to request and access merchant-specificintegration credentials (consumer keys and checkout identifiers), which will be used wheninteracting with the Masterpass services.

After the merchant invites you as a developer, you will receive your Masterpass MerchantPortal credentials in two emails from Masterpass. Follow the instructions in the emails tocreate your developer account. You will find links to the Masterpass integration guides in theinvitation emails you receive from Masterpass and on the landing page once you sign intoyour developer account on the Masterpass Merchant Portal. You do not need a MastercardDevelopers account to view this documentation.

Direct Merchant Onboarding - StepsDeveloper Registration, API Keys, Initiate Development—Developer Activity



http://developer.mastercard.com

Create a Mastercard Developers AccountDevelopers invited to integrate Masterpass™ on behalf of a merchant will use the MastercardDevelopers site to view integration documentation and generate developer keys. Completethe following steps to create your Mastercard Developers account and access these tools.

Procedure

1. From the Manage Development page of the Masterpass Merchant Portal, click StartThis Step under the Register on Developer Zone option, or go to https://developer.mastercard.com.

2. From the main page of the Mastercard Developers site, click Sign Up.

3. Complete and submit the registration form.





After submitting the form, you will receive a confirmation email.

4. Activate your Mastercard Developers profile by clicking on the link included in theconfirmation email.

Generate Mastercard Developers API KeyAfter creating your Mastercard Developers account, you will need to create API keys for boththe sandbox and production environments by completing the following steps.

Procedure

1. Click My Projects.



2. On the My Projects page, click on the Masterpass Merchant Keys button.

3. Confirm that you understand the process that you must complete before beginning work

on your Masterpass project by clicking on the Okay, got it button.



4. Under Complete Your Profile, enter your name, address, and phone number, and click

Next.5. Under Create Sandbox Key, enter an alias and password for your sandbox key, and click

Download Key and Continue.A P12 certificate file for your sandbox key will automatically be downloaded to yourpersonal computer.

6. Under Create Production Key, enter an alias and password for your production key, andclick Download Key and Continue.A P12 certificate file for your production key will automatically be downloaded to yourpersonal computer.

Results

At this point, developers will have a Sandbox Key ID and a Production Key ID, which will beused when submitting key approvals in the Masterpass Merchant Portal.



NOTE: Keys expire after one year before which they should be renewed by completing the Renew a Mastercard Developers API Key process. As of July 2016, the Mastercard Developersportal no longer supports the creation or renewal of the Certificate Signing Request (CSR)generated with MD5 digest. Notifications at 30, 15, and one day prior to key expiration willbe sent to the email address associated with the Mastercard Developers account. When thekeys expire, Masterpass transactions will fail. Therefore the keys need to be renewed prior toexpiration.

Initiate Development and Masterpass ImplementationOnce a developer has generated their Mastercard Developers API keys, they can begindeveloping their own implementation.

NOTE: All methods and flows in the current sample app available in the SDK for Masterpassmay not fully apply to U.S. service providers and merchants. For further guidance with yourimplementation, follow the integration guide and, if you need assistance, contact Masterpasssupport.

Masterpass follows the OAuth 1.0a specification. Any merchant or service provider integratingwith Masterpass must strictly adhere to the OAuth specs for interacting with Masterpassthrough Open API Gateway. Failure to implement OAuth correctly may impact yourintegration and transactions with Masterpass. For more details, refer to the Whatauthentication requirements are there to use the raw REST protocol? page on the MastercardDevelopers site.

Obtaining Integration Credentials (Consumer Keys and Checkout Identifiers)Prior to allowing the developer’s code to interact with the Masterpass™ services, the merchantadministrator must approve a request to link the developer’s API keys created by the developer



https://mastercarddevelopersupport.desk.com/customer/portal/articles/2477007-what-authentication-requirements-are-there-to-use-the-raw-rest-protocol

https://mastercarddevelopersupport.desk.com/customer/portal/articles/2477007-what-authentication-requirements-are-there-to-use-the-raw-rest-protocol

from the Mastercard Developers site with the merchant identifier to create credentials calledconsumer keys.

About this task

Typically, the developer will make two separate key approval requests:

• Request to generate a consumer key that will grant the developer access to the Masterpasssandbox environment on behalf of the merchant

NOTE: The sandbox environment does not contain real consumer data.

• Request to generate a consumer key that will grant the developer access to the productionenvironment to enable real transactions

Developers will use the Masterpass Merchant Portal to request and access merchant-specificintegration credentials which will be used when interacting with the Masterpass services. Theconsumer keys are generated by requesting key approval from the merchant administrator inthe Key Management module; the checkout identifiers are generated in the Digital Assetsmodule.

Procedure

1. To get started, sign into the Masterpass Merchant Portal. Under Manage Development,click Key Management to open an interface with Mastercard Developers, enter yourMastercard Developers credentials, and click Sign In.

NOTE: If you have not already set up your Mastercard Developers account, click here.




http://developer.mastercard.com/

2. After you have entered your Mastercard Developers information, to create a sandbox orproduction key, click Create Consumer Key .

3. Select the key type (as in, sandbox or production), and then click Continue.4. After clicking Browse Keys, a list of all the keys of the specified type you have in your

Mastercard Developers account is displayed; select the key you want to associate with themerchant’s Masterpass integration.

Click Submit for Approval; an email will be sent to the merchant administrator forapproval. Upon approval, Masterpass consumer keys will be generated for the selectedenvironment and will be displayed on this page. These keys, along with the checkoutidentifier (refer to Digital Assets section below) are required to make Masterpass calls insandbox and production environments.



5. Repeat the steps above as needed to generate additional keys. Typically, developers need

at least one sandbox and one production key for each merchant integration.6. To generate or view a checkout identifier, under Manage Development, click Digital

Assets. If the merchant administrator has previously input data for the required fields forthis module during registration, the checkout identifier(s) will be displayed on the mainpage.


If the merchant administrator has requested that the developer input the merchant assets(for example, name, logo) on behalf of the merchant, click Add Assets, and enter themerchant display name, an alias identifying this set of digital assets (for example, websiteor Android app ), and an optional description of the merchant’s goods/services. If no logois provided, only the merchant name will be displayed in consumers’ Masterpass walletsduring registration and checkout.



NOTE: If no logo is provided, the merchant name will be displayed.

Review Key Request and Approve/Deny—Merchant Activity

After the developer submits the request for sandbox and production credentials, the merchantadministrator will receive an email notification.

Procedure

1. Upon receipt of the email notification that a developer has submitted a key request foryour approval, log on to the portal and click Key Management.

Direct Merchant Onboarding - StepsReview Key Request and Approve/Deny—Merchant Activity


2. Click the down arrow to the right of the developer’s name to view the details of therequest (environment, key alias, key status, date of expiration, and the consumer key).

3. To approve the developer’s request for a new key, click Approve, or to reject the request,

click Deny. The key status will update on the portal UI for the administrator as well as forthe requesting developer. An email notification will also be sent to the requestingdeveloper notifying him/her that the approval request has been completed. If the requestwas approved, the developer will also be able to see the system-generated consumer keythat is needed to interacted with the Masterpass services.

Direct Merchant Onboarding - StepsReview Key Request and Approve/Deny—Merchant Activity


Deploy Application Using Production Credentials—Developer Activity

Once the digital assets have been entered and the checkout identifier generated, and the keyapprovals have been completed and the consumer keys generated, the developer has thesystem-generated credentials needed to communicate with the Masterpass services.

Procedure

1. Prior to production deployment, ensure that (a) you have implemented the Masterpassbutton on your site or app and (b) your sandbox implementation passes all items in the QA checklist.

2. To move your code to production, update your code with the following:

– Masterpass production endpoint– Merchant’s production consumer key– Production callback URL– Keystore (if different than Sandbox)

3. The last step is to deploy your code to production.

Direct Merchant Onboarding - StepsDeploy Application Using Production Credentials—Developer Activity


NOTE: For more details on the specific configuration parameters, refer to the MasterpassCheckout FAQs page and look for the question, “What are the various parameters I needto call Masterpass services, and where do I get them from?”

Direct Merchant Onboarding - StepsDeploy Application Using Production Credentials—Developer Activity


https://developer.mastercard.com/page/masterpass-checkout-faqs


Chapter 5 Integration ProcessThis topic provides information on the Masterpass™ integration process.

Lightbox Integration......................................................................................................................57Standard checkout........................................................................................................................59

Standard Checkout Callback.................................................................................................... 59Implementing DSRP..................................................................................................................60

Unique Masterpass Web Tokenization Use Cases................................................................. 61DSRP Extension Points in the Masterpass Merchant API........................................................62DSRP Extension Points in the Masterpass Checkout XML......................................................65Tokenization Extension Points in the Masterpass Checkout XML...........................................70

Split/Partial Shipments and Recurring Payment Transactions......................................................733-D Secure Considerations....................................................................................................... 73Testing DSRP............................................................................................................................ 73Masterpass Service Descriptions................................................................................................73

Request Token Service..........................................................................................................73Shopping Cart Service..........................................................................................................74Merchant Initialization Service .............................................................................................74Access Token Service............................................................................................................74Retrieve Payment, Shipping Data, and 3-D Secure Details.....................................................75Postback Service.................................................................................................................. 76

Android and iOS App Integration ............................................................................................ 77Completing the Integration...........................................................................................................80

Integration Process


NOTE: All methods and flows in the current sample app available in the SDK for Masterpass maynot fully apply to U.S. Service Providers and merchants. For further guidance with yourimplementation, please follow the integration guide, and if you need assistance, please contactMasterpass support.

Lightbox Integration

Lightbox integration is required to launch the Masterpass user interface.

Procedure

1. To invoke the Lightbox, merchants must include the following scripts to the page onwhich they are adding the Masterpass Checkout button.

NOTE: Merchants invoking the Lightbox from an iFrame must include both the sandboxand production scripts on the parent (outer) web page and the iFrame source that isinvoking Masterpass Lightbox.

a. Add jQuery. Include this jQuery file from the public jQuery repository:

https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.jsb. Add the Masterpass Integration Script to your checkout page.

– Sandbox

https://sandbox.static.masterpass.com/dyn/js/switch/integration/Masterpass.client.js

– Production

https://static.masterpass.com/dyn/js/switch/integration/Masterpass.client.js

2. Add the Masterpass Checkout Button to your checkout page.<imgsrc = https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_147x034px.pngid = "_masterpass_checkout_btn" />

NOTE: Be sure to change the image name to the image size and locale that you would liketo use. For further details, refer to Masterpass Branding.

3. Launch Masterpass checkout on the click of the button.

Integration ProcessLightbox Integration


Parameters for Invoking Masterpass Checkout

Parameter Data Type Required Description

requestToken String Yes Your request token fromthe Standard Checkoutflow

callbackUrl String Yes The URL to which thebrowser must redirectwhen checkout iscomplete

NOTE:

This is required even if youuse callback functions.

merchantCheckoutId String Yes Your unique checkoutidentifier from theMasterpass MerchantPortal

allowedCardTypes String array No Card types accepted bymerchant

Version String No (default: v6) Masterpass API Version

successCalback Function No The function that will becalled if the Masterpassflow ends successfully

failureCallback Function No The function that will becalled if the Masterpassflow ends in a failure

Integration ProcessLightbox Integration



cancelCallback Function No The function that will becalled if the user cancelsthe Masterpass flow

4. Handle the callback on completion of checkout.

On completion of checkout (success, failure or cancellation), the control will be transferredto your system either via the callback url or the callback functions.

NOTE: If Masterpass is forced to go full screen, then you will not be able to call theJavaScript callback method and must use a merchant callback redirect. As a result, youmust support always support the callback url redirect.

Standard checkout

The following steps are necessary to integrate a standard Masterpass checkout.

For more details, click on each of the following steps:

1. Request Token Service2. Shopping Cart Service3. Merchant Initialization Service4. Invoke Masterpass UI (Lightbox) for checkout5. Standard Callback method and Redirect to callback URL6. Access Token Service7. Retrieve Payment, Shipping Data, and 3DS Details8. Authorize Payment through payment processor9. Postback Service

NOTE: Origin URL can no longer be sent along with the Shopping Cart. Merchant must use theMerchant Initialization service to send the Origin URL.

Standard Checkout CallbackOnce a checkout is completed, Masterpass™ will return context to the merchant.

This can be done via the following:

NOTE: If Masterpass is forced to go full screen, then you will not be able to call the JavaScriptcallback method and must use a merchant callback redirect. As a result, you must supportboth the callback method and the redirect.

• A callback URL: Masterpass uses the callback URL ( callbackUrl ) parameter passed wheninvoking lightbox or oauth_callback from the request token call to direct back to themerchant site when lightbox is rendered in full-screen mode.

Integration ProcessStandard checkout


• A JavaScript callback method: Use the failureCallback and successCallbackparameters to give control back to the page that initiated the Lightbox without anyredirects. These parameters must be set when invoking the Masterpass lightbox userinterface. Use the cancelCallback parameter to notify a Masterpass merchant that aconsumer has canceled their transaction.

Callback Parameters for Standard Checkout


mpstatus String Success, Failure,Cancel

Indicates whether theMasterpass flow wascompleted and results insuccess, failure or cancel

oauth_token String Used in conjunction withoauth_verifier to retrievethe access token

oauth_verifier String Used in conjunction withoauth_token to retrieve theaccess token

checkout_resource_url String API URL to retrievecheckout information

Example of Callback URL (Successful Transaction)

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=successcheckout_resource_url=https%3A%2F%2Fapi.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F17%3Fwallet%3Dphw&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc

Example of Callback URL (Cancelled Transaction)

http://www.somemerchant.com/checkoutcomplete.htm?mpstatus=cancel

Example of Callback Function

function handleCallbackSuccess (data) { callYourServerWith(data.oauth_token, data.oauth_verifier, data.checkout_resource_ur);}

Implementing DSRPA Masterpass™ transaction must meet the following conditions to be processed as a DigitalSecure Remote Payment (DSRP) transaction.

• The merchant must have successfully implemented Masterpass Merchant API version 6,including the merchant initialization call and the new DSRP and tokenization extensionpoints.



• The merchant must have succesfully implemented Masterpass Merchant Mobile Checkoutlibraries/SDK that facilitates consumer transactions from the merchant Android™

application on an Android Masterpass wallet application (app-to-app). DSRP cryptogramscan currently only be generated for transactions that occur for these app-to-app use caseson Android. If Mobile Checkout is available in your country, refer to the Mobile CheckoutMerchant Integration Guide and SDK found on the Masterpass - Merchant Android SDKpage of the Mastercard Developers site.

• Systems must be in place to correctly identify authorizations for split/partial shipments andrecurring payments so that the DSRP data is accurately processed for subsequentauthorizations (for more information, refer to the section below).

• The payment gateway and acquirer must have successfully updated their interfaces to passand receive DSRP data elements. Masterpass recommends that merchants contact theirpayment gateway(s) and acquirer(s) to:

– Understand the changes the acquirer is making to support DSRP.– Identify any corresponding work that the merchant must complete.

• The consumer’s card issuer/wallet provider must have successfully updated their interfacesto pass and receive DSRP data elements.

• The consumer has elected to pay with a card that has been digitized (for MasterpassMobile 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 standardMasterpass transaction.

Unique Masterpass Web Tokenization Use CasesMerchants should be aware that some issuers provide Masterpass™ consumer wallets that willtokenize the consumer’s payment credentials to deliver a more secure web shoppingexperience; this means that, instead of the usual 16-digit primary account number (PAN),these Masterpass wallets will pass a token to the merchant for a web transaction, which willbe transparent to the merchant.

Why is This Important?

It is important for merchants to be aware of this tokenization of payment credentials becausesome merchants use the 16-digit PAN as a consumer identifier for certain business practices.For example, some merchants may use the PAN as a customer identifier for in-store returns ofgoods purchased on the web. For these tokenized web transactions, the merchant will have a16-digit token on record, while the consumer may be asked to present their 16-digit PAN forverification. The fact that the token on record with the merchant and the consumer’s PAN aredifferent may confuse the consumer and the merchant’s staff.

Depending on the merchants’ policies, the primary use cases through which this issue mayoccur are as follows:

• In-store return of a purchase made with a web token• In-store pickup of a purchase made with a web token• Pickup of a rental car reserved with a web token



• Hotel reservation made online with a web token

What Should Merchants Do?

To help avoid confusion between the token and the consumer’s PAN, Masterpass recommendsthat its merchants implement the following practices:

• Incorporate the last four digits of the PAN (as described below) into your online orderingprocesses wherever applicable (for example, the order confirmation page and onlinereceipts); this will help match the consumer’s PAN with the token in the merchant’s records.Merchants may access the last four digits of the PAN through the following two sources:

– Acquirers that support tokenized transactions via the Mastercard Digital EnablementService (MDES) must send the last four digits of the PAN to their merchants; these lastfour digits are sent in data element (DE) 48 (Additional Data—Private Use), subelement33 (PAN Mapping File Information), subfield 2 (Account Number) within theAuthorization Request Response/0110 message.

– The last four digits of the PAN are included in the Masterpass Checkout XML for DigitalSecure Remote Payment (DSRP) transactions initiated on Android devices. Merchantscan parse the Masterpass Checkout XML to extract the last four digits of the PAN.

• Educate your customer service staff of the scenarios that commonly result in confusion andimplement any necessary policies to accommodate them.

• Where possible, use your own unique consumer identifiers rather than the PAN, as thisissue generally occurs in scenarios in which the merchant uses the PAN as a consumeridentifier.

DSRP Extension Points in the Masterpass Merchant APIMerchants 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 DSRPdata elements and values.

MerchantInitializationRequest with DSRP Extension Points V6—XML Details

NOTE:

This section shows the Merchant Initialization service with DSRP extensions only. For furtherdetails, see Merchant Initialization Service.

Element Description Type Min–Max

MerchantInitializationRequest

Root Element XML –

MerchantInitializationRequest.OAuthToken

Request Token(oauth_token) returnedby call to therequest_token API

–



Element Description Type Min–Max

MerchantInitializationRequest.OriginUrl

Identifies the URL of thepage that initializes thelightbox

string NA

MerchantInitializationRequest.ExtensionPoint.DSRP.DSRPOptions.Option.BrandId

Required for DSRPtransactions. Identifiesthe card brands forwhich DSRP is desired.The valid card IDs aremaster andmaestro .

string

MerchantInitializationRequest.ExtensionPoint.DSRP.DSRPOptions.Option.AcceptanceType

Required for DSRPtransactions. Indicatesthe type(s) ofcryptograms themerchant or serviceprovider can accept.Valid types are: UCAFand/or ICC (seedescriptions thatfollow).

Masterpass passes themost secure selection(ICC) if both acceptancetypes are indicated.

alpha

MerchantInitializationRequest.ExtensionPoint.DSRP.UnpredictableNumber

Optional for DSRPtransactions. EMV-quality random numbergenerated by themerchant, serviceprovider, or—if null—byMasterpass and Base64encoded

4-byte binary string 8

A cryptogram is the output of the process of transforming clear text into ciphertext forsecurity or privacy.

There are two forms in which the DSRP cryptograms may be generated and sent dependingon the capabilities of the merchant/service provider, payment gateway, and acquirer systems:

• UCAF™ data: In this case, the EMV cryptogram—and a subset of the EMV data—arecarried 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 containsa subset of the EMV data including the application cryptogram, application transactioncounter (ATC), unpredictable number, and cryptogram version.

Most merchant/service provider and acquirer systems are configured today to supportUCAF data transmission.

• Full EMV data: In this case the full set of EMV data is carried in data element (DE) 55Integrated 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 thefull set of EMV data including all the data listed previously for UCAF plus other informationsuch 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 accountnumber (PAN), application expiration date, and terminal country code.

While ICC is considered the more secure, recommended option, many merchant/serviceprovider and acquirer systems today are not yet configured to support this data element.

If the merchant/service provider and acquirer systems are enabled to send and receive theDSRP cryptogram data in both the UCAF and/or ICC (DE 55) forms, the merchant can specifyboth UCAF and ICC. In this instance, Masterpass passes the cryptogram with the highest levelof security (ICC) if the consumer’s wallet provider also supports ICC. If the consumer’s walletcannot support ICC, Masterpass passes the UCAF form of the cryptogram.

The Unpredictable Number is four-byte binary data that is randomly generated (per theEMVCo Specification Bulletin No. 144) by either the merchant or Masterpass (which is thenpassed back to the merchant at the end of the transaction). The presence of theUnpredictable Number provides an additional layer of security by providing an element that isunknowable and unique to a specific transaction. This prevents a cryptogram from being usedfor anything other than the transaction for which it was generated. Masterpass recommendsthat you do not populate the Unpredictable Number element; in such cases, Masterpass willgenerate 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 thenumber that you generated with what was returned to you—refer to EMVCo’s requirementsfor this value in the “Random Number Generation” section of the EMV Acquirer and TerminalSecurity Guidelines document. After generation, the value must then be Base64 encoded andpassed in the Unpredictable Number extension point in the Merchant Initialization RequestOpenAPI call.

MerchantInitializationRequest with DSRP Extension Points—Sample

URL: https://api.mastercard.com/masterpass/v6/merchant-initialization

NOTE: This section shows the Merchant Initialization service with DSRP extensions only. Forfurther details, see Merchant Initialization Service.



http://www.emvco.com/download_agreement.aspx?id=973

https://www.emvco.com/download_agreement.aspx?id=852


NOTE: The following example illustrates a case in which a merchant has chosen to generatethe unpredictable number; if the UnpredictableNumber field is left null, Masterpass willgenerate the value on behalf of the merchant.

<MerchantInitializationRequest> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <OriginUrl>https://somemerchant.com</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 XMLAfter a remote transaction has been facilitated and secured via Digital Secure RemotePayment (DSRP), the Masterpass™ wallet will generate a cryptogram that the merchant willreceive in the Checkout XML.

The following "Checkout XML—Sample with UCAF Cryptogram" example illustrates a case inwhich a merchant has indicated that it can only receive a UCAF cryptogram. The "CheckoutXML—Sample with ICC Cryptogram" illustrates a case in which a merchant has indicated thatit can receive either a UCAF or ICC or an ICC crytogram. The elements shown in bold areelements that are impacted by the presence of a cryptogram.

• The AccountNumber element is a 16-digit, device-based token rather than the cardholder'sactual card number.

• The ExpiryMonth and ExpiryYear elements indicate the expiration data of the providedtoken.

• The AuthenticateMethod element indicates that Digital Secure Remote Payment (DSRP)was the method utilized for this transaction.

• The DSRP ExtensionPoint elements are populated with the cryptogram, type, unpredictablenumber, and ECI flag. These extension points will be followed by token extension pointsdescribed in more detail below. The presence of these extensions points indicates that thetransaction has been tokenized.



Checkout XML—Sample with UCAF Cryptogram

Received from URL: https://api.mastercard.com/itf/masterpass/v6/checkout/{checkoutId}

NOTE: U.S. merchants will not receive the PreCheckout element in the following example.

<Checkout> <Card> <BrandId>master</BrandId> <BrandName>Mastercard</BrandName> <AccountNumber>5178058604388374</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>286532912</TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <EmailAddress>[email protected]</EmailAddress> <PhoneNumber>1-3692581470</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+1-8734048394</RecipientPhoneNumber> </ShippingAddress> <AuthenticationOptions> <AuthenticateMethod>DSRP</AuthenticateMethod> </AuthenticationOptions> <WalletID>208</WalletID> <PreCheckoutTransactionId>a4c411b-18h26t-icni2rol-1-ics6caee-123y</PreCheckoutTransactionId> <ExtensionPoint> <DSRP> <DSRPData>Qwertyuio0987654321asdfghjklpois</DSRPData> <DSRPDataType>UCAF</DSRPDataType> <UnpredictableNumber>413142==</UnpredictableNumber> <Eci>02</Eci> </DSRP> </ExtensionPoint>



Checkout XML—Sample with ICC Cryptogram

Received from URL: https://api.mastercard.com/masterpass/v6/checkout/{checkoutId}

NOTE: U.S. merchants will not receive the PreCheckout element in the following example.

<Checkout> <Card> <BrandId>master</BrandId> <BrandName>Mastercard</BrandName> <AccountNumber>5178058604388374</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>286532912</TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <EmailAddress>[email protected]</EmailAddress> <PhoneNumber>1-3692581470</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+1-8734048394</RecipientPhoneNumber> </ShippingAddress> <AuthenticationOptions> <AuthenticateMethod>DSRP</AuthenticateMethod> </AuthenticationOptions> <WalletID>208</WalletID> <PreCheckoutTransactionId>a4c411b-18h26t-icni2rol-1-ics6caee-123y</PreCheckoutTransactionId> <ExtensionPoint> <DSRP> <DSRPData>Qwertyuio0987654321asdfghjklpoiuytrewq1234567890unhtsrebnkoiemskdh245678912e9inyQwertyuio0987654321asdfghjklpoiuytrewq1234567890unhtsrebnkoiemskdh245678912e9inyQwertyuio0987654321asdfghjklpoiuytrewq1234567890unhtsrebnkoiemskdh245678912e9inyQwertyuio0987654321asdfghjklpoiuytrewq1234567890unhtsrebnkoiemskdh245678912e9inyQwertyuio0987654321asdfghjklpoiuytrewq1234567890unhtsrebnkoiemskdh245678912e9inyQwertyuio0987654321asdfghjklpoiuytrewq1234567890unhtsrebnkoiemskdh245678912e9inyqazwsxedcrfvtgbyhnuj</DSRPData> <DSRPDataType>ICC</DSRPDataType> <UnpredictableNumber>413142==</UnpredictableNumber>



</DSRP> </ExtensionPoint></Checkout>

Checkout XML DSRP Details

NOTE: For details on the non-DSRP related elements in XML, refer to the V6—Checkout—XMLDetails table.

Element Description Type Min-Max

Checkout.Card.AccountNumber

Card number or primaryaccount number (PAN)that identifies theconsumer’s card.

For DSRP transactionsthe actual number isreplaced with an MDESDSRP device-based orcard on file token.

Integer 13–24

Checkout.Card.ExpiryMonth

Expiry month for theconsumer’s card.


Integer

Checkout.Card.ExpiryYear

Expiry year for theconsumer’s card.


Integer




Checkout.AuthenticationOptions.AuthenticateMethod

The method used toauthenticate thecardholder at checkout.Valid values are“MERCHANT ONLY”,“3DS” and “NOAUTHENTICATION”,and “DSRP”.

Value equals “DSRP” forDSRP transactions.

Alphanumeric NA

Checkout.ExtensionPoint.DSRP.DSRPData

DSRP cryptogramgenerated by theconsumer’s Masterpasswallet

Alphanumeric UCAF: Max 32

ICC: Max 512

Checkout.ExtensionPoint.DSRP.DSRPDataType

Indicates the type ofcryptogram generatedby the consumer’sMasterpass wallet.

Masterpass passes themost secure selection(ICC) if the merchant orservice provider hasindicated they canaccept both types(UCAF, ICC).

Alpha NA

Checkout.ExtensionPoint.DSRP.UnpredictableNumber

Encoded EMV-qualityrandom numbergenerated by either themerchant orMasterpass.

4-byte binary string 8




Checkout.ExtensionPoint.DSRP.Eci

Electronic commerceindicator (ECI) value (DE48, SE 42, position 3).Present only when DSRPdata type is UCAF. ForMastercard brand cards,value is:

02—Authenticated byACS (Card IssuerLiability)

Numeric UCAF: 02

ICC: N/A

NOTE: The Security Level Indicators (SLIs) found in Authorization DE 48 (Additional Data—Private Data), subelement 42 (Electronic Commerce Indicators), subfield 1 (ElectronicCommerce Security Level Indicator and UCAF Collection Indicator), positions 1–3 for aMasterpass DSRP transaction are in the format 24X, where the positions 1 and 2 combinationof 24 indicates a DSRP transaction and the position 3 value of X is the ECI value.

Tokenization Extension Points in the Masterpass Checkout XMLWhen Masterpass generates and replaces the primary account number (PAN) with a token ofany type (for example, device-based), the Checkout XML that is returned to the merchant willinclude (a) a token in place of the actual account/card number in the AccountNumberelement, (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 below.

Merchants 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, for example, the entryof the card security code or the printing 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.• U.S. merchants can ignore the PreCheckout element.

<Checkout> <Card> <BrandId>master</BrandId> <BrandName>Mastercard</BrandName> <AccountNumber>5178058604388374</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>286532912</TransactionId> <Contact> <FirstName>Jane</FirstName> <LastName>Doe</LastName> <NationalID>***********</NationalID> <Country>US</Country> <EmailAddress>[email protected]</EmailAddress> <PhoneNumber>1-3692581470</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+1-8734048394</RecipientPhoneNumber> </ShippingAddress> <AuthenticationOptions> <AuthenticateMethod>DSRP</AuthenticateMethod> </AuthenticationOptions> <WalletID>208</WalletID> <PreCheckoutTransactionId>a4c411b-18h26t-icni2rol-1-ics6caee-123y</PreCheckoutTransactionId> <ExtensionPoint> <DSRP> <DSRPData>Qwertyuio0987654321asdfghjklpois</DSRPData> <DSRPDataType>UCAF</DSRPDataType> <UnpredictableNumber>413142==</UnpredictableNumber> <Eci>02</Eci> </DSRP> <Tokenization> <FPanSuffix>1234</FPanSuffix> <TokenRequestorId>12345678911</TokenRequestorId> </Tokenization> <PaymentAccountReference>01123456789abcdefghijkl9</PaymentAccountReference> </ExtensionPoint></Checkout>

Checkout XML Tokenization Details

NOTE: For details on the remaining elements in XML, refer to the “V6—Checkout—XMLDetails” table.



Checkout XML Element Description Type Min–Max

Tokenization-RelatedExtension Points

FPanSuffix Last digits of cardnumber or primaryaccount numberthat identifies thecard. Also knownas Funding PrimaryAccount Number.Normally suffix isthe last four digits.

String 8

TokenRequestorId Identifier of theentity requestingthe token, typicallythe wallet fromwhich thetransactionoriginated. ForMasterpasstransactions, thisID is that forMastercard/Masterpass or forthe wallet provider.

String 11

PaymentAccountReference

Data element thatallows merchantsand acquirers tolink all transactionsfor a singleconsumer even inthe absence of theactual primaryaccount number(PAN).

Alphanumeric 24

For more information on the Payment Account Reference (PAR), refer to EMVCo DraftSpecification Bulletin No. 167.





Split/Partial Shipments and Recurring Payment TransactionsSplit/partial shipments occur when an e-commerce merchant ship several items in separateconsignments (for example, if a portion of the purchased items are out of stock or items areshipping from separate locations).

Recurring payments occur when a cardholder has authorized a merchant to bill thecardholder’s account on a recurring basis (for example, monthly or quarterly). The amount ofeach payment may or may not be the same.

Only the first authorization for split/partial or recurring payments associated with a DigitalSecure Remote Payment (DSRP) transaction may contain cryptographic data. Merchants mustnot 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 witha previous authorization that was cryptographically authenticated (by coding a value of 07 inposition 3 rather than a value of 02 as mentioned in the Eci row of the “Checkout XML DSRPDetails” table in the DSRP Extension Points in the Masterpass Merchant API section).

3-D Secure ConsiderationsIt is important to note that the Masterpass™ Mobile Checkout product that facilitatesmerchant app-to-wallet app transactions automatically suppresses 3-D Secure for DigitalSecure Remote Payment (DSRP) transactions when it is called from within the Masterpasswallet. Merchants should also suppress 3-D Secure for these transactions.

For more information about the Mobile Checkout product, refer to the Masterpass AndroidCheckout Sample App page on GitHub.

Testing DSRPFor information on the tools that are currently available for testing Digital Secure RemotePayment (DSRP) implementation, send a message to the following email address.

[email protected]

Masterpass Service DescriptionsThe following sections describe the different services offered by Masterpass™.

Request Token ServiceThis must be executed when a consumer clicks the Masterpass Checkout button on yoursite/app.Sandbox and Production Endpoints for the Request Token ServiceThe endpoints to be used for the Request Token Service are as follows.

https://sandbox.api.mastercard.com/oauth/consumer/v1/request_token

https://api.mastercard.com/oauth/consumer/v1/request_token





mailto:[email protected]

https://sandbox.api.mastercard.com/oauth/consumer/v1/request_token

https://api.mastercard.com/oauth/consumer/v1/request_token

Shopping Cart ServiceMerchants must call the Shopping Cart service before invoking the Masterpass™ UI forcheckout.

NOTE: The product description needs to be HTML encoded and has a character limit of 100characters.

Sandbox and Production Endpoints for the Shopping Cart ServiceThe endpoints to be used for the Shopping Cart Service are as follows.

• https://sandbox.api.mastercard.com/masterpass/v6/shopping-cart• https://api.mastercard.com/masterpass/v6/shopping-cart

Merchant Initialization ServiceThis service is used to secure Lightbox connections between merchant and Masterpass™.

Merchant Initialization also has an optional SecondaryOriginUrl field if the service providersets this. This is used only when the Lightbox will be invoked from a frame that is on amerchant site and when that frame is of a different domain than that of the merchant site,like for a service provider.

This service requires a request token (OAuthToken).

Request and response parameter details can be found here.

Sandbox and Production Endpoints for the Merchant Initialization ServiceThe endpoints to be used for the Merchant Initialization Service are as follows.

• https://sandbox.api.mastercard.com/masterpass/v6/merchant-initialization• https://api.mastercard.com/masterpass/v6/merchant-initialization

Access Token ServiceThe 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 themerchant callback to get an access token.


Sandbox and Production Endpoints for the Access Token ServiceThe endpoints to be used for the Access Token Service are as follows.

• https://sandbox.api.mastercard.com/oauth/consumer/v1/access_token• https://api.mastercard.com/oauth/consumer/v1/access_token



https://sandbox.api.mastercard.com/masterpass/v6/shopping-cart

https://api.mastercard.com/masterpass/v6/shopping-cart

https://sandbox.api.mastercard.com/masterpass/v6/merchant-initialization

https://api.mastercard.com/masterpass/v6/merchant-initialization

https://sandbox.api.mastercard.com/oauth/consumer/v1/access_token

https://api.mastercard.com/oauth/consumer/v1/access_token

Retrieve Payment, Shipping Data, and 3-D Secure DetailsNow you will use the Checkout Resource URL request parameter (checkout_resource_url)received from the callback URL to retrieve consumer’s payment, shipping address, and 3-DSecure information from Masterpass™.

The checkout resource URL supplied by Masterpass must be decoded and consumed by themerchant 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. https://AnyMerchant.com/CheckoutCallback?mpstatus=success&checkout_resource_url=https%3A%2F%2Fapi.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F11318523&oauth_verifier=aa2ff8e8f1144f45c3b8fdc3d42398913a49e387&oauth_token=b8361ad151af35f71df7b395e083befcaf8192dd

Decoded checkout URL:

checkout_resource_url=https://api.mastercard.com/masterpass/v6/checkout/113185232. https://AnyMerchant.com/CheckoutCallback?checkout_resource_url=https%3A%2F

%2Fapi.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F11318500&checkoutId=11318500&oauth_verifier=aa2ff8e8f1144f45c3b8fdc3d42398913a49e387&oauth_token=b8361ad151af35f71df7b395e083befcaf8192dd

Decoded checkout URL:

checkout_resource_url=https://api.mastercard.com/masterpass/v6/checkout/11318500&checkoutId=11318500


NOTE: Masterpass performs a CVC/CVV check at card enrollment. However, in accordancewith PCI standards, CVC2/CVV2 data is not persisted, and will not be provided to themerchant. As the card data has been validated and securely stored by Masterpass, merchantsmust not require CVC/CVV entry from a consumer checking out with Masterpass. In caseswhere, prior to submitting their order, the cardholder chooses to replace the payment detailsprovided by Masterpass with different, manually entered payment details, Merchants shouldask the cardholder to enter CVV2/CVC2/CID as they would in the normal course and shouldnot pass the wallet indicator flag to the acquirer. In this case, the transaction is no longerconsidered to be a Masterpass transaction. Checkout Postback is still required. It isrecommended not to allow consumers to change their card details after returning fromMasterpass.

A three-byte wallet Indicator (WID) Flag (WalletID xml element in the checkout xml) will bepart 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, yourtransactions will continue to process as-is. Contact customer support if you have anyquestions.



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—PrivateData), 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)

Postback ServiceThe final step of a Masterpass™ transaction is a service call from the merchant to Masterpass,communicating the result of the transaction (success or failure).

Abandoned transactions do not need to be reported. The <TransactionId> value should be thevalue from the <TransactionId> element of the Checkout XML returned in the Checkoutrequest.




The following fields are passed in the postback service call:

• ConsumerKey: Consumer key from key management on the Masterpass Merchant Portal• Currency: Currency for the transaction, for example, USD• OrderAmount: Transaction order amount with no decimals, for example, 1500 (for USD

15 transaction amount)• PurchaseDate: Date of Purchase• ApprovalCode: Six-digit approval code returned by payment API.• TransactionId: Transaction ID from TransactionId element of the Checkout XML from the

retrieve payment, shipping, and 3-D Secure data service call for example, “35201”• TransactionStatus: Status of transaction. Valid values are:

– SUCCESS: For approved transaction– FAILURE: For declined transaction

• PreCheckoutTransactionId: U.S. merchants can ignore this field, as it is optional

Sandbox and Production Endpoints for the Postback ServiceThe endpoints to be used for the Postback Service are as follows.

• https://sandbox.api.mastercard.com/masterpass/v6/transaction• https://api.mastercard.com/masterpass/v6/transaction

Android and iOS App IntegrationIn order to integrate the Masterpass™ web checkout experience into your Android™ or iOSapplication, you must integrate with all of the Masterpass services described previously. .

Mobile Browser Support

Below is a list of mobile browsers supported by Masterpass Lightbox.

Phone

• iOS 8+ (Safari®) on iPhone® 6+• iOS 8+ (Safari) on iPhone 5+• Android 4.0+ (Chrome™)• Android 4.0+ (Stock Browser)

Tablet

• iOS 8+ (Safari)• Android 4.0+ (Chrome)• Android 4.0+ (Stock Browser)

Sample Integration

In the merchant's application, the merchant must have a Masterpass Checkout buttondepending on the Masterpass checkout process. Please refer to Chapter 2 MasterpassCheckout Experiences section for more information on the various checkout process flows.



Merchants should integrate Masterpass Lightbox by refering to the Lightbox Integrationsection.

Once Masterpass Lightbox Integration is completed, upon the user’s clicking of MasterpassCheckout, the merchant application must redirect the user to a mobile browser that launchesthe Masterpass experience.

NOTE: Masterpass does not support webview for in-app implementation due to securityissues.

A sample web page implementation is provided below.

Open URL in Mobile Browser

Sample iOS Objective-C Code to Open URL[ [UIApplication sharedApplication ] openURL : [NSURL URLWithString : @"url_to_merchant_web_page_that_launches_masterpass" ] ] ;Sample iOS Swift Code to Open URLUIApplication . sharedApplication ( ) . openURL ( NSURL (string : "url_to_merchant_web_page_that_launches_masterpass" ) ! )Sample Android Code to Open URLUri uri = Uri . parse ( "url_to_merchant_web_page_that_launches_masterpass" ) ;Intent intent = new Intent (Intent .ACTION_VIEW , uri ) ; startActivity (intent ) ;

Sample Web Page That Launches Masterpass

<html> <head>  <script type="text/javascript" src=" https://sandbox.static.masterpass.com/dyn/js/switch/integration/Masterpass.client.js "></script>    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script> </head> <body> <script>  </script> </body></html>1234567891011121314151617Sample JavaScript to Invoke Masterpass Checkout

Below is a sample JavaScript to invoke Masterpass. You can also see Lightbox Integration -Standard checkout for more information.



$ (document ) . ready ( function ( ) { Masterpass .client . checkout ( { // from Masterpass Request Token Service "requestToken" : "request_token" , // redirect url after checkout is completed "callbackUrl" : "merchant_callback_url" , // checkout identifier from the Masterpass Merchant Portal "merchantCheckoutId" : "merchant_checkout_id" , // Card types accepted by merchant "allowedCardTypes" : "master,amex,diners,discover,maestro,visa" , // version v6 "version" : "v6" } ) ; } ) ;

Handling Callbacks from Masterpass

In addition to invoking Masterpass, the merchant must implement callbacks from Masterpasson its backend system when a transaction is successful or cancelled.

For Standard Checkout callback, please refer to Standard Checkout Callback.

Redirecting User Back to Merchant App

After a checkout is completed, the merchant should implement its own mechanism to redirectusers back to its mobile application.

Android

On Android, one of the ways to redirect users back to a native application from browser is touse an Intent. You can find more information by referring to Android's developer website.

Helpful Links

• When coming from the Chrome mobile browser

https://developer.chrome.com/multidevice/android/intents• When using Android Intent

http://developer.android.com/reference/android/content/Intent.html

iOS

On iOS, some of the ways to redirect users back to a native application from browser are touse URL Schemes and Universal Links. You can find more information by refering to Apple'sdeveloper website.

Helpful Links

• URL Schemes

https://developer.apple.com/library/ios/documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Inter-AppCommunication/Inter-AppCommunication.html

• Universal Link

https://developer.apple.com/library/ios/documentation/General/Conceptual/AppSearch/UniversalLinks.html



https://developer.chrome.com/multidevice/android/intents

http://developer.android.com/reference/android/content/Intent.html





Completing the Integration

By the end of the integration, your site or mobile app must be able to do the following:

1. Display Masterpass Checkout button and the Learn More link at the start of thecheckout experience.

2. Invoke and display the Masterpass Lightbox.3. Relay Masterpass checkout requests to the Masterpass service.4. Receive consumer’s billing and shipping address from Masterpass service.5. Process card and shipping information using existing checkout process.

NOTE: Your implementation must satisfy all criteria in the Q/A Checklist.

Integration ProcessCompleting the Integration


Chapter 6 Masterpass BrandingThis topic provides information on Masterpass™ branding.

Displaying the “Masterpass Checkout” Button and Acceptance Marks..........................................82Masterpass Checkout Button Example......................................................................................83Dynamic Checkout Button........................................................................................................84

Masterpass “Learn More” Page.................................................................................................... 84

Masterpass Branding


Displaying the “Masterpass Checkout” Button and Acceptance Marks

The Masterpass™ Masterpass Checkout button URLs and acceptance mark URLs can be foundin this section.

To ensure the best consumer experience, the checkout button should be placed at the earliestpossible entry point, prior to the collection of shipping and billing information.

NOTE: With the July 2016 Release, Masterpass has redesigned many digital assets, including—but not limited to—the Buy with Masterpass button, Masterpass acceptance marks, and theLearn More link. In the coming months, Masterpass will update the integration guides, theMasterpass Merchant Portal, the Mastercard Developers site, and so on, to reflect the newbutton design and branding.

Masterpass Checkout Button

Masterpass Acceptance Mark

NOTE: Downloading and locally hosting the Masterpass Checkout Button image andacceptance marks is against Masterpass integration guidelines. To minimize the impact offuture branding updates, use the country-specific link (indicated in the following section) tothe images on the checkout page.

To successfully integrate with Masterpass and enable successful checkout by an end-userconsumer via the service, the Masterpass Checkout button must be integrated on themerchant/service provider website and displayed as noted in the Masterpass MerchantBranding Requirements document.

The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code(ISO 3166-1), and Button file name based on size as follows: Base URL/Language/Country/Image File Name

Base URL: https://static.masterpass.com/dyn/img/

NOTE: The list of language/country folders can be found on the Masterpass Checkout FAQspage under the question, “Which countries and locales are currently supported to host ‘Buywith Masterpass’ images?”

Masterpass BrandingDisplaying the “Masterpass Checkout” Button and Acceptance Marks


https://developer.mastercard.com/media/a2/66/13f59a1a4c449bd9687dd470fe7cmp_merchant%20brand_requirements.pdf



Below is the list of all production Masterpass Checkout button URLs supported for the U.S.market:

• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_147x034px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_160x037px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_166x038px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_180x042px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_290x068px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_317x074px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_326x076px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_360x084px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_376x088px.png• https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_539x126px.png

Below is the list of all production Masterpass acceptance mark URLs supported for the U.S.market:

• https://static.masterpass.com/dyn/img/acc/en/US/mp_acc_046px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_acc_060px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_acc_068px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_acc_076px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_acc_100px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_acc_130px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_acc_226px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_mc_acc_023px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_mc_acc_030px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_mc_acc_034px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_mc_acc_038px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_mc_acc_050px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_mc_acc_065px.png• https://static.masterpass.com/dyn/img/acc/en/US/mp_mc_acc_113px.png

Masterpass Checkout Button ExampleThe following is an example of how a merchant can include the checkout button.

<div class="MasterPassBtnExample"><a href="/exampleRedirect"> <img src="https://static.masterpass.com/dyn/img/btn/en/US/mp_chk_btn_147x034px.png" alt="Checkout with Masterpass Button Example" /></a></div>

Masterpass BrandingDisplaying the “Masterpass Checkout” Button and Acceptance Marks


Dynamic Checkout ButtonAs part of the product redesign, Masterpass is introducing a new checkout button design,along with an ability to display a personalized dynamic checkout button based on aconsumer’s past wallet usage.

The dynamic button capability will be initially available to a few wallet providers, andmerchants integrating to any of the URLs in the Displaying the “Masterpass Checkout” Buttonand Acceptance Marks section will be able to display this button to their shoppers usingMasterpass.

Masterpass “Learn More” Page

In addition to the Masterpass™ checkout button and acceptance mark, Masterpass alsorequires merchants/service providers to provide a link to Learn More page which can be usedby the consumers to get additional information about Masterpass.

We recommend that you place the link in close proximity to the Masterpass Checkoutbutton.

NOTE: With the July 2016 Release, Masterpass has redesigned many digital assets, including—but not limited to—the Buy with Masterpass button, Masterpass acceptance marks, and theLearn More link. In the coming months, Masterpass will update the integration guides, theMasterpass Merchant Portal, Mastercard Developers, and so on, to reflect the new buttondesign and branding.

The following URL needs to be referenced for displaying the Learn More page for the U.S.market:

• English - https://www.mastercard.com/mc_us/wallet/learnmore/en/US/

NOTE: Downloading and locally hosting this content is against Masterpass integrationguidelines. To minimize the impact of future updates to this page, use the below mentionedcountry-specific link to the images on the checkout page.

Masterpass BrandingMasterpass “Learn More” Page


https://www.mastercard.com/mc_us/wallet/learnmore/en/US/

Chapter 7 TestingThis topic provides information on how to perform testing in the sandbox environment.

Masterpass Sandbox Testing..........................................................................................................86Sign up for a Test Masterpass Wallet Account during Checkout and Test the UnrecognizedExperience................................................................................................................................86Sign in to a Test Masterpass Wallet Account during Checkout and Test the RecognizedExperience................................................................................................................................88

3-D Secure Test Cases................................................................................................................... 89Q/A Checklist................................................................................................................................92

Checklist for Masterpass Asset Placement.................................................................................92In-Wallet Experience.................................................................................................................92Post-Wallet Experience............................................................................................................. 92Postback.................................................................................................................................. 93General.................................................................................................................................... 93

Testing


Masterpass Sandbox Testing

To access the necessary information to test in the sandbox environment, the developer mustsubmit an approval request to the merchant and obtain a sandbox consumer key as explainedearlier in the guide.

The following pre-set Masterpass wallet accounts, which have previously been available forsandbox testing, are no longer available:

• [email protected]• [email protected]• [email protected]• [email protected]

To conduct testing in the sandbox environment, you must first set up your own Masterpasstest wallet account.

Sign up for a Test Masterpass Wallet Account during Checkout and Test theUnrecognized Experience

To set up a Masterpass™ test wallet account and test the unrecognized experience in thesandbox environment, complete the following instructions.

Procedure

1. Go to your merchant website in the test environment, add an item to the shopping cart,and click on the Masterpass checkout button. Because you are an unrecognized, first-timeuser, the standard Masterpass checkout button appears.

2. Click on Sign-up.3. Add an existing email ID and phone number that you have access to (for example, your

work email address and phone number).4. Click on I’m not a robot.5. Ensure you have chosen country US-English language (see the flag in the bottom-right

corner of the screen).6. Add one of the test card numbers from the table below. Note that these are not real cards

and cannot be used outside of the Masterpass testing environment.

There are two categories of test card numbers:

– Category1 cards: Intelligent wallet routing links to a Masterpass by Mastercardwallet. When you return to the same site as a “recognized” consumer after completingcheckout at the first visit, the same Standard Checkout button will appear. Note thatthe images included here are only for illustrative purposes and may change as buttondesign is finalized.

TestingMasterpass Sandbox Testing


– Category2 cards: Intelligent wallet routing links to a “Pilot3” wallet. When you return

to the same site as a “recognized” consumer after completing checkout at the firstvisit, the Dynamic Checkout button specific to “Pilot3” wallet provider will appear.Note that the images included here are only for illustrative purposes and may changeas button design is finalized.

Category Test Card # CVCExpirationDate

BillingAddress

Category1 5506900140100305 [Any] [Any] [Any]






NOTE: You should always add one of the test cards above to test the new Masterpassexperience, which uses intelligent wallet routing and dynamic-button functionality.

On the next screen, notice the change in branding on top of the Lightbox screen based onthe wallet you were routed to (Masterpass by Mastercard wallet or “Pilot3” co-brandedwallet).

7. Add your billing addresses, password, and shipping addresses to your wallet account.8. Select the Remember me on this device option on the Congratulations screen so you

(a) do not have to rekey the entire test account information every time you login toMasterpass and (b) are not asked to authenticate with a one-time password (OTP) via SMSor email ID.

9. Click on the Continue button. All of the transaction data will be sent to your testmerchant site, and you will be redirected to your merchant test site (where you cansubmit/place the order).



NOTE: If you have a test payment gateway setup for this testing, you may need to replacethe test card details provided above with your own test card data and send thetransaction through to the gateway and Masterpass. Submit a postback, too, perMasterpass integration guidelines.

NOTE: As an exception to step 2, service providers that have onboarded merchants toMasterpass and have a need to provide them with a single wallet account should createtheir test wallet account using a false email ID ending in @example.com or @email.com .Masterpass whitelists all wallet accounts associated with an email ID with these two falseemail domains for a static OTP 123456. As a result, however, you will not receive anyemail communications related to test-account activity. If you have questions or concerns,contact your local Masterpass representative or the Mastercard implementation managerworking with you.

Sign in to a Test Masterpass Wallet Account during Checkout and Test theRecognized Experience

After setting up your Masterpass™ test wallet account, complete the following instructions totest the recognized Masterpass checkout experience.

Before you beginYou must have already created a your Masterpass test wallet account by completing the Signup for a Test Masterpass Wallet Account during Checkout and Test the UnrecognizedExperience instructions.

Procedure

1. Go to your merchant website in the test environment and add an item to the shoppingcart. Notice the change in the Masterpass checkout button that appears. The checkoutbutton you see will depend on the category of test card number that you used.

– Category1 cards: The Standard Checkout button will appear. Note that the imagesincluded here are only for illustrative purposes and may change as button design isfinalized.

– Category2 cards: The Dynamic Checkout button specific to a “Pilot3” wallet provider

will appear. Note that the images included here are only for illustrative purposes andmay change as button design is finalized.

2. Click on the Masterpass checkout button.3. Click Sign in and provide your password.



4. Confirm your card and shipping details.5. Click on the Continue button. All of the transaction data will be sent to your test

merchant site, and you will be redirected to your merchant test site (where you cansubmit/place the order).

NOTE: If you want to test the “Unrecognized consumer” experience again, clear allcookies on your browser so you can initiate the steps above again.


This section provides information on the Mastercard® SecureCode™ and Verified by Visa® testcases.

Once you have (a) created a test Masterpass wallet account and tested the “unrecognized”checkout experience and (b) tested the “recognized” checkout experience, you can add thetest card numbers provided below for each scenario that is available for testing in sandbox.

Mastercard SecureCode

The following Mastercard Test Cases table provides the expected outputs for each of the testcases for Mastercard SecureCode and the test card numbers associated with each of the TestCases:

Testing3-D Secure Test Cases


NOTE: With our 16.Q4 Release, Mastercard SecureCode downgrades any transaction to Non-SecureCode if the CAVV is not submitted in Authorization (DE 48, subelement 43). This is truein Masterpass if the Security Level Indicators in DE 48, subelement 42 equals 221, 222, or 223.

Once you have logged into Masterpass test wallet account, which you’ve presumably alreadycreated by completing these instructions, add the test card number below for the test casethat you would like to test.

Mastercard Test Cards

Test Case # Mastercard Test Card #SecureCodePIN CVC

ExpirationDate

BillingAddress

1 5204740009900014 [Any] [Any] [Any] [Any]

2 5204740009900022 [Any] [Any] [Any] [Any]

3 5204740009900030 [Any] [Any] [Any] [Any]

4 5204740009900048 [Any] [Any] [Any] [Any]

5 5204740009900055 [Any] [Any] [Any] [Any]

6 5204740009900063 [Any] [Any] [Any] [Any]

7 5204740009900071 [Any] [Any] [Any] [Any]

8 5204740009900089 [Any] [Any] [Any] [Any]

9 5204740009900097 [Any] [Any] [Any] [Any]

10 5204740009900105 [Any] [Any] [Any] [Any]

11 5204740009900113 [Any] [Any] [Any] [Any]

12 5204740009900170 [Any] [Any] [Any] [Any]

(Full auth) 5204740009900121 [Any] [Any] [Any] [Any]



(Notenrolled)

5204740009900154 [Any] [Any] [Any] [Any]

(Failed auth) 5204740009900162 [Any] [Any] [Any] [Any]

Verified by Visa

The following “Visa Test Cases” table provides the expected outputs for each of the test casesfor Verified by Visa and the test card numbers associated with each of the test cases:



Once you have logged into your consumer wallet account, which you’ve presumably alreadycreated by completing these instructions, add the test card number below for the test casethat you would like to test.

Visa Test Cards

Test Case # Test Card #Verified byVisa PIN CVC

ExpirationDate

BillingAddress

1 4440000009900010 [Any] [Any] Jan2020 [Any]

2 4440000010099018 [Any] [Any] [Any] [Any]

3 4440000042200014 [Any] [Any] [Any] [Any]

4 4440000042200022 [Any] [Any] [Any] [Any]

5 4440000042200030 [Any] [Any] [Any] [Any]

6 4440000042200048 [Any] [Any] [Any] [Any]

7 4440000042200055 [Any] [Any] [Any] [Any]

8 4440000042200063 [Any] [Any] [Any] [Any]



Test Case # Test Card #Verified byVisa PIN CVC

ExpirationDate

BillingAddress

9 4440000042200071 [Any] [Any] [Any] [Any]

10 4440000042200089 [Any] [Any] [Any] [Any]

11 4440000042200097 [Any] [Any] [Any] [Any]


(Failed SigVer)

4440000042200113 [Any] [Any] [Any] [Any]

(Failed auth) 4440000042200121 [Any] [Any] [Any] [Any]

(Attempts) 4440000042200139 [Any] [Any] [Any] [Any]

(Timeout) 4440000042200147 [Any] [Any] [Any] [Any]

Q/A Checklist

This topic provides information on the Q/A checklist.

Checklist for Masterpass Asset PlacementThe following is an checklist to follow for proper placement of Masterpass™ visual assets.

• Verify your adherence to the Masterpass Merchant Branding Requirements document.• Verify that you are linking to all Masterpass visual assets (this includes the checkout button,

acceptance marks, and Learn More link) and JavaScript library through provided URLs. Donot download and host these assets on your own side.

• Verify that the Masterpass checkout button is used appropriately on the checkout page toinitiate the Masterpass experience.

In-Wallet ExperienceThe following is a checklist for the Masterpass™ in-wallet experience.

• Verify that the consumer can only select cards and addresses that are supported by themerchant.

• Merchants requesting liability shift for Masterpass transactions should use AdvancedCheckout/3-D Secure within Masterpass. Merchants must enable 3-D Secure such that it isinvoked within the Masterpass wallet.

Post-Wallet ExperienceThe following is a checklist for post-wallet experience.

• After clicking the Finish Shopping button, verify the consumer is taken to a valid page.• Verify that the Masterpass acceptance mark is displayed for all Masterpass transactions.

TestingQ/A Checklist



• As recommended by Masterpass, do not allow consumers to edit the payment informationreturned on the merchant site.

• Verify that any information provided by a consumer’s Masterpass wallet (for example,payment, shipping, profile information, and so on) is used only for that transaction and isnot stored for subsequent use.

• Verify that your code gracefully handles consumers returning without selecting a card andaddress (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 completedwithin the timeout, the request token will expire, and the checkout will need to berestarted.

• Verify that your code is able to parse and ingest the returned data.• Verify that any post-Masterpass wallet page has a clear call to action (for example, select

preferred shipping method) versus simply having the consumer review the data they justselected in the wallet.

• Verify that the consumer is not required to enter CVC/CVV in order to complete thetransaction.

• Verify that the card primary account number (PAN) has not been provided to any entity thatdoes 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.• 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 ShippingAddresselements in checkout XML.

PostbackThe following is a checklist for postback:

• Ensure that you are submitting postback for all Masterpass™ transactions initiated with theconsumer’s click of the Masterpass checkout button (approved, declined, or abandoned).

• Verify that the transaction ID submitted as part of a postback was sourced from theassociated Masterpass transaction.

• Verify that the transaction result (postback) is reported immediately.

GeneralThe following is a general checklist.

• Ensure that you are coding to DNS and not to IP addresses for our URLs and endpoints.• Verify that your implementation follows the standard process and utilizes all calls (to the

Masterpass™ wallet, complete postback, and so on) for each and every transaction initiatedby a consumer’s click of the Masterpass checkout button.

• Verify that you are accepting and passing the wallet identifier (WID) when present forMasterpass transactions.

TestingQ/A Checklist


Chapter 8 TroubleshootingThis topic provides information on troubleshooting.

Common Errors............................................................................................................................ 95Support........................................................................................................................................ 95

Troubleshooting


Common Errors

The following are the procedures to troubleshoot the most common errors that you mayencounter.

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)


• Verify that you are passing the Access Token in the get CheckoutXML call.

If you get Error 403 - Forbidden when calling Masterpass services:

• Verify correct credentials or correct environment (that is, sandbox credentials with the prodURL).

• Verify timestamp.


• 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 Masterpass Checkout FAQs page on the Mastercard Developers site.

If you have any questions or comments relating to Masterpass merchant testing, contact theimplementation manager assigned to work with you on this implementation. If you don’t havean assigned implementation manager, send an email—with the following information (asapplicable)—to [email protected] for merchants that are new toMasterpass or [email protected] for existing Masterpass merchants:

• Merchant/Service Provider Name

TroubleshootingCommon Errors





• Email 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

TroubleshootingSupport


Appendix A AppendixAppendix

This appendix provides additional information related to Masterpass™ integration process.

Lightbox Parameters..................................................................................................................... 98OAuth Samples...........................................................................................................................100

Request Token........................................................................................................................100Merchant Initialization Service................................................................................................ 102Shopping Cart Service Parameters.......................................................................................... 106Access Token Service.............................................................................................................. 111Checkout Resource................................................................................................................ 113Postback Service.....................................................................................................................127

Renew a Mastercard Developers API Key.....................................................................................136Mastercard Developers Key Tool Utility........................................................................................ 1403-D Secure Overview...................................................................................................................141

3-D Secure Service Description............................................................................................... 141General Overview of Mastercard SecureCode and Verified by Visa TransactionAuthentication....................................................................................................................... 142Important Merchant Information............................................................................................ 143

Appendix


Lightbox Parameters

This section provides descriptions of the Masterpass™ Lightbox parameters.

Lightbox parameters invoked on clicking the Masterpass Checkout button

O = Optional; R = Required; A = Automatically populated

Parameter nameDatatype

CardSecurity Checkout Description

allowedCardTypes string[] O This parameter restricts thepayment methods that may beselected based on card brand.Omit this parameter to allow allpayment methods. Here are thevalid values for different cardtypes

Mastercard: master

Maestro: maestro

American Express: amex

Discover: discover

Diners: diners

Visa: visa

JCB: jcb

callbackUrl string O O This defines the base URL towhich the browser is redirectedto upon successful or failedcompletion of the flow if thereis no appropriate callbackfunction available.

cancelCallback function

O O This defines the function to becalled when the flow iscancelled by the consumer priorto completing checkout.

failureCallback function

O O This defines the function to becalled when the flow ends infailure.

Refer SDK for more examples.

AppendixLightbox Parameters


Parameter nameDatatype

CardSecurity Checkout Description

merchantCheckoutId string R R This is the checkout identifierwhich is used to identify themerchant and their checkoutbranding.

requestBasicCheckout boolean O Set to "true" to disable step-upauthentication (advancedcheckout) during any checkoutflow. The default is "false".

requestToken string R R This is an OAuth token.

shippingLocationProfile commaseparatedstring

O This parameter definesMerchant’s Shipping Profile(s)for the transaction that they setin their account. Multiple valuesmay be passed via commaseparation (as in, no spaceswithin a profile name). Forexample,"CHEERIO,AUONLY,NAmerica".

successCallback function

O O This defines the function to becalled when the flow ends insuccess.

suppressShippingAddressEnable boolean O When set to “true,” theconsumer placing the orderthrough Masterpass Wallet willnot provide a shipping address(for example, when theconsumer purchases digitalgoods). When set to “false,”the consumer placing the orderthrough Masterpass Wallet mustprovide a shipping address.

AppendixLightbox Parameters


OAuth Samples

This topic provides information on OAuth samples.

Request TokenThis section describes the Request Token parameters.

Request Token Parameters

request_token Request request_token Response

oauth_callback X

oauth_signature X

oauth_version X

oauth_nonce X

oauth_signature_method X

oauth_consumer_key X

oauth_timestamp X

realm X

oauth_token X

oauth_callback_confirmed X

oauth_expires_in X

oauth_token_secret X

xoauth_request_auth_url X

Request Parameter Details

Request Token—Request Description Possible Values

Signature Base String

Authorization Header

oauth_callback Endpoint that will handle thetransition from the wallet siteto the merchant checkoutpage

Variable

oauth_signature RSA/SHA1 signaturegenerated from the signaturebase string

Variable

AppendixOAuth Samples


Request Token—Request Description Possible Values

oauth_version oAuth version 1.0

oauth_nonce Unique alphanumeric stringgenerated from code

Variable

oauth_signature_method

oAuth signature method. RSA-SHA1

oauth_consumer_key

Consumer Key generatedwhen completing keymanagement on theMasterpass Merchant portal.

Variable

oauth_timestamp Current timestamp Variable

realm Used to differentiate betweenour mobile and full site.Currently not used.

eWallet

Request Token—Response Description Possible Values

Oauth Token oauth_token oauth_token is sent in thesignature base string,authorization header andredirect URL

Variable

Request Token oauth_callback_confirmed

Variable

oauth_expires_in Time the Request Tokenexpires in seconds

Variable

oauth_token_secret Oauth Secret Variable

xoauth_request_auth_url

Authorize URL Variable

Signature Base String ExamplePOST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Frequest_token&oauth_callback%3Dhttp%253A%252F%252Fprojectabc.com%252Fmerchant%252FCallback.jsp%26oauth_consumer_key%3DZGho8Df8vqW-IpGCIu559HYriL093IBXdJeKavp4dce9db2a%25216464586653467358724b616c74475445443349466a413d3d%26oauth_nonce%3D1143452272881219%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1339612030%26oauth_version%3D1.0

HTTP Request ExamplePOST /oauth/consumer/v1/request_token HTTP/1.1Authorization: OAuthoauth_callback="http%3A%2F%2Fprojectabc.com%2Fmerchant%2FCallback.jsp",oauth_signature="pzNogGtgShe16%2FwhP4CsTRXkgJ1mv%2FKm6do5ZVi6doKzAJZ0m8QqhiERi5lRup



hdyUkhW8LKdUL1TetPdxm32Vtr%2BQGF6n6IBjr8dGcyYmfaLyAYVhF%2Fx5oQhUDVpdXIc10dJ0miUwZPbJ1QopN3ibeOzvgNxhEiHYKVnpvYEhc%3D",oauth_version="1.0",oauth_nonce="1143452272881219",oauth_signature_method="RSA-SHA1",oauth_consumer_key="ZGho8Df8vqW-IpGCIu559HYriL093IBXdJeKavp4dce9db2a%216464586653467358724b616c74475445443349466a413d3d",oauth_timestamp="1339612030",realm="eWallet"

HTTP Response Exampleoauth_callback_confirmed=true&oauth_expires_in=900&oauth_token=a02c5c5c1a128c2cebc650ea9aa3dfb7&oauth_token_secret=c2daaf0888779d82bd63524159bee91f&xoauth_request_auth_url=https%3A%2F%2Fsandbox.masterpass.com%2Fonline%2FCheckout%2FAuthorize

Merchant Initialization ServiceThis section provides description on the Merchant Initialization parameters.

Merchant Initialization Parameters

Merchant InitializationResource Request

Merchant InitializationResource Response

oauth_signature X

oauth_version X

oauth_nonce X



oauth_timestamp X

realm X

oauth_body_hash X

oauth_token X

Merchant InitializationRequest XML

X

Merchant InitializationResponse XML

X



Merchant Initialization Request Parameter Details

Merchant Initialization Resource—Request Description Possible Values




Variable

oauth_version Oauth version. 1.0


Variable


oauth signature method. RSA-SHA1

oauth_consumer_key

Consumer Key generatedwhen completing keymanagement on theMasterpass Merchant Portal.

Variable


oauth_token Request token Variable

Merchant InitializationRequest XML

MerchantInitializationRequest XML

Merchant Initialization details

Merchant Initialization Resource—Response Description Possible Values

Oauth Token oauth_token oauth_token is sent in therequest

Variable

Signature Base String ExamplePOST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%merchantinitialization&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4-B4263CB5A305%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380049711%26oauth_version%3D1.0

HTTP Request ExamplePOST /masterpass/v6/merchant-initialization HTTP/1.1

Authorization: OAuth realm="eWallet",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_method="RSA-SHA1",oauth_nonce="DEAEB1CD-CA03-405D-A7B4-B4263CB5A305",oauth_timestamp="1380049711",oauth_version="1.0",oauth_body_hash="8K9uhveZjVdZW8AIYiXpR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zrav



b02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D" XML

V6—MerchantInitializationRequest—XML Schema

NOTE: U.S. merchants can ignore the PreCheckout element.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="MerchantInitializationRequest" type="MerchantInitializationRequest" /> <xs:complexType name="MerchantInitializationRequest"> <xs:sequence> <xs:element name="OAuthToken" type="xs:string" /> <xs:element name="PreCheckoutTransactionId" type="xs:string" maxOccurs="1" minOccurs="0" /> <xs:element name="OriginUrl" type="xs:string" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" /> </xs:sequence> </xs:complexType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any" /> </xs:sequence> <xs:anyAttribute /> </xs:complexType> <xs:complexType name="MerchantInitializationExtension"> <xs:sequence> <xs:element name="DSRP" type="DSRPExtension" minOccurs="1"/> <xs:element name="SecondaryOriginUrl" type="xs:string" minOccurs="0"/>

</xs:sequence> </xs:complexType></xs:schema>

URL: https://api.mastercard.com/masterpass/v6/merchant-initialization—SampleRequest<MerchantInitializationRequest> <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken> <OriginUrl>https://somemerchant.com</OriginUrl></MerchantInitializationRequest>

V6—MerchantInitializationResponse—XML Schema<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <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—MerchantInitializationResponse—XML Sample<MerchantInitializationResponse> <OAuthToken>4c7b34cc63a68282bba77a4b34f0192fcb2268fb</OAuthToken></MerchantInitializationResponse>

V6—MerchantInitializationRequest—XML Details

MerchantInitializationRequest XML Element Description Type Min–Max


Root Element XML -


OAuthToken Request Token(oauth_token) returned bycall to the request_tokenAPI

-

ExtensionPoint Reserved for futureenhancement. Optional

Any

MerchantInitializationResponse XML Element Description Type Min–Max


XML -


Any -

ExtensionPoint Elements

Starting with API v6, all schema container elements contain a new optional element named“ExtensionPoint”. These elements are intended to provide expandability of the API withoutrequiring 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 futureexpandability, 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 aseparate schema. Any such extensions will be optional. Further, only authorized schemas willbe allowed inside ExtensionPoint elements, and any unknown elements will be dropped byMasterpass.

ExtensionPoint—Sample<ExtensionPoint> <s:SampleExtension xmlns:s=”https://www.masterpass.com/location/of/example/ns”> <s:SampleField>Sample Value</s:SampleField> </s:SampleExtension> <f:AnotherExampleExtension xmlns:f=”https://www.masterpass.com/location/of/example2/ns> <f:SampleContainer> <f:AnotherSampleField>Sample Value</f:AnotherSampleField> </f:SampleContainer> </f:AnotherExampleExtension></ExtensionPoint>

Shopping Cart Service ParametersThis section provides description on the Shopping Cart parameters.

Shopping Cart Parameters

Shopping Cart Request Shopping Cart Response

oauth_signature X

oauth_version X

oauth_nonce X



oauth_timestamp X

oauth_body_hash X

oauth_token X X

Shopping Cart Request XML X

Shopping Cart Response XML X

Shopping Cart Parameter Details

Shopping Cart—Request Description Possible Values






Variable

oauth_version Oauth version 1.0


Variable


oauth signature method RSA-SHA1

oauth_consumer_key


Variable


oauth_body_hash SHA1 hash of the messagebody

Variable


Variable

Transfer XML Strings Shopping CartRequest XML

Merchant Shopping Cartdetails

Shopping Cart—Response Description Possible Values


Variable

Transfer XML Strings Shopping CartResponse XML

Signature Base String ExamplePOST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fshopping-cart&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4-B4263CB5A305%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380049711%26oauth_version%3D1.0



HTTP Request ExamplePOST /masterpass/v6/shopping-cart HTTP/1.1Authorization: OAuth realm="eWallet",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_method="RSA-SHA1",oauth_nonce="DEAEB1CD-CA03-405D-A7B4-B4263CB5A305",oauth_timestamp="1380049711",oauth_version="1.0",oauth_body_hash="8K9uhveZjVdZW8AIYiXpR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"

V6—ShoppingCartRequest—XML Schema<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="ShoppingCartRequest" type="ShoppingCartRequest" /> <xs:complexType name="ShoppingCartRequest"> <xs:sequence> <xs:element name="OAuthToken" type="xs:string" /> <xs:element name="ShoppingCart" type="ShoppingCart" /> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" /> </xs:sequence> </xs:complexType> <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="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any" /> </xs:sequence> <xs:anyAttribute/> </xs:complexType></xs:schema>



V6—ShoppingCart—XML Details

ShoppingCartRequest Element Description Type Min–Max


String Variable

ShoppingCart Merchant Shopping Cartdetails.

XML -


Any -

ShoppingCart CurrencyCode Defined by ISO 4217 to beexactly three characters,such as, USD for U.S.Dollars. AllMonetaryValues will bemodified by theCurrencyCode.

Alpha 3

Subtotal Total sum of all the itemsin the cart excludingshipping, handling andtax. Integer without thedecimal, for example, USD119.00 will be 11900.

Integer 1-12

ShoppingCartItem Details of a singleshopping cart item.

XML -


Any -

ShoppingCartItem Description Describes a singleshopping cart item.

String 1-100

Quantity Number of a singleshopping cart item.

Integer 1-12

Value Price or monetary value ofa single shopping cartitem. Cost * Quantity.Integer without decimal,for example, USD 100.00is 10000.

Integer 1-12



ImageURL Link to shopping cart itemimage. URLs must beHTTPS, and not HTTP.

String 0-2000


Any -

ShoppingCartResponse

Element Description Type Min– Max


String Variable


Any -

ShoppingCartRequest—XML Sample<?xml version="1.0" ?><ShoppingCartRequest> <OAuthToken>f7f16d8462a9424365498afade20caaa</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>https://somemerchant.com/someimage</ImageURL> </ShoppingCartItem> </ShoppingCart></ShoppingCartRequest>

ShoppingCartResponse—XML Sample<?xml version="1.0" encoding="UTF-8" standalone="yes"?><ShoppingCartResponse> <OAuthToken>a747f7e7c2e0c3048843f640b92806c8</OAuthToken></ShoppingCartResponse>

ShoppingCartResponse—XML Schema<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <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>

Access Token ServiceThis section describes the Access Token parameters.

Access Token Parameters

access_token Request access_token Response

oauth_signature X

oauth_version X

oauth_nonce X



oauth_timestamp X

realm X

oauth_token X X

oauth_token_secret X

oauth_verifier X



Access Token Parameter Details

Access Token—Request Description Possible Values

Signature Base StringAuthorization Header


Variable



Variable


oauth signature method RSA-SHA1

oauth_consumer_key


Variable



eWallet

oauth_verifier Verifier is returned on thecallback and used in theaccess token request

oauth_token oAuth token obtained fromrequest token call

Variable

Access Token—Response Description Possible Values

Access Token oauth_token oauth_token that needs to besent in the signature basestring and authorizationheader for checkout resourcecall

Variable

Oauth_Token_Secret oauth_token_secret Oauth Secret Variable

Signature Base String ExamplePOST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Faccess_token&oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3DXgqPqENy%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1433963296%26oauth_token



%3Df263a7383ce705fdf17dc163a33c00c5d49bea4e%26oauth_verifier%3Daa73f490841655a36b6ba8fe5e938367a8f0f5d9%26oauth_version%3D1.0

HTTP Request ExampleAuthorization: OAuth oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_nonce="XgqPqENy",oauth_signature="jImDsWuf1AW%2FeAjsXwwgAEeKsEZ0qJiRH39jar3BtZdA6Ccc2zbx4nhDRWm7QNmEgfkruVFbLFkdckix8ZABNW8e%2Fte0mapbCeI0ldkWPb3Bc2z9qvu8uoHpUU9t8Un6k0bbI%2BAswSA30VCcUKtcy2crA2plkAoU52SOq1Cyqdk%3D",oauth_signature_method="RSA-SHA1",oauth_timestamp="1433963296",oauth_token="f263a7383ce705fdf17dc163a33c00c5d49bea4e",oauth_verifier="aa73f490841655a36b6ba8fe5e938367a8f0f5d9",oauth_version="1.0",realm="eWallet"

HTTP Response Exampleoauth_token=9429f23bd08f992c41fb5ddabcc03ecd&oauth_token_secret=cd1ab178419c2111fb1171083f5dc8d9

Checkout ResourceThis topic provides details of the Checkout parameters and XML.

Checkout Parameters

Checkout resource RequestCheckout Resource

Response

oauth_signature X

oauth_version X

oauth_nonce X



oauth_timestamp X

realm X

oauth_token X

checkout_resource_url Used as endpoint

Checkout XML X



Checkout Parameter Details

Checkout Resource—Request Description Possible Values

Signature Base StringAuthorization Header


Variable



Variable



oauth_consumer_key


Variable



eWallet

oauth_token Access token that is returnedin the access token responseneeds to be sent in thesignature base string,authorization header forcheckout resource call

checkout_resource_url

Endpoint used to request theusers billing and shippinginformation from Masterpass

Variable

Checkout Resource—Response Description Possible Values

Transfer XML Strings Checkout XML Refer to the “V6—Checkout—XML Details” table in thissection.

Signature Base String ExampleGET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F306067563&oauth_consumer_key%3DcLb0tKkEJhG====_6ltDIibO5Wgbx4rIl====_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049====%26oauth_nonce%3D8yNKr7i3%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp



%3D1433970146%26oauth_token%3Dd475e1a692b7bfed07b492dd845b7f43190becad%26oauth_version%3D1.0

HTTP Request ExampleGET /masterpass/v6/checkout/4400 HTTP/1.1Authorization:OAuthoauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_nonce="8yNKr7i3",oauth_signature="G95Ku%2BLpJ%2BLt%2FIOCGYj5a3H1OB7LNltBrw7Hq7%2BhrTtXoiAMRp56obJYlkX10LS2lNugBPKq%2FU8YyJ8Tt8wDDsRCLFbS1XT4xi%2FzKsXk%2B7LRXN3YwLTi8exDI4rAan%2B02YYOpMyOk4uX6KDb9ue6Lu%2FxAfQ0lqB2zK7mT24TwHs%3D",oauth_signature_method="RSA-SHA1",oauth_timestamp="1433970146",oauth_token="d475e1a692b7bfed07b492dd845b7f43190becad",oauth_version="1.0",realm="eWallet"

V6—Checkout—XML Schema

URL: https://api.mastercard.com/masterpass/v6/checkout/

The checkout resource URL supplied by Masterpass should be decoded and consumed by themerchant as provided by Masterpass. Masterpass may add or delete parameters in future. Thefollowing are examples of decoded URL:

• checkout_resource_url=https://api.mastercard.com/masterpass/v6/checkout/11318500&checkoutId=11318500

• checkout_resource_url=https://api.mastercard.com/masterpass/v6/checkout/11318501

NOTE: U.S. merchants can ignore the PreCheckoutTransactionId element.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <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="WalletID" type="xs:string"/> <xs:element name="PreCheckoutTransactionId" type="xs:string" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="AuthenticationOptions"> <xs:sequence> <xs:element name="AuthenticateMethod" type="xs:string" minOccurs="0"/> <xs:element name="CardEnrollmentMethod" type="xs:string" minOccurs="0"/> <xs:element name="CAvv" type="xs:string" minOccurs="0"/> <xs:element name="EciFlag" type="xs:string" minOccurs="0"/> <xs:element name="MasterCardAssignedID" type="xs:string" minOccurs="0"/>



<xs:element name="PaResStatus" type="xs:string" minOccurs="0"/> <xs:element name="SCEnrollmentStatus" type="xs:string" minOccurs="0"/> <xs:element name="SignatureVerification" type="xs:string" minOccurs="0"/> <xs:element name="Xid" type="xs:string" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="Card"> <xs:sequence> <xs:element name="BrandId" type="NonEmptyString"/> <xs:element name="BrandName" type="NonEmptyString"/> <xs:element name="AccountNumber" type="NonEmptyString"/> <xs:element name="BillingAddress" type="Address"/> <xs:element name="CardHolderName" type="NonEmptyString"/> <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/> <xs:element name="ExpiryYear" type="Year" minOccurs="0"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="Address"> <xs:sequence> <xs:element name="City" type="NonEmptyString"/> <xs:element name="Country" type="Country"/> <xs:element name="CountrySubdivision" type="NonEmptyString" minOccurs="0"/> <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="EmailAddress" type="EmailAddress"/> <xs:element name="PhoneNumber" type="xs:string"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence>



</xs:complexType> <xs:complexType name="DateOfBirth"> <xs:sequence> <xs:element name="Year"> <xs:simpleType> <xs:restriction base="xs:int"> <xs:minInclusive value="1900"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="Month" type="Month"/> <xs:element name="Day"> <xs:simpleType> <xs:restriction base="xs:int"> <xs:minInclusive value="1"/> <xs:maxInclusive value="31"/> </xs:restriction> </xs:simpleType> </xs:element> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:simpleType name="Gender"> <xs:restriction base="xs:token"> <xs:enumeration value="M"/> <xs:enumeration value="F"/> </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: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="EmailAddress"> <xs:restriction base="xs:string"> <xs:pattern value="[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*@[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="Month"> <xs:restriction base="xs:int"> <xs:minInclusive value="1"/> <xs:maxInclusive value="12"/> </xs:restriction> </xs:simpleType>



<xs:simpleType name="Year"> <xs:restriction base="xs:int"> <xs:minInclusive value="2013"/> <xs:pattern value="\d{4}"/> </xs:restriction> </xs:simpleType> <xs:complexType name="ExtensionPoint"> <xs:sequence> <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/> </xs:sequence> <xs:anyAttribute/> </xs:complexType></xs:schema>

V6—Checkout—Sample XML Response

URL: https://api.mastercard.com/masterpass/v6/checkout/123456

<Checkout> <Card> <BrandId>master</BrandId> <BrandName>Mastercard</BrandName> <AccountNumber>5435579315709649</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>30258374209</NationalID> <Country>US</Country> <EmailAddress>[email protected]</EmailAddress> <PhoneNumber>1-9876543210</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>1-9876543210</RecipientPhoneNumber> </ShippingAddress> <WalletID>101</WalletID></Checkout>



V6—Checkout—XML Details

CheckoutXML Element Description TypeMin–Max

Checkout Root Element XML -

Checkout Card Child Element XML -

Card BrandId Identifies the cardbrand id, for example,master forMastercard.

Alpha

Numeric

0–8

BrandName Identifies the cardbrand name, forexample, Mastercard

String 0–255

AccountNumber Card number orprimary accountnumber that identifiesthe card

Integer 13–24

BillingAddress Billing Address for thecard holder.

XML -

CardHolderName Cardholder name String 1–100

ExpiryMonth Expiration monthdisplayed on thepayment card.

Date XMLformat

ExpiryYear Expiration yeardisplayed on thepayment card.

Date XMLformat

ExtensionPoint Reserved for futureenhancement.Optional

Any -

Checkout TransactionID Child Element String 1–255

Checkout Contact Child Element XML

Contact FirstName Contact First Name String 1–150

Optional MiddleName Contact Middle Nameor Initial

String 1–150

LastName Contact Surname String




Optional* Gender Contact Gender (M orF)

NOTE: This fieldmay only berequested from aMasterpass wallet ifit is required by lawin a region.Merchants andservice providersseeking to use thisfield must workwith the localMasterpassrepresentative toget the necessaryclearances beforerequesting thesedata elements.

“M” or “F”[SB1]

Optional* DateOfBirth Contact DOB –YYYY/MM/DD


Sequence:Year (Int);Month (Int)

Day (Int)

Y (4)

M (2)

D (2)

* Only when legally required and enabled by Masterpass




Optional (dependent onmerchant country ofincorporation and theconsumer country ofresidence)

NationalID Contact NationalIdentification


String 1–150

Optional Country Contact Country ofResidence

String 0–2

EmailAddress Contact EmailAddress

String 5–512

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


Any -

Checkout ShippingAddress Child Element XML -

ShippingAddress Address Child Element XML -

Address City Cardholder’s city String 0–25




Country Cardholder’s country.Defined by ISO3166-1 alpha-2 digitcountry codes, forexample, U.S. isUnited States, AU isAustralia, CA isCanada, GB is UnitedKingdom, and so on.

String 2

CountrySubdivision Cardholder’s countrysubdivision. Definedby ISO 3166-1alpha-2 digit code, forexample, US-VA isVirginia, US-OH isOhio

String 5

Line 1 Address line 1 usedfor Street number andStreet Name.

String 1–40

Line 2 Address line 2 usedfor Apt Number, SuiteNumber, and so on.

String 0–40

Line 3 Address line 3 used toenter remainingaddress information ifit does not fit in Line1 and Line 2

String 0–255

PostalCode Postal Code or ZipCode appended tomailing address forthe purpose of sortingmail.

String 0–20


Any -

ShippingAddress RecipientName Name of person set toreceive the shippedorder.

String 1–100




ShippingAddress RecipientPhoneNumber

Phone of the personset to receive theshipped order.

String 3–20

Checkout AuthenticationOptions

Child Element XML -

Checkout WalletID Helps identify originwallet

String 3

AuthenticationOptions AuthenticateMethod Method used toauthenticate thecardholder atcheckout. Valid valuesare “MERCHANTONLY”, “3DS” and“No Authentication”.

Alpha NA

CardEnrollmentMethod

Method by which thecard was added to thewallet. Valid valuesare:

Manual

Direct Provisioned

3DS Manual

NFC Tap

Alpha NA

CAvv (CAVV) CardholderAuthenticationVerification Valuegenerated by cardissuer upon successfulauthentication of thecardholder. This mustbe passed in theauthorizationmessage

Alpha

Numeric

NA




EciFlag Electronic commerceindicator (ECI) flag.

Possible values are asfollows:

Mastercard:

00—NoAuthentication

01—Attempts (CardIssuer Liability)

02—Authenticated byACS (Card IssuerLiability)

03—Maestro (MARP)

05—Risk BasedAuthentication (Issuer,not in use)

06—Risk BasedAuthentication(Merchant, not in use)

Visa:

05—Authenticated(Card Issuer Liability)

06—Attempts (CardIssuer Liability)

07—No 3DSAuthentication(Merchant Liability)

Alphanumeric

NA

MasterCardAssignedID

This value is assignedby Mastercard andrepresents programsassociated directlywith Maestro cards.This field should besupplied in theauthorization requestby the merchant.

Alpha

Numeric

NA




PaResStatus A message formatted,digitally signed, andsent from the ACS(issuer) to the MPIproviding the resultsof the issuer’sMastercardSecureCode/Verifiedby Visa cardholderauthentication.Possible values are:

Y—The card wassuccessfullyauthenticated via 3-DSecure

N—Authenticationfailed

A—signifies thateither (a) thetransaction wassuccessfullyauthenticated via a 3-D Secure attemptstransaction or (b)thecardholder wasprompted to activate3-D Secure duringshopping but declined(Visa).

U—Authenticationresults wereunavailable

Alpha NA




SCEnrollmentStatus MastercardSecureCodeEnrollment Status:Indicates if the issuerof the card supportspayer authenticationfor this card. Possiblevalues are as follows:

Y—The card is eligiblefor 3-D Secureauthentication.

N—The card is noteligible for 3-D Secureauthentication.

U—Lookup of thecard's 3-D Secureeligibility status waseither unavailable, orthe card isinapplicable (forexample, prepaidcards).

Alpha NA

SignatureVerification: Signature Verification.Possible values are asfollows:

Y—Indicates that thesignature of the PaReshas been validatedsuccessfully and themessage contents canbe trusted.

N—Indicates that fora variety of reasons(tampering, certificateexpiration, and so on)the PaRes could notbe validated, and theresult should not betrusted.

Alpha NA




XID Transaction identifierresulting fromauthenticationprocessing.

Alpha

Numeric

NA


Any

PreCheckoutTransactionId Pre CheckoutTransaction ID

ID associated with thePreCheckoutTransaction

NOTE: This elementis not applicable toU.S. merchants.

Alphanumeric

Postback ServiceThis topic provides information on the Postback parameters.

Postback Parameters

Post Transaction Request Post Transaction Response

oauth_signature X

oauth_version X

oauth_nonce X



oauth_timestamp X

oauth_body_hash X

MerchantTransactions XML X X



Postback Parameter Details

Post Transaction—Request Description Possible Values




Variable



Variable



oauth_consumer_key


Variable


oauth_body_hash SHA1 hash of the messagebody

Variable

Transfer XML Strings MerchantTransactions XML

Transaction details

Post Transaction—Response Description Possible Values

Transfer XML Strings MerchantTransactions XML

Transaction details

Signature Base String ExamplePOST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Ftransaction&oauth_body_hash%3DycNt7A676VEY7i0SkyymKorihCg%253D%26oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3D26123188000346%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380054060%26oauth_version%3D1.0

HTTP Request ExamplePOST /masterpass/v6/transaction HTTP/1.1Authorization: OAuth oauth_signature="Aom0wFGFI7ItYV1IZFn125BoD6jgFtdX15dQ8XbjvMGgKgKtJ5awV7wSMGwUcceGlpl52HFS%2B%2BOQzVrCdXUidvgeKOX1nHDFhns0l1yIaqGdkJQYR%2BCQGu1qo7xVjvzTqpXUlrc2uzVCjyLoQEroIWv5cAOj5l4aBxDopz7OKQA%3D",oauth_body_hash="ycNt7A676VEY7i0SkyymKorihCg%3D",oauth_version="1.0",oauth_nonce="26123188000346",oauth_signature_method="RSA-SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_timestamp="1380054060"



MerchantTransactions Request XML Schema

NOTE: U.S. merchants can ignore the PreCheckout and ExpressCheckout elements.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema"> <xs:element name="MerchantTransactions" type="MerchantTransactions"/> <xs:complexType name="MerchantTransactions"> <xs:sequence> <xs:element name="MerchantTransactions" type="MerchantTransaction" minOccurs="0" maxOccurs="unbounded"/> <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/> </xs:sequence> </xs:complexType> <xs:complexType name="MerchantTransaction"> <xs:sequence> <xs:element name="TransactionId" type="xs:string"/> <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

NOTE: U.S. merchants can ignore the PreCheckoutTransactionId andExpressCheckoutIndicator elements.

<MerchantTransactions> <MerchantTransactions> <TransactionId>4549794</TransactionId> <ConsumerKey>0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b48675861677159682b563745776b593652377939673d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate>2014-08-01T14:52:57.539-05:00</PurchaseDate> <TransactionStatus>Success</TransactionStatus>



<ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-947</PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> <MerchantTransactions></MerchantTransactions>

MerchantTransactionsResponse—Schema

NOTE: U.S. merchants can ignore the PreCheckout and ExpressCheckout elements.

<?xml version-/="1.0" encoding-/="UTF-8" standalone-/="yes"?><xs:schema version-/="1.0" xmlns:xs-/="http://www.w3.org/2001/XMLSchema"> <xs:element name-/="MerchantTransactions" type-/="MerchantTransactions"/> <xs:complexType name-/="MerchantTransactions"> <xs:sequence> <xs:element name-/="MerchantTransactions" type-/="MerchantTransaction" minOccurs-/="0" maxOccurs-/="unbounded"/> <xs:element name-/="ExtensionPoint" type-/="ExtensionPoint" minOccurs-/="0"/> </xs:sequence> </xs:complexType> <xs:complexType name-/="MerchantTransaction"> <xs:sequence> <xs:element name-/="TransactionId" type-/="xs:string"/> <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 wassuccessful)

NOTE: U.S. merchants can ignore the PreCheckoutTransactionId andExpressCheckoutIndicator elements.



<MerchantTransactions> <MerchantTransactions> <TransactionId>4549794</TransactionId> <ConsumerKey>0zMKpm0nFtUv8lLXT97jDRo2b593652377939673d0zMKpm0nFt9682b563745776b593652377939673d</ConsumerKey> <Currency>USD</Currency> <OrderAmount>1229</OrderAmount> <PurchaseDate>2014-08-01T14:52:57.539-05:00</PurchaseDate> <TransactionStatus>Success</TransactionStatus> <ApprovalCode>sample</ApprovalCode> <PreCheckoutTransactionId>a4a6x55-rgb1c5-hyaqkemj-1-hybxhplo-9477</PreCheckoutTransactionId> <ExpressCheckoutIndicator>false</ExpressCheckoutIndicator> </MerchantTransactions></MerchantTransactions>

MerchantTransactions—XML Details

MerchantTransactionsRequest Element Description Type Min - Max

MerchantTransactions

MerchantTransactions XML -


Any -



MerchantTransactionsRequest Element Description Type Min - Max

MerchantTransactions TransactionID Uses the TransactionIDelement of the CheckoutXML

String 1–255

ConsumerKey Consumer Key generatedwhen completing keymanagement on theMasterpass MerchantPortal.

String 97

Currency Currency of the transaction.Defined by ISO 4217 to beexactly three characters,such as, USD for U.S.Dollars.

String 3

OrderAmount (Integer) Transaction orderamount without decimal,for example, 1500.

Integer 1–12

PurchaseDate Date and Time of theshopping cart purchase.

Date XML format

TransactionStatus State of the transaction.Indicates whethersuccessful. Valid values areSuccess or Failure.

String 7

ApprovalCode Approval code returned tomerchant from merchant'spayment API with paymentgateway or service provider.

String 6

PreCheckoutTransactionId

Value returned from thePrecheckoutData call.

NOTE: This does notapply to U.S. merchants.

String

ExpressCheckoutIndicator

True or False. Set to falsefor connected checkout

NOTE: This does notapply to U.S. merchants

Boolean


Any -



MerchantTransactionsResponse Element Description Type Min - Max

MerchantTransactions

MerchantTransactions Root Element XML -


Any -




MerchantTransactions TransactionID Uses the TransactionIDelement of the CheckoutXML

String 1–255

ConsumerKey Consumer Key generatedwhen completing keymanagement on theMasterpass MerchantPortal.

String 97

Currency Currency of the transaction.Defined by ISO 4217 to beexactly three characters,such as, USD for U.S.Dollars.

String 3

OrderAmount Integer Transaction orderamount without decimal,for example, 1500.

Integer 1–12

PurchaseDate Date and Time of theshopping cart purchase, forexample,2012-06-06T15:12:24.254-05:00

Date XML format

TransactionStatus State of the transaction.Indicates whethersuccessful. Valid values areSuccess or Failure.

String 7

ApprovalCode Approval code returned tomerchant from merchant'spayment API with paymentgateway or service provider.

String 6

PreCheckoutTransactionId

Value returned from thePrecheckoutData call.


String




ExpressCheckoutIndicator

True or False. Set to falsefor connected checkout.


Boolean


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 withoutrequiring 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 futureexpandability, all integrators must not perform any validation of elements received inside anExtensionPoint element, beyond any that may be defined by Masterpass in the future with aseparate schema. Any such extensions will be optional. Further, only authorized schemas willbe allowed inside ExtensionPoint elements, and any unknown elements will be dropped byMasterpass.

ExtensionPoint—Sample<ExtensionPoint> <s:SampleExtension xmlns:s=“https://www.masterpass.com/location/of/example/ns”> <s:SampleField>Sample Value</s:SampleField> </s:SampleExtension> <f:AnotherExampleExtension xmlns:f=“https://www.masterpass.com/location/of/example2/ns”> <f:SampleContainer> <f:AnotherSampleField>Sample Value</f:AnotherSampleField> </f:SampleContainer> </f:AnotherExampleExtension></ExtensionPoint>



Renew a Mastercard Developers API Key

This section provides information on how to complete the key-renewal process on theMastercard Developers site.

About this task

The Mastercard Developers portal no longer supports the creation or renewal of keys usingcertificate signing request (CSR) files generated with MD5 digest. Renewing keys with suchCSR files will result in the error message “cert renewal failed.”

For instructions on how to work around this potential error, refer to step four of this task.

Procedure

1. Login to Mastercard Developers (https://developer.mastercard.com).2. Click on My Projects.

3. Select the project associated with the key you’re trying to renew.4. In the Keys section of the project page, click the Manage Keys button.

AppendixRenew a Mastercard Developers API Key



5. In the row of the key you need to renew, click the Renew link.

6. In the Renew Key window, click on Upload existing CSR instead.



7. Browse and select the CSR file you’ve generated, and click the Save button.

If you receive an error message when you try to upload your CSR file, try to generate anew CSR file by running the following three OpenSSL commands from your P12 file:

– openssl pkcs12 -in MCOpenAPI.p12 -out key.pem– openssl rsa -in key.pem -out server.key– openssl req -out CSR.csr -key server.key –[digest] –new

Users will only be able to generate SHA standard keys using one of the following keyformats:

– sha1WithRSAEncryption– sha256WithRSAEncryption– sha512WithRSAEncryption– ecdsa-with-SHA1– ecdsa-with-SHA256– ecdsa-with-SHA512

If you have any questions or concerns, contact the Masterpass Merchant Product Team orsend an email to [email protected].




Notice the updated key expiration date.

NOTE: If the CSR you've uploaded is not associated with the private key you are currentlyusing to make API calls, then you must update your integration with the new private key.Failure to do so will cause rejections at the gateway.



Mastercard Developers Key Tool Utility

This topic provides information on the Mastercard Developers key tool utility.

Procedure

1. From the Add A Key screen, click Click Here to launch the Key Tool utility.

2. Under Certificate Request (CSR), do one of the following::

AppendixMastercard Developers Key Tool Utility


– Under Generate a CSR, specify the CSR details, and then click Generate &Download.

– Under Upload an existing CSR, click Choose File, specify a CSR to upload from yoursystem, and then click Submit.

3-D Secure Overview

This topic provides information on the 3-D Secure protocol.

3-D Secure Service DescriptionWhen enrolling for Masterpass™, a merchant selects either Basic Checkout services orAdvanced Checkout payer authentication services.

Basic Checkout is already offered with the core Masterpass™ offering, and facilitates a simplecheckout experience. Advanced Checkout provides merchants a payer authentication serviceto enable a merchant to authenticate its transactions with the issuer of the applicable cardaccount leveraging the 3-D Secure protocol provided through the Mastercard® SecureCode™

or Verified by Visa programs (collectively, the “Programs”).

Merchants have two authentication options to choose from when implementing theMasterpass Checkout button:

1. Basic Checkout: A simple checkout experience where a consumer logs in to theirMasterpass wallet and selects their payment method for use at the merchant site. Thepayment method will be returned to the merchant for checkout completion.

NOTE: No additional enrollment steps are required for merchant integration with BasicCheckout as it is part of the core Masterpass Online services.

2. Advanced Checkout: When this option is selected by a merchant, Advanced Checkoutwill, on behalf of a merchant, attempt authentication leveraging the MastercardSecureCode or Verified by Visa protocols, depending on the card selected by the consumerin connection with the purchase. At this time, Masterpass supports only the brandsincluded here. A merchant may choose this service for each supported card brand offered,such as Mastercard cards, or Visa cards, or for both.

Before Advanced Checkout is selected, a merchant must take the following actions:

a. A merchant must first be enrolled in the Mastercard SecureCode and/or Verified byVisa program, as applicable, directly with their acquirer. Merchants should contacttheir Acquirer in connection with any such enrollment(s).

b. In connection with their Masterpass enrollment and Advanced Checkout opt-in, amerchant must provide the applicable Acquiring Merchant ID and Acquirer ID (BIN) forthe appropriate card brand. In connection with their acquirer enrollment, merchantsmust also provide the Acquiring Merchant ID and Acquirer ID (BIN) for each currencyprocessed (dependent on the applicable Acquirer’s processing requirements). Oncesubmitted, it will take five business days to complete setup.

Appendix3-D Secure Overview


c. The merchant is responsible for providing accurate acquirer data to Mastercard inconnection with their Masterpass enrollment and for updating such information on atimely basis should it change.

d. Providing accurate enrollment data to Mastercard is critical and required—without it,the merchant most likely cannot receive the benefits of the Advanced Checkoutservice or of the associated Programs.

e. The merchant is responsible for submitting correctly formatted authorization andclearing ecommerce values to their payment processor to indicate use of theMastercard SecureCode or Verified by Visa as defined by the Programs, respectively.Specifically, ECI and CAVV (if present) must be amended to the Authorization request.

General Overview of Mastercard SecureCode and Verified by Visa TransactionAuthentication

The Mastercard® SecureCode™ and Verified by Visa payer authentication programs (also,“Programs”) are based on the 3-D Secure protocol.

Service Process Flow for Merchant that Selects Advanced Checkout

1. Consumer shops online at merchant website and selects the Masterpass™ Checkoutbutton to pay.

2. The consumer logs into their wallet to access payment and shipping information.3. The consumer selects their Mastercard, Maestro®, or Visa Card for a payment.4. Based on the payment information provided, the Masterpass system receives a

cmpi_lookup message in order to check the card participation in the applicable cardissuer’s payer authentication.

5. Based on the response, the status of the consumer’s participation in the applicableProgram will be identified. The three responses include an enrolled, not enrolled, andunavailable for authentication.

– If the card is not enrolled or unavailable, there will be no consumer interaction withtheir issuing bank and the applicable consumer’s Masterpass wallet.

– Data will be returned to the merchant via Masterpass indicating that the merchantattempted to authenticate the consumer with the issuer. The merchant will need topass these data elements in the authorization request, specifically the ECI value.

– If the response is the consumer is enrolled in the applicable program, the consumer willhave an interaction with their issuing bank. The following are the four consumerexperiences that can occur. This is controlled only by the card issuer and not the bankproviding the Masterpass wallet service.

– Consumer either passes or fails authentication.– Consumer is asked to Activate their card for 3-D Secure.– The Merchant attempted to authenticate the consumer, but authentication was

unavailable (Attempts)..6. The issuing bank encrypts the results of authentication between the consumer and their

issuing bank and returns this value to Masterpass.



7. Mastercard will receive a response indicating the result of authentication between theconsumer and their issuing bank. The scenarios that may occur are as follows:

– Consumer Fully Authenticates– Consumer Fails Authentication– Consumer Attempted Enrollment During Shopping (Prompted for Activation During

Shopping and did Not Activate their Card)– Authentication was attempted but was unavailable due to the account range not being

enrolled in the authentication service, the cardholder not being enrolled in theauthentication service, or the authentication service itself being unavailable at the timeof authentication

8. Based on the Authentication response from Cardinal Commerce, Mastercard will promptthe consumer for another form of payment or send back the authentication details to themerchant for processing of the transaction.

9. The following authentication data will be sent back:

– AAV (Accountholder Authentication Value)—This value is generated by the issuer or bythe Mastercard Attempts Service and is presented to the merchant for placement in theauthorization request upon successful authentication or attempted authentication ofthe consumer.

– Authentication Method Used—Value should be created by Wallet for merchant toreceive (Initial possible values: "merchant only" or "3DS". “No Authentication”indicates 3-D Secure was not invoked.

– Card Enrollment status—Value should be created by Wallet for merchant to receive(Initial possible values: "manual" ; "directly provisioned" ; "3DS manual")

– ECI (electronic commerce indicator) Flag

– Security Level Indicator (SLI)

– The SLI for Masterpass is 22X, with X being the result of the ECI.– The SLI for Masterpass Digital Secure Remote Payment (DSRP) transactions would

be 24X, with X being the result of the ECI.– PaRes Status– SecureCode Enrollment Status– Signature Verification

10. Specifically the CAVV and the ECI value must be amended to the Authorization in Clearingmessages in accordance with program rules.

Important Merchant InformationMastercard does not represent or warrant that the Advanced Checkout service referencedherein is free from defects and mistakes and provides the service on an “as is” basis. Noparticular results are promised or assured. Merchant expressly assumes all risk for the use ofthe Advanced Checkout service.

Mastercard, at all times, and in its sole discretion, reserves the right to begin and stopsupporting any particular brand, service and/or type of payment transaction.



Merchant indemnifies and holds harmless Mastercard from and against any claim, demand,loss, cost, or expense arising from or relating to use of the Advanced Checkout services.Mastercard expressly disclaims any responsibility with regard to the acts or omissions of anyMerchant or other person in regard to its compliance with applicable law or regulation. Thesigning or electronic signature of the Masterpass™ Merchant Terms of Use for Masterpassservices inclusive of Advanced Checkout, and the submission of any other forms relatedthereto, including the Information Sheet referenced previously, indicates that the Merchantunderstands and agrees to the terms and conditions set forth herein. Merchant acknowledgesthat its acceptance of these terms and conditions is relied upon by Mastercard in permittingthe Merchant’s participation in Masterpass and Advanced Checkout.



Notices

Following are policies pertaining to proprietary rights, trademarks, translations, and detailsabout the availability of additional information online.

Proprietary Rights

The information contained in this document is proprietary and confidential to Mastercard InternationalIncorporated, one or more of its affiliated entities (collectively “Mastercard”), or both.

This material may not be duplicated, published, or disclosed, in whole or in part, without the prior writtenpermission of Mastercard.

Trademarks

Trademark notices and symbols used in this document reflect the registration status of Mastercardtrademarks in the United States. Please consult with the Global Customer Service team or the MastercardLaw Department for the registration status of particular product, program, or service names outside theUnited States.

All third-party product and service names are trademarks or registered trademarks of their respectiveowners.

Disclaimer

Mastercard makes no representations or warranties of any kind, express or implied, with respect to thecontents of this document. Without limitation, Mastercard specifically disclaims all representations andwarranties with respect to this document and any intellectual property rights subsisting therein or any partthereof, including but not limited to any and all implied warranties of title, non-infringement, or suitabilityfor any purpose (whether or not Mastercard has been advised, has reason to know, or is otherwise in factaware of any information) or achievement of any particular result. Without limitation, Mastercard specificallydisclaims all representations and warranties that any practice or implementation of this document will notinfringe any third party patents, copyrights, trade secrets or other rights.

Translation

A translation of any Mastercard manual, bulletin, release, or other Mastercard document into a languageother than English is intended solely as a convenience to Mastercard customers. Mastercard provides anytranslated document to its customers “AS IS” and makes no representations or warranties of any kind withrespect to the translated document, including, but not limited to, its accuracy or reliability. In no event shallMastercard be liable for any damages resulting from reliance on any translated document. The Englishversion of any Mastercard document will take precedence over any translated version in any legalproceeding.

Information Available Online

Mastercard provides details about the standards used for this document—including times expressed,language use, and contact information—on the Publications Support page available on MastercardConnect™. Go to Publications Support for centralized information.

Notices


https://w201.mastercardconnect.com/hsm3ca267/homememb/library/shared/ENG/Support/Menu_Support.shtm

Masterpass Merchant Onboarding & Integration Guide · 2016. 9. 13. · Masterpass Merchant Onboarding & Integration Guide— U.S. Version 6.17 • 14 September 2016 2. ... Merchant

Documents