MasterPass^TM Service Provider Onboarding & Integration Guide - Bulk Merchant Upload Version 6.0

Notices

Proprietary Rights

The information contained in this document is proprietary and confidential to MasterCard International Incorporated, one or more of its affiliated entities (collectively "MasterCard"), or both. This material may not be duplicated, published, or disclosed, in whole or in part, without the prior written permission of MasterCard.

Trademarks

Trademark notices and symbols used in this document reflect the registration status of MasterCard trademarks in the United States. Please consult with the Customer Operations Services team or the MasterCard Law Department for the registration status of particular product, program, or service names outside the United States. All third-party product and service names are trademarks or registered trademarks of their respective owners.

Translation

A translation of any MasterCard manual, bulletin, release, or other MasterCard document into a language other than English is intended solely as a convenience to MasterCard members and other customers. MasterCard provides any translated document to its members and other customers "AS IS" and makes no representations or warranties of any kind with respect to the translated document, including, but not limited to, its accuracy or reliability. In no event shall MasterCard be liable for any damages resulting from members' and other customers' reliance on any translated document. The English version of any MasterCard document will take precedence over any translated version in any legal proceeding.

Content Disclaimer

No assurances are given that the information provided herein is error-free. You acknowledge and agree that inaccuracies and inconsistencies may be present. The information is provided to you on an "AS IS" basis for use at your own risk. MasterCard will not be responsible for any action you take as a result of this document, or any inaccuracies, inconsistencies, formatting errors, or omissions.

Publication Code

MWMI

Release Notes

Date	Enhancement Type	Description
9/19/2014	Updates	Page 7: Added Lightbox UI experience. Page 13: Added New Checkout experience: Connected checkout details Page 48 and 62: Merchant Initialization Service - version V6 Page 47 and 66: Shopping Cart Service - version V6 Page 42, 43, 45 and 46: Checkout version - version V6 Page 48 and 82: Precheckout Service - version v6 Page 50 and 94: Postback Service - version V6 Page 56: Updated QA Checklist Page 59: Lightbox Parameters Page 18, 19, 38, 39 and 104: BMU API Service
10/26/2013	Updates	p.12: Checkout project auto approval p.30: 3DS "No Authentication" value p.35: High resolution image links p.35: MasterPass 'Learn More' link p.51-55: Checkout version v5 schema and xml p.69: Updated result file schema p.71: Instructions to use Developer Zone Key Tool Utility

Overview

This document is intended to orient Merchants and their developers seeking to integrate MasterPass as a checkout option on their website and mobile application.

How does MasterPass work?

MasterPass is a service that enables consumers to store, manage and securely share their payment, shipping and rewards information with the websites and mobile apps they transact with. MasterPass supports checkout on full and mobile websites, as well as in-app purchases on Android^™ and iOS^™ apps.

MasterPass User Interface

The MasterPass user interface, or Lightbox, floats the MasterPass wallet interface on top of the Merchant's web page through illuminated overlays, and backgrounds dimmed to 0.7 opacity. This modern method allows a consumer to interact with their MasterPass digital wallet without having to leave the merchant's page. MasterPass Lightbox is built in a responsive design style allowing it to respond dynamically to the various screen sizes and orientations.

MasterPass supports the following displays:

· Standard Lightbox display

· Standard full screen display

Standard "Lightbox Display" (desktop and laptop)

At full screen, where the browser is set to 100% height and width, the overall Lightbox dimensions are 740 pixels (height) by 700 pixels (width). This is inclusive of the Lightbox header and footer. The interior Lightbox dimensions are 590 pixels (height) by 680 pixels (width). The interior Lightbox dimensions specify the content area within which the Partner can design (see screenshot below).

If the height of the browser is reduced so that the entire Lightbox has a height of 740 pixels and the width is maintained, the content container has the following dimensions: 530 pixels (height) by 680 pixels (width).

If the browser is set to 100% maximum width, but is less than 530 pixels in height (for the content container), vertical scrolling will appear.

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

Standard Mobile Display (.mobi)

Within the .mobi experience, the header and footer are approximately 70 pixels high except for the iPhone 5/5S, which has a header and footer which are approximately 30 pixels high. The interior content area for mobile devices is content dependent. The initial view of content is based on the overall screen sizes. Content that does not fit within the initial view of content can be accessed by scrolling. There will not be a landscape view for mobile; only portrait will be supported.

Standard Full Screen Display

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

MasterPass Checkout Experiences

Overview

MasterPass is introducing new checkout options that offer merchants greater flexibility and control over the MasterPass checkout experience.

	Merchant		MasterPass			Merchant
Experience	Logs into Merchant	Consumer Clicks	Signs into Wallet	Finalizes Payment Method/ Address	Reviews/ Submits Order	Confirms Order	Receipt/ Thank You Page
Standard Checkout	Buy with MasterPass	X	X	X	(recommended)	X
Connected Checkout	X	Checkout	X			X*	X

*If applicable, advanced authentication, will be invoked after this step.

MasterPass Merchant Standard Checkout process flow

The flows below depicts the Standard MasterPass Checkout flow with the Lightbox MasterPass UI. Merchants should use this flow for a non-recognized (guest) user.

MasterPass Connected Checkout Experience

