1. technology and computing
2. software
3. databases

™
MasterPass Service Provider Onboarding & Integration
Guide—File- and API-Based Merchant Onboarding
MASTERPASS™ SERVICE PROVIDER
ONBOARDING & INTEGRATION GUIDE—FILEAND API-BASED MERCHANT ONBOARDING
VERSION 6.5, AS OF 25 JUNE 2015
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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
2
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Table of Contents
Notices ........................................................................................................................................................... 2
Proprietary Rights ......................................................................................................................................... 2
Trademarks .................................................................................................................................................... 2
Translation ..................................................................................................................................................... 2
Content Disclaimer........................................................................................................................................ 2
Publication Code ........................................................................................................................................... 2
Document Version Notes.............................................................................................................................. 6
Overview ........................................................................................................................................................ 9
MasterPass File-Based Onboarding ............................................................................................................ 9
MasterPass API-Based Onboarding ............................................................................................................ 9
How does MasterPass work? ....................................................................................................................... 9
MasterPass User Interface ........................................................................................................................... 9
Standard “Lightbox Display” (desktop and laptop) ...................................................................................... 9
Standard Mobile Display (.mobi) ............................................................................................................... 10
Standard Full Screen Display.................................................................................................................... 11
MasterPass Checkout Experiences ........................................................................................................... 12
Overview ...................................................................................................................................................... 12
MasterPass Merchant Standard Checkout Process Flow ........................................................................ 13
Standard Checkout Flow: .......................................................................................................................... 19
Service Provider File- and API-Based Onboarding Model ....................................................................... 20
Incorporating MasterPass into Your Site or App...................................................................................... 20
File-Based Onboarding ............................................................................................................................. 20
API-Based Onboarding ............................................................................................................................. 20
Service Providers NEW to MasterPass should start here: .............................................................................. 20
Service Providers with an EXISTING MasterPass Relationship ........................................................................ 21
Single-Merchant API Service ....................................................................................................................... 22
Open Feed Checkout Project .................................................................................................................... 22
Service Provider File- and API-Based Onboarding—Steps ..................................................................... 24
1. Service Provider Registration and Setup—Service Provider Activity ................................................ 24
Auto Approval ........................................................................................................................................... 26
2. Add Developer to Service Provider Profile—Service Provider Activity.............................................. 27
3. Developer Registration—Developer Activity ........................................................................................ 28
MasterPass Developer Account ................................................................................................................ 28
MasterCard Developer Zone Account ....................................................................................................... 28
Generate MasterCard Developer Zone Developer API Keys .................................................................... 29
Initiate Development ................................................................................................................................. 32
4. Request Sandbox Credentials—Developer Activity ............................................................................. 32
Create Checkout Project ........................................................................................................................... 33
File-Based Onboarding ............................................................................................................................. 34
Generate Merchant Files........................................................................................................................... 35
Validate Merchant Files in the Merchant Portal prior to Upload ................................................................ 35
Validate, Select, Upload, and Review ....................................................................................................... 35
Submit Checkout Project for Sandbox Approval ....................................................................................... 41
5. Review Integration Project & Sandbox Approval—Service Provider Activity.................................... 42
6. Access Sandbox Credentials, Complete Development and Test—Developer Activity ..................... 43
3
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Access Sandbox Details ........................................................................................................................... 43
7. Request Production Credentials—Developer Activity ......................................................................... 43
8. Review Integration Project & Production Approval– Service Provider Activity ................................ 44
9. Deploy application using Production Credentials—Developer Activity ............................................. 45
Follow Steps 10–12 to setup Single-Merchant API................................................................................... 45
10. Set Auto-Approval—Service Provider Activity ................................................................................... 45
11. Use Open Feed to Production Checkout Project—Service Provider Activity .................................. 46
12. Upload Merchant Record to Open Feed Checkout Project—System Activity ................................. 47
Integration Process ..................................................................................................................................... 49
Lightbox Integration.................................................................................................................................... 49
Standard Checkout ..................................................................................................................................... 49
Invoke MasterPass UI (Lightbox) .............................................................................................................. 49
Lightbox parameter details can be found here. ........................................................................................ 50
Standard Checkout Callback..................................................................................................................... 50
a.
Redirect to Merchant Callback URL Example ................................................................................. 50
b.
Checkout Callback method Example .............................................................................................. 50
Service Descriptions:.................................................................................................................................. 50
Request Token Service ............................................................................................................................... 50
Sandbox and Production Endpoints .......................................................................................................... 51
Shopping Cart Service ................................................................................................................................ 51
Sandbox and Production Endpoints .......................................................................................................... 51
Merchant Initialization Service ................................................................................................................... 51
Access Token Service ................................................................................................................................ 52
Sandbox and Production Endpoints .......................................................................................................... 52
Retrieve Payment, Shipping Data, Rewards and 3DS Details ................................................................. 52
Postback Service......................................................................................................................................... 53
Sandbox and Production Endpoints .......................................................................................................... 54
Android and iOS App Integration............................................................................................................... 54
MasterPass - Branding ............................................................................................................................... 56
Displaying “Buy with MasterPass” Button and Acceptance Marks........................................................ 56
MasterPass “Learn More” page ................................................................................................................. 57
Testing ......................................................................................................................................................... 59
MasterPass Sandbox Testing .................................................................................................................... 59
3DS Test Cases ........................................................................................................................................... 60
Q/A Checklist ............................................................................................................................................... 64
Asset Placement ....................................................................................................................................... 64
In-Wallet Experience ................................................................................................................................. 64
Post Wallet Experience ............................................................................................................................. 64
Postback ................................................................................................................................................... 65
General ..................................................................................................................................................... 65
Troubleshooting .......................................................................................................................................... 65
Troubleshooting .......................................................................................................................................... 65
Support ........................................................................................................................................................ 66
Appendix ...................................................................................................................................................... 67
Merchant Initialization Service .................................................................................................................. 70
Shopping Cart Service .............................................................................................................................. 74
Access Token Service .............................................................................................................................. 78
Postback Service ...................................................................................................................................... 90
File-Based Merchant Onboarding .............................................................................................................. 95
4
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Merchant Upload Schema......................................................................................................................... 95
Merchant Upload Schema Details............................................................................................................. 95
Merchant Upload Sample—Create ........................................................................................................... 98
Merchant Upload Sample—Create with Advanced Authentication Settings (3DS) for MasterCard .......... 99
Merchant Upload Sample—Create with Advanced Authentication Settings (3DS) for Visa .................... 100
Merchant Upload Sample—Update ........................................................................................................ 101
Merchant Upload Sample—Update ........................................................................................................ 101
Merchant Upload Sample with Advanced Authentication Settings (3DS)—Update ................................ 102
Merchant Upload Sample—Delete.......................................................................................................... 104
Merchant Upload Sample—Delete.......................................................................................................... 104
Merchant Upload Sample with Advanced Authentication Settings (3DS)—Delete.................................. 104
Merchant Upload Validate Response Schema Details ............................................................................ 106
Merchant Download Schema .................................................................................................................. 106
Merchant Download Schema Details ...................................................................................................... 106
Merchant Download Sample ................................................................................................................... 107
Single-Merchant API Service .................................................................................................................... 109
Single-Merchant API ............................................................................................................................... 109
Single-Merchant API Validation Service ................................................................................................. 112
3DS Status ................................................................................................................................................. 114
Developer Zone Key Renewal Process ................................................................................................... 116
Developer Zone Key Tool Utility .............................................................................................................. 118
3DS Overview ............................................................................................................................................ 119
Service Description ................................................................................................................................. 119
General Overview of Transaction Authentication .................................................................................... 120
Important Merchant Information .............................................................................................................. 121
Validation Error Messages ....................................................................................................................... 121
5
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Document Version Notes
Document
Version
6.5
6.4
6.3
Date
Updates
06/25/2015
Added note to the "Submit Checkout Project for Sandbox Approval" section to indicate
that once a checkout project is submitted/approved, it cannot be deleted. (p 41)
Added note to the "Lightbox Integration" section indicating that those invoking the
Lightbox from an iFrame must include the listed scripts on the parent (outer) frame in
addition to the iFrame source that is invoking MasterPass Lightbox. (p 49)
Updated the Sandbox Consumer Account table in the "MasterPass Sandbox Testing"
section to indicate that the security question and answer are "Pet's Name" and "fido,"
respectively, for the 3DS Test accounts. (p 59)
Replaced the "merchant-initialization—XML Schema Request." (p 71)
Replaced the "URL: https://api.mastercard.com/masterpass/v6/merchant-initialization —
Sample Request." (p 72)
Replace the "Shopping Cart V6—XML Schema." (p 75)
Replaced the "Shopping Cart Request XML with Optional SecondaryOriginUrl Field—
Sample." (p 77)
05/28/2015
Updated the document to reflect new branding for the services. The old BMU API has
been rebranded as “Single-Merchant API.” The file-based BMU has been rebranded
as “File-Based Onboarding.” Collectively, they are named “File- and API-Based
Onboarding,” as reflected in the new title of the document. (throughout document)
Added sample Download and Upload files for Create, Update, and Delete Actions with
Advanced Authentication Settings (3DS). (throughout the document where applicable)
Updated the "Are you registering as a Merchant or Service Provider?" screenshot in the
"Service Provider Registration and Setup—Service Provider Activity" section. (p 22)
Introduced a new section titled "Validate Merchant Files prior to Upload." (p 33)
Added a list of information that merchants should email to
[email protected] if they don't have an implementation
manager assigned to them. (p 66)
Introduced a new section in the appendix titled "Validation Error Messages." (p 97)
05/05/2015
Replaced references to the [email protected] email address.
(throughout document)
Updated the "Standard Checkout User Flow" screenshots to reflect the online interface
rather than the mobile interface. (p 11)
Added statement to the "Service Provider Registration and Setup—Service Provider
Activity" section to indicate that, before registering with MasterPass, the service
provider must request an invitation code from their MasterCard representative. (p 21)
Updated verbiage in the "Service Provider Registration and Setup—Service Provider
Activity" section to clarify that once Auto Approval has been enabled for a developer,
subsequent projects that they submit using the same credentials do not need
business owner approval prior to sandbox and production deployment, and any
changes made to the project are effective immediately. (p 23)
Added verbiage to the "Select, Upload, and Review" subsection of the "Request Sandbox
Credentials—Developer Activity" section to indicate that service providers may submit
corrections to the merchant files they upload under the same checkout project as the
original upload if the checkout project has not already been approved. (p 33)
Updated the note in the "Submit Checkout Project for Sandbox Approval" subsection of
the "Request Sandbox Credentials—Developer Activity" section to clarify that once
Auto Approval has been enabled for a developer, subsequent projects that they
submit using the same credentials do not need business owner approval prior to
sandbox and production deployment, and any changes made to the project are
effective immediately. (p 34)
Added verbiage to the "Shopping Cart Service" section about the new SecondaryOriginUrl
6
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
field. (p 41)
Added instruction to the "Android and iOS App Integration" section to set the
android:targetSdkVersion value in your application to 19 or higher if you are
integrating MasterPass for Android devices. (p 44)
Added verbiage to the note in the "Create Production Key" subsection of the "Developer
Registration—Developer Activity" section indicating that the initial files for the key
creation are needed to renew a production API key. (p 49)
Added item to the "Post Wallet Experience" Q/A checklist indicating that the user must
verify that the card PAN has not been provided to any entity that does not have the
appropriate security in place for storage and transmission of card data (per PCI
guidelines). (p 52)
Added the new SecondaryOriginUrl element to the Merchant-initialization—XML Schema
Request XML sample. (p 58)
Added the new SecondaryOriginUrl element to the "MerchantInitializationRequest XML
Details" table. (p 60)
Added the new SecondaryOriginUrl element to the "Shopping Cart V6-XML Schema". (p
62)
Added the new SecondaryOriginUrl element to the "Shopping Cart V6 XML Details" table.
(p 62)
Added the "Shopping Cart Request XML with Optional SecondaryOriginUrl Field—
Sample" (p 63)
Added a note to the "MerchantTransactions Request—Schema" subsection stating that
BMU service providers may ignore the optional PreCheckoutTransactionId and
ExpressCheckoutIndicator elements. (p 77)
Added a note to the "Merchant Upload Sample—Update" section to indicate that if the
Checkout ID is not included in the Checkout Brand element, then MasterPass will
produce a unique checkout ID for merchant record. (p 86)
6.2
6.1
6.0
03/03/2015
Updated screenshots. (throughout document)
Removed note about the activation delay that service providers might experience
following the initial checkout. (p 15)
Added verbiage about the Auto Approval feature, which merchants may use to approve
checkout projects. (p 40)
Removed caveat stating that JCB is supported in select markets only. (p 49)
Added information about a new email element to the “Merchant Upload Schema Details”
table. (p 77)
12/01/2014
Removed the Connected checkout table (p 10)
Added user flows for Standard, Paired, and Returned Checkout (p 13, 16, 17, 19)
Updated information about unpairing (p 20)
Added further information about OAuth (p 32)
Added note about key renewal requirements (p 40)
Clarified production deployment instructions (p 35)
Added note about new SDK/sample code availability (p 44)
Clarified checkout resource URL information (p 52 & 79)
Added note about liability shift and Advanced Checkout (p 57)
Added sandbox JavaScript URL (p 43)
Updated ECI Values (p 86)
Updated XML schema-MerchantAquirerBrand (p 102)
Added note about currency being required field for 3DS (p 105)
Noted inclusion of JCB as an allowed card type (p 62)
9/19/2014
Added Lightbox UI experience (p 7)
Added New Checkout experience: Connected checkout details (p 13)
Merchant Initialization Service - version V6 (p 48)
Shopping Cart Service - version V6 (p47, 66)
Checkout version - version V6 (p 42, 43, 45, 46)
Precheckout Service - version v6 (p48, 82)
Postback Service - version V6 (p50, 94)
Updated QA Checklist (p 56)
7
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Lightbox Parameters (p59)
SINGLE-MERCHANT API Service (p18, 19, 38, 39, 104)
10/26/2013
Checkout project auto approval (p 12)
3DS “No Authentication” value (p 30)
High resolution image links (p 35)
MasterPass ‘Learn More’ link (p 35)
Checkout version v5 schema and xml (p 51-55)
Updated result file schema (p 69)
Instructions to use Developer Zone Key Tool Utility (p 71)
8
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Overview
This guide is intended for service providers that would like to use one of the following mechanisms:
•
•
MasterPass File-Based Onboarding
MasterPass API-Based Onboarding
MasterPass File-Based Onboarding
Under this onboarding method, service providers upload a file with merchant records through the
MasterPass Merchant and Service Provider portal. Service providers can use this onboarding mechanism to
add merchants, update merchants, or delete merchant records on the MasterPass platform. Upon
successful processing of the file by MasterPass, a results file is available for the service provider to
download.
MasterPass API-Based Onboarding
At this time, a Single-Merchant API is available for merchant onboarding.
This onboarding mechanism may be used to onboard a single merchants to MasterPass in real time. This
API may be used to (a) add an individual merchant to MasterPass, (b) update an individual, existing
MasterPass merchant record, or (c) delete an individual merchant record from MasterPass. MasterPass
then provides a real-time response to the API.
How does MasterPass work?
MasterPass is a service that enables consumers to store, manage and securely share their payment,
shipping and rewards information with the websites and mobile apps with which they transact. MasterPass
™
™
supports checkout on full and mobile websites, as well as in-app purchases on Android and iOS apps.
Shop on
merchant
site
Click Buy with
MasterPass
at checkout
Sign into
MasterPass
-enabled
Wallet
Select card,
shipping
address
and loyalty
Select
shipping
method
Review and
confirm
transaction
MasterPass User Interface
The MasterPass user interface, or Lightbox, floats the MasterPass wallet interface on top of the Merchant’s
web page through illuminated overlays, and backgrounds dimmed to 0.7 opacity. This modern method
allows a consumer to interact with their MasterPass digital wallet without having to leave the merchant’s
page. MasterPass Lightbox is built in a responsive design style allowing it to respond dynamically to the
various screen sizes and orientations.
MasterPass supports the following displays:
•
•
Standard Lightbox display
Standard full screen display
Standard “Lightbox Display” (desktop and laptop)
At full screen, where the browser is set to 100% height and width, the overall Lightbox dimensions are 740
pixels (height) by 700 pixels (width). This is inclusive of the Lightbox header and footer. The interior Lightbox
dimensions are 590 pixels (height) by 680 pixels (width).
9
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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 (as in, phones and smaller tablets). There is a 320 pixel width threshold for the content
container.
Standard Mobile Display (.mobi)
Within the .mobi experience, the header and footer are approximately 70 pixels high except for the iPhone
5/5S, 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.
10
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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.
11
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
MasterPass Checkout Experiences
Overview
The following table depicts the steps of involved in the standard MasterPass checkout experience.
Merchant
Experience
Standard
Checkout
Merchant
identifies
consumer
MasterPass
Merchant
Consumer
Clicks
Signs
into
Wallet
Finalizes
Payment
Method/
Address
Reviews/
Submits
Order
Confirms
Order
Receipt/
Thank
You
Page
Buy with
MasterPass
X
X
X
X
X
12
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
MasterPass Merchant Standard Checkout Process Flow
The flows below depict the Standard MasterPass Checkout flow with the Lightbox MasterPass UI.
Standard Checkout User Flow
1) The consumer clicks the Buy with MasterPass button.
13
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
2) The consumer logs in to their wallet.
14
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
3) The consumer selects their payment method and shipping address.
15
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
4) The consumer reviews and submits the order.
16
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
5) The merchant confirms the order.
17
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
18
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Standard Checkout Flow:
19
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Service Provider File- and API-Based Onboarding 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 service providers that would like to use the File- or API-based methods for
onboarding merchants.
File-Based Onboarding
Under this onboarding method, service providers upload a file with merchant profile records through the
MasterPass Merchant Portal.
Service Providers can onboard merchants by uploading file(s) containing multiple merchant records. Service
Providers will access the MasterPass Merchant Portal to enroll and provision their merchants to
MasterPass. The File-Based Onboarding method should be used by Service Providers who will be
onboarding a large number of merchants and can generate XML formatted files(s) with the required
information for multiple merchants. This process allows multiple merchant profiles to be set up at the same
time rather than manually creating a MasterPass account for each merchant. No Merchant interaction with
MasterPass is required in this onboarding method. Service Provider developers will create checkout projects
and the Service Provider will approve the checkout projects. Service Provides can also enable [Auto
Approval] (insert hyperlink to auto approve section) for each developer to avoid having to approve each and
every checkout project by that developer.
Service providers can use File-Based Onboarding to add merchants, update merchants, or delete merchant
records on the MasterPass platform. Upon successful processing of the file by MasterPass, a results file is
available for the service provider to download.
API-Based Onboarding
At this time, a Single-Merchant API is available for merchant onboarding.
This Single-Merchant API may be used by Service Providers to onboard merchant records one at a time and
in real time to MasterPass. This method is best suited for Service Providers that want to onboard merchants
in real time from their system to MasterPass without any manual intervention. No Merchant interaction with
MasterPass is required in this onboarding method. By using the API, service provider developers do not
have to create multiple checkout projects for onboarding merchants. An Open Feed checkout project is
available for service providers using the API that can be used for ongoing submission of merchant records to
MasterPass.
This API may be used to add, update, or delete merchants one at a time to MasterPass.
provides a real time response to the API.
MasterPass
Service Providers NEW to MasterPass should start here:
All new service providers that have not onboarded merchants, whether using file- or API-based onboarding,
must complete steps 1–9 that are summarized in the table below.
By completing steps 1–9, you will have created your relationship to MasterPass and onboarded an initial set
of merchants. Detailed instructions for steps 1–9 can be found here, or click on the links within the table
below.
At the successful completion of step 9, you will have a Checkout Project that has been approved for
production and at least one merchant in the MasterPass system. At this point, the Service Provider will be
considered existing in the MasterPass system.
20
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Activity
1. Service Provider
Registration and
Setup
2. Add Developer to
Service Provider
Profile
3. Developer
Registration
Actor
Steps
Service
Provider
Create Service Provider account and create shipping
profile
MasterPass
Merchant Portal
Service
Provider
Add Developer to Service Provider Profile
MasterPass
Merchant Portal
Create MasterPass Developer account
MasterPass
Merchant Portal
Developer
Create Developer Zone account
Generate developer’s sandbox and production keys
Review sample code/SDK and design services
integration
Create Checkout Project
Obtain details for merchant(s) and generate merchant
upload file(s).
4. Request Sandbox
Credentials
5. Review Integration
Project & Approval
Environment
Developer
Service
Provider
Business
Owner
Select merchant file(s), Upload and Review results
from the Download Merchant File.
MasterCard
Developer Zone
MasterPass
Merchant Portal
Service Provider
Engineering
Environment
MasterPass
Merchant Portal
Submit Checkout Project for sandbox approval.
MasterPass
Merchant Portal
Approve sandbox credentials.
MasterPass
Merchant Portal
Obtain checkout IDs for each successfully
provisioned merchant. Map each checkout Id to the
correct merchant.
MasterPass
Merchant Portal
6. Access Sandbox
Credentials
Developer
7. Request Production
Credentials
Developer
Submit Checkout Project for production approval
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
Test against MasterPass sandbox environment
Service Provider
Engineering
Environment
MasterPass
Merchant Portal
Service Providers with an EXISTING MasterPass Relationship
Existing Service Providers that are using the File-Based Onboarding method and would like to use the
Single-Merchant API can skip down [here] (insert link Single API section)
Existing Service Providers have two options for adding, updating, and deleting merchants in the MasterPass
system:
•
Use File-Based Onboarding via the MasterPass Merchant and Service 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.
21
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
•
Use the Single-Merchant API Service to upload the XML file containing a single merchant record,
which is explained in the section below. Follow Steps 10-12 below to setup the Single-Merchant
API Service for your account.
Single-Merchant API Service
Once a service provider has at least one checkout project approved all the way through to production (Step
8) that service provider can then choose to activate the Single-Merchant API Service. Interfacing with the
Single-Merchant API Service will require coding on the Service Provider side.
Service Providers using the API can use the Open Feed Checkout Project to submit merchant records to
MasterPass.
Open Feed Checkout Project
The Open Feed to Production Checkout Project has the advantage over a standard checkout project in
that it allows continuous sumbissions of merchant records for the desired action (add/update/delete) directly
to the production environment.
To create the Open Feed to Production Checkout Project, complete the following steps:
10. Set Auto Approval
11. Use Open Feed to
Production Checkout
Project
12. Send XML to Open
Feed Project
Service
Provider
Business
Owner
Service
Provider
Business
Owner
Developer
Check Enable Auto Approval Checkbox
Check Use Open Feed to Production Checkout
Project (Auto Approval must be enabled, step 10)
Send a single merchant record in XML format via
the Single-Merchant API service using the
Checkout Project ID of the Open Feed Project and
the production consumer key, which can be
obtained from one of the previous production
approved checkout projects on the Merchant
Portal.
XML flows automatically to Approved for
Production, step 9.
MasterPass
Merchant Portal
MasterPass
Merchant Portal
Upload XML via
API
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
Merchant Portal –
Service Provider
account
Merchant Portal Developer Account(s)
Details
Created by Service Provider business owner. This id should be
used to login at https://masterpass.com/SP/Merchant/Home
Account Info
Userid: __________
Email: ___________
Go here to create Service Provider account, invite developers, create
shipping profiles, approve checkout projects etc.
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
Userid: __________
Email: ___________
Go here to create checkout project, upload merchant files, get checkout
22
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
project details etc.
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
Userid: __________
Email: ___________
Go here to perform key exchange, download SDKs and Sample
Application, Integration Guides and to access FAQs, etc.
By the end of the integration, your site or mobile app should be able to:
1. Display the Buy with MasterPass button and the Learn More link at the start of the checkout
experience.
2. Invoke and display the MasterPass Lightbox.
3. Relay MasterPass checkout requests to the MasterPass service.
4. Receive consumer’s billing, shipping address, and rewards data from MasterPass service.
5. Process card, shipping and rewards information using existing process.
Note that your implementation must satisfy all criteria in the Q/A checklist.
23
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Service Provider File- and API-Based Onboarding—Steps
1. Service Provider Registration and Setup—Service Provider Activity
Before beginning this process, request an invitation code from your MasterCard representative; this will
grant you access and allow you to register as a service provider within the merchant portal.
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. 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
24
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
25
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
After your account has been created, select Shipping Locations to manage shipping for your merchants.
You can have multiple shipping profiles that you can use with multiple merchants, or you may set a preferred
shipping profile if most of your merchants use it.
Auto Approval
The Service Provider business owner has an option to Enable Auto Approval of checkout projects. This
feature allows Service Providers to determine if they wish to have a checkpoint/audit step prior to having
merchants setup in sandbox and production or not. Once enabled, subsequent projects submitted by the
developer—using the same credentials—do not need business owner approval prior to sandbox and
production deployment. Any changes made to the project are effective immediately. To enable Auto
Approval, click Account Settings from the top navigation bar and click on the Enable Auto Approval check
box.
26
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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. 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.
27
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
MasterPass will send two separate emails to each newly added developer indicating that he/she has been
invited to handle the technical integration of MasterPass on-behalf of your company. These emails will
contain the username and password to log in to the MasterPass Merchant Portal. Invitation emails sent to
the developer will contain links to the MasterPass integration guides that developers can use to get started
with MasterPass integration.
3. Developer Registration—Developer Activity
Developers invited to integrate MasterPass on behalf of a service provider will manage their integration
activities through two portals:
•
MasterPass Merchant Portal (https://masterpass.com/SP/Merchant/Home)
•
MasterCard Developer Zone (http://developer.mastercard.com)
NOTE: These are two different websites that use different login credentials. If you are a new developer for
MasterPass, you must sign up for a new account on Developer Zone.
MasterPass 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.
You will find links to the MasterPass integration documentation in the invitation emails you receive from
MasterPass and on the landing page once you sign in to your Developer account on the MasterPass
Merchant Portal.
You do not need a Developer Zone account to access and view this documentation.
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.
28
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Generate MasterCard Developer Zone Developer API Keys
After creating your account, you will need to generate two API keys: one for the sandbox environment and
one for the production environment. To make keys easy to distinguish, it’s recommended to prefix sandbox
keys with "SBX_" and production keys with "PRD_".
29
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Create Sandbox Key
To create a Sandbox key, click My Account, then My Dashboard.
On the My Dashboard page, click on the My Keys tab and the 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.
30
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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 a Sandbox Key ID and a Production Key ID, which will be used when
creating a checkout project in the MasterPass Merchant Portal.
31
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
NOTE: Keys expire after one year before which they should be renewed by initiating the Developer Zone
Key Renewal process. The Certificate Request File initially submitted for the key creation will be needed to
renew the key. Notifications at 30, 15, and 1 day prior to key expiration will be sent to the email address
associated with the Developer Zone account.
When the keys expire, the checkout project will not work and the MasterPass transactions will fail.
Therefore the keys need to be renewed prior to expiration.
Initiate Development
At this point, developers should begin developing their own implementation. Sample Applications for C#
.NET, Java, PHP, and Ruby will be made available for download from the Sample Code tab in the Developer
Zone. Contact MasterPass Support if the sample applications are not available in the language you need.
MasterPass follows the OAuth 1.0a specification. Any merchant or Service Provider integrating with
MasterPass must strictly adhere to the OAuth specs for interacting with MasterPass through Open API
Gateway. Failure to implement OAuth correctly may impact your integration and transactions with
MasterPass.
Further information can be found here:
https://developer.mastercard.com/portal/display/api/Authentication
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.
32
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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 the Project Name and Project Description. Enter the sandbox and production Key IDs that were
created from MasterCard Developer Zone.
If you are a Service Provider developer uploading files containing several merchant records, choose the
Bulk Merchant Upload Implementation option in the Create Checkout Project window.
33
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Create Checkout Project
Developer Zone – Production Key ID
Developer Zone – Sandbox Key ID
File-Based Onboarding
Service Providers can associate multiple merchant profiles to a checkout project all at once using a
merchant upload file. The first step in this process is to obtain the merchant upload file template referenced
in the appendix. Service Providers should gather the details for each merchant.
34
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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.
Validate Merchant Files in the Merchant Portal prior to Upload
This feature enables service providers to optionally check or validate their file containing merchant records
and ensure that it meets the schema and business rules requirements before submitting the file for
processing to MasterPass.
To begin the validation process, click the Validate File button on the Checkout Projects page.
Click Choose File and select a file to validate. Initiate the file validation by clicking Validate Now. Once the
validation is complete, the system will display an error message if the file is invalid. Any schema errors must
be corrected before the file can be submitted for validation against business rules. Once validation is
complete, a success or failure result is displayed in the UI, and details of errors are provided in the results
file.Refer to the “Validation Error Messages” section of the Appendix for a list and descriptions of the
validation error messages. The results of the validation are not stored by MasterPass and, hence, will not
available to service providers when they return. Service providers must use the “download” capability to take
note of the validation results, which can be used to correct any errors in the file.
Once the service provider has corrected the XML errors, validate the file again. If there are no errors in the
file, the system will display a “Validation complete, no errors found” message. There are no limits on the
number of times a file or record can be validated.
The validation feature supports the same file sizes as can be used with File-Based Onboarding.
Validate, Select, Upload, and Review
To verify your file submission for schema and business rules validation before uploading, go to the
Checkout Projects page and click the Validate File button.
35
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Click the Choose File button.
Select the file you want to validate and click the Validate Now button.
36
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
The system will first validate the XML schema of your file. If your file does not meet the XML schema rules,
you will receive an error message (as in the screenshot below) and must repair the error.
If your files meets the XML schema rules, the system will then validate against the business rules. If your file
does not meet the business rules, you will receive an error message (as in the screenshot below) and must
repair the error.
37
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
To see the cause of the validation error, click the Download Result File button.
Once your file meets both the XML schema and business rules, you (a) will receive a result file with an
ErrorText status of “Successful” (as in the following screenshot) and (b) are ready to upload the file to
MasterPass.
38
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Once the merchant files have been generated and the merchant is ready to upload files to MasterPass, click
Upload to select the merchant files and initiate the File-Based Onboarding process.
39
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
40
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
A message will display indicating the processing has finished and the number of records processed—
successes and failures. The service provider account owner will still need to approve the successfully
processed merchants before they will be able to process transactions. You will also get an 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.
Corrections can be uploaded under the same checkout project, provided that the checkout project has not
already been approved via manual or auto approval. To check on the 3DS status of a successfully uploaded
merchant, refer to the "3DS Status" section.
Submit Checkout Project for Sandbox Approval
After creating the checkout project but before submission, the developer may modify previously entered
information. To submit the project for sandbox approval, click Submit. Clicking Submit will kick-off the
Checkout Project Approval Process.
NOTE: Once the checkout project is submitted/approved, it cannot be deleted.
41
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
NOTE: If Auto Approval has been enabled by the merchant or service-provider business owner for a
developer, sandbox and production credentials will be generated at this time and steps 5-8 will be skipped.
Once Auto Approval has been enabled for a developer, subsequent projects that they submit using the
same credentials do not need business owner approval prior to sandbox and production deployment. Any
changes made to the project are effective immediately.
5. Review Integration Project & 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 and
Service Provider 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.
42
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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.
43
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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.
44
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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 onbehalf of the Merchant. Prior to production deployment:
-
Ensure that you have implemented the MasterPass button on merchant’s site or app
Your sandbox implementation passes all items in the QA checklist
To move your code to production, update your code with the MasterPass API Production 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 Single-Merchant API
10. Set Auto-Approval—Service Provider Activity
Once the first checkout project has been completely approved for production, the Enable Auto Approval
checkbox will be available in the Account Settings.
The Service Provider business owner has an option to enable auto approval of checkout projects, which
must be done to use the API-Based Onboarding method. This feature allows Service Providers to determine
if they wish to have a checkpoint/audit step prior to having merchants setup in sandbox and production or
not. When auto approval is enabled, the system will automatically approve any submitted merchant profiles
for both Sandbox and Production credentials. This is applicable to all developers associated with the
account, and changes are effective immediately. To enable auto approval, click Account Settings from the
top navigation bar and click on the Enable Auto Approval check box. Click Agree when prompted.
45
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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 that want to use the Single-Merchant 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 checkbox. To view the newly created Open
Feed to Production project, click Checkout Projects.
46
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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 Merchant Record to Open Feed Checkout Project—System
Activity
The Open Feed to Production Project can only be used for onboarding via the API.
NOTE: The Single-Merchant API is limited to a file size of less than 399K (409600 bytes) and must be used
for one merchant record at a time.
The Service Provider system must be designed to send the XML containing details for a single merchant
record, the Checkout Project ID and approved consumer key*, to the Open Feed to Production project
through the Single-Merchant API service call. This will auto-submit and push merchant adds/updates/deletes
directly to Production.” See Appendix for SINGLE-MERCHANT API Upload parameter details.
*If you are a new service provider, then you will first need to get a project approved all the way to
production (steps 1–8 in the Onboarding table) and you can use consumer keys of the first
production approved checkout project. If you are an existing Service provider, that has used the
File-Based Onboarding, you can use the consumer key that associated with any checkout project
approved all the way to production that you have used onboard merchants using the File-Based
Onboarding method
The API call to upload each merchant must be made using a production consumer key and the associated
production developer Key ID credentials. The checkout project ID of the Open feed project needs to be used
in the API request URL.
NOTE: Once MasterPass successfully processes the merchant record, the API will provide a response with
the checkout identifier for the merchant.
Validate Merchant API Service
Service providers may use an API service to verify their submission for schema and business rules
validation before uploading merchant records to MasterPass via the onboarding API.
To begin the validation process via the Validation API service, the developer must call the API and send the
XML containing the merchant record.
•
If there are schema errors errors, the system will indicate that and the errors must be corrected
before the xml can be validated against the business rules. Once validation is complete if there are
47
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
•
•
•
any errors, the API response will indicate that, and if the XML contains no errors the API will
provide a success response.
The results of the validation are not stored by MasterPass and available to service providers when
they return, so they must save the results of the API response on their end which can be used to
correct any errors with their submission.
There are no limits on the number of times the validation API can be called for validating an XML.
The validation API supports the same size of the onboarding API (399 KB) and only one merchant
record may be submitted at a time via the validation API.
The Validation API system will display an error message if the file is invalid.
Refer to the “Validation Error Messages” section of the Appendix for a list and descriptions of the validation
error messages. If the XML file is valid, the Validation API system will send a confirmation response
indicating that the XML file was loaded successfully.
48
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Integration Process
For a step by step guide through integration and illustration of the various calls to MasterPass,
you can download the example of our code available in various languages such as Java, C#,
PHP, and Ruby. You can also access the sample code for correct implementation of signature
base string and exchanges with MasterPass at the following link.
https://developer.mastercard.com/portal/display/api/MasterPass+-+Merchant+Checkout+-+Sample+Code
Lightbox Integration
Lightbox integration is required to launch the MasterPass user interface for consumer wallets. In order to
invoke the Lightbox, merchants will need to include the following scripts on the page they implement the
Buy with MasterPass button:
1. https://www.masterpass.com/lightbox/Switch/assets/js/jquery-1.10.2.min.js
» It is recommended to pull the jQuery file from the public jQuery repository
https://ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js
2. MasterPass Script
NOTE: Those invoking the Lightbox from an iFrame must include the following scripts on the parent
(outer) frame in addition to the iFrame source that is invoking MasterPass Lightbox:
a. Production - https://www.masterpass.com/lightbox/Switch/integration/MasterPass.client.js
b. Sandbox https://sandbox.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.
2.
3.
4.
5.
6.
7.
8.
9.
Request Token Service
Shopping Cart Service
Merchant Initialization Service (Optional based on Shopping Cart parameters.)
Invoke MasterPass UI(Lightbox) for checkout
Standard Callback method or Redirect to callback URL
Access Token Service
Retrieve Payment, Shipping Data, Rewards and 3DS Details
Authorize Payment through payment processor
Postback Service
Invoke MasterPass UI (Lightbox)
Within a script tag the merchant must invoke the checkout method with the required parameters. Here is an
example
<script type="text/javascript" language="Javascript">
MasterPass.client.checkout({
"requestToken":"insert_request_token_here",
"callbackUrl":"http://www.somemerchant.com/checkoutcomplete.htm",
"merchantCheckoutId":"insert_checkout_id_here",
"allowedCardTypes":["master,amex,diners,discover,maestro,visa"],
"version":"v6"
});
49
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
</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 identifier from the MasterPass Merchant
Portal
allowedCardTypes—Card types accepted by merchant
version—checkout version (v6)
Lightbox parameter details can be found here.
Standard Checkout Callback
Once a checkout is completed, MasterPass will return context to the merchant. This can be done via one of
the following options:
a.
b.
A callback URL—MasterPass uses the callback URL (oauth_callback) from the request token call
to direct back to the merchant site when Lightbox is rendered in full screen mode.
A javascript callback method—Use “failureCallback” and “successCallback” to give control back to
the page that initiated the Lightbox without any redirects. These parameters must be set when
invoking MasterPass Lightbox UI.
It is recommended that your code takes care of both scenarios.
a.
Redirect to Merchant Callback URL Example
http://www.somemerchant.com/checkoutcomplete.htm?status=success&checkout_res
ource_url=https%3A%2F%2Fstage.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckou
t%2F10189977%3Fwallet%3Dphw&oauth_verifier=6c50838e31b7441e6eafa222938545288
9255b13&oauth_token=d6fa60984308aebb6183d44fb9688fb9dc8332dc
b.
Checkout Callback method Example
function onSuccessfulCheckout(data)
{
document.getElementById('oauthToken').value=data.oauth_token;
document.getElementById('oauthVerifer').value=data.oauth_verifier;
document.getElementById('checkoutUrl').value=data.checkout_resource
_url;
}
Service Descriptions:
Request Token Service
This should be executed when a consumer clicks the Buy with MasterPass button.
Request and response parameter details can be found here.
50
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Sandbox and Production Endpoints
» https://sandbox.api.mastercard.com/oauth/consumer/v1/request_token
» https://api.mastercard.com/oauth/consumer/v1/request_token
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, which—if the merchant sets it—will remove the need
to call the merchant initialization service before displaying the Lightbox. Request and response parameter
details can be found here.
Shopping cart request has an optional SecondaryOriginUrl field, which—if the merchant sets it—should
only be used when the Lightbox will be invoked from a frame that’s on a merchant site and when that frame
is of a different domain than that of the merchant site, like for a service provider.
NOTE: The product description needs to be HTML-encoded and has a character limit of 100 characters.
Sandbox and Production Endpoints
» https://sandbox.api.mastercard.com/masterpass/v6/shopping-cart
» https://api.mastercard.com/masterpass/v6/shopping-cart
Merchant Initialization Service
This service is used to secure Lightbox connections between merchant and MasterPass. This service
requires a request token (OAuthToken). This service call should be used when shopping cart service is not
called.
Request and response parameter details can be found here.
51
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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. 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
» https://sandbox.api.mastercard.com/oauth/consumer/v1/access_token
» https://api.mastercard.com/oauth/consumer/v1/access_token
Retrieve Payment, Shipping Data, Rewards and 3DS Details
Now you will use the Checkout Resource URL request parameter (checkout_resource_url) received from the
callback URL to retrieve consumer’s payment, shipping address, reward and 3DS information from
MasterPass.
The checkout resource url supplied by MasterPass should be decoded and consumed by the
merchant or Service Provider as provided by MasterPass. MasterPass may add or delete parameters
in future.
Example:
Below are two example callback urls with the checkout_resource_url parameter highlighted:
1)
https://AnyMerchant.com/CheckoutCallback?mpstatus=success&checkout_resource_url=https%3A%2F
%2Fapi.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F11318523&oauth_verifier=aa2ff8e8f11
44f45c3b8fdc3d42398913a49e387&oauth_token=b8361ad151af35f71df7b395e083befcaf8192dd
Decoded checkout url:
checkout_resource_url=https://api.mastercard.com/masterpass/v6/checkout/11318523
2)
https://AnyMerchant.com/CheckoutCallback?checkout_resource_url=https%3A%2F%2Fapi.mastercard.
com%2Fmasterpass%2Fv6%2Fcheckout%2F11318500&checkoutId=11318500&oauth_verifier=aa2ff8e
8f1144f45c3b8fdc3d42398913a49e387&oauth_token=b8361ad151af35f71df7b395e083befcaf8192dd
Decoded checkout url:
checkout_resource_url=https://api.mastercard.com/masterpass/v6/checkout/11318500&checkoutId=11318500
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
52
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
transaction. Checkout Postback is still required. It is recommended not to allow consumers to change their
card details after returning from MasterPass.
A three-byte wallet Indicator (WID) Flag (WalletID xml element in the checkout xml) will be part of the output
returned by this request. This value must be passed to your acquiring bank, and will indicate that the
customer’s payment details were provided by the MasterPass, rather than being manually entered. You may
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 element, your
transactions will continue to process as is. Contact Customer Support if you have questions.
The following message elements in the Dual Message System (Authorization and Clearing) and Single
Message System carry this WID Flag:
•
•
•
Dual Message System (Authorization)—Data element (DE) 48 (Additional Data—Private Data),
subelement 26 (Wallet Program Data), subfield 1 (Wallet Identifier)
Dual Message System (Clearing)—PDS 0207 (Wallet Identifier)
Single Message System—DE 48 (Additional Data), subelement 26 (Wallet Program Data), subfield
1 (Wallet Identifier)
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
53
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
•
•
•
•
•
•
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
o SUCCESS: For approved transaction
o FAILURE: For declined transaction
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.
If you are integrating MasterPass for Android devices, set the android:targetSdkVersion value in your
application to 19 or higher. There will be significant MasterPass User Interface usability issues for users with
the latest devices and Android releases if this version is not declared. For more information on Android SDK
targets, refer to the <uses-sdk> page on the Android Developers site. To maintain your application along
with each Android release, you should increase the value of this attribute to match the latest API level.
The basic process for integrating the Android or iOS application is as follows:
1.
Perform a POST to ${server}/appToWallet/initialize with the shopping cart data in the POST
message
a.
The server will request the Request Token, post the shopping cart data to MasterPass
services and generate the Redirect URL.
b.
The server will pass the Redirect URL and the Callback URL back to the mobile
application.
2.
On a 200 response, save the Callback URL, and use the user Redirect URL to open a Web View
3.
Watch the Web View for navigation to the Callback URL.
4.
On navigation to the Callback URL,
a.
If the query parameter section of the Callback URL only contains the oauth_token, the
user did not complete selection in MasterPass. Return the user to the cart view, or
wherever your particular requirements dictate.
b.
If the query parameter of the Callback URL section contains information, parse out the
oauth_token, oauth_verifier, and checkout_resource parameter values, perform a string
replacement on the checkout_resource value to replace ‘/’ with ‘.’ and use these to
perform a GET
to${server}/appToWallet/checkoutInformation/${oauth_token}/${oauth_verifier}/${checkout
_resource}
c.
NOTE: Do not send the full PAN to the mobile device. This information should be stored
on the server similarly to the server/browser implementation.
54
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
5.
On a 200 response, use the returned information to produce a summary view for the user to give
final approval to the transaction (pursuant to your specific requirements.)
6.
After the consumer completes the transaction, the server should submit postback to MasterPass.
55
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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 earliest possible entrypoint, 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.
For all production button URLs and "Learn More" links, refer to the MasterPass™ Digital Assets – Buttons
and Learn More Links document.
The URL naming convention uses the base URL, Language Code (ISO 639-1), Country Code (ISO 3166and 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 class="MasterPassBtnExample">
<a href="/exampleRedirect">
<img
src="https://www.mastercard.com/mc_us/wallet/img/en/US/mcpp_wllt_btn_chk_147x
034px.png" alt="Checkout with MasterPass Button Example" />
</a>
</div>
MasterPass Checkout Images
PNG Checkout Buttons
/mcpp_wllt_btn_chk_147x034px.png
/mcpp_wllt_btn_chk_160x037px.png
/mcpp_wllt_btn_chk_166x038px.png
/mcpp_wllt_btn_chk_180x042px.png
56
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
GIF Checkout Buttons
/mcpp_wllt_btn_chk_147x034px.gif
/mcpp_wllt_btn_chk_160x037px.gif
/mcpp_wllt_btn_chk_166x038px.gif
/mcpp_wllt_btn_chk_180x042px.gif
GIF Acceptance Marks
/mp_mc_acc_023px_gif.gif
/mp_mc_acc_030px_gif.gif
/mp_mc_acc_034px_gif.gif
/mp_mc_acc_038px_gif.gif
/mp_mc_acc_050px_gif.gif
/mp_mc_acc_065px_gif.gif
/mp_mc_acc_113px_gif.gif
PNG Checkout Buttons – High Resolution
/mcpp_wllt_btn_chk_290x068px.png
/mcpp_wllt_btn_chk_317x074px.png
/mcpp_wllt_btn_chk_326x076px.png
/mcpp_wllt_btn_chk_360x084px.png
GIF Checkout Buttons – High Resolution
/mcpp_wllt_btn_chk_290x068px.gif
/mcpp_wllt_btn_chk_317x074px.gif
/mcpp_wllt_btn_chk_326x076px.gif
/mcpp_wllt_btn_chk_360x084px.gif
GIF Acceptance Marks – High Resolution
/mp_acc_046px_gif.gif
/mp_acc_060px_gif.gif
/mp_acc_068px_gif.gif
/mp_acc_076px_gif.gif
/mp_acc_100px_gif.gif
/mp_acc_130px_gif.gif
/mp_acc_226px_gif.gif
Here are a few examples
U.S. English URL:
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
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.
57
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
The “Learn More” page is available in multiple languages and can be accessed from the following link. For
the list of all available languages, refer to the MasterPass™ Digital Assets – Buttons and Learn More Links
document.
The following URLs contain examples of the “Learn More” page in various languages:
English - 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
58
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Testing
MasterPass Sandbox Testing
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.
The accounts in the following table are shared by many sandbox testers. If you experience difficulty using
these accounts, wait at least 30 minutes and try again.
Sandbox Consumer
Account
Test Account 1
Login Email
Password
Security Question
Security Answer
[email protected]
abc123
Pet’s Name
fido
Test Account 2
[email protected]
abc123
Pet’s Name
fido
3DS Test - MasterCard
SecureCode
[email protected]
tester123
Pet’s Name
fido
3DS Test - Visa Verified
by Visa
[email protected]
tester123
Pet’s Name
fido
Use the “remember me” and “remember this device” options when testing so that you don’t have to rekey
the entire test account information every time you login to MasterPass.
Once you are redirected to the sandbox environment, select MasterPass wallet to sign-in to Sandbox
Consumer Wallet Account. Below is a quick walkthrough of the Wallet experience.
(Select) MasterPass Wallet
59
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Sign-in & Verify Your ID (Login email for Sandbox)
Select Payment & Shipping
3DS Test Cases
MasterCard SecureCode
Use the “3DS Test - MasterCard SecureCode” from the Sandbox Consumer Account table above to test
MasterCard and Maestro SecureCode 3DS functionality. The following table provides the expected outputs
for each of the Test Cases for MasterCard SecureCode.
60
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Once you have logged into the “3DS Test - MasterCard SecureCode” account, choose the Test Case Card
nickname that corresponds to the Test Case number from the table above for the Test Case that you would
like to test. For example, use the below Test Case 1 card to test TC# 1 from the MasterCard and Maestro
Test Cases table above.
61
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Verified by Visa
Use the “3DS Test - Visa Verified by Visa” Sandbox Consumer Account from the table above to test Visa’s
Verified by Visa 3DS functionality. The following table provides the expected outputs for each of the Test
Cases for Verified by Visa.
62
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Once you have logged into the “3DS Test - Visa Verified by Visa” account, choose the Test Case Card
nickname that corresponds to the Test Case number from the table above for the Test Case that you would
like to test. For example, use the below Test Case 1 card to test TC# 1 from the Visa Test table above.
63
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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.
Merchants requesting liability shift for MasterPass transactions should use Advanced Checkout within
MasterPass
Post Wallet Experience
»
»
After clicking the “Finish Shopping” button, verify the consumer is taken to a valid page.
Verify that MasterPass acceptance mark is displayed for all MasterPass transactions.
64
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
»
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.
Ensure you are decoding and consuming the checkout_resource_url as provided by MasterPass
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 the card PAN has not been provided to any entity that does not have the appropriate security
in place for storage and transmission of card data (per PCI guidelines).
Verify that if merchants are provided with the PAN, this value is not displayed on-screen.
Verify that your system can handle the PostalCode element of up to nine characters; this element is
sent by MasterPass as part of the BillingAddress and the ShippingAddress elements in checkout XML.
»
»
»
»
»
»
»
Postback
»
Verify that the transaction id submitted as part of a postback was sourced from the associated
MasterPass transaction.
Verify that the transaction result (Postback) is reported immediately after card authorization.
»
General
» Ensure you are coding to DNS and not to IP addresses for our urls or endpoints.
Troubleshooting
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
65
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
»
»
»
»
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 merchant testing, contact the implementation
manager assigned to work with you on this implementation. If you don’t have an assigned implementation
manager, send an email—with the following information (as applicable)—to
[email protected]:
•
•
•
•
•
•
•
•
•
•
•
•
Merchant/Service Provider Name
Email Address
Country/Region
Onboarding Model (Direct Merchant, Service Provider Merchant-by-Merchant or Service Provider
File and API Onboarding)
Environment of Integration (Sandbox or Production)
Checkout Version and Checkout Identifier
Consumer Key
Postback Details (Amount, Date and Time of recent Checkout)
Detailed description of the issue, including expected and actual test results (if applicable)
Error Message(s)
Screenshot(s)
Exact Timestamp
66
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Appendix
Lightbox Parameters
Lightbox Parameters invoked on clicking Buy with MasterPass or Connect with MasterPass button.
Parameter name
allowedCardTypes
string[]
O
Connect
Checkout
Card security
Data type
O = Optional; R = Required; A = Automatically populated
Description
This parameter restricts the payment
methods that may be selected based on
card brand. Omit this parameter to
allow all payment methods. Here are the
valid values for different card types
MasterCard: master
Maestro: maestro
American Express: amex
Discover: discover
Diners: diners
Visa: visa
JCB: jcb
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.
67
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
failureCallback
function
O O O This defines the function to be called
when the flow ends in failure.
merchantCheckoutId
string
R
requestToken
suppressShippingAddressEnable
string
Bool
successCallback
function
Refer to the SDK for more examples
This is the checkout identifier which is
used to identify the merchant and their
checkout branding.
R R R This is an OAuth token.
O
When set to “true,” the consumer
placing the order through MasterPass
Wallet will not provide a shipping
address (for example, when the
consumer purchases digital goods).
When set to “false,” the consumer
placing the order through MasterPass
Wallet must provide a shipping address.
O O O This defines the function to be called
when the flow ends in success.
R
R
OAuth Samples
Request Token
Request Token Parameters
request_token
Request
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
request_token
Response
oauth_token
X
oauth_callback_confirmed
X
oauth_expires_in
X
oauth_token_secret
X
68
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
X
xoauth_request_auth_url
Request Parameter Details
Request Token—Request
Signature Base String
Authorization Header
Description
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.
RSASHA1
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
Oauth Token
oauth_token
Description
oauth_token is sent in the signature base
string, authorization header and redirect
URL
Possible
Values
Variable
Variable
oauth_callback_confirmed
Request Token
Possible
Values
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%2Freque
st_token&oauth_callback%3Dhttp%253A%252F%252Fprojectabc.com%252Fmerchant%252F
Callback.jsp%26oauth_consumer_key%3DZGho8Df8vqWIpGCIu559HYriL093IBXdJeKavp4dce9db2a%25216464586653467358724b616c744754454433
49466a413d3d%26oauth_nonce%3D1143452272881219%26oauth_signature_method%3DRSASHA1%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%2FKm6do5ZVi6doKzAJZ0m8QqhiERi5lRup
hdyUkhW8LKdUL1TetPdxm32Vtr%2BQGF6n6IBjr8dGcyYmfaLyAYVhF%2Fx5oQhUDVpdXIc10dJ0m
iUwZPbJ1QopN3ibeOzvgNxhEiHYKVnpvYEhc%3D",oauth_version="1.0",oauth_nonce="114
3452272881219",oauth_signature_method="RSASHA1",oauth_consumer_key="ZGho8Df8vqWIpGCIu559HYriL093IBXdJeKavp4dce9db2a%216464586653467358724b616c74475445443349
466a413d3d",oauth_timestamp="1339612030",realm="eWallet"
69
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
HTTP Response Example
oauth_callback_confirmed=true&oauth_expires_in=900&oauth_token=a02c5c5c1a128c2
cebc650ea9aa3dfb7&oauth_token_secret=c2daaf0888779d82bd63524159bee91f&xoauth_r
equest_auth_url=https%3A%2F%2Fsandbox.masterpass.com%2Fonline%2FCheckout%2FAut
horize
Merchant Initialization Service
Merchant Initialization Parameters
Merchant
Initialization
resource
Request
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 Request
XML
Merchant Initialization Response
XML
X
Merchant
Initialization
Resource
Response
X
Merchant Initialization Request Parameter Details
Merchant Initialization Resource—Request
Signature Base String
Description
Possible
Values
oauth_signature
RSA/SHA1 signature generated from the
signature base string
Variable
oauth_version
Oauth version.
1.0
oauth_nonce
Unique alphanumeric string generated from
code
Variable
oauth_signature_method
oauth signature method.
RSASHA1
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
Authorization Header
70
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Merchant Initialization
Request XML
MerchantInitializationRequest
XML
Merchant Initialization Resource—Response
Oauth Token
oauth_token
Merchant Initialization details
Description
oauth_token is sent in the request
Possible
Values
Variable
Signature Base String Example
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%merchantinitial
ization&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_key
%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a3
27474695545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4B4263CB5A305%26oauth_signature_method%3DRSASHA1%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_jRd4b
0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_metho
d="RSA-SHA1",oauth_nonce="DEAEB1CD-CA03-405D-A7B4B4263CB5A305",oauth_timestamp="1380049711",oauth_version="1.0",oauth_body_hash=
"8K9uhveZjVdZW8AIYiXpR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C
8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zrav
b02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"
XML
V6/merchant-initialization—XML Schema Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="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="MerchantInitializationExtension" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:element name="MerchantInitializationExtension"
type="MerchantInitializationExtension"/>
<xs:complexType name="MerchantInitializationExtension">
<xs:sequence>
<xs:element name="SecondaryOriginUrl" type="xs:string"
minOccurs="0"/>
71
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
</xs:sequence>
</xs:complexType>
URL: https://api.mastercard.com/masterpass/v6/merchant-initialization — Sample Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantInitializationRequest>
<OAuthToken>oauth_demo_token4sj4x6f1eqka2ib2f1nzd1ib2ivvjx16a</OAuthToken>
<OriginUrl>http://localhost:8080</OriginUrl>
<ExtensionPoint>
<SecondaryOriginUrl>http://localhost:8080</SecondaryOriginUrl>
</ExtensionPoint>
</MerchantInitializationRequest>
V6/merchant-initialization -XML Schema Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="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
MerchantInitializationRequest
Element
Description
MerchantInitializationRequest
Root Element
OAuthToken
Request Token (oauth_token)
returned by call to the
request_token API
Type
Min–
Max
XML
-
72
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
MerchantInitializationRequest
XML
ExtensionPoint
MerchantInitializationResponse
XML
Description
Type
Min–
Max
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
SecondaryOriginUrl
Identifies the domain URL of
the outer/parent web page.
This optional field should only
be used when the Lightbox will
be invoked from a frame that’s
on a merchant site, and when
that frame is of a different
domain than that of the
merchant site, like for a
service provider.
string
NA
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
-
Element
Element
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
73
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Value</f:AnotherSampleField>
</f:SampleContainer>
</f:AnotherExampleExtension>
</ExtensionPoint>
Shopping Cart Service
Shopping Cart Parameters
Shopping
Cart
Request
oauth_signature
X
oauth_version
X
oauth_nonce
X
oauth_signature_method
X
oauth_consumer_key
X
oauth_timestamp
X
oauth_body_hash
oauth_token
Shopping Cart Request XML
X
X
X
Shopping
Cart
Response
Shopping Cart Response XML
X
X
Shopping Cart Parameter Details
Shopping Cart—Request
Signature Base String
Authorization Header
Description
Possible
Values
oauth_signature
RSA/SHA1 signature generated from the
signature base string
Variable
oauth_version
Oauth version
1.0
oauth_nonce
Unique alphanumeric string generated
from code
Variable
oauth_signature_method
oauth signature method
RSASHA1
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
Oauth Token
oauth_token
Transfer XML Strings
Shopping Cart Response XML
Description
oauth_token is sent in the signature base
string, authorization header and redirect
URL
Possible
Values
Variable
74
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Signature Base String Example
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fshopping-cart
&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_key%3DcLb0
tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a32747469
5545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4B4263CB5A305%26oauth_signature_method%3DRSASHA1%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_jRd4b
0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_metho
d="RSA-SHA1",oauth_nonce="DEAEB1CD-CA03-405D-A7B4B4263CB5A305",oauth_timestamp="1380049711",oauth_version="1.0",oauth_body_hash=
"8K9uhveZjVdZW8AIYiXpR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C
8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zrav
b02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"
Shopping Cart V6—XML Schema
<xs:complexType name="ShoppingCart">
<xs:sequence>
<xs:element name="CurrencyCode" type="xs:string"/>
<xs:element name="Subtotal" type="xs:long"/>
<xs:element name="ShoppingCartItem" type="ShoppingCartItem" minOccurs="0"
maxOccurs="unbounded"/>
<xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ShoppingCartItem">
<xs:sequence>
<xs:element name="Description" type="xs:string"/>
<xs:element name="Quantity" type="xs:long"/>
<xs:element name="Value" type="xs:long"/>
<xs:element name="ImageURL" type="xs:string" minOccurs="0"/>
<xs:element name="ExtensionPoint" type="ExtensionPoint" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="ShoppingCartRequest">
<xs:sequence>
<xs:element name="OAuthToken" type="xs:string"/>
<xs:element name="ShoppingCart" type="ShoppingCart"/>
<xs:element name="OriginUrl" type="xs:string" minOccurs="0"/>
<xs:element name="ExtensionPoint" type="ShoppingCartRequestExtensionPoint"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:element name="ShoppingCartRequestExtensionPoint" type="ShoppingCartRequestExtensionPoint"/>
<xs:complexType name="ShoppingCartRequestExtensionPoint">
<xs:sequence>
<xs:element name="SecondaryOriginUrl" type="xs:string" minOccurs="0"/>
75
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
</xs:sequence>
<xs:anyAttribute/>
</xs:complexType>
<xs:element name="ExtensionPoint" type="ExtensionPoint"/>
<xs:complexType name="ExtensionPoint">
<xs:sequence>
<xs:any maxOccurs="unbounded" processContents="lax" namespace="##any"/>
</xs:sequence>
<xs:anyAttribute/>
</xs:complexType>
Shopping Cart V6 XML Details
ShoppingCartRequest
ExtensionPoint
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
-
String
NA
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
SecondaryOriginUrl
Identifies the domain URL of the
outer/parent web page. This optional field
should only be used when the Lightbox will
be invoked from a frame that’s on a
merchant site, and when that frame is of a
different domain than that of the merchant
site, like for a service provider.
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
ShoppingCart
ShoppingCartItem
Details of a single shopping cart item.
XML
-
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>
76
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<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 Request XML with Optional SecondaryOriginUrl Field—Sample
<?xml version="1.0" ?>
<ShoppingCartRequest>
<OAuthToken>oauth_demo_token4sj4x6f1eqka2ib2f1nzd1ib2imvce151</OAuthTo
ken>
<ShoppingCart>
<CurrencyCode>USD</CurrencyCode>
<Subtotal>2500</Subtotal>
<ShoppingCartItem>
<Description>Apple MacBook Pro MD101LL/A 13.3-Inch
Laptop</Description>
<Quantity>1</Quantity>
<Value>2500</Value>
<ImageURL>http://ecx.imagesamazon.com/images/I/41t0EjbJXYL._SL500_SS100_.jpg</ImageU
Im>
</ShoppingCartItem>
</ShoppingCart>
<OriginUrl>http://localhost:8080</OriginUrl>
<ExtensionPoint>
<SecondaryOriginUrl>http://localhost:8080</SecondaryOriginUrl>
</ExtensionPoint>
</ShoppingCartRequest>
Shopping Cart Response XML—Sample
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ShoppingCartResponse>
<OAuthToken>a747f7e7c2e0c3048843f640b92806c8</OAuthToken>
77
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
</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>
Access Token Service
Access Token Parameters
access_token
Request
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_expires_in
access_token
Response
X
X
78
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
oauth_token_secret
X
xoauth_request_auth_url
X
X
oauth_verifier
Access Token Parameter Details
Access Token—Request
oauth_signature
Signature Base String
Authorization Header
oauth_version
oauth_nonce
oauth_signature_method
oauth_consumer_key
oauth_timestamp
realm
oauth_verifier
oauth_token
Description
RSA/SHA1 signature generated from the
signature base string
Oauth version.
Unique alphanumeric string generated
from code
oauth signature method
Consumer Key generated when creating a
checkout project on MasterPass Merchant
portal
Current timestamp
Used to differentiate between our mobile
and full site. Currently not used.
Verifier is returned on the callback and
used in the access token request
oAuth token obtained from request token
call
Access Token—Response
Oauth Token
Request Token
oauth_token
oauth_expires_in
oauth_token_secret
Description
oauth_token is sent in the signature base
string, authorization header and redirect
URL
Time the Request Token expires in
seconds
Oauth Secret
Possible
Values
Variable
1.0
Variable
RSASHA1
Variable
Variable
eWallet
Variable
Possible
Values
Variable
900
Variable
Signature Base String Example
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Foauth%2Fconsumer%2Fv1%2Faccess_t
oken&oauth_callback%3Dhttp%253A%252F%252Fprojectabc.com%252Fmerchant%252FCallbac
k.jsp%26oauth_consumer_key%3DZGho8Df8vqWIpGCIu559HYriL093IBXdJeKavp4dce9db2a%25216464586653467358724b616c744754454433494
66a413d3d%26oauth_nonce%3D1144858422275061%26oauth_signature_method%3DRSASHA1%26oauth_timestamp%3D1339613436%26oauth_token%3Da02c5c5c1a128c2cebc650ea9aa3
dfb7%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_sig
nature="OKcp2KmzUEr8kqs%2F7m2ePV6uJ30n786AnZ0kvJSNGV4Q8%2FP3%2Bs7lqv7YIk0yb2h0fU
TC7gSHsfJwmCCk4ES%2FlWVIpSRmVxotgLacxj%2FXI08DS0BZ0XMZZIkhY5Dcg775U3Re4GRN4xa9vm
bztOBd%2BKkNyFIw35To22N1ZUHrYpI%3D",oauth_version="1.0",oauth_nonce="11448584222
75061",oauth_signature_method="RSA-SHA1",oauth_consumer_key="ZGho8Df8vqWIpGCIu559HYriL093IBXdJeKavp4dce9db2a%216464586653467358724b616c74475445443349466
a413d3d",oauth_token="a02c5c5c1a128c2cebc650ea9aa3dfb7",oauth_verifier="96782690
ce6289d0faf45be777d2d86f",oauth_timestamp="1339613436",realm="eWallet"
79
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
HTTP Response Example
oauth_token=9429f23bd08f992c41fb5ddabcc03ecd&oauth_token_secret=cd1ab178419c2111
fb1171083f5dc8d9
Checkout Resource
Checkout Parameters
Checkout
resource
Request
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
Response
Used as endpoint
checkout_resource_url
X
Checkout XML
Checkout Parameter Details
Checkout Resource—Request
oauth_signature
Signature Base String
Authorization Header
oauth_version
oauth_nonce
oauth_signature_method
oauth_consumer_key
oauth_timestamp
realm
oauth_verifier
Checkout Resource—Response
Oauth Token
Transfer XML Strings
oauth_token
Checkout XML
Description
RSA/SHA1 signature generated from the
signature base string
Oauth version.
Unique alphanumeric string generated
from code
oauth signature method.
Consumer Key generated when creating a
checkout project on MasterPass Merchant
portal
Current timestamp
Used to differentiate between our mobile
and full site. Currently not used.
Verifier is returned on the callback and
used in the access token request
Description
oauth_token is sent in the signature base
string, authorization header and redirect
URL
Details of the Checkout
Possible
Values
Variable
1.0
Variable
RSASHA1
Variable
Variable
eWallet
Possible
Values
Variable
Signature Base String Example
GET&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Fcheckout%2F3494
84&oauth_consumer_key%3DcLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414
f4859446c4a366c726a327474695545332b353049303d%26oauth_nonce%3D25780242027605
80
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
%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="CKs9xjeHksuVNKotsRmoOG0Rwmveoc2dTqnNw8IwlsZeG1ZNkVrPsTjde32YBndHR
7iLFvujrY1GJRFsWHFeQGVFbCidGUVbOwtDtm5ArJPTIbedw21GhhXGWRrRpjh3ZhHLDOdSxtxjSCJaHF
QkfGyq%2B0DHhMLLYizIzbH8%2Fp0%3D",oauth_version="1.0",oauth_nonce="25780242027605",oau
th_signature_method="RSASHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%21414f
4859446c4a366c726a327474695545332b353049303d",oauth_token="c531cce64ca2d88ecb223a
8a37afe98e",oauth_timestamp="1380053717",realm="eWallet"
Checkout XML
V6/Checkout-XML Schema
URL: https://api.mastercard.com/masterpass/v6/checkout/
The checkout resource url supplied by MasterPass should be decoded and consumed by the merchant as
provided by MasterPass. MasterPass may add or delete parameters in future
Examples of decoded url:
checkout_resource_url=https://api.mastercard.com/masterpass/v6/checkout/11318500&checkoutId=113185
00
checkout_resource_url=https://api.mastercard.com/masterpass/v6/checkout/11318501
<?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>
81
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<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">
82
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<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"/>
83
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<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-Zaz0-9!#-'\*\+\-/=\?\^_`\{-~]+)*@[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Zaz0-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"/>
84
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<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
<Checkout>
<Card>
<BrandId>master</BrandId>
<BrandName>MasterCard</BrandName>
<AccountNumber>5435579315709649</AccountNumber>
<BillingAddress>
<City>Anytown</City>
<Country>US</Country>
<Line1>100 Not A Real Street</Line1>
<PostalCode>63011</PostalCode>
</BillingAddress>
<CardHolderName>Joe Test</CardHolderName>
<ExpiryMonth>02</ExpiryMonth>
<ExpiryYear>2016</ExpiryYear>
</Card>
<TransactionId>72525</TransactionId>
<Contact>
<FirstName>Joe</FirstName>
<MiddleName>M</MiddleName>
<LastName>Test</LastName>
<Gender>M</Gender>
<DateOfBirth>
<Year>1975</Year>
<Month>03</Month>
<Day>28</Day>
</DateOfBirth>
<NationalID>30258374209</NationalID>
<Country>US</Country>
<EmailAddress>[email protected]</EmailAddress>
<PhoneNumber>1-9876543210</PhoneNumber>
</Contact>
<ShippingAddress>
<City>O Fallon</City>
<Country>US</Country>
<CountrySubdivision>US-AK</CountrySubdivision>
<Line1>1 main street</Line1>
85
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<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
Min–
Max
Type
Checkout
Root Element
XML
-
Checkout
Card
BrandId
XML
Alpha
Numeric
-
Card
Child Element
Identifies the card brand id e.g.
master for MasterCard.
Identifies the card brand name e.g.
MasterCard
Card number or primary account
number that identifies the card
Billing Address for the card holder
Cardholder name
Expiration month displayed on the
payment card.
Expiration year displayed on the
payment card.
Reserved for future enhancement.
Optional
Child Element
Child Element
Contact First Name
Contact Middle Name or Initial
Contact Surname
Contact Gender (M or F)
String
0-255
Integer
13-24
XML
String
1-100
XML
format
XML
format
BrandName
AccountNumber
BillingAddress
CardHolderName
ExpiryMonth
ExpiryYear
ExtensionPoint
Checkout
Checkout
Contact
Optional
TransactionID
Contact
FirstName
MiddleName
LastName
Optional*
Gender
Optional *
DateOfBirth
NOTE: This field may only be
requested from a MasterPass wallet
if it is required by law in a region.
Merchants and service providers
seeking to use this field must work
with the local MasterPass
representative to get the necessary
clearances before requesting these
data elements.
Contact DOB – YYYY/MM/DD
NOTE: This field may only be
requested from a MasterPass wallet
if it is required by law in a region.
Merchants and service providers
Date
Date
0-8
Any
-
String
XML
String
String
String
1-255
1-150
1-150
-
“M” or “F”
Sequence:
Year (Int);
Month (Int)
Day (Int)
Y (4)
M (2)
D (2)
86
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
CheckoutXML
Element
Description
Min–
Max
Type
seeking to use this field must work
with the local MasterPass
representative to get the necessary
clearances before requesting these
data elements.
Contact National Identification
Optional* (dependent on
merchant country of
incorporation and the
consumer country of
residence)
Optional
NationalID
Country
EmailAddress
PhoneNumber
DateOfBirth
Year
Month
Day
ExtensionPoint
Checkout
ShippingAddress
Address
ShippingAddress
Address
City
Country
CountrySubdivision
Line 1
Line 2
Line 3
PostalCode
ExtensionPoint
ShippingAddress
RecipientName
ShippingAddress
RecipientPhoneNumber
Checkout
Checkout
AuthenticationOptions
WalletID
AuthenticationOptions
AuthenticateMethod
NOTE: This field may only be
requested from a MasterPass wallet
if it is required by law in a region.
Merchants and service providers
seeking to use this field must work
with the local MasterPass
representative to get the necessary
clearances before requesting these
data elements.
Contact Country of Residence
Contact Email Address
Contact Phone
Contact DOB
Contact DOB Year
Contact DOB Month
Contact DOB Day
Reserved for future enhancement.
Optional
Child Element
Child Element
Cardholder’s city
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.
Cardholder’s country subdivision.
Defined by ISO 3166-1 alpha-2 digit
code e.g. US-VA is Virginia, US-OH
is Ohio
Address line 1 used for Street
number and Street Name.
Address line 2 used for Apt
Number, Suite Number ,etc.
Address line 3 used to enter
remaining address information if it
does not fit in Line 1 and Line 2
Postal Code or Zip Code appended
to mailing address for the purpose
of sorting mail.
Reserved for future enhancement.
Optional
Name of person set to receive the
shipped order.
Phone of the person set to receive
the shipped order.
Child Element
Helps identify origin wallet
Method used to authenticate the
cardholder at checkout. Valid
values are “MERCHANT ONLY”,
“3DS” and “No Authentication”.
String
1-150
String
String
String
0-2
5-512
3-20
Integer
Integer
Integer
4
1-2
1-2
Any
-
XML
XML
String
0-25
String
2
String
5
String
1-40
String
0-40
String
0-255
String
0-20
Any
-
String
1-100
String
3-20
XML
String
3
Alpha
NA
87
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
CheckoutXML
Element
CardEnrollmentMethod
CAvv
EciFlag:
MasterCardAssignedID
PaResStatus
SCEnrollmentStatus
Description
Method by which the card was
added to the wallet. Valid values
are:
Manual
Direct Provisioned
3DS Manual
NFC Tap
(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
Electronic commerce indicator (ECI)
flag. Present when the PaRes value
is "Y" or "A." Possible values are;
MasterCard:
00-No Authentication
01-Attempts (Card Issuer Liability)
02- Authenticated by ACS (Card
Issuer Liability)
03-Maestro (MARP)
05-Risk Based Authentication
(Issuer, not in use)
06-Risk Based Authentication
(Merchant, not in use)
Visa:
05-Authenticated (Card Issuer
Liability)
06-Attempts (Card Issuer Liability)
07-No 3DS Authentication
(Merchant Liability)
This value is assigned by
MasterCard and represents
programs associated directly with
Maestro cards. This field should be
supplied in the authorization
request by the merchant.
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
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.
Type
Min–
Max
Alpha
NA
Alpha
Numeric
NA
Alpha
Numeric
NA
Alpha
Numeric
NA
Alpha
NA
Alpha
NA
88
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
CheckoutXML
Element
SignatureVerification:
XID
ExtensionPoint
Checkout
Reward Program
Reward Program
RewardNumber
RewardId
Reward Program
Description
N-The card is not eligible for 3DS
authentication.
U-Lookup of the card's 3DS
eligibility status was either
unavailable, or the card is
inapplicable (i.e. prepaid cards).
Signature Verification. Possible
values are:
Y- Indicates that the signature of
the PaRes has been validated
successfully and the message
contents can be trusted.
N-Indicates that for a variety of
reasons (tampering, certificate
expiration, etc.) the PaRes could
not be validated, and the result
should not be trusted.
Transaction identifier resulting from
authentication processing.
Reserved for future enhancement.
Optional
Child Element
Consumer’s reward number
associated with the reward program
ID associated with the reward
program
RewardName
Name of reward program
ExpiryMonth
Month the reward program expires
ExpiryYear
Year the reward program expires
ExtensionPoint
Reserved for future enhancement.
Optional
Min–
Max
Type
Alpha
NA
Alpha
Numeric
NA
Any
-
XML
Alpha
Numeric
Alpha
Numeric
Alpha
Numeric
Alpha
Numeric
Alpha
Numeric
Any
-
* Only when legally required and enabled by MasterPass
ExtensionPoint Elements
Starting with API v6, all schema container elements contain a new optional element named
“ExtensionPoint”. These elements are intended to provide expandability of the API without requiring a new
major version. These elements are defined to contain a sequence of “xs:any”, meaning that any 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>
89
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<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
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
Post
Transaction
Response
X
Postback Parameter Details
Post Transaction—Request
oauth_timestamp
RSA/SHA1 signature generated from the signature
base string
Oauth version.
Unique alphanumeric string generated from code
oauth signature method.
Consumer Key generated when creating a
checkout project on MasterPass Merchant portal
Current timestamp
oauth_body_hash
SHA1 hash of the message body
Merchant Transactions
XML
Transaction details
oauth_signature
Signature Base
String
Authorization
Header
oauth_version
oauth_nonce
oauth_signature_method
oauth_consumer_key
Transfer XML
Strings
Description
Post Transaction—Response
Transfer XML
Strings
Merchant Transactions
XML
Description
Possible
Values
Variable
1.0
Variable
RSA-SHA1
Variable
Variable
Variable
Possible
Values
Transaction details
Signature Base String Example
POST&https%3A%2F%2Fsandbox.api.mastercard.com%2Fmasterpass%2Fv6%2Ftransaction
&oauth_body_hash%3DycNt7A676VEY7i0SkyymKorihCg%253D%26oauth_consumer_key%3DcLb0
tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a32747469
5545332b353049303d%26oauth_nonce%3D26123188000346%26oauth_signature_method%3DRS
A-SHA1%26oauth_timestamp%3D1380054060%26oauth_version%3D1.0
90
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
HTTP Request Example
POST /masterpass/v6/transaction HTTP/1.1
Authorization: OAuth
oauth_signature="Aom0wFGFI7ItYV1IZFn125BoD6jgFtdX15dQ8XbjvMGgKgKtJ5awV7wSMGwUcc
eGlpl52HFS%2B%2BOQzVrCdXUidvgeKOX1nHDFhns0l1yIaqGdkJQYR%2BCQGu1qo7xVjvzTqpXUlrc
2uzVCjyLoQEroIWv5cAOj5l4aBxDopz7OKQA%3D",oauth_body_hash="ycNt7A676VEY7i0SkyymK
orihCg%3D",oauth_version="1.0",oauth_nonce="26123188000346",oauth_signature_met
hod="RSASHA1",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2141
4f4859446c4a366c726a327474695545332b353049303d",oauth_timestamp="1380054060"
MerchantTransactions Request—Schema
NOTE: Service providers using the File- and API-Based Onboarding method may ignore the optional
PreCheckoutTransactionId and ExpressCheckoutIndicator elements.
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">
<xs:element name="MerchantTransactions" type="MerchantTransactions"/>
<xs:complexType name="MerchantTransactions">
<xs:sequence>
<xs:element name="MerchantTransactions"
type="MerchantTransactions" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="ExtensionPoint" type="ExtensionPoint"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="MerchantTransactions">
<xs:sequence>
<xs:element name="TransactionId" type="xs:string"/>
<xs:element name="ConsumerKey" type="xs:string" minOccurs="0"/>
<xs:element name="Currency" type="xs:string"/>
<xs:element name="OrderAmount" type="xs:long"/>
<xs:element name="PurchaseDate" type="xs:dateTime"/>
<xs:element name="TransactionStatus" type="TransactionStatus"/>
<xs:element name="ApprovalCode" type="xs:string"/>
<xs:element name="PreCheckoutTransactionId" type="xs:string"
minOccurs="0"/>
<xs:element name="ExpressCheckoutIndicator" type="xs:boolean"
minOccurs="0"/>
<xs:element name="ExtensionPoint" type="ExtensionPoint"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="TransactionStatus">
<xs:restriction base="xs:string">
<xs:enumeration value="Success"/>
<xs:enumeration value="Failure"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="ExtensionPoint">
<xs:sequence>
91
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<xs:any maxOccurs="unbounded" processContents="lax"
namespace="##any"/>
</xs:sequence>
<xs:anyAttribute/>
</xs:complexType>
</xs:schema>
HTTP Request Example
<MerchantTransactions>
<MerchantTransactions>
<TransactionId>4549794</TransactionId>
<ConsumerKey>0zMKpm0nFtUv8lLXT97jDRo2bp4vNF8MFYyt3R5R87e3f3f4!414b4867
5861677159682b563745776b593652377939673d</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-hybxhplo947</PreCheckoutTransactionId>
<ExpressCheckoutIndicator>false</ExpressCheckoutIndicator>
</MerchantTransactions>
</MerchantTransactions>
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="MerchantTransactions" minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="ExtensionPoint" type="ExtensionPoint"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="MerchantTransactions">
<xs:sequence>
<xs:element name="TransactionId" type="xs:string"/>
<xs:element name="ConsumerKey" type="xs:string" minOccurs="0"/>
<xs:element name="Currency" type="xs:string"/>
<xs:element name="OrderAmount" type="xs:long"/>
<xs:element name="PurchaseDate" type="xs:dateTime"/>
<xs:element name="TransactionStatus" type="TransactionStatus"/>
<xs:element name="ApprovalCode" type="xs:string"/>
<xs:element name="PreCheckoutTransactionId" type="xs:string"
minOccurs="0"/>
<xs:element name="ExpressCheckoutIndicator" type="xs:boolean"
92
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
minOccurs="0"/>
<xs:element name="ExtensionPoint" type="ExtensionPoint"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<xs:simpleType name="TransactionStatus">
<xs:restriction base="xs:string">
<xs:enumeration value="Success"/>
<xs:enumeration value="Failure"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="ExtensionPoint">
<xs:sequence>
<xs:any maxOccurs="unbounded" processContents="lax"
namespace="##any"/>
</xs:sequence>
<xs:anyAttribute/>
</xs:complexType>
</xs:schema>
HTTP Response Example (response will be identical to the XML sent if call was successful)
<MerchantTransactions>
<MerchantTransactions>
<TransactionId>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>
</MerchantTransactions>
</MerchantTransactions>
MerchantTransactionsXML—Details
MerchantTransactionsRequest
Element
Description
Min Max
Type
MerchantTransactions
MerchantTransactions
ExtensionPoint
TransactionID
MerchantTransactions
ConsumerKey
Reserved for future
enhancement. Optional
Uses the TransactionID element
of the Checkout XML
Automatically generated when
creating a checkout project on
MasterPass Merchant portal.
XML
-
Any
-
String
1-255
String
97
93
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Currency
OrderAmount
PurchaseDate
TransactionStatus
ApprovalCode
ExtensionPoint
MerchantTransactionsResponse
Element
Currency of the transaction.
Defined by ISO 4217 to be
exactly three characters, such as,
USD for US Dollars.
(Integer) Transaction order
amount without decimal e.g.
1500.
Date and Time of the shopping
cart purchase.
State of the transaction. Indicates
whether successful. Valid values
are Success or Failure.
Approval code returned to
merchant from merchant's
payment API with payment
gateway or service provider
Reserved for future
enhancement. Optional
Description
String
3
Integer
1-12
Date
XML
format
String
7
String
6
Any
Min Max
Type
MerchantTransactions
MerchantTransactions
ExtensionPoint
TransactionID
ConsumerKey
Currency
MerchantTransactions
OrderAmount
PurchaseDate
TransactionStatus
ApprovalCode
ExtensionPoint
Root Element
Reserved for future
enhancement. Optional
Uses the TransactionID element
of the Checkout XML
Automatically generated when
creating a checkout project on
MasterPass Merchant portal.
Currency of the transaction.
Defined by ISO 4217 to be
exactly three characters, such as,
USD for US Dollars.
Integer Transaction order amount
without decimal e.g. 1500.
Date and Time of the shopping
cart purchase e.g. 2012-0606T15:12:24.254-05:00
State of the transaction. Indicates
whether successful. Valid values
are Success or Failure.
Approval code returned to
merchant from merchant's
payment API with payment
gateway or service provider
Reserved for future
enhancement. Optional
XML
-
Any
-
String
1-255
String
97
String
3
Integer
1-12
Date
XML
format
String
7
String
6
Any
-
ExtensionPoint Elements
Starting with API v6, all schema container elements contain a new optional element named
“ExtensionPoint”. These elements are intended to provide expandability of the API without requiring a new
major version. These elements are defined to contain a sequence of “xs:any”, meaning that any XML
content can be contained within the element. In order to ensure future expandability, all integrators must not
perform any validation of elements received inside an ExtensionPoint element, beyond any that may be
defined by MasterPass in the future with a separate schema. Any such extensions will be optional. Further,
only authorized schemas will be allowed inside ExtensionPoint elements, and any unknown elements will be
dropped by MasterPass.
94
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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>
File-Based Merchant Onboarding
Merchant Upload Schema
The file schema can be downloaded from the MasterPass - Merchant Checkout - Documentation page on
Developer Zone.
Merchant Upload Schema Details
NOTE: Please contact Merchant Support for details regarding how to specify a reward program for a
merchant in the Merchant Upload file.
MerchantUpload
Mandatory
/Optional
Description
Merchant
Merchant Details
Element
M
Variable
SPMerchantId
Service Provider
Issued Merchant
ID. This should be
unique per Service
Provider
String
M
Variable
Action
Merchant
Type
Element
Profile
CheckoutBrand
AuthOption
Merchant Action
Merchant Profile
String
M
Child
Mandatory
for Create
and
Update.
Not used
for Delete.
Branding
Information
Child
Authentication
Options
Child
Mandatory
for Create,
Optional for
Update and
Delete
Min
1
1
Max
Comment
e.g.
123456789
1
Valid
values are
C (Create),
U (Update)
and D
(Delete)
1
Mandatory
for Create
(Action=C)
and Update
(Action=U)
At least one
CheckoutBr
and
element
MUST be
present for
merchant
creation.
Variable
per
95
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Merchant
MerchantAcquirer
Name
DoingBusAs
FedTaxId
Profile
Url
BusinessCategory
Address
Phone
Acquirer
Address
Child
Merchant Name
String
M
1
255
String
M
1
255
String
O
1
100
String
M
5
1000
String
O
1
255
Doing Business As
- Alias
Merchant’s
Federal Tax ID
Merchant’s
Website URL
Merchant’s
business type
Merchant’s
Address
Merchant’s Phone
Merchant’s
Acquirer
Child
Child
O
Merchant’s City
M
1
25
Country
Merchant’s
Country
M
2
2
Country
Subdivision
Line2
Line3
PostalCode
CountryCode
Phone
Merchant’s
Country
Subdivision.
Defined by ISO
3166-1 alpha-2
digit code e.g. USVA is Virginia, USOH is Ohio
Merchant’s
Address Line 1
Merchant’s
Address Line 2
Merchant’s
Address Line 3
Merchant’s Postal
Code
Merchant’s phone
country code
Number
Merchant’s phone
Number
Action
Merchant Acquirer
action
Id
Merchant’s
Acquirer Id
Name
Merchant’s
Acquirer Name
e.g. XYZ
Pizza
E.g. XYZ
Pizza Inc
e.g.
999990001
e.g.
www.xyzpiz
za.com
e.g.
Restaurant
Child
City
Line1
Acquirer
Merchant Acquirer
String
e.g. New
York
Standard 2letter ISO
3166
country
codes e.g.
US
O
1
100
if defined
choose
string (1100) or
defined
enumerator
e.g. US-NY
M
1
40
e.g. 1 Main
Street
O
1
40
O
1
40
M
1
10
e.g. 10001
M
1
10
e.g. 75
M
3
20
O
1
1
M
1
15
e.g. 453214
250
e.g., Test
Acquirer.
3DS
merchants
must
reduce their
M
1
e.g.
978545343
2
Valid
values are
C (Create),
U (Update),
and D
(Delete)
96
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
AssignedMerchan
tId
Acquirer assigned
merchant ID
M
1
255
Password
Acquirer Password
for 3DS setup
O
1
8
CheckoutId
Name
O
1
255
e.g.
a4c411by7l
ob4i81xb6r
41i820mw3
n151
M
1
255
e.g. XYZ
Pizza
DisplayName
Display Name
M
1
255
ProductionUrl
Production
checkout URL
M
5
255
SandboxUrl
Sandbox checkout
URL
M
5
255
LogoUrl
Merchant logo
displayed on
MasterPass site
during checkout. If
not specified, the
Name is displayed
O
2
2000
CheckoutBrand
CardBrand
Card brands
enrolled for
advanced
authentication
M
NA
NA
Type
Authentication type
M
NA
NA
Action
Action
O
0
C, U,
or D
AuthOption
MerchantAcquirer
If not specified for
Update Action,
then MasterPass
will produce a
unique checkout
ID.
Name displayed
on MasterPass site
during checkout
when no logo is
provided
Child
character
limit to 250
to meet
Cardinal
Commerce’s
API
specifications.
e.g.
435t6543
e.g., Visa.
3DS
merchants
must
reduce their
character
limit to 8 to
meet
Cardinal
Commerce’s
API
specifications.
e.g. XYZ
Pizza
e.g.
https://xyzpi
zza.com
e.g.
https://test.
xyzpizza.co
m
e.g.
http://xyzpiz
za.com/log
o.jpg
Refer to the
schema to
get valid
values. For
example,
for
MasterCard
, use
"MASTER".
Refer to the
schema to
get valid
values.
Used to
create (C),
update (U)
97
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
or delete
(D) Visa
Password
Acquirer
MerchantAcquirer
Brand
Acquirer
Merchant Acquirer
Brand
Child
Child
M
CardBrand
Card Brand
M
NA
NA
Currency
Currency
O
3
3
MerchantAcquirer
Brand
Refer to the
schema to
get valid
values. For
example,
for
MasterCard
, use
"MASTER".
ISO 4217
standard 3letter
currency
code. Refer
to the
schema to
get valid
values.
NOTE: If
this field is
left blank,
then all
currency
codes will
be enabled.
Merchant Upload Sample—Create
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload>
<Merchant>
<SPMerchantId>SPMerch58401</SPMerchantId>
<Action>C</Action>
<Profile>
<Name>SPMerch58401</Name>
<DoingBusAs>SPMerch58401</DoingBusAs>
<FedTaxId>211624440</FedTaxId>
<Url>https://SPMerch58401.com</Url>
<BusinessCategory>test</BusinessCategory>
<Address>
<City>SPMerch58401</City>
<Country>US</Country>
<Line1>898 SPMerch58401</Line1>
<PostalCode>78090</PostalCode>
</Address>
<Phone>
<CountryCode>1</CountryCode>
<Number>3734517671</Number>
</Phone>
<Acquirer>
<Id>292978156</Id>
98
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<Name>QATESTACQ</Name>
<AssignedMerchantId>MCQA1</AssignedMerchantId>
</Acquirer>
</Profile>
<CheckoutBrand>
<Name>SPMerch58401</Name>
<DisplayName>SPMerch58401</DisplayName>
<ProductionUrl>https://SPMerch58401.com</ProductionUrl>
<SandboxUrl>https://SPMerch58401.com</SandboxUrl>
<LogoUrl>http://www.mastercard.us/_globalAssets/img/nav/n
avl_logo_mastemasterca.png</LogoUrl>
</CheckoutBrand>
</Merchant>
</MerchantUpload>
Merchant Upload Sample—Create with Advanced Authentication Settings (3DS) for MasterCard
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Merchant>
<SPMerchantId>022416_TESTMERCH</SPMerchantId>
<Action>C</Action>
<Profile>
<Name>022416_TESTMERCH</Name>
<DoingBusAs>022415testmerchant</DoingBusAs>
<Url>http://www.testmerchant.com</Url>
<Address>
<City>Padova</City>
<Country>IT</Country>
<Line1>Boettgerstr</Line1>
<PostalCode>35129</PostalCode>
</Address>
<Phone>
<CountryCode>39</CountryCode>
<Number>0614554552</Number>
</Phone>
</Profile>
<CheckoutBrand>
<Name>022416_TESTMERCH</Name>
<DisplayName>022416_TESTMERCH</DisplayName>
<ProductionUrl>https://TESTMERCH.com</ProductionUrl>
<SandboxUrl>http://TESTMERCH.com</SandboxUrl>
</CheckoutBrand>
<AuthOption>
<CardBrand>MASTER_CARD</CardBrand>
<Type>ALL_TRANSACTIONS</Type>
</AuthOption>
<MerchantAcquirer>
<Acquirer>
<Id>523078</Id>
99
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<Name>CartaSI</Name>
<AssignedMerchantId>001</AssignedMerchantId>
</Acquirer>
<MerchantAcquirerBrand>
<CardBrand>MASTER_CARD</CardBrand>
<Currency>EUR</Currency>
</MerchantAcquirerBrand>
</MerchantAcquirer>
</Merchant>
</MerchantUpload>
Merchant Upload Sample—Create with Advanced Authentication Settings (3DS) for Visa
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload>
<Merchant>
<SPMerchantId>SPMerchantId1</SPMerchantId>
<Action>C</Action>
<Profile>
<Name>XYZ Pizza</Name>
<DoingBusAs>XYZ Pizza</DoingBusAs>
<FedTaxId>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>
<AuthOption>
<CardBrand>VISA</CardBrand>
<Type>ALL_TRANSACTIONS</Type>
</AuthOption>
<MerchantAcquirer>
<Action>C</Action>
<Acquirer>
<Id>12345678</Id>
100
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<Name>CRDNLDEMO4</Name>
<AssignedMerchantId>00710212014</AssignedMerchantId>
<Password>tester456</Password>
</Acquirer>
<MerchantAcquirerBrand>
<CardBrand>VISA</CardBrand>
<Currency>USD</Currency>
</MerchantAcquirerBrand>
</MerchantAcquirer>
</Merchant>
</MerchantUpload>
Merchant Upload Sample—Update
NOTE: If the Checkout ID is not included in the Checkout Brand element, then MasterPass will produce a
unique checkout ID for merchant record.
<?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>
<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—Update
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
101
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<MerchantUpload>
<Merchant>
<SPMerchantId>SPMerch58401</SPMerchantId>
<Action>U</Action>
<Profile>
<Name>SPMerch58401</Name>
<DoingBusAs>SPMerch58401</DoingBusAs>
<FedTaxId>211624440</FedTaxId>
<Url>https://SPMerch58401.com</Url>
<BusinessCategory>test</BusinessCategory>
<Address>
<City>SPMerch58401</City>
<Country>US</Country>
<Line1>898 SPMerch58401</Line1>
<PostalCode>78090</PostalCode>
</Address>
<Phone>
<CountryCode>1</CountryCode>
<Number>3734517671</Number>
</Phone>
<Acquirer>
<Id>292978156</Id>
<Name>QATESTACQ</Name>
<AssignedMerchantId>MCQA1</AssignedMerchantId>
</Acquirer>
</Profile>
<CheckoutBrand>
<Name>SPMerch58401</Name>
<DisplayName>SPMerch58401</DisplayName>
<ProductionUrl>https://SPMerch58401.com</ProductionUrl>
<SandboxUrl>https://SPMerch58401.com</SandboxUrl>
<LogoUrl>http://www.mastercard.us/_globalAssets/img/nav/navl_logo_maste
rcardcom.png</LogoUrl>
</CheckoutBrand>
</Merchant>
</MerchantUpload>
Merchant Upload Sample with Advanced Authentication Settings (3DS)—Update
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Merchant>
<SPMerchantId>022416_TESTMERCH</SPMerchantId>
<Action>U</Action>
<Profile>
<Name>022416_TESTMERCH</Name>
<DoingBusAs>022415testmerchant</DoingBusAs>
<Url>http://www.testmerchant.com</Url>
<Address>
<City>Padova</City>
<Country>IT</Country>
102
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<Line1>Boettgerstr</Line1>
<PostalCode>35129</PostalCode>
</Address>
<Phone>
<CountryCode>39</CountryCode>
<Number>0614554552</Number>
</Phone>
</Profile>
<CheckoutBrand>
<CheckoutId>a4a6w4vr8jzii6j0wk2e1i6kx962m2gle</CheckoutId>
<Name>022416_TESTMERCH</Name>
<DisplayName>022416_TESTMERCH</DisplayName>
<ProductionUrl>https://TESTMERCH.com</ProductionUrl>
<SandboxUrl>http://TESTMERCH.com</SandboxUrl>
</CheckoutBrand>
<AuthOption>
<CardBrand>MASTER_CARD</CardBrand>
<Type>ALL_TRANSACTIONS</Type>
</AuthOption>
<AuthOption>
<CardBrand>VISA</CardBrand>
<Type>ALL_TRANSACTIONS</Type>
</AuthOption>
<MerchantAcquirer>
<Acquirer>
<Id>523078</Id>
<Name>CartaSI</Name>
<AssignedMerchantId>001</AssignedMerchantId>
</Acquirer>
<MerchantAcquirerBrand>
<CardBrand>MASTER_CARD</CardBrand>
<Currency>EUR</Currency>
</MerchantAcquirerBrand>
</MerchantAcquirer>
<MerchantAcquirer>
<Acquirer>
<Id>453997</Id>
<Name>CartaSI</Name>
<AssignedMerchantId>011</AssignedMerchantId>
</Acquirer>
<MerchantAcquirerBrand>
<CardBrand>VISA</CardBrand>
<Currency>EUR</Currency>
</MerchantAcquirerBrand>
</MerchantAcquirer>
</Merchant>
</MerchantUpload>
103
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Merchant Upload Sample—Delete
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload>
<Merchant>
<SPMerchantId>SPMerchantId1</SPMerchantId>
<Action>D</Action>
</Merchant>
</MerchantUpload>
Merchant Upload Sample—Delete
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload>
<Merchant>
<SPMerchantId>SPMerch58401</SPMerchantId>
<Action>D</Action>
<Profile>
<Name>SPMerch58401</Name>
<DoingBusAs>SPMerch58401</DoingBusAs>
<FedTaxId>211624440</FedTaxId>
<Url>https://SPMerch58401.com</Url>
<BusinessCategory>test</BusinessCategory>
<Address>
<City>SPMerch58401</City>
<Country>US</Country>
<Line1>898 SPMerch58401</Line1>
<PostalCode>78090</PostalCode>
</Address>
<Phone>
<CountryCode>1</CountryCode>
<Number>3734517671</Number>
</Phone>
<Acquirer>
<Id>292978156</Id>
<Name>QATESTACQ</Name>
<AssignedMerchantId>MCQA1</AssignedMerchantId>
</Acquirer>
</Profile>
<CheckoutBrand>
<Name>SPMerch58401</Name>
<DisplayName>SPMerch58401</DisplayName>
<ProductionUrl>https://SPMerch58401.com</ProductionUrl>
<SandboxUrl>https://SPMerch58401.com</SandboxUrl>
<LogoUrl>http://www.mastercard.us/_globalAssets/img/nav/navl_log
l_mastercardcom.png</LogoUrl>
</CheckoutBrand>
</Merchant>
</MerchantUpload>
Merchant Upload Sample with Advanced Authentication Settings (3DS)—Delete
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
104
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<Merchant>
<SPMerchantId>022416_TESTMERCH</SPMerchantId>
<Action>D</Action>
<Profile>
<Name>022416_TESTMERCH</Name>
<DoingBusAs>022415testmerchant</DoingBusAs>
<Url>http://www.testmerchant.com</Url>
<Address>
<City>Padova</City>
<Country>IT</Country>
<Line1>Boettgerstr</Line1>
<PostalCode>35129</PostalCode>
</Address>
<Phone>
<CountryCode>39</CountryCode>
<Number>0614554552</Number>
</Phone>
</Profile>
<CheckoutBrand>
<CheckoutId>a4a6w4vr8jzii6j0wk2e1i6kx962m2gle</CheckoutId>
<Name>022416_TESTMERCH</Name>
<DisplayName>022416_TESTMERCH</DisplayName>
<ProductionUrl>https://TESTMERCH.com</ProductionUrl>
<SandboxUrl>http://TESTMERCH.com</SandboxUrl>
</CheckoutBrand>
<AuthOption>
<CardBrand>MASTER_CARD</CardBrand>
<Type>ALL_TRANSACTIONS</Type>
</AuthOption>
<AuthOption>
<CardBrand>VISA</CardBrand>
<Type>ALL_TRANSACTIONS</Type>
</AuthOption>
<MerchantAcquirer>
<Acquirer>
<Id>523078</Id>
<Name>CartaSI</Name>
<AssignedMerchantId>001</AssignedMerchantId>
</Acquirer>
<MerchantAcquirerBrand>
<CardBrand>MASTER_CARD</CardBrand>
<Currency>EUR</Currency>
</MerchantAcquirerBrand>
</MerchantAcquirer>
<MerchantAcquirer>
<Acquirer>
<Id>453997</Id>
<Name>CartaSI</Name>
<AssignedMerchantId>011</AssignedMerchantId>
</Acquirer>
<MerchantAcquirerBrand>
<CardBrand>VISA</CardBrand>
<Currency>EUR</Currency>
</MerchantAcquirerBrand>
</MerchantAcquirer>
</Merchant>
</MerchantUpload>
105
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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 Upload Validate Response Schema Details
ValidateFileResponse
Element
Description
ValidatedMerchant
Validation
Details of a
Merchant
MerchantId
ValidatedMerchant
ErrorText
ExtensionPoint
ExtensionPoint
Name
Identifier of
the merchant
defined by
the Service
Provider
Description
of validation
error
Reserved for
future
enhancemen
t.
Merchant
Name
Type
Mandatory /
Optional
Element
M
String
M
Max
Comment
Variable
1
1
e.g.
STGQA09
VBMU0140:
merchantId
already
exists for
serviceProvi
derId=28541
5466 and
spMerchantI
d=STGQA09
M
0
unbou
nded
Optional
0
unbou
nded
M
1
255
String
Any
Min
String
e.g. XYZ
Pizza
Merchant Download Schema
The file schema can be downloaded from the MasterPass - Merchant Checkout - Documentation page on
Developer Zone.
Merchant Download Schema Details
MerchantDownload
MerchantDownload
Mandatory
/Optional
Min
Max
Summary of the
Upload
List of merchants
uploaded/edited
Element
M
-
-
System assigned
Batch ID
Desctiption provided
during file upload
Integer
M
Variable
M
1
50
1
255
Description
Summary
MerchantResp
onseRecord
BatchId
Description
Summary
Type
Element
Element
String
Date/Time
UploadTimestam
p
Upload Time Stamp
UploadFileName
Upload File Name
Comment
M
String
M
e.g. 277800
e.g. Merchant
file upload
DateTime
field e.g.
2013-0518T11:45:19.
444-05:00
e.g.
merchant.xml
106
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
SuccessCount
FailureCount
ErrorText
Number of
successfully
uploaded Merchant
Brandings
Number of
unsuccessfully
uploaded Merchant
Brandings
Description of errors
resulting upload
failures
Integer
M
NA
NA
e.g. 490
M
NA
NA
e.g. 10
O
1
255
e.g. Invalid
Format
Integer
String
String
SandboxKey
Developer’s
sandbox API key
1
50
1
50
String
ProductionKey
Developer’s
production key
SPMerchantId
Merchant identifier
for a specific Service
provider
String
M
Child
MerchantResponseR
ecord
CheckoutBrand
Checkout Branding
ErrorText
Error description for
failure
Name
CheckoutIdentifi
er
CheckoutBrand
ProductionUrl
SandboxUrl
Checkout Brand
Name
Checkout identifier
generated by
MasterPass
Production
Checkout Branding
URL
Sandbox Checkout
Branding URL
String
String
String
String
Variable
e.g.,
245d5a537a4
57c2f2b55644
b7041426944
49644b56673
d9d
e.g.,
245d5a537a4
57c2f2b55644
b7041426944
49644b56673
d9d
e.g. 12345
Choice
(ErrorText or
CheckoutBra
nd)
O
1
255
M
1
255
M
1
255
M
5
255
M
5
255
e.g. Invalid
rewards logo
URL
e.g. XYZ
Pizza
e.g.
a4a6x3oehb3f
zhgu2e
e.g.
https://xyzpizz
a.com
e.g.
https://test.xyz
pizza.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>
<ProjectKeys>
<SandboxKey>41496b7a452f35764d715752755579436b70467871476f3d</SandboxKey>
<ProductionKey>41496b7a452f35764d715752755579436b70467871476f3d</ProductionKey>
107
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
</ProjectKeys>
</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>
Merchant Download Sample with Advanced Authentication Settings (3DS)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantDownload Version="1.1">
<Summary>
<BatchId>285395970</BatchId>
<Description>1P_Upload_MC_3DS.xml</Description>
<UploadTimestamp>2015-04-03T15:00:12.331-05:00</UploadTimestamp>
<UploadFileName>1P_Upload_MC_3DS (1).xml</UploadFileName>
<SuccessCount>1</SuccessCount>
<FailureCount>0</FailureCount>
<ProjectKeys>
<SandboxKey>456d5a537a346c2f2b55644b704142694449644b56673d3d</SandboxKey>
<ProductionKey>456d5a537a346c2f2b55644b704142694449644b56673d3d</ProductionKey>
</ProjectKeys>
</Summary>
<MerchantResponseRecord>
<SPMerchantId>022416_RAMA</SPMerchantId>
<CheckoutBrand>
<Name>022416_RAMA</Name>
<CheckoutIdentifier>a4c411by7lob4i81xb6r41i820mw3n151</CheckoutIdentifier>
<ProductionUrl>https://RAMA.com</ProductionUrl>
<SandboxUrl>http://RAMA.com</SandboxUrl>
</CheckoutBrand>
<MerchantAcquirer>
<ID>523078</ID>
<Name>CartaSI</Name>
<AssignedMerchantID>001</AssignedMerchantID>
<DSStatus>Not Submitted</DSStatus>
</MerchantAcquirer>
</MerchantResponseRecord>
</MerchantDownload>
108
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Single-Merchant API Service
Single-Merchant API
The Single-Merchant API is used by service providers to onboard merchant information one at a time to
MasterPass through the Open Feed Project. The XML schema for the Single-Merchant API is the same as
that used for the File-Based Merchant onboarding via the merchant and service provider portal. See the
Merchant Upload Schema and Merchant Download Schema for details.
Single-Merchant API Parameters
Upload
oauth_signature
X
oauth_version
X
oauth_nonce
X
oauth_signature_method
X
oauth_consumer_key
X
oauth_timestamp
X
oauth_body_hash
X
Merchant Upload XML
X
Response
X
Merchant Download XML
Single-Merchant API Parameter Details
MerchantUpload—Request
Signature Base String
Possible
Values
oauth_signature
RSA/SHA1 signature generated from the
signature base string
Variable
oauth_version
Oauth version
1.0
oauth_nonce
Unique alphanumeric string generated
from code
Variable
oauth_signature_method
oauth signature method
RSASHA1
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
MerchantUpload
Uploaded Merchant Information (XML)
Authorization Header
Merchant Upload XML
Description
MerchantDownload—Response
Description
Possible
109
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Values
Merchant Download
MerchantDownload
Results File of a Merchant Upload
Signature Base String Example
POST&https%3A%2F%2F.api.mastercard.com%2Fmasterpasspsp%2Fv6%2Fcheckoutproject%2
F[0-9]+%2Ffile
&oauth_body_hash%3D8K9uhveZjVdZW8AIYiXpR70KCtk%253D%26oauth_consumer_key%3DcLb0
tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b0476c%2521414f4859446c4a366c726a32747469
5545332b353049303d%26oauth_nonce%3DDEAEB1CD-CA03-405D-A7B4B4263CB5A305%26oauth_signature_method%3DRSASHA1%26oauth_timestamp%3D1380049711%26oauth_version%3D1.0
HTTP Request Example
POST /masterpasspsp/v6/checkoutproject/[0-9]+/file
Authorization: OAuth
realm="eWallet",oauth_consumer_key="cLb0tKkEJhGTITp_6ltDIibO5Wgbx4rIldeXM_jRd4b
0476c%21414f4859446c4a366c726a327474695545332b353049303d",oauth_signature_metho
d="RSA-SHA1",oauth_nonce="DEAEB1CD-CA03-405D-A7B4B4263CB5A305",oauth_timestamp="1380049711",oauth_version="1.0",oauth_body_hash=
"8K9uhveZjVdZW8AIYiXpR70KCtk%3D",oauth_signature="IdV4%2FREyJ7nAXK%2FYvuJ2BtO4C
8t6PlW8xTrDob0WzWJ5%2FRBOPDj534Sm7oPdojivWTGOLAcZq3kbVF6rwrsjGFWlNJITXt3HT3zrav
b02oqTrVQH3Zlx5fi4o0u2xxqrDwHZvbhjPgwByBRmE%2FoTw2l9H%2FznSn45xcS1eJPa%2FGI%3D"
HTTP Response Sample
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantDownload version=”1.1”/>
<Summary>
<BatchId>10247700</BatchId>
<Description>test</Description>
<UploadTimestamp>2014-04-02T16:55:31.308-05:00</UploadTimestamp>
<UploadFileName>CreateMerchant1314.xml</UploadFileName>
<SuccessCount>1</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>
</MerchantDownload>
110
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
HTTP Response Sample
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantDownload Version="1.1">
<Summary>
<BatchId>21946024</BatchId>
<Description>Uploaded Via API</Description>
<UploadTimestamp>2015-03-02T11:25:43.080-06:00</UploadTimestamp>
<UploadFileName>API_UPLOADED_RECORDS</UploadFileName>
<SuccessCount>1</SuccessCount>
<FailureCount>0</FailureCount>
<ProjectKeys>
<SandboxKey>5a7172776e4e2f4c2f6151366c2b4a6947334a3452413d3d</SandboxKey>
<ProductionKey>414f51415350374966414f4f504f78395a2b56573930513d</ProductionKey>
</ProjectKeys>
</Summary>
<MerchantResponseRecord>
<SPMerchantId>BAPPI01</SPMerchantId>
<CheckoutBrand>
<Name>BAPPI1</Name>
<CheckoutIdentifier>a4d6x32y2j9lsi6lbphnw1i6s50ybh14fa</CheckoutIdentifier>
<ProductionUrl>https://cccc.com</ProductionUrl>
<SandboxUrl>https://bbbbbb.com</SandboxUrl>
</CheckoutBrand>
</MerchantResponseRecord>
</MerchantDownload>
HTTP Response Sample with Advanced Authentication Settings (3DS)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantDownload Version="1.1">
<Summary>
<BatchId>285395970</BatchId>
<Description>1P_Upload_MC_3DS.xml</Description>
<UploadTimestamp>2015-04-03T15:00:12.331-05:00</UploadTimestamp>
<UploadFileName>1P_Upload_MC_3DS (1).xml</UploadFileName>
<SuccessCount>1</SuccessCount>
<FailureCount>0</FailureCount>
<ProjectKeys>
<SandboxKey>456d5a537a346c2f2b55644b704142694449644b56673d3d</SandboxKey>
<ProductionKey>456d5a537a346c2f2b55644b704142694449644b56673d3d</ProductionKey>
</ProjectKeys>
</Summary>
<MerchantResponseRecord>
<SPMerchantId>022416_RAMA</SPMerchantId>
<CheckoutBrand>
<Name>022416_RAMA</Name>
<CheckoutIdentifier>a4c411by7lob4i81xb6r41i820mw3n151</CheckoutIdentifier>
<ProductionUrl>https://RAMA.com</ProductionUrl>
<SandboxUrl>http://RAMA.com</SandboxUrl>
111
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
</CheckoutBrand>
<MerchantAcquirer>
<ID>523078</ID>
<Name>CartaSI</Name>
<AssignedMerchantID>001</AssignedMerchantID>
<DSStatus>Not Submitted</DSStatus>
</MerchantAcquirer>
</MerchantResponseRecord>
</MerchantDownload>
Single-Merchant API Validation Service
The Single-Merchant API Validation Service is used by service providers to validate upload merchant prior
to actual onboarding submission via Open Feed Project. This process mimics the validation xml process via
the user interface used within the merchant portal. See the Merchant Upload Schema Details section for the
Merchant Upload Validate schema, the Merchant Upload Validate Response Schema Details section for the
Merchant Upload Validate Response schema, and the Validation Error Messages section of the appendix for
details of the validation error messages.
Single-Merchant API Validation Parameters
Upload
oauth_signature
X
oauth_version
X
oauth_nonce
X
oauth_signature_method
X
oauth_consumer_key
X
oauth_timestamp
X
oauth_body_hash
X
Merchant Upload XML
Validated Merchant Response
XML
X
Response
X
Single-Merchant API Validation Parameter Details
MerchantUpload—Request
Signature Base String
Authorization Header
Description
Possible
Values
oauth_signature
RSA/SHA1 signature generated from the
signature base string
Variable
oauth_version
Oauth version
1.0
oauth_nonce
Unique alphanumeric string generated
from code
Variable
oauth_signature_method
oauth signature method
RSASHA1
112
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
Merchant Upload XML
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
MerchantUpload
Uploaded Merchant Information (XML)
ValidatedMerchant—Response
Validated Merchant
ValidatedMerchant
Description
Possible
Values
Results of the merchant validation
HTTP Request Example
POST /masterpasspsp/v6/checkoutproject/[0-9]+/file/validation
Authorization: OAuth
oauth_signature="eWr32NfsnxEN%2FUiNX3ntaRvJPWKV6p0sqcy%2F5EiEgSCQYm3%2Bm8MPPvr0
5EdoRwDsm%2Fu7iqg8BA5P40WHdq0TsOX8k6NbFjZwWXZuLv%2BkqRS6oFBJH0sL4ajdE%2BcevuJiR
M6wSZ1LLwCwniUE%2Fm81r%2F43KWQPIw7KGgUYDndz5T4%3D",oauth_body_hash="CWrePW5A%2B
KMde7DxI5mBpNVr%2Fok%3D",oauth_version="1.0",oauth_nonce="17157164231493",oauth
_signature_method="RSASHA1",oauth_consumer_key="ewdIBgRu1i6uCoFjuWGU4BNGDb0Udvh26N_mYah68efd62f9%2141
496b7a452f35764d715752755579436b70467871476f3d",oauth_timestamp="1432749165"
Signature Base String Example
POST&https%3A%2F%2Fapi.mastercard.com%2Fitf%2Fmasterpasspsp%2Fv6%2Fcheckoutproj
ect%2F285415568%2Ffile%2Fvalidation&oauth_body_hash%3DCWrePW5A%252BKMde7DxI5mBp
NVr%252Fok%253D%26oauth_consumer_key%3DewdIBgRu1i6uCoFjuWGU4BNGDb0Udvh26N_mYah6
8efd62f9%252141496b7a452f35764d715752755579436b70467871476f3d%26oauth_nonce%3D1
7157164231493%26oauth_signature_method%3DRSASHA1%26oauth_timestamp%3D1432749165%26oauth_version%3D1.0
Merchant Upload Validation Request Sample
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<MerchantUpload>
<Merchant>
<SPMerchantId>STGQA09</SPMerchantId>
<Action>C</Action>
<CheckoutBrand>
<Name>STGQA09</Name>
<DisplayName>STGQA09</DisplayName>
<ProductionUrl>https://STGQA09.com</ProductionUrl>
<SandboxUrl>https://STGQA09.com</SandboxUrl>
<LogoUrl>http://www.mastercard.us/_globalAssets/img/nav/navl_logo_mastercardcom.png</LogoUrl>
</CheckoutBrand>
113
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
</Merchant>
</MerchantUpload>
Merchant Upload Validation Response Sample
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ValidateFileResponse>
<ValidatedMerchant>
<MerchantId>STGQA09</MerchantId>
<ErrorText>VBMU0140: merchantId already exists for serviceProviderId=285415466
and spMerchantId=STGQA09</ErrorText>
</ValidatedMerchant>
</ValidateFileResponse>
3DS Status
Service Providers can include Advanced Authentication information as an XML element during the File- and
API-Based Merchant Onboarding processes. This is done using the <MerchantAcquirer> element as
detailed starting on Page 75.
MasterCard uses a Third Party, Cardinal Commerce, to act as a Merchant Plug In (MPI) for the 3DS step-up
process. When used, 3DS will run for all checkout transactions for the appropriate card brand. Where
available, 3DS may be opted into for MasterCard, Maestro, and Visa only.
Once the File- or API-Based Merchant Onboarding process has been completed for a merchant, the Service
Provider can check on the 3DS status of the uploaded merchant.
The possible 3DS statuses are as follows:
•
•
•
•
NOTSUBMITTED: Merchant’s acquirer information has not been submitted to Cardinal Commerce
SUBMITTED: Merchant’s acquirer information has been submitted to Cardinal Commerce
ACTIVE: The Merchant has been successfully registered in the Cardinal Commerce system, and
the acquirer is participating. You are ready to process 3DS production transactions
ACQUIRERNOTPARTICIPATING: The acquirer ID (BIN) used in the merchant registration is not
valid. Upon receiving this message, contact the implementation manager assigned to work with
you on this implementation. If you don’t have an assigned implementation manager, send an
email—with the information listed in the Support section—to
[email protected].
An uploaded Merchant 3DS status can be checked in one of two ways:
114
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
1)
The Service Provider developer can click on the “Download Result File” button located with the
Checkout Project used to upload the Merchant.
The result file will show the current status of each Acquirer for the Merchant that was uploaded:
2)
The Service Provider developer can use the “Search” button found at the top of the Checkout
Project page:
When the Search Bar pops up, enter the SPMerchantID of the uploaded merchant:
115
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
The Search output will display the current 3DS status for the Merchant:
Developer Zone Key Renewal Process
Login to MasterCard’s Developer Zone (https://developer.mastercard.com), click My Account, then My
Dashboard.
116
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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.
117
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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.
118
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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.
119
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
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
™
1. Consumer shops online at merchant website and selects the MasterPass Checkout Button to pay.
2. The consumer logs into their wallet to access payment and shipping information.
3. The consumer selects their MasterCard, Maestro or Visa Card for a payment.
™
4. Based on the payment information provided, the MasterPass system receives a cmpi_lookup message
in order to check the card participation in the applicable card issuer’s payer authentication.
5. 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.
6. 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
™
a) 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.
6. 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.
b) Consumer enters issuer challenge
c) Consumer is asked to Activate their card for 3-D Secure
d) 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.
7. The issuing bank encrypts the results of authentication between the consumer and their issuing bank
and returns this value to MasterPass.
8. MasterCard will receive a response indicating the result of authentication between the consumer and
their Issuing Bank. Below are the scenarios that can occur.
a) Consumer Fully Authenticates
b) Consumer Attempted Authentication (Prompted for Activation During Shopping and did Not Activate
their Card)
c) Failed Authentication
d) Issuing bank Unavailable
e) Attempts/Risk Based Authentication
9. 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.
120
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
10. The authentication data sent back will be:
a) 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
b) Authentication Method Used - Value should be created by Wallet for merchant to receive (Initial
possible values: "merchant only"; "3DS")
c) Card Enrollment status - Value should be created by Wallet for merchant to receive (Initial possible
values: "manual" ; "directly provisioned"; "3DS manual")
d) ECI (electronic commerce indicator) Flag
e) Pa Res Status
f) Secure Code Enrollment Status
g) Signature Verification
h) SLI (SecureCode Level Indicator)
11. 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.
Validation Error Messages
The following table contains the error messages resulting from business validations. if there are any schema
errors in the file, they must be resolved first before the file can be validated for business rules.
Error Codes
Description
Sample Error Message
VBMU0100
Validate that a provided checkout brand data
element exists.
VBMU0100: minimum of one checkoutBrand
required : merchant-spMerchantId=STGQA09
VBMU0101
Validate that a merchant with action code “C” does
not include any brandings with checkout
identifiers.
VBMU0101: checkoutBrand cannot include
checkout identifiers on create :
checkoutId=a4a6w4vnkdeazi6c6ynxk1i6cdd6e2aki
VBMU0102
Validate that a provided checkout identifier exists
when using Action Code “U” within CheckoutBrand
VBMU0102: checkoutBrand does not exist :
121
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
data element.
checkoutId=a4d6x344fquvhi8ix0v6n1i8udwvar1zv6
VBMU0110
For Merchant Action Code “U” and Merchant
Acquirer Action Code “C," validate the merchant
acquirer doesn’t exist in Cardinal Commerce.
VBMU0110: invalid merchant acquirer actionCode
during create : actionCode=U
VBMU0111
For Merchant Action Code “U” and Merchant
Acquirer Action Codes “U” or “D," validate the
merchant acquirer does exist in Cardinal
Commerce.
VBMU0111: invalid merchant acquirer action code:
U or D
VBMU0112
Validate Profile data element exists in the
MerchantUpload XML file.
VBMU0112: merchant create requires profile for
spMerchantId=STGQA09
VBMU0120
Validate Reward Program Name is Unique.
VBMU0120: reward program name must be
unique: RAMAQA312, spMerchantId=STGQA09
VBMU0121
Validate Reward Program ID is Unique.
VBMU0121: reward program id must be unique:
RAMAQA312, spMerchantId=STGQA09
VBMU0130
Validate a Merchant Acquirer is provisioned in
Cardinal for a specified CardBrand.
VBMU0130: no merchant acquirer for cardbrand
type=MAESTRO
VBMU0140
Validate SPMerchantID is Unique when applying
Merchant Action Code of “C.”
VBMU0140: merchantId already exists for
serviceProviderId=305960760 and
spMerchantId=STGQA03
VBMU0141
Validate Merchant Acquirer ID is unique when
applying Merchant Action Code of “C.”
VBMU0141: invalid merchant acquirer
actionCode=C : acquirer record already exists :
acquirerId=523078 assignedMerchantId=001test
cardBrand=MASTER_CARD currencyCode=EUR
VBMU0142
Validate Merchant Acquirer ID exists in Cardinal
Commerce.
VBMU0142: acquirer id does not exist :
id=88848888, cardBrand=MASTER_CARD
VBMU0150
Validate SPMerchantID exists for Merchant Action
Codes "U" or "D".
VBMU0150: merchant not found for update or
delete
VBMU0160
Validate the SPMerchantID is alphanumeric and
less than 25 characters.
VBMU0160: invalid
assignedMerchantId=STGAPI21_******5681M,
must be alpha-numeric and less than 25
characters in length
VBMU0170
Validate the Merchant Acquirer CurrencyCode is
supported by Cardinal Commerce.
VBMU0170: unsupported currency code : USD
VBMU0171
Validate two merchant acquirers of the same
CardBrand are not configured to support the same
currency by Cardinal Commerce.
VBMU0171: acquirer card brand currency code
pairing must be unique
Validation Error Message Sample
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<ValidateFileResponse>
<ValidatedMerchant>
<MerchantId>584RAMAKOTI07</MerchantId>
122
™
MasterPass Service Provider Onboarding & Integration Guide—
File- and API-Based Merchant Onboarding
<ErrorText>VBMU0140: merchantId already exists for serviceProviderId=5 and
spMerchantId=584RAMAKOTI07</ErrorText>
</ValidatedMerchant>
</ValidateFileResponse>
© 2014–2015 MasterCard. Proprietary and Confidential. All rights reserved.
123