'Connected Checkout" enables MasterPass merchants to provide a customized checkout experience to their registered consumers across all connected channels. In the connected checkout model, consumers who have paired their wallet with the merchant allow that merchant to retrieve the consumer's pre-checkout data (shipping, and other wallet information, without the actual card number without the consumer having to log in to their wallet. The actual PAN will be provided to the merchant only after the consumer logs in to their wallet (by entering only the wallet password). Data shared in connection with the "Connected Checkout" can only be used to implement checkout and must be deleted immediately following the check-out experience. No data shared during the "Connected Checkout" experience may be retained after the checkout is completed. Adherence to MasterPass branding requirements is required. (For display of Wallet Partner logo and MasterPass logo near the pre-checkout information).

Connected checkout is supported by 3 components.

Pairing of wallet

The consumer consents to 'pair' their wallet account with their account on the merchant side (consumer's merchant account), by agreeing to Connected Checkout. Pairing can happen during Checkout or outside of checkout on the merchant site/app. Pairing enables the consumers' MasterPass wallet data to be shared with the merchant during current and/or future visits to merchant app/site. This is accomplished by passing a Long Access token to the merchant. No cardholder data should be retained by the Merchant or Service Provider in between checkouts.

NOTE: Long Access token is a one-time use token. Each time a call using Long Access Token is made, a new Long Access token will be passed back to the merchant. This new Long Access token will then need to be stored, to be used the next time.

Pair with MasterPass Wallet during Checkout

In this experience, a consumer pairs their wallet with a merchant while performing checkout. The pairing process starts when a consumer clicks the 'Buy with MasterPass' button on the merchant site. This begins a set of exchanges that will bring the consumer through MasterPass and back out to the merchant again. If the consumer agrees to pair their wallet with the merchant, the consumer's pre-checkout data will be available to the merchant during the subsequent checkouts without the consumer having to log in to their wallet. When checkout is completed, the consumer data must be immediately deleted.

Pair with MasterPass Wallet outside of a Checkout

In this experience, a consumer pairs their wallet with a merchant while not performing checkout e.g. account management. The pairing process starts when a consumer clicks the 'Connect with MasterPass' button on the merchant site. This begins a set of exchanges that will bring the consumer through MasterPass and back out to the merchant again. If the consumer agrees to pair their wallet with the merchant, the consumer's pre-checkout data will be available to the merchant during their next checkout without the consumer having to log in to their wallet. When checkout is completed, the consumer data must be immediately deleted.

Return Checkout

Once the consumer has paired their wallet account with merchant account, when the consumer returns to the merchant site/app and logs in to their merchant account, the Merchant submits the token to MasterPass to retrieve the consumer's up to date wallet information (card details without card number, addresses etc.). The merchant can then present this information to the consumer as part of their own experience, with the ability to streamline/personalize the consumer's experience during Pre-checkout. Consumers can then checkout easily. The actual PAN will be provided to the merchant only after the consumer logs in to their wallet (by entering the wallet password).

Data shared in connection with the "Return/Connect Checkout" can only be used for the express purposes permitted in the MasterPass Operating Rules and must be removed immediately following the check-out experience. No data shared during the "Return/Connect Checkout" experience may be retained after the checkout is completed. Service Providers that engage in bulk merchant upload, and the Customers that register them, are responsible for ensuring that merchants participating in MasterPass through the bulk merchant upload mechanism comply with this requirement.

Unpairing

A consumer can 'unpair' the token or disconnect their current pairing consent any time, using MasterPass account management. This will prevent the merchant from accessing the consumer's wallet information going forward.

Service Provider Bulk Merchant Upload Model

Incorporating MasterPass into your site or app

Enabling checkout with MasterPass on-behalf of your merchant site or mobile app is straightforward-here are the required activities for the Bulk Merchant Upload model.

Existing Service Providers who would like to use the BMU API can skip down to this section.

Service Providers NEW to MasterPass should start here:

Bulk Merchant Upload

Service Providers can onboard merchants by uploading file(s) containing multiple merchant profiles. Service Providers will access the MasterPass Merchant Portal to enroll and provision their merchants. The Bulk Merchant Upload onboarding process should be used by Service Providers who will be onboarding a large number of merchants and can generate XMLformatted files(s) with the required information for multiple merchants. This process allows multiple merchant profiles to be setup at the same time rather than manually creating a MasterPass account for each merchant. No Merchant interaction with MasterPass is required in this onboarding process. Service Provider developers will create checkout projects and the Service Provider will approve the checkout projects.

All new Service Providers need to go through Steps 1-9 that are summarized in the table below. By following these steps, you will create your relationship to MasterPass, and onboard a first group of merchants. At the successful completion of Step 9, you will have a Checkout Project that has been Approved for Production, and some merchants in the MasterPass system. At this point, the Service Provider would be considered Existing.

Detailed instructions for Steps 1-9 can be found here, or click on the links within the table below.

Activity	Actor	Steps	Environment
1. Service Provider Registration and Setup	Service Provider	Create Service Provider account and create shipping profile	MasterPass Merchant Portal
2. Add Developer to Service Provider Profile	Service Provider	Add Developer to Service Provider Profile	MasterPass Merchant Portal
3. Developer Registration	Developer	Create MasterPass Developer account	MasterPass Merchant Portal
		Create Developer Zone account	MasterCard Developer Zone
		Generate developer's sandbox and production keys
		Review sample code/SDK and design services integration
4. Request Sandbox Credentials	Developer	Create Checkout Project	MasterPass Merchant Portal
		Obtain details for merchant(s) and generate merchant upload file(s).	Service Provider Engineering Environment
		Select merchant file(s), Upload and Review results from the Download Merchant File.	Service Provider Engineering Environment
			MasterPass Merchant Portal
		Submit Checkout Project for sandbox approval.	MasterPass Merchant Portal
5. Review Integration Project & Approval	Service Provider Business Owner	Approve sandbox credentials.	MasterPass Merchant Portal
6. Access Sandbox Credentials	Developer	Obtain checkout IDs for each successfully provisioned merchant. Map each checkout Id to the correct merchant.	MasterPass Merchant Portal
6. Access Sandbox Credentials	Developer	Test against MasterPass sandbox environment	Service Provider Engineering Environment
7. Request Production Credentials	Developer	Submit Checkout Project for production approval	MasterPass Merchant Portal
8. Review Integration Project & Approval	Service Provider Business Owner	Approve production credentials	MasterPass Merchant Portal
9. Production Migration	Developer	Update MasterPass API endpoints, Consumer key, Callback URL and Private Key (p12), if different than Sandbox.	Service Provider Production Environment

Service Providers with an EXISTING MasterPass relationship:

An Existing Service Provider would have already performed Steps 1-9 (summarized in the table above) during their initial Integration. To be considered Existing, a Service Provider will have a Checkout Project that has previously been Approved for Production.

Existing Service Providers have two options for adding, updating and deleting Merchants in the MasterPass system:

Continuing to use the MasterPass Merchant Portal User Interface to upload XML file(s). In other words, you can always choose to simply follow steps 4-9 in the table above to add, update or delete merchants.
Upload XML file(s) by using the BMU API Service, which is explained in the section below. Follow Steps 10-12 below to setup the BMU API Service for your account.

BMU API Service

Once the first checkout project has been approved through to production (Step 8) the Service Provider can then choose to activate the new BMU API Service. Interfacing with the BMU API services will require coding on the Service Provider side. Such work is outside the scope of this document.

Note: For Service Providers that are just beginning MasterPass integration, please allow 2-3 days following the initial checkout project Approval to Production (from Step 8) for the BMU API service to become active for your account. If after this 2-3 day waiting period you still experience issues using the BMU API, please contact merchant_support@masterpass.com.

The BMU API Service can be used to submit XML file(s) to the Open Feed to Production Checkout Project.

Open Feed to Production Project

The Open Feed to Production Checkout Project has the advantage over a standard checkout project in that it allows continuous sumbissions regardless of the approval status and it will auto-submit merchant adds/updates/deletes directly through to "Approved for Production."

To create the Open Feed to Production Checkout Project, you will do the following:

10. Set Auto Approval	Service Provider Business Owner	Check Enable Auto Approval Checkbox	MasterPass Merchant Portal
11. Use Open Feed to Production Checkout Project	Service Provider Business Owner	Check Use Open Feed to Production Checkout Project (Auto Approval must be enabled, step 10)	MasterPass Merchant Portal
12. Send XML to Open Feed Project	Developer	Send XML via API service using the Checkout Project ID.	Upload XML via API
12. Send XML to Open Feed Project	Developer	XML flows automatically to Approved for Production, step 9.	Service Provider Production Environment

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

Account Type	Details	Account Info
Merchant Portal - Service Provider account	Created by Service Provider business owner. This id should be used to login at https://masterpass.com/SP/Merchant/Home Go here to create Service Provider account, invite developers, create shipping profiles, approve checkout projects etc.	Userid: __________ Email: ___________
Merchant Portal - Developer Account(s)	Created when a Service Provider invites a developer. It's a system generated user id. This id should be used to login at https://masterpass.com/SP/Merchant/Home Go here to create checkout project, upload merchant files, get checkout project details etc.	Userid: __________ Email: ___________
Developer Zone - Developer Account(s)	Created by developer and is used for key exchange. This id should be used to login at https://developer.mastercard.com Go here to perform key exchange, download SDKs and Sample Application, Integration Guides and to access FAQs, etc.	Userid: __________ Email: ___________

Account Type

Details

Account Info

Merchant Portal - Service Provider account

Created by Service Provider business owner. This id should be

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

Go here to create Service Provider account, invite developers, create shipping profiles, approve checkout projects etc.

Userid: __________

Email: ___________

Merchant Portal - Developer Account(s)

Created when a Service Provider invites a developer. It's a system generated user id. This id should be used to login at https://masterpass.com/SP/Merchant/Home

Go here to create checkout project, upload merchant files, get checkout project details etc.

Userid: __________

Email: ___________

Developer Zone - Developer Account(s)

Created by developer and is used for key exchange. This id should be used to login at https://developer.mastercard.com

Go here to perform key exchange, download SDKs and Sample Application, Integration Guides and to access FAQs, etc.

Userid: __________

Email: ___________

By the end of the integration, your site or mobile app should be able to:

Display "Buy with MasterPass" button at the start of the checkout experience.
Display "Connect with MasterPass" button.
Invoke and display the MasterPass Lightbox.
Relay MasterPass checkout requests to the MasterPass service.
Get Precheckout data for consumers that have consented to pair their wallets
Receive consumer's billing, shipping address, and rewards data from MasterPass service.
Process card, shipping and rewards information using existing process.

Note that your implementation must satisfy all criteria in the Q/A checklist.

Service Provider Bulk Merchant Upload - Steps

1.Service Provider Registration and Setup-Service Provider Activity

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

Create an Account

Enter Invitation Code

Select Service Provider

After the Service Provider account has been created, select "Shipping Locations" to manage your shipping options. You can have multiple shipping profiles and can also set a preferred shipping profile option.

The Service Provider business owner has an option to enable "Auto Approval" of checkout projects. This feature is available allows Service Providers to determine if they wish to have a checkpoint/audit step prior to having merchants setup in sandbox and production or not. When Auto Approval is enabled, the system will automatically approve any submitted merchant profiles for both Sandbox and Production credentials. This is applicable to all developers associated with the account, and changes are effective immediately. To enable "Auto Approval", click "Account Settings" from the top navigation bar and click on "Enable Auto Approval" check box.

2. Add Developer to Service Provider Profile-Service Provider Activity

The next step is to add developers who will integrate MasterPass into the checkout flow. From the landing page, you will add developers to the Service Provider profile. These developers will handle the technical implementation of MasterPass for merchant sites. Click on Manage Setup and add developers to your Service Provider account. To get started, click the Start This Step button from the MasterPass Setup page.

You will need to indicate who will perform the technical integration. Service Providers who have an internal or contracted engineering team should select An internal or contracted developer, and provide contact information for each developer he/she wishes to invite.

Each developer will receive two invitation emails from MasterPass, indicating that he/she has been invited to handle the technical integration of MasterPass on-behalf of your company. Please forward this integration guide to each invited developer. This integration guide will guide the developer through the integration process.

3. Developer Registration - Developer Activity

Developers invited to integrate MasterPass on behalf of a service provider will manage their integration activities through two portals:

MasterPass Merchant Portal (https://masterpass.com/SP/Merchant/Home)
MasterCard Developer Zone (http://developer.mastercard.com)

MasterPass Developer Account

Developers will use the MasterPass Merchant Portal to request, and access merchant-specific integration credentials, which will be used when interacting with the MasterPass web services. After the service provider invites you as a developer, you should have received your MasterPass Developer credentials in two emails from MasterPass. Follow the instructions in the emails to create your developer account.

MasterCard Developer Zone Account

Developers invited to integrate MasterPass on behalf of a service provider will use MasterCard Developer Zone to view integration documentation and generate developer keys. To create a Developer Zone account, visit Developer Zone and click Create account. After submitting the form, be sure to activate the account using the confirmation email.

Generate MasterCard Developer Zone Developer API Keys

After creating your account, you will need to generate two sets of API keys (one each for the sandbox and production environments). To make keys easy to distinguish, it's recommended to prefix sandbox keys with "SBX_" and production keys with "PRD_".

Create Sandbox Key

To create a Sandbox key, click My Account, then My Dashboard.

On the My Dashboard page, click My Keys button and then click on Add a Key button.

In order to get an API Key, you need to supply a PEM encoded Certificate Request File. You may use a tool of your choice, such as "openssl" or Java's "keytool" to generate this CSR, or you may use the CSR generation tool on the developer zone portal. Click here to see instructions for using CSR generation tool.

Complete the form, select Sandbox for Environment, and click Submit.

You will have Sandbox Key ID at this point.

Create Production Key

To create a Production API key, return to My Dashboard and click on My Keys. Then click on Add a Key and make sure you select Production environment. Complete the form and click Submit.

At this point, developers will have Sandbox and Production Key ID. These IDs will be used when submitting a checkout project to the merchant for approval.

Note: Keys expire after 1 year before which they should be renewed by initiating the Developer Zone Key Renewal process. Notifications at 30, 15 and 1 day prior to key expiration will be sent to the email address associated with the Developer Zone account.

Initiate Development

At this point, developers should begin developing their own implementation. Sample Application for .NET (C#), Java, PHP and Ruby are available for download on Developer Zone .

4. Request Sandbox Credentials - Developer Activity

Prior to allowing the developer's code to interact with the MasterPass the project must be approved by the Service Provider Business Owner. The developer will make two separate approval requests. The first request is to grant the developer access to credentials that will enable his/her code to transact with the MasterPass sandbox environment on-behalf of the merchant. The sandbox environment does not contain real consumer data. The second is for production credentials, which will enable real transactions.

Developers will use MasterPass Merchant Portal to request, and access merchant-specific integration credentials, which will be used when interacting with the MasterPass services. The credentials are requested by submitting a checkout project.

Create Checkout Project

To get started, sign into the MasterPass Merchant Portal. Under Manage Development, click Checkout Projects -> Create New Project and complete the New Project creation wizard.

Enter Project Name, Project Description

Enter the sandbox and production Key IDs that were created from MasterCard Developer Zone.

Bulk Merchant Upload

Service Providers can associate multiple merchant profiles to a checkout project all at once using a merchant upload file. The first step in this process is to obtain the merchant upload file template referenced in the appendix. Service Provider should gather the details for each merchant.

Generate Merchant Files

Once the merchant details are available, developer should create the file(s) to upload. Upload file size cannot be more than 10 MB. For best results, try not to exceed 1000 merchant records in a file. If you want to upload more than 1000 merchants, consider creating multiple files to upload at the same time or as part of a new checkout project.

Select, Upload and Review

Once the merchant files have been generated, click Upload to select the merchant files and initiate the "Bulk Merchant Upload" process.

A message will display indicating the processing has finished and the number of records processed-successes and failures. You will also get an email when the file processing is complete.

Once the processing is complete, click Download Result File to view the results of the Upload process. Any merchant records which fail processing will need to be reviewed, corrected and submitted for processing. A sample Download Result File is available in the appendix.

Submit Checkout Project for Sandbox Approval

After creating the checkout project but before submission, the developer can edit the file to modify previously-entered information. To submit the project for sandbox approval, click Submit. Clicking "Submit" will kick-off the Checkout Project Approval Process.

Note: If Auto Approval is enabled by the business owner, sandbox and production credentials will be generated at this time and steps 5-8 will be skipped.

5. Review Integration Project & Sandbox Approval - Service Provider Activity

Note: Skip if Auto Approval is enabled.

After the Developer submits the request for sandbox credentials, the Service Provider Business Owner will get an email notification. The Service Provider Business Owner will log on to the MasterPass Merchant Portal, review and provide approval.

After clicking Approval Requests on the navigation bar, the user will see a list of open requests. The user will be presented with the option to either Approve or Reject the project. Users can also view processing results by clicking on 'Download Result File' button or download the uploaded file by clicking on 'Download Merchant File'. If rejected, a reason must be provided, and the developer will be allowed to modify the entry and resubmit.

Upon approval, the developer will receive an email containing the Consumer Key for the sandbox environment. The developer will be able to sign into the MasterPass Merchant Portal and access credentials necessary to develop and test his/her MasterPass implementation in the sandbox environment.

6. Access Sandbox Credentials, Complete Development and Test-Developer Activity

Note: Skip if Auto Approval is enabled.

Access Sandbox Details

After signing into the portal, the developer will click the Action Required button associated with the entry, and note the Sandbox Consumer Key. For each successfully uploaded merchant, Developers will obtain the checkout identifiers from the result file and map to the correct merchant. These will be used in the code to call MasterPass web services. Please refer to MasterCard Developer Zone for sample code and SDKs

7. Request Production Credentials-Developer Activity

Note: Skip if Auto Approval is enabled.

Once the application has been tested against sandbox, the Developer will request the production credential. This is done by submitting the checkout project created in Step 4 and submitting it again for approval.

8. Review Integration Project & Production Approval - Service Provider Activity

Note: Skip if Auto Approval is enabled.

After the Developer submits request for production credentials, the Service Provider Business Owner will get an email notification. The business owner will log on to the MasterPass Merchant Portal, review and provide approval (similar to step 5). The user will be presented with the option to either Approve or Reject the project. Users can also view processing results by clicking on 'Download Result File' button. If rejected, a reason must be provided, and the developer will be allowed to modify the entry and resubmit.

9. Deploy application using Production Credentials-Developer Activity

Once the application has been approved, the Developer will receive an email containing the production Consumer Key and will enable the Service Provider platform to transact with the MasterPass Services on-behalf of the Merchant. Prior to production deployment, update your code with the MasterPass API Production endpoints, Consumer Key, Checkout Identifier and the private key if different than Sandbox. The last step is to deploy your code to production. You're all done!

Follow Steps 10-12 to setup BMU API

10. Set Auto-Approval - Service Provider Activity

Once the first checkout project has been completely approved for production, the Auto Approval checkbox will be available in the Account Settings.

Note: The API Service will be made available 2-3 days following the initial SP BMU account creation and the addition of a production approved checkout project.

The Service Provider business owner has an option to enable "Auto Approval" of checkout projects. This feature allows Service Providers to determine if they wish to have a checkpoint/audit step prior to having merchants setup in sandbox and production or not. When Auto Approval is enabled, the system will automatically approve any submitted merchant profiles for both Sandbox and Production credentials. This is applicable to all developers associated with the account, and changes are effective immediately. To enable "Auto Approval", click "Account Settings" from the top navigation bar and click on "Enable Auto Approval" check box. Click on Agree when prompted.

When the Enable Auto Approval checkbox is checked, the checkbox Use Open Feed to Production Checkout Project will be available.

11. Use Open Feed to Production Checkout Project - Service Provider Activity

Service Providers, who want to use the new BMU API Service, will need to create the Open Feed to Production Checkout Project. It is created when the Use Open Feed to Production Checkout Project checkbox is checked for the first time. To create, click "Account Settings" from the top navigation bar and click on "Use Open Feed to Production Checkout Project" check box. To view the newly created Open Feed to Production project, click "Checkout Projects"

When the Use Open Feed to Production Checkout Project checkbox is unchecked, the Open Feed to Production project will be hidden in the UI from the user and any calls made to that project will be rejected. Checking the Use Open Feed to Production Checkout Project checkbox again will unhide the Open Feed to Production project.

12. Upload to Open Feed Checkout Project - Developer Activity

The Open Feed to Production Project can only be used through the BMU API Service. The API Service calls will be initiated by the Service Provider's system where Developers will use the Checkout Project ID and approved consumer key to submit XML through the API.

Once the merchant details are available, the developer will create the XML. The API is limited to file size of less than 399K (409600 bytes).

The Service Provider system should be designed to send the XML to the Open Feed to Production project through the API. Calling the Open Feed to Production checkout project will auto-submit and push merchant adds/updates/deletes directly to "Approved for Production." See Appendix for BMU API Upload parameter details.

Note: For the Open Feed Project, the API service will provide a response if appropriate.

Integration Process

Note: Signature base string, request and response samples are available in theAppendix. Sample code for all the steps in the integration process is also available on Developer Zone .

Lightbox Integration

Lightbox integration is required to launch the MasterPass user interface for consumer wallets. Implementation of MasterPass Lightbox is a pre-requisite to offer Connected checkout. In order to invoke the Lightbox, merchants will need to include the following scripts in the page they implementing the Buy with MasterPass button:

https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js

It is recommended to pull the jQuery file from the public jQuery repository

https://www.masterpass.com/lightbox/Switch/integration/MasterPass.client.js

Standard Checkout

The following steps are necessary to integrate a standard MasterPass checkout. For further information, click on each step of the process.

1. Request Token Service

2. Shopping Cart Service

3. Merchant Initialization Service (Optional based on Shopping Cart parameters.)

4. Invoke MasterPass UI(Lightbox) for checkout

5. Standard Callback method or Redirect to callback URL

6. Access Token Service

7. Retrieve Payment, Shipping Data, Rewards and 3DS Details

8. Authorize Payment through payment processor

9. Postback Service

Invoke MasterPass UI (Lightbox)

Within a script tag the merchant must invoke the checkoutButton method with the required parameters. Here is an example

          <script type="text/javascript"
          language="Javascript">
          MasterPass.client.checkout({
                  "requestToken":"insert_request_token_here",                 
          "callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",                 
          "merchantCheckoutId":"insert_checkout_id_here",                 
          "allowedCardTypes":["master,amex,diners,discover,maestro,visa"],  
                  "version":"v6"
          });

          </script>

Required parameters are:

requestToken- The merchants request token from OpenAPI.
callbackUrl- A URL to redirect the browser to when checkout is complete. Required unless you use the callback method.
merchantCheckoutId- The merchant's unique checkout id.
allowedCardTypes - Card types accepted by merchant
version - checkout version (v6)

Lightbox parameter details can be found here.

Standard Checkout Callback

Once a checkout completes, MasterPass will return context to the merchant. This can be done via:

callback URL or
A javascript call back method. If you wish to use the callback method, "failureCallback" and "successCallback" parameters must be set when invoking MasterPass Lightbox UI.

Redirect to Merchant Callback URL Example

http://www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc">www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10189977%3Fwallet%3Dphw&oauth_verifier=6c50838e31b7441e6eafa2229385452889255b13&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc

Checkout Callback method Example

function onSuccessfulCheckout(data) {                     

    document.getElementById('oauthToken').value=data.oauth_token;    

    document.getElementById('oauthVerifer').value=data.oauth_verifier;

    document.getElementById('checkoutUrl').value=data.checkout_resource_url;

}

Pairing with MasterPass Wallet without Checkout

Note: For Pairing to occur, the merchant must have a way of identifying consumers on the merchant site prior to requesting pairing

The following steps are necessary to establish a connection to a consumer's wallet outside of checkout flow. For further information, click on each step of the process.

Authenticate user on merchant site
Request Token Service
Merchant Initialization Service
Invoke MasterPass UI(Lightbox) for Pairing
Pairing Callback method or Redirect to callback URL
Access Token Service

Invoke MasterPass UI

Consumers can pair their MasterPass wallet with merchant outside of checkout by clicking on "Connect With MasterPass button". Merchants can display the "Connect with MasterPass" button anywhere on their site except on checkout pages or pages where payment is initiated to enable pairing outside of checkout e.g. Account Management.

Within a script the merchant must invoke the connect method with the required parameters. Here is an example

          <script type="text/javascript"
          language="Javascript">
          MasterPass.client.connect({                 
          "pairingRequestToken":"de7647ac630b50f32f5c9addac122614a727ba52f",                 
          "callbackUrl":"http://www.somemerchant.com/pairingcomplete.htm",                 
          "merchantCheckoutId":"insert_checkout_id_here",
                  "requestedDataTypes":"[REWARD_PROGRAM, ADDRESS, PROFILE, CARD]",   
                  "requestPairing":true, 
                  "version":"v6"
          });
          </script>

Required parameters are:

pairingRequestToken- Request token for pairing
callbackUrl- A URL to redirect the browser to when pairing is complete. Required unless you use the callback method.
merchantCheckoutId- The merchant's unique checkout identifier.
requestedDataTypes- an array of data types the merchant wants paired for. Valid values are CARD, PROFILE, ADDRESS and REWARD_PROGRAM.
requestPairing- value should be true
version - checkout version (v6)

Lightbox parameter details can be found here.

Pairing without checkout Callback

Once a pairing flow completes, MasterPass will return context to the merchant. This can be done via a callback URL or a javascript call back method. If you wish to use the callback method, "failureCallback" and "successCallback" parameters must be set when invoking MasterPass lightbox.

Callback Parameter Details

   
    http://www.somemerchant.com/pairingcomplete.htm?status=success&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13&pairing_token=886116426bdb8cd83deed1fbe73df21646016b1f

Pairing Callback method Example

    function onSuccessfulPairing(data) {                          
    document.getElementById('pairingToken').value=data.pairing_token;      
    document.getElementById('pairingVerifer').value=data.pairing_verifier;}

Pairing with MasterPass Wallet during Checkout

The following steps are necessary to establish a connection to a consumer's wallet during a checkout. For further information, click on each step of the process.

Request Token Service* - to get Checkout request token
Request Token Service* - to get pairing request token
Shopping Cart Service
Merchant Initialization Service (Optional based on Shopping Cart parameters)
Invoke MasterPass UI for Standard Checkout with Pairing
Pairing Callback method or Redirect to callback URL
Access Token Service** - to get Checkout pairing token
Access Token Service**- to get long access token
Retrieve Payment, Shipping Data, Rewards and 3DS Details
Authorize Payment through payment processor
Postback Service

*The request token service for checkout and pairing is the same call but needs to be differentiated by the service provider.

**The access token service for checkout and pairing is the same call but one will be for long access token (needed to retrieve pre-checkout data) and other to retrieve checkout data for current transaction

Invoke MasterPass UI for Pairing during Checkout

Within a script tag the merchant must invoke the checkout method with the required parameters. Here is an example

<script type="text/javascript"
language="Javascript">
MasterPass.client.checkout({     
"requestToken":"de4847ac630b50f32f5c9ddac122614a727ba52f",     
"callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",     
"pairingRequestToken":"de7647ac630b50f32f5c9addac122614a727ba52f",
     "requestedDataTypes":"[REWARD_PROGRAM, ADDRESS,PROFILE, CARD]",     
"merchantCheckoutId":"a4d6x6r6zhak9hvkkkl091hvofxxmat4y",
      "allowedCardTypes":["master", "amex","discover"],       
      "requestPairing":true,  
      "version":"v6"
});
</script>

Required parameters are:

requestToken- Request token used to get checkout access token.
callbackUrl- A URL to redirect the browser to when checkout is complete. Required unless you use the callback method.
pairingRequestToken - Request token used to get long access token
requestedDataTypes- an array of data types the merchant wants paired for. Valid values are CARD, PROFILE, ADDRESS and REWARD_PROGRAM. PROFILE and CARD are mandatory.
merchantCheckoutId- The merchant's unique checkout id.
allowedCardTypes - Card types accepted by merchant
requestPairing- value should be true.
version - checkout version (v6)

Lightbox parameter details can be found here.

Pairing during Checkout Callback

Once a checkout and pairing completes, MasterPass will return context to the merchant. This can be done via a callback URL or a javascript call back method. If you wish to use the callback method, "failureCallback" and "successCallback" parameters must be set when invoking MasterPass lightbox. Parameter Details

Redirect to Merchant Callback URL Example

   
          http://www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10706241%3Fwallet%3Dphw&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498&pairing_verifier=6c50838e31b7441e6eafa2229385452889255b13&pairing_token=35b2a0cf87f8160fcb5d24996a12edb7cce4c530

Callback method Example

         
function onSuccessfulCheckout(data)      {                   
  document.getElementById('oauthToken').value=data.oauth_token; 
  document.getElementById('oauthVerifer').value=data.oauth_verifier;
  document.getElementById('checkoutUrl').value=data.checkout_resource_url;
  document.getElementById('pairingToken').value=data.pairing_token;
  document.getElementById('pairingVerifer').value=data.pairing_verifier;   
}

Return Checkout (Checkout after Wallet Pairing)

The following steps are necessary to integrate a connected checkout flow. For further information, click on each step of the process.

Consumer logs onto Merchant site/app
Pre-Checkout Data Service
Consumer makes card / shipping address selection and clicks on 'Buy with MasterPass'
Request Token Service
Shopping Cart Service
Merchant Initialization Service (Optional based on Shopping Cart parameters)
Invoke MasterPass UI for Connected Checkout
Callback method or Redirect to callback URL
Access Token Service (Checkout)
Retrieve Payment, Shipping Data, Rewards and 3DS Details
Authorize Payment through payment processor
Postback Service

Invoke MasterPass UI for Connected Checkout

Connected checkout can be used after a user has paired their wallet. The merchant will pass in selections based on the precheckout data for a streamlined checkout experience.

Within a script tag the merchant must invoke the checkout method with the required parameters. Here is an example

<script type="text/javascript"
language="Javascript">
MasterPass.client.checkoutButton({
        "requestToken":"insert_request_token_here",       
"callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",       
"merchantCheckoutId":"insert_checkout_id_here",
        "cardId":"insert_card_id_here",       
"shippingId":"insert_shipping_address_id_here",       
"precheckoutTransactionId":"insert_prechechout_txn_id_here",
        "walletName":"insert_wallet_name_here",       
"consumerWalletId":"insert_consumer_walletid_here",
        "version":"v6"
});
</script>

Required parameters are:

requestToken- The merchants request token from OpenAPI.
callbackUrl- A URL to redirect the browser to when checkout is complete. This URL should match the domain specified when creating the checkout project. Required unless you use the callback method.
merchantCheckoutId- The merchant's unique checkout id.
cardId- The id of the card the user selected.
shippingId- The id of the shipping address the user selected
precheckoutTransactionId - Pre checkout transaction ID from precheckout xml
walletName - Wallet Name from precheckout xml
consumerwalletId - Consumer Wallet ID id from precheckout xml
version - checkout version (v6)

Lightbox parameter details can be found here

Connected Checkout Callback

Once a checkout completes, MasterPass will return context to the merchant. This can be done via a callback URL or a javascript call back method. If you wish to use the callback method, "failureCallback" and "successCallback" parameters must be set when invoking MasterPass lightbox. Here are the examples

Redirect to Merchant Callback URL Example

http://www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_resource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F10706241%3Fwallet%3Dphw&oauth_verifier=fbe45bcad30299c93765b1fb4b45bab208f84458&oauth_token=d9382e34e0721a68a9952110cecdf89517e45498

Callback method Example

         
function onSuccessfulCheckout(data)      {              
  document.getElementById('oauthToken').value=data.oauth_token; 
  document.getElementById('oauthVerifer').value=data.oauth_verifier;
  document.getElementById('checkoutUrl').value=data.checkout_resource_url;
}

Service Descriptions:

Request Token Service

This should be executed when a consumer clicks "Buy with MasterPass" button or "Connect with MasterPass" button on your site/app.

For Pairing during checkout, this service will need to be called twice:

· once to exchange for a Long Acess Token which is used to retrieve precheckout data and

· once to exchange for an Access Token which is used to retrieve checkout data

Request and response parameter details can be found here.

Sandbox and Production Endpoints

Shopping Cart Service

Merchants must call the Shopping Cart service before invoking the MasterPass UI for checkout. This enables shopping cart data to be displayed to users as they proceed through the MasterPass login and checkout.

Shopping cart request has an optional OriginUrl field, if the merchant sets this, it will remove the need to call the merchant initialization service before displaying the Lightbox. Request and response parameter details can be found here.

Note: The product description needs to be HTML encoded.

Sandbox and Production Endpoints

Merchant Initialization Service

This service is used to secure Lightbox connections between merchant and MasterPass This service requires a request token (OAuthToken); This service call should be used when shopping cart service is not called e.g. pairing during non-checkout flow.

Request and response parameter details can be found here.

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

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

Access Token Service

Next step is to exchange a Request token for an Access token from the MasterPass service. For Pairing during checkout, this service will need to be called twice: once for requesting the checkout access token which is used to retrieve checkout data; and one for requesting the long access token which is used to retrieve pre-checkout data. You will use the Request Token (oauth_token) and Verifier (oauth_verifier) from the merchant callback to get an access token. Request and response parameter details can be found here.

Sandbox and Production Endpoints

Pre-Checkout Data Service

MasterPass provides merchants with the ability to request paired consumer's data (card alias, shipping addresses, loyalty program, and profile information) prior to the actual MasterPass checkout. This gives the merchant the ability to provide the consumer the opportunity to pre-select their checkout options before completing the checkout.

If for any reason the precheckout call gets rejected at MasterPass (merchant requests data that the consumer did not originally consent to, if the pairing has been deleted by the user, if the Long Access token has expired, etc.) the merchant has to request pairing again.

Note: This is not required for standard checkout.

Request and response parameter details can be found here.

Sandbox and Production Endpoints

https://sandbox.api.mastercard.com/masterpass/v6/precheckout

https://api.mastercard.com/masterpass/v6/precheckout

Retrieve Payment, Shipping Data, Rewards and 3DS Details

Now you will use the Checkout Resource URL request parameter (checkout_resource_url) received from the callback URL to retrieve consumer's payment, shipping address, reward and 3DS information from MasterPass. Request and response parameter details can be found here.

Please note that MasterPass performs a CVC/CVV check at card enrollment. However, in accordance with PCI standards, CVC2/CVV2 data is not persisted, and will not be provided to the merchant. As the card data has been validated and securely stored by MasterPass, merchants must not require CVC/CVV entry from a consumer checking out with MasterPass.

Note: In cases where, prior to submitting their order, the cardholder chooses to replace the payment details provided by MasterPass with different, manually entered payment details, Merchants should ask the cardholder to enter CVV2/CVC2/CID as they would in the normal course and should not pass the wallet indicator flag to the acquirer. In this case, the transaction is no longer considered to be a MasterPass transaction. Checkout Postback is still required. It is recommended not to allow consumers to change their card details after returning from MasterPass.

In accordance with MasterCard bulletin Global 550-Identification of PayPass Transactions, a 3-byte wallet Indicator (WID) Flag (WalletID xml element in the checkout xml will be part of the output returned by this request. This value must be passed to your acquiring bank, and will indicate that the customer's payment details were provided by the MasterPass, rather than being manually entered. You many need to work with your payment provider (acquirer, payment gateway, etc.) to understand how best to handle this data element. In the event, your acquirer has not completed implementation of this bulletin, your transactions will continue to process as-is. Please contact your MasterCard representative to get the bulletin.

This project created the following new message elements in Dual Message Authorization, Dual Message Clearing, and the Single Message System to carry this identifier:

Dual Message System (Authorization)-Data element (DE) 48 (Additional Data-Private Data), sub element 26 (Wallet Program Data), subfield 1 (Wallet Identifier)
Dual Message System (Clearing)-PDS 0207 (Wallet Identifier)
Single Message System-DE 48 (Additional Data), sub element 26 (Wallet Program Data), subfield 1 (Wallet Identifier)

Postback Service

Note: This is a mandatory step.

The final step of a MasterPass transaction is a service call from the merchant to MasterPass, communicating the result of the transaction (success or failure). Abandoned transactions do not need to be reported. Please note that the <TransactionId> value should be the value from the <TransactionId> element of the Checkout XML returned in the Checkout request.

Request and response parameter details can be found here.

The following fields are passed in the postback service call:

ConsumerKey: Consumer key from checkout project
Currency: Currency for the transaction e.g. USD
OrderAmount: Transaction Order Amount e.g., 1500 (for $15 transaction amount)
PurchaseDate: Date of Purchase
ApprovalCode: 6-digit approval code returned by payment API.
TransactionId: Transaction ID from TransactionId element of the Checkout XML from the retrieve payment, shipping, rewards and 3DS data service call for example, "35201"
TransactionStatus: Status of transaction. Valid values are

SUCCESS: For approved transaction
FAILURE: For declined transaction

PreCheckoutTransactionId: Comes from PrecheckoutTransactionId element of the PrecheckoutData XML. (this is not required for Standard Checkout)

Sandbox and Production Endpoints

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

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

Android and iOS App Integration

Your Android or iOS application should invoke a backend service to initiate the OAuth authorization. On the native application side, most of the work involves connecting to your backend services.

The basic process is as follows:

Perform a POST to ${server}/appToWallet/initialize with the shopping cart data in the POST message

The server will request the Request Token, post the shopping cart data to MasterPass services and generate the Redirect URL.
The server will pass the Redirect URL and the Callback URL back to the mobile application.

On a 200 response, save the Callback URL, and use the user Redirect URL to open a Web View
Watch the Web View for navigation to the Callback URL.
On navigation to the Callback URL,

If the query parameter section of the Callback URL only contains the oauth_token, the user did not complete selection in MasterPass. Return the user to the cart view, or wherever your particular requirements dictate.
If the query parameter of the Callback URL section contains information, parse out the oauth_token, oauth_verifier, and checkout_resource parameter values, perform a string replacement on the checkout_resource value to replace '/' with '.' and use these to perform a GET to${server}/appToWallet/checkoutInformation/${oauth_token}/${oauth_verifier}/${checkout_resource}
Note: Do not send the full PAN to the mobile device. This information should be stored on the server similarly to the server/browser implementation.

On a 200 response, use the returned information to produce a summary view for the user to give final approval to the transaction (pursuant to your specific requirements.)
After the consumer completes the transaction, the server should submit postback to MasterPass.

MasterPass - Branding

Displaying "Buy with MasterPass" Button and Acceptance Marks

The MasterPass acceptance mark and checkout button image URLs can be found below. To ensure the best consumer experience, the checkout button should be placed at the beginning of the checkout experience, prior to the collection of shipping and billing information.

To minimize the impact of future branding updates, please use the country specific link to the images on the checkout page rather than downloading them and hosting the images locally. In order to successfully integrate with MasterPass and enable successful checkout by an end-user consumer via the service, the "Buy with MasterPass" checkout button must be integrated on the merchant website and displayed as noted in the MasterPass Branding Requirements document available on MasterCard developer zone.

The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO 3166-and Button as shown below: Base URL/Language/Country/Image File Name

Base URL: https://www.mastercard.com/mc_us/wallet/img/

Note: The list of language/country folders can be found at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs under the question, "Which countries and locales are currently supported to link 'Buy with MasterPass' images?"

Buy with MasterPass button Example:

Below is an example of how a Merchant can include the checkout button.

  
<div "MasterPassBtnExample"> 
        <a href="/exampleRedirect"> 
              <imgsrc="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png"alt="Checkout with MasterPass Button Example" /> 
        </a>  
</div>

MasterPass Checkout Images

PNG Checkout Buttons

/mcpp_wllt_btn_chk_147x034px.png

/mcpp_wllt_btn_chk_160x037px.png

/mcpp_wllt_btn_chk_166x038px.png

/mcpp_wllt_btn_chk_180x042px.png

GIF Checkout Buttons

/mcpp_wllt_btn_chk_147x034px.gif
/mcpp_wllt_btn_chk_160x037px.gif
/mcpp_wllt_btn_chk_166x038px.gif
/mcpp_wllt_btn_chk_180x042px.gif

GIF Acceptance Marks

/mp_mc_acc_023px_gif.gif
/mp_mc_acc_030px_gif.gif
/mp_mc_acc_034px_gif.gif
/mp_mc_acc_038px_gif.gif
/mp_mc_acc_050px_gif.gif
/mp_mc_acc_065px_gif.gif
/mp_mc_acc_113px_gif.gif

PNG Checkout Buttons - High Resolution

/mcpp_wllt_btn_chk_290x068px.png

/mcpp_wllt_btn_chk_317x074px.png

/mcpp_wllt_btn_chk_326x076px.png

/mcpp_wllt_btn_chk_360x084px.png

GIF Checkout Buttons - High Resolution

/mcpp_wllt_btn_chk_290x068px.gif

/mcpp_wllt_btn_chk_317x074px.gif

/mcpp_wllt_btn_chk_326x076px.gif

/mcpp_wllt_btn_chk_360x084px.gif

GIF Acceptance Marks - High Resolution

/mp_acc_046px_gif.gif

/mp_acc_060px_gif.gif

/mp_acc_068px_gif.gif

/mp_acc_076px_gif.gif

//mp_acc_100px_gif.gif

/mp_acc_130px_gif.gif

/mp_acc_226px_gif.gif

Here are a few examples

US English URL:
https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x034px.png

Canada French URL:
https://www.mastercard.com/mc_us/wallet/img/fr/CA/mcpp_wllt_btn_chk_147x034px.png

Displaying "Connect with MasterPass" Button

This button is used to initiate Pairing outside of a checkout.

The MasterPass connect button image URLs can be found below. To ensure the best consumer experience, it is recommended that you place the connect button in close proximity to the "Buy with MasterPass" button.

To minimize the impact of future branding updates, please use the country specific link to the images on the checkout page rather than downloading them and hosting the images locally. In order to successfully integrate with MasterPass and enable successful connection by an end-user consumer via the service, the "Connect with MasterPass" connect button must be integrated on the merchant website and displayed as noted in the MasterPass Branding Requirements document available on MasterCard developer zone.

The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO 3166-and Button as shown below: Base URL/Language/Country/Image File Name

Base URL: https://www.mastercard.com/mc_us/wallet/img/.

Here are a few examples

US English URL - Connect Button:

https://www.mastercard.com/mc_us/wallet/img/en/US/mp_connect_with_button_126px.png

Canada French URL - Connect Button:
https://www.mastercard.com/mc_us/wallet/img/fr/CA/mp_connect_with_button_034px.png

Connect with MasterPass button Example:

Below is an example of how a Merchant can include the connect button.

   
<div "MasterPassConnectBtnExample"> 
        <a href="/exampleRedirect"> 
              <img src="https://www.masterpass.com/lightbox/Switch/integration/MasterPass.connect.png"alt="Connect with MasterPass Button Example" /> 
        </a>   
</div>

Connect with MasterPass Images

PNG Connect with Buttons

/mp_connect_with_button_034px.png

/mp_connect_with_button_037px.png

/mp_connect_with_button_038px.png

/mp_connect_with_button_042px.png

/mp_connect_with_button_068px.png

/mp_connect_with_button_074px.png

/mp_connect_with_button_126px.png

MasterPass "Learn More" page

In addition to the MasterPass checkout button and acceptance mark, MasterPass also requires merchants to provide a link to "Learn More" page which can be used by the consumers to get additional information about MasterPass. It is recommended that you place the link in close proximity to the "Buy with MasterPass" button.

"Learn More" page is available in multiple languages and can be accessed from the following link. For the list of all available languages, please refer to FAQs on developer zone

English - http://www.mastercard.com/mc_us/wallet/learnmore/en

Swedish - http://www.mastercard.com/mc_us/wallet/learnmore/se

French - http://www.mastercard.com/mc_us/wallet/learnmore/fr

Italian - http://www.mastercard.com/mc_us/wallet/learnmore/it

Spanish - http://www.mastercard.com/mc_us/wallet/learnmore/es

Please refer to the FAQs for a list of all available countries at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs under the question, "Which languages are currently available for use with the MasterPass 'Learn More' page?"

Testing

MasterPass Sandbox Testing

In order to access the necessary information to test in the sandbox environment, you must submit an approval request to the merchant as explained earlier in the guide. Testing can be conducted in the sandbox environment, using the test consumer account. Your code must gracefully handle the error states and scenarios listed below.

Note: You cannot add cards to a sandbox account. Only shipping addresses can be added to sandbox accounts.

Consumer Account (Sandbox) Do not modify this shared account
Test Account 1
Login Email	Joe.test@email.com	Password	abc123
Answer to Security Question	Pets Name: fido	Security Message
Test Account 2
Login Email	Joe.test3@email.com	Password	abc123
Answer to Security Question	Pets Name: fido	Security Message

Use the "remember me" and "remember this device" options when testing so that you don't have to rekey the entire test account information every time you login to MasterPass.

Once you are redirected to the sandbox environment, select MasterPass wallet to sign-in to Sandbox Consumer Wallet Account. Below is a quick walkthrough of the Wallet experience.

(Select) MasterPass Wallet

Sign-in & Verify Your ID (Login email for Sandbox)

Select Payment & Shipping

Q/A Checklist

Asset Placement

Verify your adherence to the MasterPass Branding Requirements document.
Verify that you are linking to (versus hosting your own) MasterPass visual assets

In-Wallet Experience

Verify that the consumer can only select card/addresses/rewards that are supported by the merchant
Verify shopping cart information is sent to MasterPass and is displayed.

Post Wallet Experience

After clicking the "Finish Shopping" button, verify the consumer is taken to a valid page.
Verify that MasterPass acceptance mark is displayed for all MasterPass transactions
Verify that MasterPass and issuer logo are displayed with pre-checkout data (for connected checkout)
It's recommended to not allow consumers to edit the payment information returned by MasterPass.
Verify that your code gracefully handles consumers returning without selecting a card and address (as a result of user choice or login failure)
Verify that your code handles the return of a consumer with an expired request token. Note: The Request Token is valid for 15 minutes therefore if the process is not completed within the timeout, the request token will expire and the checkout will need to be restarted.
Verify that your code is able to parse and ingest the returned data
Verify that any post-Wallet page has a clear call to action (e.g. select preferred shipping method), versus simply having the consumer review the data they just selected in the Wallet
Verify that consumer is not required to enter CVC/CVV in order to complete the transaction
Verify that non-PCI compliant merchants do not receive the card PAN
Verify that if merchants are provided with the PAN, this value is not displayed on-screen

Postback

Verify that the transaction id submitted as part of a postback was sourced from the associated MasterPass transaction
Verify that the transaction result (Postback) is reported immediately after card authorization

Connected Checkout Experience

Verify that consumer is logged into Merchant site before offering Connected Checkout
For Pairing, you must request at least Card and Profile data elements
If precheckout call gets rejected by MasterPass (merchant requests data that the consumer did not originally consent to, if the pairing has been deleted by the user, if the Long Access token has expired, etc.) the merchant has to request pairing again.
Verify that pairing is offered during checkout or outside of checkout (e.g. account management)

Troubleshooting

If you get "Error 400" when calling MasterPass web services

Verify Authorization header is not missing from the request
Verify Authorization header has the following:

Signature
Consumer Key (exists and correct length)
Nonce
Signature Method
Timestamp
Callback URL (Request Token call only)
oauth_verifier (Access Token call only)
oauth_token (Access Token call only)

If you get "Error 401" when calling MasterPass web services

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

If you get "Error 403 - Forbidden" when calling MasterPass services

Verify correct credentials or correct environment (i.e., sandbox credentials with the prod URL)
Verify timestamp

If you get "Error 500" when calling MasterPass web services

Verify oauth_body_hash exists and is correct (Post Transaction call only)
Verify Content-Type HTTP header is being sent
Verify correct private key
Verify signature is readable (example, encoded incorrectly)

Support

Please refer to the FAQs at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs.

If you have any questions or comments relating to MasterPass integration, please contact us at merchant_support@masterpass.com.

Appendix

Lightbox Parameters

Lightbox Parameters invoked on clicking Buy with MasterPass or Connect with MasterPass button.

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

Parameter name	Data type	Card security	Checkout	Connect	Description
allowedCardTypes	string[]		O		This parameter restricts the payment methods that may be selected based on card brand. Omit this parameter to allow all payment methods. Here are the valid values for different card types MasterCard: master Maestro: maestro American Express: amex Discover: discover Diners: diners Visa: visa
loyaltyEnabled	bool		O		This parameter defines if the merchant is requesting consumer's loyalty details from MasterPass for the transaction. Valid values are true / false
shippingLocationProfile	string[]		O		This parameter defines Merchant's Shipping Profile(s) for the transaction that they set in their account.
callbackUrl	string	O	O	O	This defines the base URL to which the browser is redirected to upon successful or failed completion of the flow if there is no appropriate callback function available.
cardId	string		O		Required for connected checkout. Set to a valid payment card ID.
failureCallback	function	O	O	O	This defines the function to be called when the flow ends in failure. Refer SDK for more examples
loyaltyId	string		O		Optional for connected checkout. Set to a valid loyalty card ID.
merchantCheckoutId	string	R	R	R	This is the checkout identifier which is used to identify the merchant and their checkout branding.
precheckoutTransactionId	string	R			Helps the wallet identify the wallet account for which precheckout data is provided. MasterPass includes this parameter in the checkout xml for Connected checkout
requestBasicCheckout	bool		O		Set to "true" to disable step-up authentication (advanced checkout) during any checkout flow. The default is "false".
requestedDataTypes	string[]		O	R	This indicates the types of data being requested for pairing. Possible values include "PROFILE", "CARD", "ADDRESS", and "REWARD_PROGRAM". "PROFILE" and "CARD" are mandatory data types. Refer to precheckout data xml to get details of these data types. This parameter is required when requestPairing is "true".
requestPairing	bool		O	A	This indicates that the user is being asked to enable pairing. It is automatically set to "true" for the "Connected" flow. The default for other flows is "false".
requestToken	string	R	R	R	This is an OAuth token.
pairingRequestToken	string		O	R	This is an OAuth token.
suppressShippingAddressEnable	Bool		O		When set to "True" shipping address screen is not displayed to consumer. When set to "false", shipping address is displayed and consumer can select.
shippingId	string		O		Optional for connected checkout. Set to a valid shipping destination ID.
walletName	string			R	Required for connected checkout to uniquely identify wallet name
consumerWalletId	string			R	Required for connected checkout to uniquely identify consumer
successCallback	function	O	O	O	This defines the function to be called when the flow ends in success.

OAuth Samples

Request Token

Request Token Parameters

	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 the transition from the wallet site to the merchant checkout page	Variable
	oauth_signature	RSA/SHA1 signature generated from the signature base string	Variable
	oauth_version	oAuth version	1.0
	oauth_nonce	Unique alphanumeric string generated from code	Variable
	oauth_signature_method	oAuth signature method.	RSA-SHA1
	oauth_consumer_key	Consumer Key generated when creating a checkout project on MasterPass Merchant portal	Variable
	oauth_timestamp	Current timestamp	Variable
	realm	Used to differentiate between our mobile and full site. Currently not used.	eWallet
Request Token-Response		Description	Possible Values
Oauth Token	oauth_token	oauth_token is sent in the signature base string, authorization header and redirect URL	Variable
Request Token	oauth_callback_confirmed		Variable
	oauth_expires_in	Time the Request Token expires in seconds	Variable
	oauth_token_secret	Oauth Secret	Variable
	xoauth_request_auth_url	Authorize URL	Variable

Signature Base String Example

    POST&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 Example

POST /oauth/consumer/v1/request_token HTTP/1.1
    Authorization: OAuth
    oauth_callback="http%3A%2F%2Fprojectabc.com%2Fmerchant%2FCallback.jsp",oauth_signature="pzNogGtgShe16%2FwhP4CsTRXkgJ1mv%2FKm6do5ZVi6doKzAJZ0m8QqhiERi5lRuphdyUkhW8LKdUL1TetPdxm32Vtr%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 Example

    oauth_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 Service

Merchant Initialization Parameters

	Merchant Initialization resource Request	Merchant Initialization Resource Response
oauth_signature	X
oauth_version	X
oauth_nonce	X
oauth_signature_method	X
oauth_consumer_key	X
oauth_timestamp	X
realm	X
oauth_body_hash	X
oauth_token	X
Merchant Initialization		X

Merchant Initialization Request Parameter Details

Merchant Initialization Resource-Request		Description	Possible Values
Signature Base String Authorization Header	oauth_signature	RSA/SHA1 signature generated from the signature base string	Variable
	oauth_version	Oauth version.	1.0
	oauth_nonce	Unique alphanumeric string generated from code	Variable
	oauth_signature_method	oauth signature method.	RSA-SHA1
	oauth_consumer_key	Consumer Key generated when creating a checkout project on MasterPass Merchant portal	Variable
	oauth_timestamp	Current timestamp	Variable
	oauth_token	Request token	Variable
	Merchant_Initialization _origin_url	URL of the page that will initialize the lightbox
Merchant Initialization Resource-Response		Description	Possible Values
Oauth Token	oauth_token	oauth_token is sent in the request	Variable
PreCheckout TransactionID	PreCheckout TransactionID	PreCheckoutTransactionID sent in the request only for Connected checkout.	Variable

Signature Base String Example

    POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%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 Example

POST /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%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQh4Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"
    XML

V6/merchant-initialization -XML Schema Request

  
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="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:schema>

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

<MerchantInitializationRequest>
    <OAuthToken>297d0203c3434be0400d8a755a62b65500e944b9</OAuthToken>
    <OriginUrl>https://somemerchant.com</OriginUrl>
</MerchantInitializationRequest>

V6/merchant-initialization -XML Schema Response

<?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/ MerchantInitialization -Sample Response

<MerchantInitializationResponse>
  <OAuthToken>4c7b34cc63a68282bba77a4b34f0192fcb2268fb</OAuthToken>
</MerchantInitializationResponse>

V6 - MerchantInitializationRequest XML Details

MerchantInitializationRequest XML	Element	Description	Type	Min-Max
	MerchantInitializationRequest	Root Element	XML	-
MerchantInitializationRequest	OAuthToken	Request Token (oauth_token) returned by call to the request_token API		-
	PreCheckoutTransactionID	Identifies pre-checkout transaction. Returned from get pre-checkout data call; Optional	string	NA
	OriginUrl	Identifies the URL of the page that will initialize the lightbox.	string	NA
	ExtensionPoint	Reserved for future enhancement. Optional	Any
MerchantInitializationResponse XML	Element	Description	Type	Min-Max
	OAuthToken	Request Token (oauth_token) returned by call to the request_token API	XML	-
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-

ExtensionPoint Elements

Starting with API v6, all schema container elements contain a new optional element named "ExtensionPoint". These elements are intended to provide expandability of the API without requiring a new major version. These elements are defined to contain a sequence of "xs:any", meaning that any XML content can be contained within the element. In order to ensure future expandability, all integrators must not perform any validation of elements received inside an ExtensionPoint element, beyond any that may be defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further, only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be dropped by MasterPass.

ExtensionPoint - Sample

<ExtensionPoint>
       <s:SampleExtension
xmlns:s="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

Shopping Cart Parameters

	Shopping Cart Request	Shopping Cart Response
oauth_signature	X
oauth_version	X
oauth_nonce	X
oauth_signature_method	X
oauth_consumer_key	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
Signature Base String Authorization Header	oauth_signature	RSA/SHA1 signature generated from the signature base string	Variable
	oauth_version	Oauth version	1.0
	oauth_nonce	Unique alphanumeric string generated from code	Variable
	oauth_signature_method	oauth signature method	RSA-SHA1
	oauth_consumer_key	Consumer Key generated when creating a checkout project on MasterPass Merchant portal	Variable
	oauth_timestamp	Current timestamp	Variable
	oauth_body_hash	SHA1 hash of the message body	Variable
Oauth Token	oauth_token	oauth_token is sent in the signature base string, authorization header and redirect URL	Variable
Transfer XML Strings	Shopping Cart Request XML	Merchant Shopping Cart details
Shopping Cart-Response		Description	Possible Values
Oauth Token	oauth_token	oauth_token is sent in the signature base string, authorization header and redirect URL	Variable
Transfer XML Strings	Shopping Cart Response XML

Signature Base String Example

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

HTTP Request Example

POST /masterpass/v6/shopping-cart 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%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQh4Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"

Shopping Cart V6-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="OriginUrl" type="xs:string" minOccurs="0" />
      <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ShoppingCart">
    <xs:sequence>
    <!-- CurrencyCode is defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars. All Monetary Values will be modified by the CurrencyCode. For example a Monetary Value of 11900 combined with a CurrencyCode of USD will be handled at $119.00. -->
      <xs:element name="CurrencyCode" type="xs:string" />
      <xs:element name="Subtotal" type="xs:long" />
      <xs:element name="ShoppingCartItem" type="ShoppingCartItem" minOccurs="0" maxOccurs="unbounded" />
      <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ShoppingCartItem">
    <xs:sequence>
      <xs:element name="Description" type="xs:string" />
      <xs:element name="Quantity" type="xs:long" />
      <xs:element name="Value" type="xs:long" />
      <xs:element name="ImageURL" type="xs:string" minOccurs="0" />
      <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0" />
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="ExtensionPoint">
    <xs:sequence>
      <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any" />
    </xs:sequence>
    <xs:anyAttribute/>
  </xs:complexType>
</xs:schema>

Shopping Cart V6 XML Details

ShoppingCartRequest	Element	Description	Type	Min-Max
	OAuthToken	Request Token (oauth_token) returned by call to the request_token API	String	Variable
	ShoppingCart	Merchant Shopping Cart details.	XML	-
	OriginUrl	Identifies the URL of the page that will initialize the lightbox.	String	Variable
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
ShoppingCart	CurrencyCode	Defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars. All MonetaryValues will be modified by the CurrencyCode	Alpha	3
	Subtotal	Total sum of all the items in the cart excluding shipping, handling and tax. Integer without the decimal e.g. $119.00 USD will be 11900.	Integer	1-12
	ShoppingCartItem	Details of a single shopping cart item.	XML	-
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
ShoppingCartItem	Description	Describes a single shopping cart item.	String	1-100
	Quantity	Number of a single shopping cart item.	Integer	1-12
	Value	Price or monetary value of a single shopping cart item. Cost * Quantity. Integer without decimal e.g., $100.00 is 10000.	Integer	1-12
	ImageURL	Link to shopping cart item image. URLs must be HTTPS, and not HTTP.	String	0-2000
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
ShoppingCartResponse	Element	Description	Type	Min- Max
	OAuthToken	Request Token (oauth_token) returned by call to the request_token API	String	Variable
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-

Shopping Cart Request XML-Sample

<?xml version="1.0" ?>
<ShoppingCartRequest> 
  <OAuthToken>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>
  <OriginUrl>https://somemerchant.com</OriginUrl>
</ShoppingCartRequest>

Shopping Cart Response XML-Sample

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

Shopping Cart-XML Response 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>

Redirect & Callback

Redirect & Callback Parameters

	Redirect to MasterPass	Callback from MasterPass
oauth_token	X	X
oauth_verifier		X
checkout_resource_url		X
acceptable_cards	X
checkout_identifier	X
version	X
suppress_shipping_address	X
auth_basic	X
accept_reward_program	X
shipping_location_profile	X

Redirect & Callback Parameter Details

Redirect to MasterPass		Description	Possible Values
Oauth Token	oauth_token	oauth_token is sent in the signature base string, authorization header and redirect URL	Variable
Redirect URL Parameters	acceptable_cards	Comma delimited list of accepted cards.	master, amex, diners, discover, maestro, visa
	checkout_identifier	Checkout identifier generated when creating a checkout project on MasterPass Merchant portal	Variable
	version	Attribute to indicate which Checkout XML version to return.	v5
	suppress_shipping_address	Flag to suppress the shipping options presented to the user. This parameter is optional and will default to false.	true false
	auth_level	Flag to reduce the 3DS authentication from advanced to basic on per transaction basis. Note: the 3DS level must be set to advance on the merchant profile to be reduced to basic with this flag. Possible value = basic. This parameter is optional and only used when 3DS authentication is used.	basic
	accept_reward_program	Optional flag to specify if you want MasterPass to return consumer's reward program	true / false
	shipping_location_profile	ID of shipping location profile	variable
Callback from MasterPass		Description	Possible Values
Oauth Token	oauth_token	oauth_token is sent in the signature base string, authorization header and redirect URL	Variable
Access Token	oauth_verifier	Verifier is returned on the callback and used in the access token request	Variable
Access Token	checkout_resource_url	Endpoint used to request the users billing and shipping information from MasterPass	Variable

Redirect to MasterPass Example

    https://sandbox.masterpass.com/Checkout/Authorize?oauth_token=c43d6591aa0d01ba85d95f8c1832983f&acceptable_cards=master,amex,diners,discover,maestro,visa&checkout_identifier=a4a6x1ywxlkxzhensyvad1hepuouaesuv&version=v6&suppress_shipping_address=false&accept_reward_program=false

Redirect to Merchant Callback URL Example

    http://projectabc.com/OauthCallbackServlet?oauth_token=c43d6591aa0d01ba85d95f8c1832983f&oauth_verifier=7f09b8d9bd62edd8a96be34a7b5594ce&checkout_resource_url=https://sandbox.api.mastercard.com/masterpass/v6/checkout/282139

Access Token Service

Access Token Parameters

	access_token Request	access_token Response
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	X
oauth_expires_in		X
oauth_token_secret		X
xoauth_request_auth_url		X
oauth_verifier	X

Access Token Parameter Details

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

Signature Base String Example

    POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Faccess_token&oauth_callback%3Dhttp%253A%252F%252Fprojectabc.com%252Fmerchant%252FCallback.jsp%26oauth_consumer_key%3DZGho8Df8vqW-IpGCIu559HYriL093IBXdJeKavp4dce9db2a%25216464586653467358724b616c74475445443349466a413d3d%26oauth_nonce%3D1144858422275061%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1339613436%26oauth_token%3Da02c5c5c1a128c2cebc650ea9aa3dfb7%26oauth_verifier%3D96782690ce6289d0faf45be777d2d86f%26oauth_version%3D1.0

HTTP Request Example

POST /oauth/consumer/v1/access_token HTTP/1.1
      Authorization: OAuth
    oauth_callback="http%3A%2F%2Fprojectabc.com%2Fmerchant%2FCallback.jsp",oauth_signature="OKcp2KmzUEr8kqs%2F7m2ePV6uJ30n786AnZ0kvJSNGV4Q8%2FP3%2Bs7lqv7YIk0yb2h0fUTC7gSHsfJwmCCk4ES%2FlWVIpSRmVxotgLacxj%2FXI08DS0BZ0XMZZIkhY5Dcg775U3Re4GRN4xa9vmbztOBd%2BKkNyFIw35To22N1ZUHrYpI%3D",oauth_version="1.0",oauth_nonce="1144858422275061",oauth_signature_method="RSA-SHA1",oauth_consumer_key="ZGho8Df8vqW-IpGCIu559HYriL093IBXdJeKavp4dce9db2a%216464586653467358724b616c74475445443349466a413d3d",oauth_token="a02c5c5c1a128c2cebc650ea9aa3dfb7",oauth_verifier="96782690ce6289d0faf45be777d2d86f",oauth_timestamp="1339613436",realm="eWallet"

HTTP Response Example

    oauth_token=9429f23bd08f992c41fb5ddabcc03ecd&oauth_token_secret=cd1ab178419c2111fb1171083f5dc8d9

Checkout Resource

Checkout Parameters

	Checkout resource Request	Checkout Resource Response
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
checkout_resource_url	Used as endpoint
Checkout XML		X

Checkout Parameter Details

Checkout Resource-Request		Description	Possible Values
Signature Base String Authorization Header	oauth_signature	RSA/SHA1 signature generated from the signature base string	Variable
	oauth_version	Oauth version.	1.0
	oauth_nonce	Unique alphanumeric string generated from code	Variable
	oauth_signature_method	oauth signature method.	RSA-SHA1
	oauth_consumer_key	Consumer Key generated when creating a checkout project on MasterPass Merchant portal	Variable
	oauth_timestamp	Current timestamp	Variable
	realm	Used to differentiate between our mobile and full site. Currently not used.	eWallet
	oauth_verifier	Verifier is returned on the callback and used in the access token request
Checkout Resource-Response		Description	Possible Values
Oauth Token	oauth_token	oauth_token is sent in the signature base string, authorization header and redirect URL	Variable
Access Token	checkout_resource_url	Endpoint used to request the users billing and shipping information from MasterPass	Variable
Transfer XML Strings	Checkout XML	Details of the Checkout

Signature Base String Example

    GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F349484&oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3D25780242027605%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380053717
    %26oauth_token%3Dc531cce64ca2d88ecb223a8a37afe98e%26oauth_version%3D1.0

HTTP Request Example

GET /masterpass/v6/checkout/4400 HTTP/1.1
    Authorization: OAuth
    oauth_signature="CKs9xjeHksuVNKotsRmoOG0Rwmveoc2dTqnNw8IwlsZeG1ZNkVrPsTjde32YBndHR7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhXGWRrRpjh3ZhHLDOdSxtxjSCJaHFQkfGyq%2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce="25780242027605",oauth_signature_method="RSA-SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_token="c531cce64ca2d88ecb223a8a37afe98e",oauth_timestamp="1380053717",realm="eWallet"

Checkout XML

V6/Checkout-XML Schema

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

  <?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="RewardProgram" type="RewardProgram" minOccurs="0"/>
            <xs:element name="WalletID" type="xs:string"/>
            <xs:element name="PreCheckoutTransactionId" type="xs:string" minOccurs="0"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="AuthenticationOptions">
        <xs:sequence>
            <xs:element name="AuthenticateMethod" type="xs:string" minOccurs="0"/>
            <xs:element name="CardEnrollmentMethod" type="xs:string" minOccurs="0"/>
            <xs:element name="CAvv" type="xs:string" minOccurs="0"/>
            <xs:element name="EciFlag" type="xs:string" minOccurs="0"/>
            <xs:element name="MasterCardAssignedID" type="xs:string" minOccurs="0"/>
            <xs:element name="PaResStatus" type="xs:string" minOccurs="0"/>
            <xs:element name="SCEnrollmentStatus" type="xs:string" minOccurs="0"/>
            <xs:element name="SignatureVerification" type="xs:string" minOccurs="0"/>
            <xs:element name="Xid" type="xs:string" minOccurs="0"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="Card">
        <xs:sequence>
            <xs:element name="BrandId" type="NonEmptyString"/>
            <xs:element name="BrandName" type="NonEmptyString"/>
            <xs:element name="AccountNumber" type="NonEmptyString"/>
            <xs:element name="BillingAddress" type="Address"/>
            <xs:element name="CardHolderName" type="NonEmptyString"/>
            <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/>
            <xs:element name="ExpiryYear" type="Year" minOccurs="0"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="Address">
        <xs:sequence>
            <xs:element name="City" type="NonEmptyString"/>
            <xs:element name="Country" type="Country"/>
            <xs:element name="CountrySubdivision" type="NonEmptyString" minOccurs="0"/>
            <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:complexType name="RewardProgram">
        <xs:sequence>
            <xs:element name="RewardNumber" type="xs:string"/>
            <xs:element name="RewardId" type="xs:string"/>
            <xs:element name="RewardName" type="xs:string" minOccurs="0"/>
            <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/>
            <xs:element name="ExpiryYear" type="Year" minOccurs="0"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:simpleType name="NonEmptyString">
        <xs:restriction base="xs:string">
            <xs:minLength value="1"/>
            <xs:whiteSpace value="collapse"/>
        </xs:restriction>
    </xs:simpleType>
    <xs:simpleType name="Country">
        <xs:restriction base="xs:string">
            <xs:pattern value="[A-Z]{2}"/>
        </xs:restriction>
    </xs:simpleType>
    <xs:simpleType name="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 Response

URL: https://api.mastercard.com/online/v6/checkout/512345?wallet=phw

<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>joe.test@email.com</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>
  <RewardProgram>
    <RewardNumber>123</RewardNumber>
    <RewardId>1234</RewardId>
    <RewardName>ABC Rewards</RewardName>
    <ExpiryMonth>02</ExpiryMonth>
    <ExpiryYear>2015</ExpiryYear>
  </RewardProgram>
</Checkout>

V6 - Checkout XML Details

CheckoutXML	Element	Description	Type	Min-Max
	Checkout	Root Element	XML	-
Checkout	Card	Child Element	XML	-
Card	BrandId	Identifies the card brand id e.g. master for MasterCard.	Alpha Numeric	0-8
	BrandName	Identifies the card brand name e.g. MasterCard	String	0-255
	AccountNumber	Card number or primary account number that identifies the card	Integer	13-24
	BillingAddress	Billing Address for the card holder.	XML	-
	CardHolderName	Cardholder name	String	1-100
	ExpiryMonth	Expiration month displayed on the payment card.	Date	XML format
	ExpiryYear	Expiration year displayed on the payment card.	Date	XML format
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
Checkout	TransactionID	Child Element	String	1-255
Checkout	Contact	Child Element	XML
Contact (V5 Updates)	FirstName	Contact First Name	String	1-20
Optional	MiddleName	Contact Middle Name or Initial	String	1-20
	LastName	Contact Surname	String	1-20
Optional*	Gender	Contact Gender (M or F)	"M" or "F"
Optional *	DateOfBirth	Contact DOB - YYYY/MM/DD	Sequence: Year (Int); Month (Int) Day (Int)	Y (4) M (2) D (2)
Optional* (dependent on merchant country of incorporation and the consumer country of residence)	NationalID	Contact National Identification	String	1-150
Optional	Country	Contact Country of Residence	String	0-2
	EmailAddress	Contact Email Address	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
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
Checkout	ShippingAddress	Child Element	XML	-
ShippingAddress	Address	Child Element	XML	-
Address	City	Cardholder's city	String	0-25
	Country	Cardholder's country. Defined by ISO 3166-1 alpha-2 digit country codes e.g. US is United States, AU is Australia, CA is Canada, GB is United Kingdom, etc.	String	2
	CountrySubdivision	Cardholder's country subdivision. Defined by ISO 3166-1 alpha-2 digit code e.g. US-VA is Virginia, US-OH is Ohio	String	5
	Line 1	Address line 1 used for Street number and Street Name.	String	1-40
	Line 2	Address line 2 used for Apt Number, Suite Number ,etc.	String	0-40
	Line 3	Address line 3 used to enter remaining address information if it does not fit in Line 1 and Line 2	String	0-255
	PostalCode	Postal Code or Zip Code appended to mailing address for the purpose of sorting mail.	String	0-20
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
ShippingAddress	RecipientName	Name of person set to receive the shipped order.	String	1-100
ShippingAddress	RecipientPhoneNumber	Phone of the person set to receive the shipped order.	String	3-20
Checkout	AuthenticationOptions	Child Element	XML	-
AuthenticationOptions	AuthenticateMethod	Method used to authenticate the cardholder at checkout. Valid values are "MERCHANT ONLY", "3DS" and "No Authentication".	Alpha	NA
	CardEnrollmentMethod	Method by which the card was added to the wallet. Valid values are: Manual Direct Provisioned 3DS Manual NFC Tap	Alpha	NA
	CAvv	(CAVV) Cardholder Authentication Verification Value generated by card issuer upon successful authentication of the cardholder and which should be . This should be passed in the authorization message	Alpha Numeric	NA
	EciFlag:	Electronic commerce indicator (ECI) flag. Present when the PaRes value is "Y" or "A." Possible values are; 01-Indicates Merchant Liability (MasterCard) 02-Indicates Card Issuer Liability (MasterCard) 05-Indicates Card Issuer Liability (Visa) 06-Indicates Card Issuer Liability (Visa) 07-Indicates Merchant Liability (Visa)	Alpha Numeric	NA
	MasterCardAssignedID	This value is assigned by MasterCard and represents programs associated directly with Maestro cards. This field should be supplied in the authorization request by the merchant.	Alpha Numeric	NA
	PaResStatus	A message formatted, digitally signed, and sent from the ACS (issuer) to the MPI providing the results of the issuer's SecureCode/Verified by Visa cardholder authentication. Possible values are: Y-the card was successfully authenticated via 3DS A-signifies that either; 1) the transaction was successfully authenticated via a 3DS attempts transaction; or 2)The cardholder was prompted to activate 3DS during shopping but declined (Visa). U-Authentication results were unavailable	Alpha	NA
	SCEnrollmentStatus	SecureCode Enrollment Status: Indicates if the issuer of the card supports payer authentication for this card. Possible values are; Y-The card is eligible for 3DS authentication. N-The card is not eligible for 3DS authentication. U-Lookup of the card's 3DS eligibility status was either unavailable, or the card is inapplicable (i.e. prepaid cards).	Alpha	NA
	SignatureVerification:	Signature Verification. Possible values are: Y- Indicates that the signature of the PaRes has been validated successfully and the message contents can be trusted. N-Indicates that for a variety of reasons (tampering, certificate expiration, etc.) the PaRes could not be validated, and the result should not be trusted.	Alpha	NA
	XID	Transaction identifier resulting from authentication processing.	Alpha Numeric	NA
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
Checkout	Reward Program	Child Element	XML
Reward Program	RewardNumber	Consumer's reward number associated with the reward program	Alpha Numeric
Reward Program	RewardId	ID associated with the reward program	Alpha Numeric
	RewardName	Name of reward program	Alpha Numeric
	ExpiryMonth	Month the reward program expires	Alpha Numeric
	ExpiryYear	Year the reward program expires	Alpha Numeric
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
PreCheckoutTransactionId	Pre Checkout Transaction ID	ID associated with the PreCheckout Transaction	Alpha Numeric

* Only when legally required and enabled by MasterPass

Pre-Checkout Service

Pre-Checkout Parameters

	Checkout resource Request	Checkout Resource Response
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
PreCheckout Data Request XML	X
PreCheckout Data Response XML		X

Pre Checkout Parameter Details

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

Signature Base String Example

    GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F349484&oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3D25780242027605%26oauth_signature_method%3DRSA-SHA1%26oauth_timestamp%3D1380053717 %26oauth_token%3Dc531cce64ca2d88ecb223a8a37afe98e%26oauth_version%3D1.0

HTTP Request Example

POST /masterpass/v6/precheckout/4400 HTTP/1.1 Authorization: OAuth
    oauth_signature="CKs9xjeHksuVNKotsRmoOG0Rwmveoc2dTqnNw8IwlsZeG1ZNkVrPsTjde32YBndHR7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhXGWRrRpjh3ZhHLDOdSxtxjSCJaHFQkfGyq%2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce="25780242027605",oauth_signature_method="RSA-SHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_token="c531cce64ca2d88ecb223a8a37afe98e",oauth_timestamp="1380053717",realm="eWallet"

V6/PreCheckoutDataRequest-XML Schema

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

<?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="PrecheckoutDataRequest" type="PrecheckoutDataRequest"/>
    <xs:complexType name="PrecheckoutDataRequest">
        <xs:sequence>
            <xs:element name="PairingDataTypes" type="PairingDataTypes"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="PairingDataType" type="PairingDataType"/>
    <xs:complexType name="PairingDataType">
        <xs:sequence>
            <xs:element name="Type">
                <xs:simpleType>
                    <xs:restriction base="xs:string">
                        <xs:enumeration value="CARD"/>
                        <xs:enumeration value="ADDRESS"/>
                        <xs:enumeration value="REWARD_PROGRAM"/>
                        <xs:enumeration value="PROFILE"/>
                    </xs:restriction>
                </xs:simpleType>
            </xs:element>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="PairingDataTypes" type="PairingDataTypes"/>
    <xs:complexType name="PairingDataTypes">
        <xs:sequence>
            <xs:element name="PairingDataType" type="PairingDataType" minOccurs="1" maxOccurs="unbounded"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:complexType name="ExtensionPoint">
        <xs:sequence>
            <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/>
        </xs:sequence>
        <xs:anyAttribute/>
    </xs:complexType>    
</xs:schema>

V6/PreCheckoutData -Sample Request

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

  <PrecheckoutDataRequest>
    <PairingDataTypes>
        <PairingDataType>
            <Type>CARD</Type>
        </PairingDataType>
        <PairingDataType>
            <Type>ADDRESS</Type>
        </PairingDataType>
        <PairingDataType>
            <Type>PROFILE</Type>
        </PairingDataType>
        <PairingDataType>
            <Type>REWARD_PROGRAM</Type>
        </PairingDataType>
    </PairingDataTypes>
</PrecheckoutDataRequest>

V6 - PreCheckoutData XML Details

PreCheckoutXML	Element	Description	Type	Min-Max
	PrecheckoutDataRequest	Root Element	XML	-
PrecheckoutDataRequest	PairingDataTypes	Child Element	XML	-
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
	PairingDataType	Child Element	XML	-
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
PairingDataType	PairingDataType	Child Element	XML	-
PairingDataType	PairingDataType	Card, ShippingAddress, Reward_Program, Profile	String	-
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-

V6/PreCheckoutDataResponse-XML Schema

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
    <xs:element name="PrecheckoutDataResponse" type="PrecheckoutDataResponse"/>
    <xs:complexType name="PrecheckoutDataResponse">
        <xs:sequence>
            <xs:element name="PrecheckoutData" type="PrecheckoutData"/>
            <xs:element name="WalletPartnerLogoUrl" type="xs:anyURI"/>
            <xs:element name="MasterpassLogoUrl" type="xs:anyURI"/>
            <xs:element name="LongAccessToken" type="xs:string" minOccurs="1"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="PrecheckoutData" type="PrecheckoutData"/>
    <xs:complexType name="PrecheckoutData">
        <xs:sequence>
            <xs:element name="Cards" type="PrecheckoutCards"/>
            <xs:element name="Contact" type="Contact" minOccurs="0"/>
            <xs:element name="ShippingAddresses" type="PrecheckoutShippingAddresses"/>
            <xs:element name="RewardPrograms" type="PrecheckoutRewardPrograms"/>
            <xs:element name="WalletName" type="xs:string" minOccurs="1"/>
            <xs:element name="PrecheckoutTransactionId" type="xs:string" />
            <xs:element name="ConsumerWalletId" type="xs:string" minOccurs="1"/>
            <xs:element name="Errors" type="Errors" minOccurs="0"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="PrecheckoutCards" type="PrecheckoutCards"/>  
    <xs:complexType name="PrecheckoutCards">
        <xs:sequence>
            <xs:element name="Card" type="PrecheckoutCard" minOccurs="0" maxOccurs="unbounded"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="PrecheckoutCard" type="PrecheckoutCard"/>
    <xs:complexType name="PrecheckoutCard">
        <xs:sequence>
            <xs:element name="BrandId" type="xs:string" />
            <xs:element name="BrandName" type="xs:string" />
            <xs:element name="BillingAddress" type="Address" />
            <xs:element name="CardHolderName" type="xs:string" />
            <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/>
            <xs:element name="ExpiryYear" type="Year" minOccurs="0"/>
            <xs:element name="CardId" type="xs:string"></xs:element>
            <xs:element name="LastFour" type="xs:string" />
            <xs:element name="CardAlias" type="xs:string" />
            <xs:element name="SelectedAsDefault" type="xs:boolean" />
            <xs:element name="BNBUnverified" type="xs:boolean" />
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
      <xs:complexType name="Contact">
    <xs:sequence>
      <xs:element name="FirstName" type="NonEmptyString"/>
      <xs:element name="MiddleName" minOccurs="0">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:minLength value="1"/>
            <xs:maxLength value="150"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="LastName" type="NonEmptyString"/>
      <xs:element name="Gender" type="Gender" minOccurs="0"/>
      <xs:element name="DateOfBirth" type="DateOfBirth" minOccurs="0"/>
      <xs:element name="NationalID" minOccurs="0">
        <xs:simpleType>
          <xs:restriction base="xs:string">
            <xs:minLength value="1"/>
            <xs:maxLength value="150"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="Country" type="Country"/>
      <xs:element name="EmailAddress" type="EmailAddress"/>
      <xs:element name="PhoneNumber" type="xs:string"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="NonEmptyString">
    <xs:restriction base="xs:string">
      <xs:minLength value="1"/>
      <xs:whiteSpace value="collapse"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="Gender">
    <xs:restriction base="xs:token">
      <xs:enumeration value="M"/>
      <xs:enumeration value="F"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:complexType name="DateOfBirth">
    <xs:sequence>
      <xs:element name="Year">
        <xs:simpleType>
          <xs:restriction base="xs:int">
            <xs:minInclusive value="1900"/>
            <xs:pattern value="\d{4}"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
      <xs:element name="Month" type="Month"/>
      <xs:element name="Day">
        <xs:simpleType>
          <xs:restriction base="xs:int">
            <xs:minInclusive value="1"/>
            <xs:maxInclusive value="31"/>
          </xs:restriction>
        </xs:simpleType>
      </xs:element>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
  <xs:simpleType name="Month">
    <xs:restriction base="xs:int">
      <xs:minInclusive value="1"/>
      <xs:maxInclusive value="12"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="Year">
    <xs:restriction base="xs:int">
      <xs:minInclusive value="2013"/>
      <xs:pattern value="\d{4}"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="Country">
    <xs:restriction base="xs:string">
      <xs:pattern value="[A-Z]{2}"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:simpleType name="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:element name="PrecheckoutShippingAddresses" type="PrecheckoutShippingAddresses"/>
    <xs:complexType name="PrecheckoutShippingAddresses">
        <xs:sequence>
            <xs:element name="ShippingAddress" type="PrecheckoutShippingAddress" minOccurs="0" maxOccurs="unbounded"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="PrecheckoutShippingAddress" type="PrecheckoutShippingAddress"/>
    <xs:complexType name="PrecheckoutShippingAddress">
        <xs:complexContent>
            <xs:extension base="Address">
                <xs:sequence>
                    <xs:element name="RecipientName" type="xs:string" />
                    <xs:element name="RecipientPhoneNumber" type="xs:string" />
                    <xs:element name="AddressId" type="xs:string"/>
                    <xs:element name="SelectedAsDefault" type="xs:boolean" />
                    <xs:element name="ShippingAlias" type="xs:string" />
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
  <xs:complexType name="Address">
    <xs:sequence>
      <xs:element name="City" type="NonEmptyString"/>
      <xs:element name="Country" type="Country"/>
      <xs:element name="CountrySubdivision" type="NonEmptyString" minOccurs="0"/>
      <xs:element name="Line1" type="NonEmptyString"/>
      <xs:element name="Line2" type="NonEmptyString" minOccurs="0"/>
      <xs:element name="Line3" type="NonEmptyString" minOccurs="0"/>
      <xs:element name="PostalCode" type="NonEmptyString" minOccurs="0"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
    </xs:sequence>
  </xs:complexType>
    <xs:element name="PrecheckoutRewardPrograms" type="PrecheckoutRewardPrograms"/>
    <xs:complexType name="PrecheckoutRewardPrograms">
        <xs:sequence>
            <xs:element name="RewardProgram" type="PrecheckoutRewardProgram" minOccurs="0" maxOccurs="unbounded"/>
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
    <xs:element name="PrecheckoutRewardProgram" type="PrecheckoutRewardProgram"/>
    <xs:complexType name="PrecheckoutRewardProgram">
        <xs:sequence>
            <xs:element name="RewardNumber" type="xs:string"/>
            <xs:element name="RewardId" type="xs:string"/>
            <xs:element name="RewardName" type="xs:string" minOccurs="0"/>
            <xs:element name="ExpiryMonth" type="Month" minOccurs="0"/>
            <xs:element name="ExpiryYear" type="Year" minOccurs="0"/>
            <xs:element name="RewardProgramId" type="xs:string"/>
            <xs:element name="RewardLogoUrl" type="xs:string" />
            <xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
        </xs:sequence>
    </xs:complexType>
  <xs:complexType name="Error">
    <xs:sequence>
      <xs:element name="Description" type="xs:string" minOccurs="0"/>
      <xs:element name="ReasonCode" type="xs:string"/>
      <xs:element name="Recoverable" type="xs:boolean"/>
      <xs:element name="Source" type="xs:string"/>
      <xs:element name="Details" type="Details" minOccurs="0" maxOccurs="1"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="Errors">
    <xs:sequence>
      <xs:element name="Error" type="Error" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="Details">
    <xs:sequence>
      <xs:element name="Detail" type="Detail" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>
  <xs:complexType name="Detail">
    <xs:sequence>
      <xs:element name="Name" type="xs:string"/>
      <xs:element name="Value" type="xs:string"/>
    </xs:sequence>
  </xs:complexType> 
  <xs:complexType name="ExtensionPoint">
    <xs:sequence>
      <xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/>
    </xs:sequence>
    <xs:anyAttribute/>
  </xs:complexType>
</xs:schema>

V6/PreCheckoutData -Sample Response

<PrecheckoutDataResponse>
    <PrecheckoutData>
        <Cards>
            <Card>
                <BrandId>master</BrandId>
                <BrandName>MasterCard</BrandName>
                <CardHolderName>Joe Cardholder</CardHolderName>
                <ExpiryMonth>2</ExpiryMonth>
                <ExpiryYear>2016</ExpiryYear>
                <CardId>10153047</CardId>
                <LastFour>2149</LastFour>
                <CardAlias>Rewards Card</CardAlias>
                <SelectedAsDefault>false</SelectedAsDefault>
            </Card>
            <Card>
                <BrandId>master</BrandId>
                <BrandName>MasterCard</BrandName>
                <CardHolderName>Joe Cardholder</CardHolderName>
                <ExpiryMonth>2</ExpiryMonth>
                <ExpiryYear>2016</ExpiryYear>
                <CardId>12963120</CardId>
                <LastFour>0144</LastFour>
                <SelectedAsDefault>true</SelectedAsDefault>
            </Card>
        </Cards>
        <Contact>
            <FirstName>Joe</FirstName>
            <LastName>Cardholder</LastName>
            <Country>US</Country>
            <EmailAddress>joe.cardholder@gmail.com</EmailAddress>
            <PhoneNumber>1-6365555309</PhoneNumber>
        </Contact>
        <ShippingAddresses>
            <ShippingAddress>
                <City>chesterfield</City>
                <Country>US</Country>
                <CountrySubdivision>US-MO</CountrySubdivision>
                <Line1>123 main st</Line1>
                <Line2/>
                <Line3/>
                <PostalCode>63017</PostalCode>
                <RecipientName>Joe Cardholder</RecipientName>
                <RecipientPhoneNumber>1-6365555309</RecipientPhoneNumber>
                <AddressId>10423457</AddressId>
                <SelectedAsDefault>true</SelectedAsDefault>
            </ShippingAddress>
            <ShippingAddress>
                <City>St Louis</City>
                <Country>US</Country>
                <CountrySubdivision>US-MO</CountrySubdivision>
                <Line1>11642 Frontier Dr</Line1>
                <Line2/>
                <Line3/>
                <PostalCode>63146</PostalCode>
                <RecipientName>Joe Cardholder</RecipientName>
                <RecipientPhoneNumber>1-6365555309</RecipientPhoneNumber>
                <AddressId>10073359</AddressId>
                <SelectedAsDefault>false</SelectedAsDefault>
            </ShippingAddress>
        </ShippingAddresses>
        <WalletName>Mobile</WalletName>
        <PrecheckoutTransactionId>a4d6x6s-55pqrj-hyko44a5-1-hyq76c51-a4a</PrecheckoutTransactionId>
        <ConsumerWalletId>10073003</ConsumerWalletId>
    </PrecheckoutData>    
    <WalletPartnerLogoUrl>https://www.masterpass.com/walletlogo.png </WalletPartnerLogoUrl>       <MasterpassLogoUrl>https://www.masterpass.com/masterpasslogo.png </MasterpassLogoUrl>    <LongAccessToken>a2abae6b0b21be8fc23113bf8477a7dd1f0f4041</LongAccessToken>
</PrecheckoutDataResponse>

V6 - PreCheckoutData Response XML Details

PreCheckouthataXML	Element	Description	Type	Min-Max
	PrecheckoutData	Root Element	XML	-
PrecheckoutData	Cards	Child Element	PrecheckoutCard	-
	Contact	Child Element	Contact	-
	ShippingAddresses	Child Element	PrecheckoutShippingAddress	-
	WalletName	Child Element	String	-
	RewardPrograms	Child Element	PrecheckoutRewardProgram	-
	PrecheckoutTransactionId	Child Element	String	-
	ConsumerWalletId	Child Element	String	-
	WalletPartnerLogoUrl	Child Element	String	-
	MasterpassLogoUrl	Child Element	String
	LongAccessToken	Child Element	String
	Errors	Child Element	String	-
	PrecheckoutCard	Root Element	String	-
	CardId	Child Element	String	-
	BrandId	Child Element	String	-
	BrandName	Child Element	String	-
	BillingAddress	Child Element	Address	-
	CardHolderName	Child Element	String	-
	LastFour	Child Element	String	-
	CardAlias	Child Element	String	-
	ExpiryMonth	Child Element	String	0-9, 2
	ExpiryYear	Child Element	String	0-9, 4
	SelectedAsDefault	Child Element	Boolean	-
	ExtensionPoint		Any	-
	Contact	Root Element	String	-
Contact	FirstName	Child Element	String	-
	MiddleName	Child Element	String	1-150
	LastName	Child Element	String	-
	Gender*	Child Element	String	M/F
	DateOfBirth	Child Element	String	-
DateOfBirth	Year	Child Element	Integer	1900, 4
	Month	Child Element	Integer	1-12
	Day	Child Element	Integer	1-31
	ExtensionPoint		Any	-
Contact	NationalId*	Child Element	String	1-150
	Country	Child Element	Country	-
	EmailAddress	Child Element	EmailAddress	-
	PhoneNumber	Child Element	String	-
	ExtensionPoint		Any	-
	PrecheckoutShippingAddress	Root Element	String	-
PrecheckoutShippingAddress	Address	Child Element	String	-
Address	AddressId	Child Element	String	-
	RecipientName	Child Element	String	-
	RecipientPhoneNumber	Child Element	String	-
	SelectedAsDefault	Child Element	Boolean	-
	ShippingAlias	Child Element	String	-
	ExtensionPoint		Any	-
	PrecheckoutRewardProgram	Root Element	String	-
PrecheckoutRewardProgram	RewardProgramId	Child Element	String	-
	RewardNumber	Child Element	String	-
	RewardId	Child Element	String	-
	RewardName	Child Element	String	-
	ExpiryMonth	Child Element	String	0-9, 2
	ExpiryYear	Child Element	String	0-9, 4
	RewardLogo	Child Element	Logo	-
	ExtensionPoint		Any	-
	Address	Root Element	String	-
Address	Line1	Child Element	String	1-40
	Line2	Child Element	String	0-40
	Line3	Child Element	String	0-255
	City	Child Element	String	1-25
	CountrySubdivision	Child Element	String	0-255
	PostalCode	Child Element	String	0-10
	Country	Child Element	String	0-255
	ExtensionPoint		Any	-
	Country	Root Element	String	-
Country	Code	Child Element	String	A-Z, 3
	Name	Child Element	String	-
	CallingCode	Child Element	String	-
	Locale	Child Element	String	-
	EmailAddress	Root Element	String	-
	Logo	Root Element	String	-
Logo	Ref	Child Element	String	-
	Height	Child Element	String	-
	Width	Child Element	String	-
	BackgroundColor	Child Element	String	-
	Url	Child Element	String	-
	LongDescription	Child Element	String	-
	Errors	Root Element	Error	-
Errors	Error	Child Element	String	-
Error	Description	Child Element	String	-
	ReasonCode	Child Element	String	-
	Recoverable	Child Element	Boolean	-
	Source	Child Element	String	-

*Only when legally required and enabled by MasterPass

ExtensionPoint Elements

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>

Postback Service

Postback Parameters

	Post Transaction Request	Post Transaction Response
oauth_signature	X
oauth_version	X
oauth_nonce	X
oauth_signature_method	X
oauth_consumer_key	X
oauth_timestamp	X
oauth_body_hash	X
MerchantTransactions XML	X	X

Postback Parameter Details

Post Transaction-Request		Description	Possible Values
Signature Base String Authorization Header	oauth_signature	RSA/SHA1 signature generated from the signature base string	Variable
	oauth_version	Oauth version.	1.0
	oauth_nonce	Unique alphanumeric string generated from code	Variable
	oauth_signature_method	oauth signature method.	RSA-SHA1
	oauth_consumer_key	Consumer Key generated when creating a checkout project on MasterPass Merchant portal	Variable
	oauth_timestamp	Current timestamp	Variable
	oauth_body_hash	SHA1 hash of the message body	Variable
Transfer XML Strings	Merchant Transactions XML	Transaction details
Post Transaction-Response		Description	Possible Values
Transfer XML Strings	Merchant Transactions XML	Transaction details

Signature Base String Example

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

HTTP Request Example

POST /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-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="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

<MerchantTransaction>
  <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>
</MerchantTransaction>

MerchantTransactionsResponse-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="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 was successful)

<MerchantTransaction>
  <TransactionId>4549794</TransactionId>
  <ConsumerKey>0zMKpm0nFt9682b563745776b593652377939673d</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-7</PreCheckoutTransactionId>
  <ExpressCheckoutIndicator>true</ExpressCheckoutIndicator>
</MerchantTransaction>

MerchantTransactionsXML-Details

MerchantTransactionsRequest	Element	Description	Type	Min - Max
	MerchantTransactions
	MerchantTransaction		XML	-
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
MerchantTransaction	TransactionID	Uses the TransactionID element of the Checkout XML	String	1-255
	ConsumerKey	Automatically generated when creating a checkout project on MasterPass Merchant portal.	String	97
	Currency	Currency of the transaction. Defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars.	String	3
	OrderAmount	(Integer) Transaction order amount without decimal e.g. 1500.	Integer	1-12
	PurchaseDate	Date and Time of the shopping cart purchase.	Date	XML format
	TransactionStatus	State of the transaction. Indicates whether successful. Valid values are Success or Failure.	String	7
	ApprovalCode	Approval code returned by payment API.	String	6
	PreCheckoutTransactionId	Value returned from the PrecheckoutData call.	String
	ExpressCheckoutIndicator	True or False	Boolean
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
MerchantTransactionsResponse	Element	Description	Type	Min - Max
	MerchantTransactions
	MerchantTransaction	Root Element	XML	-
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-
MerchantTransaction	TransactionID	Uses the TransactionID element of the Checkout XML	String	1-255
	ConsumerKey	Automatically generated when creating a checkout project on MasterPass Merchant portal.	String	97
	Currency	Currency of the transaction. Defined by ISO 4217 to be exactly three characters, such as, USD for US Dollars.	String	3
	OrderAmount	Integer Transaction order amount without decimal e.g. 1500.	Integer	1-12
	PurchaseDate	Date and Time of the shopping cart purchase e.g. 2012-06-06T15:12:24.254-05:00	Date	XML format
	TransactionStatus	State of the transaction. Indicates whether successful. Valid values are Success or Failure.	String	7
	ApprovalCode	Approval code returned by payment API.	String	6
	PreCheckoutTransactionId	Value returned from the PrecheckoutData call.	String
	ExpressCheckoutIndicator	True or False	Boolean
	ExtensionPoint	Reserved for future enhancement. Optional	Any	-

ExtensionPoint Elements

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>

Bulk Merchant Upload

Merchant Upload Schema

Bulk merchant upload file schema can be downloaded from Developer zone. Here are the steps

Go to https://developer.mastercard.com and login.
Click on Services from the navigation bar and then click on MasterPass-Merchant Checkout.
Navigate to Documentation tab to download the upload file schema. If you don't have access to Documentation tab, follow the instructions on Overview tab to request access.

Merchant Upload Schema Details

Note: Please contact Merchant Support for details regarding how to specify a reward program for a merchant in the Bulk Merchant Upload file.

MerchantUpload	Element	Description	Type	Mandatory/Optional	Min	Max	Comment
	Merchant	Merchant Details	Element	M	Variable
Merchant	SPMerchantId	Service Provider Issued Merchant ID. This should be unique per Service Provider	String	M	Variable		e.g. 123456789
	Action	Merchant Action	String	M	1	1	Valid values are C (Create), U (Update) and D (Delete)
	Profile	Merchant Profile	Child	Mandatory for Create and Update. Not used for Delete.	1	1	Mandatory for Create (Action=C) and Update (Action=U)
	CheckoutBrand	Branding Information	Child	Mandatory for Create, Optional for Update and Delete			At least one CheckoutBrand element MUST be present for merchant creation.
	AuthOption	Authentication Options	Child				Variable per Merchant
	MerchantAcquirer	Merchant Acquirer	Child
Profile	Name	Merchant Name	String	M	1	255	e.g. XYZ Pizza
	DoingBusAs	Doing Business As - Alias	String	M	1	255	E.g. XYZ Pizza Inc
	FedTaxId	Merchant's Federal Tax ID	String	O	1	100	e.g. 999990001
	Url	Merchant's Website URL	String	M	5	1000	e.g. www.xyzpizza.com
	BusinessCategory	Merchant's business type	String	O	1	255	e.g. Restaurant
	Address	Merchant's Address	Child
	Phone	Merchant's Phone	Child
	Acquirer	Merchant's Acquirer	Child	O
Address	City	Merchant's City		M	1	25	e.g. New York
	Country	Merchant's Country		M	2	2	Standard 2-letter ISO 3166 country codes e.g. US
	Country Subdivision	Merchant's Country Subdivision. Defined by ISO 3166-1 alpha-2 digit code e.g. US-VA is Virginia, US-OH is Ohio		O	1	100	if defined choose string (1-100) or defined enumerator e.g. US-NY
	Line1	Merchant's Address Line 1		M	1	40	e.g. 1 Main Street
	Line2	Merchant's Address Line 2		O	1	40
	Line3	Merchant's Address Line 3		O	1	40
	PostalCode	Merchant's Postal Code		M	1	10	e.g. 10001
Phone	CountryCode	Merchant's phone country code		M	1	10	e.g. 75
Phone	Number	Merchant's phone Number		M	3	20	e.g. 9785453432
Acquirer	Id	Merchant's Acquirer Id		M	1	15	e.g. 453214
	Name	Merchant's Acquirer Name		M	1	255	e.g. Test Acquirer
	AssignedMerchantId	Acquirer assigned merchant ID		M	1	255	e.g. 435t6543
	Password	Acquirer Password for 3DS setup		O	1	255	e.g. password
CheckoutBrand	CheckoutId (New)	If not specified for Update Action, new branding element will be created.		O	1	255
	Name	Name displayed on MasterPass site during checkout when no logo is provided		M	1	255	e.g. XYZ Pizza
	DisplayName	Display Name		M	1	255	e.g. XYZ Pizza
	ProductionUrl	Production checkout URL		M	5	255	e.g. https://xyzpizza.com
	SandboxUrl	Sandbox checkout URL		M	5	255	e.g. https://test.xyzpizza.com
	LogoUrl	Merchant logo displayed on MasterPass site during checkout. If not specified, the Name is displayed		O	2	2000	e.g. http://xyzpizza.com/logo.jpg
AuthOption	CardBrand	Card brands enrolled for advanced authentication		M	NA	NA	Refer to the schema to get valid values
AuthOption	Type	Authentication type		M	NA	NA	Refer to the schema to get valid values
MerchantAcquirer	Acquirer	Acquirer	Child	M
MerchantAcquirer	MerchantAcquirerBrand	Merchant Acquirer Brand	Child
MerchantAcquirerBrand	CardBrand	Card Brand		M	NA	NA	Refer to the schema to get valid values
MerchantAcquirerBrand	Currency	Currency		O	3	3	ISO 4217 standard 3-letter currency code. Refer to the schema to get valid values

Merchant Upload Sample - Create

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload>
  <Merchant>
    <SPMerchantId>SPMerchantId1</SPMerchantId>
    <Action>C</Action>
    <Profile>
      <Name>XYZ Pizza</Name>
      <DoingBusAs>XYZ Pizza</DoingBusAs>
      <FedTaxId>123456785</FedTaxId>
      <Url>https://xyzpizza.com</Url>
      <BusinessCategory>Restaurant</BusinessCategory>
      <Address>
        <City>Springfield</City>  
        <Country>US</Country>
        <Line1>1234 Main Street</Line1>
        <PostalCode>12345</PostalCode>
      </Address>
      <Phone>
        <CountryCode>1</CountryCode>
        <Number>1234567895</Number>
      </Phone>
    </Profile>
    <CheckoutBrand>
      <Name>XYZ Pizza</Name>
      <DisplayName>XYZ Pizza</DisplayName>
      <ProductionUrl>https://test.xyzpizza.com</ProductionUrl>
      <SandboxUrl>https://xyzpizza.com</SandboxUrl>
      <LogoUrl>http://www.xyzpizza.com/logo.png</LogoUrl>
    </CheckoutBrand>
  </Merchant>
</MerchantUpload>

Merchant Upload Sample-Update (New Element Added)

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload>
  <Merchant>
    <SPMerchantId>SPMerchantId1</SPMerchantId>
    <Action>U</Action>
    <Profile>
      <Name>XYZ Pizza Co</Name>
      <DoingBusAs>XYZ Pizza</DoingBusAs>
      <FedTaxId>999999999</FedTaxId>
      <Url>https://xyzpizza.com</Url>
      <BusinessCategory>Restaurant</BusinessCategory>
      <Address>        
        <City>Springfield</City>
        <Country>US</Country>
        <Line1>1 Main Street</Line1>
        <PostalCode>12345</PostalCode>
      </Address>
      <Phone>
        <CountryCode>1</CountryCode>
        <Number>1234567895</Number>
      </Phone>
    </Profile>
    <CheckoutBrand>
 New Element  <CheckoutId> a466w1sj09wfehqqy3xxl12</CheckoutId>
      <Name>XYZ Pizza</Name>
      <DisplayName>XYZ Pizza Co</DisplayName>
      <ProductionUrl>https://test.xyzpizza.com</ProductionUrl>
      <SandboxUrl>https://xyzpizza.com</SandboxUrl>
      <LogoUrl>http://www.xyzpizza.com/logo.png</LogoUrl>
    </CheckoutBrand>
  </Merchant>
</MerchantUpload>

Merchant Upload Sample-Delete

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload>
    <Merchant>
        <SPMerchantId>SPMerchantId1</SPMerchantId>
        <Action>D</Action>
    </Merchant>
</MerchantUpload>

Please refer to the FAQs for additional sample scenarios for using Create, Update and Delete at https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+FAQs.

Merchant Download Schema

Bulk merchant result file schema can be downloaded from Developer zone. Here are the steps:

Go to https://developer.mastercard.com and login.
Click on Services from the navigation bar and then click on MasterPass-Merchant Checkout.
Navigate to Documentation tab to download the result file schema. If you don't have access to Documentation tab, follow the instructions on Overview tab to request access.

Merchant Download Schema Details

Merchanthownload	Element	Description	Type	Mandatory/Optional	Min	Max	Comment
MerchantDownload	Summary	Summary of the Upload	Element	M	-	-
MerchantDownload	MerchantResponseRecord	List of merchants uploaded/edited	Element
Summary	BatchId	System assigned Batch ID	Integer	M	Variable		e.g. 277800
	Description	Desctiption provided during file upload	String	M	1	50	e.g. Merchant file upload
	UploadTimestamp	Upload Time Stamp	Date/Time	M			DateTime field e.g. 2013-05-18T11:45:19.444-05:00
	UploadFileName	Upload File Name	String	M	1	255	e.g. merchant.xml
	SuccessCount	Number of successfully uploaded Merchant Brandings	Integer	M	NA	NA	e.g. 490
	FailureCount	Number of unsuccessfully uploaded Merchant Brandings	Integer	M	NA	NA	e.g. 10
	ErrorText	Description of errors resulting upload failures	String	O	1	255	e.g. Invalid Format
MerchantResponseRecord	SPMerchantId	Merchant identifier for a specific Service provider	String	M	Variable		e.g. 12345
	CheckoutBrand	Checkout Branding	Child		Choice (ErrorText or CheckoutBrand)
	ErrorText	Error description for failure		O	1	255	e.g. Invalid rewards logo URL
CheckoutBrand	Name	Checkout Brand Name	String	M	1	255	e.g. XYZ Pizza
	CheckoutIdentifier	Checkout identifier generated by MasterPass	String	M	1	255	e.g. a4a6x3oehb3fzhgu2e
	ProductionUrl	Production Checkout Branding URL	String	M	5	255	e.g. https://xyzpizza.com
	SandboxUrl	Sandbox Checkout Branding URL	String	M	5	255	e.g. https://test.xyzpizza.com

Merchant Download Sample

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantDownload>
    <Summary>
        <BatchId>277800</BatchId>
        <Description>Merchant Upload</Description>
        <UploadTimestamp>2013-05-18T11:45:19.444-05:00</UploadTimestamp>
        <UploadFileName>merchant_1.xml</UploadFileName>
        <SuccessCount>1</SuccessCount>
        <FailureCount>0</FailureCount>
    </Summary>
    <MerchantResponseRecord>
        <SPMerchantId>SPMerchantId1</SPMerchantId>
        <CheckoutBrand>
            <Name>XYZ Pizza</Name>
            <CheckoutIdentifier>a4a6x3oehb3fzh</CheckoutIdentifier>
            <ProductionUrl>https://test.xyzpizza.com</ProductionUrl> 
            <SandboxUrl>https://xyzpizza.com</SandboxUrl> 
        </CheckoutBrand>
    </MerchantResponseRecord>
</MerchantDownload>

BMU API Service

BMU API Upload

The BMU API Upload is used by Service Providers to upload merchant information to an Open Feed Project. This process mimics the upload xml process via the user interface used within the merchant portal. See Merchant Upload Schema and Merchant Download Schema for details.

BMU API Upload Parameters

	Upload	Response
oauth_signature	X
oauth_version	X
oauth_nonce	X
oauth_signature_method	X
oauth_consumer_key	X
oauth_timestamp	X
oauth_body_hash	X
oauth_token	X
Merchant Upload XML	X
Merchant Download XML		X

BMU API Upload Parameter Details

MerchantUpload-Request		Description	Possible Values
Signature Base String Authorization Header	oauth_signature	RSA/SHA1 signature generated from the signature base string	Variable
	oauth_version	Oauth version	1.0
	oauth_nonce	Unique alphanumeric string generated from code	Variable
	oauth_signature_method	oauth signature method	RSA-SHA1
	oauth_consumer_key	Consumer Key generated when creating a checkout project on MasterPass Merchant portal	Variable
	oauth_timestamp	Current timestamp	Variable
	oauth_body_hash	SHA1 hash of the message body	Variable
Oauth Token	oauth_token	oauth_token is sent in the signature base string, authorization header and redirect URL	Variable
Merchant Upload XML	MerchantUpload	Uploaded Merchant Information (XML)
Merchanthownload-Response		Description	Possible Values
Merchant Download	MerchantDownload	Results File of a Merchant Upload

Signature Base String Example

    POST&https%3A%2F%2F.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckoutproject%2F[0-9]+%2Ffile
    &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 Example

POST /masterpasspsp/v6/checkoutproject/[0-9]+/file Authorization: OAuthrealm="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"

HTTP Response Example

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantDownload version="1."/>
    <Summary>
        <BatchId>10247700</BatchId>
        <Description>test</Description>
        <UploadTimestamp>2014-04-02T16:55:31.308-05:00</UploadTimestamp>
        <UploadFileName>CreateMerchant1314.xml</UploadFileName>
        <SuccessCount>2</SuccessCount>
        <FailureCount>0</FailureCount>
        <ProjectKeys>  <SandboxKey>5a4830514b4531706e326e44494953754c39594c46413d3d</SandboxKey>   <ProductionKey>414d7a322b4363567531485146614a48543351505670343d</ProductionKey>
        </ProjectKeys>
    </Summary>
    <MerchantResponseRecord>
        <SPMerchantId>Merchant13_03132014</SPMerchantId>
        <CheckoutBrand>
            <Name>Merchant13_03132014</Name>
            <CheckoutIdentifier>a4d6x6szgu68phtbovwx11htj5lew816jn</CheckoutIdentifier>
            <ProductionUrl>http://gh-fxgx1r1.corp.mastercard.org</ProductionUrl>
            <SandboxUrl>http://gh-fxgx1r1.corp.mastercard.org</SandboxUrl>
        </CheckoutBrand>
    </MerchantResponseRecord>
    <MerchantResponseRecord>
        <SPMerchantId>Merchan14_03132014</SPMerchantId>
        <CheckoutBrand>
            <Name>Merchan14_03132014</Name>                       <CheckoutIdentifier>a4d6x6szgu68phtbovwx11htj5lew016jm</CheckoutIdentifier>
            <ProductionUrl>http://gh-fxgx1r1.corp.mastercard.org</ProductionUrl>
            <SandboxUrl>http://gh-fxgx1r1.corp.mastercard.org</SandboxUrl>
        </CheckoutBrand>
    </MerchantResponseRecord>
</MerchantDownload>

BMU API Submit

The BMU API Submit is used by Service Providers to submit a standard checkout project for approval via the API.

BMU API Submit Parameters

	Submit Request	Response
oauth_signature	X
oauth_version	X
oauth_nonce	X
oauth_signature_method	X
oauth_consumer_key	X
oauth_timestamp	X
oauth_body_hash	X
oauth_token	X

BMU API Submit Parameter Details

Submit-Request		Description	Possible Values
Signature Base String Authorization Header	oauth_signature	RSA/SHA1 signature generated from the signature base string	Variable
	oauth_version	Oauth version	1.0
	oauth_nonce	Unique alphanumeric string generated from code	Variable
	oauth_signature_method	oauth signature method	RSA-SHA1
	oauth_consumer_key	Consumer Key generated when creating a checkout project on MasterPass Merchant portal	Variable
	oauth_timestamp	Current timestamp	Variable
	oauth_body_hash	SHA1 hash of the message body	Variable
Oauth Token	oauth_token	oauth_token is sent in the signature base string, authorization header and redirect URL	Variable

Signature Base String Example

    POST&https%3A%2F%2Fapi.mastercard.com%2Fmasterpass%2Fv6%2Fcheckoutproject%2F[0-9]+
    &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 Example

POST /masterpasspsp/v6/checkoutproject/[0-9]+/

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%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zravb02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"

Developer Zone Key Renewal Process

On the My Dashboard page, click My Keys button, select the key you want to renew and then click on Renew Key button.

In order to renew the API Key, you need to supply a PEM encoded Certificate Request File. Choose the file, and click Submit. Notice the updated Key ID expiry date.

Note: If the CSR file is different than the CSR that was originally submitted when you created the key, make sure that your application is using the correct key store (.p12), otherwise calls to MasterPass services will fail.

Developer Zone Key Tool Utility

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

Click on "Generate Keys and CSR" and then click on "Save to Files". Next screen will prompt you to select the password.

Choose the folder where you want to save the files. This utility will create the PEM and p12 file.

3DS Overview

Service Description

When enrolling for MasterPass,^™ a merchant selects either Basic Checkout services, or Advanced Checkout payer authentication services. Basic Checkout is already offered with the core MasterPass^™ offering, and facilitates a simple checkout experience. Advanced Checkout provides merchants a payer authentication service to enable a merchant to authenticate its transactions with the issuer of the applicable card account leveraging the 3D 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 "Buy with MasterPass" Button:

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

No additional enrollment steps are required for merchant integration with Basic Checkout as it is part of the core MasterPass^™ Online services.

Advanced Checkout: When this option is selected by a merchant, Advanced Checkout will, on behalf of a merchant, attempt authentication leveraging the MasterCard^® SecureCode^™ or Verified by Visa protocols, depending on the card selected by the consumer in connection with the purchase. At this time, MasterPass^™ supports only the brands included 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 merchant must first be enrolled in the MasterCard^® SecureCode^™ and/or Verified by Visa program, as applicable, directly with their Acquirer. Merchants should contact their Acquirer in connection with any such enrollment(s).

Merchant must, in connection with their MasterPass^™ enrollment and Advanced Checkout opt-in, provide the applicable Acquiring Merchant ID and Acquirer ID (BIN) for the appropriate card brand. In connection with their Acquirer enrollment, merchants must also provide the Acquiring Merchant ID and Acquirer ID (BIN) for each currency processed (dependent on the applicable Acquirer's processing requirements). Once submitted, it will take 5 business days to complete setup.

The merchant is responsible for providing accurate Acquirer data to MasterCard in connection with their MasterPass^™ enrollment and for updating such information on a timely basis should it change.

Providing accurate enrollment data to MasterCard is critical and required-without it, the merchant most likely cannot receive the benefits of the Advanced Checkout service or of the associated Programs.

The merchant is responsible for submitting correctly formatted authorization and clearing ecommerce values to their payment processor to indicate use of the MasterCard^® 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 Transaction Authentication

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 who Select Advanced Checkout

Consumer shops online at merchant website and selects the MasterPass^™ Checkout Button to pay.
The consumer logs into their wallet to access payment and shipping information.
The consumer selects their MasterCard, Maestro or Visa Card for a payment.
Based on the payment information provided, the MasterPass^™ system receives a cmpi_lookup message in order to check the card participation in the applicable card issuer's payer authentication.
Based on the response, the status of the consumer's participation in the applicable Program will be identified. The three responses include an enrolled, not enrolled, and unavailable for authentication.
A. If the card is not enrolled or unavailable, there will be no consumer interaction with their issuing bank and the applicable consumer's MasterPass^™ Wallet

Data will be returned to the merchant via MasterPass^™ indicating that the merchant attempted to authenticate the consumer with the issuer. The merchant will need to pass these data elements in the authorization request, specifically the ECI value.

B. If the response is the consumer is enrolled in the applicable Program, the consumer will have an interaction with their issuing bank. Below are the four consumer experiences that can occur. This is controlled only by the card issuer and not the bank providing the MasterPass^™ Wallet service.

Consumer enters issuer challenge
Consumer is asked to Activate their card for 3-D Secure
Attempts (Visa US only scenario)

Risk Based Data will be returned indicating that the merchant attempted to authenticate the consumer with the issuer, the merchant will need to pass these data elements in the authorization request, specifically the ECI value, and AAV or CAVV.
The issuing bank encrypts the results of authentication between the consumer and their issuing bank and returns this value to MasterPass.
MasterCard will receive a response indicating the result of authentication between the consumer and their Issuing Bank. Below are the scenarios that can occur.

Consumer Fully Authenticates
Consumer Attempted Authentication (Prompted for Activation During Shopping and did Not Activate their Card)
Failed Authentication
Issuing bank Unavailable
Attempts/Risk Based Authentication

Based on the Authentication response from Cardinal, MasterCard will prompt the consumer for another form of payment or send back the authentication details to the Merchant for processing of the transaction.
The authentication data sent back will be:

AAV (Accountholder Authentication Value): This value is generated by the issuer and presented to the merchant for placement in the authorization request upon successful authentication of the consumer
Authentication Method Used - Value should be created by Wallet for merchant to receive (Initial possible values: "merchant only"; "3DS")
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
Pa Res Status
Secure Code Enrollment Status
Signature Verification
SLI (SecureCode Level Indicator)

Specifically the CAVV and the ECI value must be amended to the authorization in clearing messages in accordance with program rules.

Important Merchant Information

MasterCard does not represent or warrant that the Advanced Checkout service referenced herein is free from defects and mistakes and provides the service on an "as is" basis. No particular results are promised or assured. Merchant expressly assumes all risk for the use of the Advanced Checkout service. MasterCard, at all times, and in its sole discretion, reserves the right to begin and stop supporting 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 any Merchant or other person in regard to its compliance with applicable law or regulation. The signing or electronic signature of the MasterPass^™ Merchant Terms of Use for MasterPass^™ services inclusive of Advanced Checkout, and the submission of any other forms related thereto, including the Information Sheet referenced above, indicates that the Merchant understands and agrees to the terms and conditions set forth herein. Merchant acknowledges that its acceptance of these terms and conditions is relied upon by MasterCard in permitting the Merchant's participation in MasterPass^™ and Advanced Checkout.

MasterPassTM Service Provider Onboarding & Integration Guide - Bulk Merchant Upload Version 6.0

Proprietary Rights

Trademarks

Translation

Content Disclaimer

Publication Code

How does MasterPass work?

MasterPass User Interface

Standard "Lightbox Display" (desktop and laptop)

Standard Mobile Display (.mobi)

Standard Full Screen Display

Overview

MasterPass Merchant Standard Checkout process flow

MasterPass Connected Checkout Experience

Pairing of wallet

Pair with MasterPass Wallet during Checkout

Pair with MasterPass Wallet outside of a Checkout

Return Checkout

Unpairing

Incorporating MasterPass into your site or app

Service Providers NEW to MasterPass should start here:

Bulk Merchant Upload

Service Providers with an EXISTING MasterPass relationship:

BMU API Service

Open Feed to Production Project

1.Service Provider Registration and Setup-Service Provider Activity

Create an Account

Enter Invitation Code

Select Service Provider

2. Add Developer to Service Provider Profile-Service Provider Activity

3. Developer Registration - Developer Activity

MasterPass Developer Account

MasterCard Developer Zone Account

Generate MasterCard Developer Zone Developer API Keys

Create Sandbox Key

Create Production Key

Initiate Development

4. Request Sandbox Credentials - Developer Activity

Create Checkout Project

Bulk Merchant Upload

Generate Merchant Files

Select, Upload and Review

Submit Checkout Project for Sandbox Approval

5. Review Integration Project & Sandbox Approval - Service Provider Activity

6. Access Sandbox Credentials, Complete Development and Test-Developer Activity

Access Sandbox Details

7. Request Production Credentials-Developer Activity

8. Review Integration Project & Production Approval - Service Provider Activity

9. Deploy application using Production Credentials-Developer Activity

Follow Steps 10-12 to setup BMU API

10. Set Auto-Approval - Service Provider Activity

11. Use Open Feed to Production Checkout Project - Service Provider Activity

12. Upload to Open Feed Checkout Project - Developer Activity

Lightbox Integration

Standard Checkout

Invoke MasterPass UI (Lightbox)

Lightbox parameter details can be found here.

Standard Checkout Callback

Redirect to Merchant Callback URL Example

Checkout Callback method Example

Pairing with MasterPass Wallet without Checkout

Invoke MasterPass UI

Pairing without checkout Callback

Pairing with MasterPass Wallet during Checkout

Invoke MasterPass UI for Pairing during Checkout

Pairing during Checkout Callback

Return Checkout (Checkout after Wallet Pairing)

Invoke MasterPass UI for Connected Checkout

Connected Checkout Callback

Service Descriptions:

Request Token Service

Sandbox and Production Endpoints

Shopping Cart Service

Sandbox and Production Endpoints

Merchant Initialization Service

Access Token Service

Sandbox and Production Endpoints

Pre-Checkout Data Service

Sandbox and Production Endpoints

Retrieve Payment, Shipping Data, Rewards and 3DS Details

MasterPass^TM Service Provider Onboarding & Integration Guide - Bulk Merchant Upload Version 6.0