d e
A MasterCard Customer Implementation Services
2d
Quick Reference Guide
MasterPass Merchant Checkout ServicesImplementation Quick Reference Guide
©2015 MasterCard. Proprietary and Confidential. All rights reserved
September 2015
MasterPass
Merchant Checkout Services
Implementation Quick Reference Guide
Merchant.com
Computers
I
Electronics
I
Books
I
Sign in
Movies
I
Music
I
Video Games
I
Toys & Baby
I
Your cart
Order Summary
An Item
Random Item description.
Shopping Cart
I
Contact
Home & Household
I
I
More...
Order
Shipping
Quantity
Price
Standard
1
24.65 €
Price
Items
Shipping
Tax
Total
24.65 €
4.25 €
0.00 €
28.90 €
Proceed to checkout
Proceed to checkout
Or Checkout With:
Or Checkout With:
Learn More
Learn More
MasterPass Merchant Checkout Services / How to read this document
How to read this guide
This page gives you a brief description of the different sections you will find in this document.
vv who needs it?
?
Explains who the topic applies to.
mm prerequisites
Lists the processes or actions that must be
completed before you start a specific process.
ee also known as
Lists the alternative names that are used for
certain terms.
jj good to know
what is it?
Gives a high-level overview of the service, prerequisites or process.
AKA
the process
Describes the tasks to follow to complete each process.
nonMasterCard
task
White circles indicate a task that must be performed by the merchant, service
provider and/or developer.
MasterCard
task
Orange circles indicate a task that must be performed by MasterCard.
Provides additional background information to
help you better understand the topic.
ll want to know more?
Provides links to MasterCard manuals and forms
that contain more detailed information.
2
MasterPass Merchant Checkout Services / Contents
contents
Welcome to MasterPass Merchant Checkout Services
AKA
What is MasterPass? 5
MasterPass in Action
6
MasterPass Benefits
8
MasterPass Wallets
9
MasterPass Merchant Checkout Services
10
MasterPass Development Landscape
11
Standard Checkout—Under the Covers
14
Implementing MasterPass Merchant Checkout Services
Implementation Roles and Approaches 16
1. Project Initiation 17
2. Merchant/Service Provider Registration
18
3. Developer Generates Keys 20
4. Development and Local Testing
22
5. Approval and Sandbox Testing
23
6. “Buy with MasterPass” Deployment 25
Support, Documentation and Resources, Feedback
26
3
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services
Welcome to MasterPass
Merchant Checkout Services
mm prerequisites
This guide provides a broad introduction to MasterPass™ as well as details of how to implement MasterPass™
Merchant Checkout Services (the “Buy with MasterPass” functionality) on a merchant’s checkout site or mobile
app.
Merchants wanting to implement MasterPass
Merchant Checkout Services on their site must
satisfy the following requirements:
The primary intended audience of this guide is merchants, service providers, and their developer(s). However, it
will be of interest to anyone wanting to learn more about MasterPass.
bb
accept MasterCard-branded cards
bb
be in good standing with their acquirer
bb
be able to accept online purchases via the Internet,
.mobi (domain name for mobile devices accessing
the Internet), or a mobile app
Introduction to MasterPass
bb
adhere to MasterPass Online Merchant Acceptable
Use Policy
• We explain what MasterPass is and provide an example of a “Buy with MasterPass” transaction.
bb
demonstrate PCI compliance if integrating
MasterPass directly (not using a service provider)
This guide is split into two sections:
This section covers the following:
• We highlight the key benefits of MasterPass—for merchants, consumers, and issuers.
• We introduce the components of MasterPass—the Wallets and the Merchant Checkout Services.
• Finally, we provide a high-level overview of the environments used during development.
AKA
Implementing MasterPass Merchant Checkout Services on your website
We describe the activities required to implement MasterPass Merchant Checkout Services, as well
as best practices and tips to help ensure a smooth integration.
4
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / What is MasterPass?
PreCheckout
Data
vv who needs it?
bb
Proceed to checkout
Merchants and service providers
Or Checkout With:
implementing MasterPass
Merchant Checkout (“Buy with MasterPass”)
Learn More
Learn More
on the merchant’s website
or mobile app.
?
What is MasterPass?
MasterPass™ is MasterCard’s integrated digital wallet and checkout solution.
MasterPass enables consumers to store and manage their payment, shipping, and loyalty program information
in their MasterPass Wallet, and to quickly and seamlessly access this information to make secure payments
wherever they see the “Buy with MasterPass” button on a merchant website or mobile app.
ee also known as
bb
MasterPass Merchant Checkout Services comprise
the services behind the “Buy with MasterPass” button.
bb
Service providers are also known as “payment service
providers” or “third party platform providers.”
1
rch
Sea
2
p
Sho
3
t
ckou
Che
jj good to know
cc
Merchants that are not PCI compliant (meeting
guidelines for securing card details) must use a PCI
compliant service provider.
cc
A service provider in this context is a company
that helps merchants accept payments on their website or mobile app.
ll want to know more?
cc
For general information on the MasterPass product,
visit the MasterPass site.
cc
For implementation, consult the Onboarding and
Integration Guides at MasterCard Developer Zone >
Services > MasterPass - Merchant Checkout Services
> Documentation.
cc
For development, go to MasterCard Developer
Zone > Services > MasterPass - Merchant Checkout
Services > Sample Code.
4
t
en
Paym
Type
5
t
en
Paymils
Deta
7 g
8
ping
Shipmation Billinmation Sale pleted
Infor
Infor
Com
6
s
step
y
n
a
too m
y
ed b
c
a
l
rep
1
h
rc
Sea
2
p
Sho
3
t
ckou
Che
5
Sale pleted
Com
From a cardholder’s perspective, MasterPass significantly speeds up the checkout process, removing the need
to re-enter payment, shipping or loyalty program details during checkout.
The MasterPass solution is simple, secure and easy for merchants to integrate into their existing website or app.
5
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / MasterPass in Action
MasterPass in Action
jj good to know
cc
The graphic on the right represents a “Standard
Checkout” transaction.
cc
Connected Checkout and Express Checkout are
also available and are described on the next page.
cc
cc
1 1
The “Lightbox” MasterPass Wallet user interface
“floats” on top of the merchant’s web page so
that the consumer feels that they are still in the
merchant’s checkout space.
Adding MasterPass Merchant Checkout Services
(“Buy with MasterPass”) to your site does not
impact the established processes you have with
your acquirer or payment gateway provider.
Merchant
.com
Computers
I
Electronics
I
Books
I
Sign in
Movies
I
Music
I
Video Games
I
Toys & Baby
I
Shopping Cart
I
Contact
Home & Household
I
I
More...
Your cart
Order
Order Summary
An Item
Random Item description.
Shipping
Quantity
Price
Standard
1
24.65 €
Price
Items
Shipping
Tax
24.65 €
4.25 €
0.00 €
Total
28.90 €
Proceed to checkout
Or Checkout With:
Proceed to checkout
Or Checkout With:
Learn More
2
ll want to know more?
dd
Customer clicks “Buy with MasterPass” button on the
merchant’s checkout page.
The MasterPass window (“Lightbox”) appears on top
of the merchant’s site or app.
Customer enters their MasterPass Wallet login
information.
Merchant
.com
Computers
I
Electronics
I
Books
I
Sign in
Movies
I
Music
I
Video Games
I
Toys & Baby
I
Shopping Cart
I
Contact
Home & Household
I
I
More...
johntest@testmail.com
Your cart
Learn More
Order
Order Summary
An Item
Random Item description.
Shipping
Quantity
Price
Standard
1
24.65 €
Price
MasterPass Onboarding and Integration Guides
Items
Shipping
Tax
24.65 €
4.25 €
0.00 €
Total
28.90 €
Proceed to checkout
• Overview
• MasterPass Checkout Experiences
Or Checkout With:
Learn More
3
Customer selects their preferred payment card,
shipping, and rewards information from their
MasterPass Wallet.
Merchant
.com
Computers
I
Electronics
I
Books
Sign in
Pay with
I Movies
I
Music
I
Ship to
Video Games I Toys & Baby
John’s Main Card
**** **** **** 1234
06/2019
Your cart
Order Summary
An Item
Random Item description.
I
Shopping Cart
I
Contact
Rewards
Home & Household I More...
I
John Test
Chaussée de Tervuren 198A
1410 Waterloo
Belgium
Any Merchant
Rewards
**** **** **** 5678
Order
Shipping
Quantity
Price
Standard
1
24.65 €
Price
Items
Shipping
Tax
24.65 €
4.25 €
0.00 €
Total
28.90 €
Proceed to checkout
Or Checkout With:
Learn More
4
The MasterPass window closes and the customer is
returned to the merchant site to complete their order.
Merchant
.com
Computers
I
Electronics
I
Shipping
Shipping To
John Test
Chaussée de Tervuren, 198A
1410 Waterloo
Belgium
Books
I
Sign in
Movies
I
Music
I
Video Games
I
Toys & Baby
I
Payment Info
Payment Method
johntest@testmail.com
**** **** **** 1234
Exp: 06/19
Shopping Cart
I
Contact
Home & Household
I
I
More...
Summary
Billing Adress
Price
John Test
Chaussée de Tervuren, 198A
1410 Waterloo
Belgium
Items
Shipping
Tax
24.65 €
4.25 €
0.00 €
Total
28.90 €
Place your order
6
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / MasterPass in Action
3 4
jj good to know
cc
The process described on the previous page is referred to as the “Standard” Checkout. MasterPass also allows
consumers to “pair” their MasterPass Wallet with participating merchants for speedier future checkouts, using
the Connected Checkout and Express Checkout options described below.
The Connected Checkout and Express Checkout
types are only available for merchants using the
Direct Merchant or Merchant by Merchant integration
approaches described later in this guide.
Pairing can be done either during checkout or outside of checkout separately, on the merchant’s site using the
“Connect with MasterPass” button. Consumers can easily unpair at any time by logging into their wallet account.
ll want to know more?
cc
cc
Pairing and Pre-checkout data
Merchant.com
Computers
For Connected Checkout, consult the Onboarding
and Integration Guides at MasterCard Developer
Zone > Services > MasterPass - Merchant Checkout
Services > Documentation.
I
Electronics
I
Books
I
Sign in
Movies
I
Music
I
Video Games
I
Toys & Baby
I
Billing info
Please select the card you want to use:
To obtain MasterPass Express Checkout guides,
contact a regional MasterCard representative.
-
I
Shopping Cart
I
Contact
Home & Household
I
More...
Order
Add New Card
MasterCard **** **** **** 1234
Maestro **** **** **** 5678
American Express **** **** **** 1112
Visa **** **** **** 1314
Price
Items
Shipping
Tax
24.65 €
4.25 €
0.00 €
Total
28.90 €
Shipping address
integration level
consumer’s
merchants can
payment details
display
stored in
consumer’s wallet
MasterPass wallet
details
Please select a shipping address:
merchant login
only MasterPass login
not required
John Test - Chaussée de Tervuren 198A, 1410 Waterloo, Belgium
John Test - Avenue du Panorama 600, 1000 Brussels, Belgium
a
Standard Checkout
b
Connected Checkout
c
Express Checkout
Add New Shipping Address
Learn More
As shown here, after pairing
merchants can obtain the
consumer’s wallet data
(shipping, rewards, and
payment details [last 4 digits of
the Primary Account Number])
and display it on their site
without the consumer logging in
to MasterPass.
Once the user has paired their
wallet, behind the scenes the
merchant receives a Long
Access token which they use
on subsequent consumer
checkouts to obtain ‘precheckout’ data from MasterPass.
When the consumer clicks “Buy with MasterPass,” the MasterPass Lightbox is invoked where they can login and
select payment, shipping, and rewards details. No information is shared with the merchant prior to this point.
This option allows merchants to access pre-checkout data (shipping, rewards, and payment details [last 4 digits
of the Primary Account Number]) from the consumer’s paired MasterPass wallet, and present it to consumers
from within their merchant site or app. At this point only the last 4 digits of the consumer’s card number are
passed to the merchant.
This is the fastest checkout experience, available to merchants that have previously passed a MasterPass
vetting process.
From the consumer’s perspective, it works like Connected Checkout, except they will not need to sign into
MasterPass; their merchant login is all that is required for their full details to be released to the merchant.
7
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / MasterPass Benefits
jj good to know
cc
One of the challenges faced by merchants is
shopping cart abandonment. 38% of online
customers abandon their transaction due to
complicated registrations and logins.
MasterPass Benefits
The MasterPass service was created to support the many different ways that consumers shop. MasterPass offers
one simple checkout platform that can be used anytime, on any device.
“The Connecting with Customers Report: A Global
In-depth Study of the Online Customer Experience,”
LivePerson, January 2013
cc
Checkout environments that offer simple, safe,
and seamless experiences can help to reduce cart
abandonment.
cc
65% of online retailers reported increased retention
rates due in part to improved, consumer-friendly
checkout procedures.
“The State of Retailing Online 2011,” Forrester
Research, September 2011
cc
A unique feature of MasterPass Merchant Checkout
is that by clicking on the shopping cart icon in the
MasterPass “Lightbox” screen, consumers can
quickly view their shopping cart contents.
merchants
ll want to know more?
tt
MasterPass website
consumers
issuers
flexibility
ease of use
accessibility
simple integration of
MasterPass with your
websites and mobile apps
simple checkout experience
reduces cart abandoment
and boosts sales
access to millions of
consumers through the
MasterPass Acceptance
Network
supports credit, debit,
and prepaid cards from all
major brands
card details need only be
entered once, during initial
signup for MasterPass
shopping anywhere,
anytime, on any device
issuers can build their
own branded MasterPass
wallets
consumers benefit from the
security and simplicity of
the MasterPass solution
“Buy with MasterPass”
button globally recognized
8
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / MasterPass Wallets
MasterPass Wallets
jj good to know
cc
wallet
hosted
customization level
hosted
This guide focuses on the process for merchants to implement MasterPass Merchant Checkout. However, it is
important to also understand the MasterPass Wallet that consumers will use.
There are three types of MasterPass Wallets, either offered directly by MasterCard or by MasterCard’s partners.
branding
Regardless of who is hosting the wallet, all integrate consistently and seamlessly with MasterPass Merchant
Checkout and offer consumers the same levels of service, security, and simplicity.
a
MasterPass™ by MasterCard® Wallet
b
MasterCard®-hosted MasterPass™ Wallet
A wallet designed, built, powered by, and available directly from MasterCard.
A wallet solution owned and branded by a MasterCard partner but hosted by MasterCard. This differs from the
MasterPass by MasterCard Wallet in that:
• Some partner branding is allowed.
• Customer support may also be managed by the partner.
• There are several ways the cardholder accounts can be loaded into the wallet.
• May require that the consumer is a client of the wallet issuer.
c
+
wallet
support
-
hosting
wallet
The MasterPass solution has two distinct components: the MasterPass Wallet, where consumers store their
payment, shipping and rewards details, and the MasterPass Merchant Checkout (“Buy with MasterPass”)
which merchants implement onto their websites and mobile apps to allow consumers to access their wallets.
Certain wallet types may not be available in
your location. Contact a regional MasterCard
representative for more information.
Partner-hosted MasterPass™ Wallet
A wallet solution that is completely hosted and maintained by the partner. The partner will leverage MasterPass
APIs to craft a fully-customized wallet.
Note: The focus of this guide is on the MasterPass Merchant Checkout. It does not address how issuer partners can set up
their own MasterPass Wallet. If you would like more information, contact a regional MasterCard representative.
ll want to know more?
tt
MasterCard Developer Zone > Services >
MasterPass - Partner Wallet > Overview
9
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / MasterPass Merchant Checkout Services
MasterPass Merchant Checkout
Services
ll want to know more?
There is one guide on the MasterCard Developer
Zone for each of the integration approaches:
dd
DM: MasterPass™—Merchant Onboarding and
Integration Guide
dd
MM: MasterPass™—Service Provider Onboarding
and Integration Guide—Merchant by Merchant
dd
FA: MasterPass™—Service Provider Onboarding and
Integration Guide—File- and API-Based Merchant
Onboarding
approval
From a consumer’s perspective, the “Buy with MasterPass” experience is the same regardless of the merchant’s
implementation approach. However, from the merchant’s perspective, there are three different implementation
approaches; all three are covered by this guide.
a
Merchant
Merchant
Service
Provider
FA
Service
Provider
ee also known as
Merchants work directly with MasterCard to implement the MasterPass Merchant Checkout solution onto their
website or mobile app. The merchant manages all development and interaction with MasterCard.
Merchants that are not PCI compliant (meeting guidelines for securing payment card information) cannot use the
Direct Merchant approach; they must use a PCI compliant service provider to manage their development.
b
Merchant
MM—Merchant by Merchant Onboarding
Merchants are responsible for managing their MasterPass merchant account, providing details such as
shipping profile(s), and approving the developer’s checkout project.
However, they will use a service provider to handle most of the development and integration tasks with
MasterCard. This option is suitable for merchants who do not utilize in-house or contracted development staff but
want to retain ultimate control of their checkout solution.
+
MM
delegation level
DM
DM—Direct Merchant Onboarding
Merchants that integrate MasterPass Merchant Checkout independently are referred to as Direct Merchants.
-
development
The MasterPass Merchant Checkout Services allow merchants to add the “Buy with MasterPass” button to their
website or mobile app so that consumers can connect to their MasterPass Wallet and gather the payment,
shipping, and loyalty program details needed to complete their purchase online.
Service
Provider
• File-based or API-based Merchant Onboarding
was previously known as “Bulk Merchant Upload.”
c
FA—File-based or API-based Merchant Onboarding
Service providers handle all integration activities on-behalf of one or several merchants.
In this method, merchants are not involved at all. Instead, the service provider manages all elements of the
implementation and provides merchant details to MasterPass directly via either a file upload (file-based) or the
API interface (API-based).
All of these approaches are described in more detail in the Implementing MasterPass Merchant Checkout
Services section of this guide.
10
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / MasterPass Development Landscape
jj good to know
cc
The MasterPass Merchant and Service Provider
Portal is where:
• Merchants and service providers register and
set up profiles identifying them to MasterPass.
• Merchants and service providers “invite” their
developers to create their own profiles.
• Developers request and access merchant
credentials to include in their XML code.
cc
Before you can access the MasterPass Merchant
and Service Provider Portal, you will need an
invitation code from MasterCard. Full details on
how to do this can be found in the implementation
section of this guide.
cc
On the MasterCard Developer Zone, developers:
• View documentation for integration (including
FAQs and other resources)
• Download software development kits (SDKs) and
sample code templates
• Generate API Key IDs to use in the Sandbox
(test) and Production environments
ll want to know more?
tt
Merchant and Service Provider Portal—Support
FAQs
tt
MasterPass - Merchant Checkout Services
• Documentation
• Discussions (developer login needed)
• FAQs
• Sample Code
• Resources
MasterPass Development Landscape
MasterCard provides various portals, toolkits, and environments to facilitate Merchant Checkout deployment.
MasterPass Merchant and Service Provider Portal
The MasterPass Merchant and Service Provider Portal is used to
create two types of MasterPass Merchant Checkout accounts:
• Merchant/Service Provider Account—Defines each merchant
and service provider that will work with MasterPass. For the
Merchant by Merchant onboarding approach, the merchant
and its service provider must both create an account.
• Developer Account—Defines each developer that will work
with MasterPass. Merchants or service providers create these
accounts for each developer who will be working with them.
Developers will use their account to submit checkout projects
for approval, and to receive checkout project credentials upon
approval.
Note: This is not the same as the developer account used for the Developer Zone (see below); the two are currently not linked.
MasterCard Developer Zone
As described in more detail in the implementation section of
this guide, developers also need to create an account in the
Developer Zone.
The MasterCard Developer Zone contains support for all
MasterCard e-commerce APIs (not just MasterPass).
Within this Developer Zone is a dedicated product area for
MasterPass - Merchant Checkout Services that contains all
the information developers will need to implement MasterPass
Merchant Checkout, including guides, FAQs, discussions, and
sample code (including Software Developer Kits).
Developers also use their Developer Zone account to generate
API Key IDs for use in the MasterPass Sandbox (test) and
production environments, as described further on in this guide.
11
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / MasterPass Development Landscape
jj good to know
cc
Developers do not need to have a formal
relationship with MasterCard to start building
solutions that take advantage of the Software
Development Kits (SDKs).
ll want to know more?
cc
MasterCard - Merchant Checkout Services
MasterCard APIs and SDKs
An Application Programming Interface (API) is a set of commands (routines and protocols) that one
application (MasterPass, in this example) makes available so that other applications (those of merchants and
service providers in this example) can interface with it.
MasterCard APIs are Open APIs, meaning that anybody can access them to build solutions that take advantage
of the services offered by MasterCard. The MasterPass Merchant Checkout APIs are among several APIs offered
by MasterCard.
A software development kit (SDK) is a set of coding tools that aid creation of applications for a specific
software package, and is usually code-specific. MasterCard provides a MasterPass Merchant Checkout SDK in
several language options (Java, C# .Net, PHP, and Ruby). Contact a regional MasterCard representative if your
desired programming language is not listed.
MasterPass Open API Environments
In addition to your own local environment, MasterCard has two Open API environments—the testing (Sandbox)
environment and the live (Production) environment:
<html>
<head>
<meta http-eq
Local
Developers begin coding in
their own environment;
no need for formal merchant or
service provider involvement.
</body>
</html>
Sandbox (Test)
A production-like
MasterPass environment;
facilitates testing using
actual merchant credentials.
Production
The live MasterPass production
environlment; allows merchant
site or mobile app to access live
MasterPass Wallets.
12
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / MasterPass Development Landscape
jj good to know
cc
The MasterPass Merchant Checkout APIs allow developers to add Merchant Checkout “Buy with MasterPass”
functionality to the site or app. Depending on the checkout type, different services/activities will apply.
By integration completion, the merchant site or mobile
app should be able to:
Services and activities supporting Merchant Checkout types
• Display the “Connect with MasterPass” button (for
merchants pairing outside of Checkout).
►
• Display the “Buy with MasterPass” button and the
“Learn More” link at the start of the checkout.
• Invoke and display the MasterPass Lightbox.
• Relay checkout requests to the MasterPass
service.
• Get pre-checkout data for consumers that have
consented to pair their wallets (for merchants
implementing Connected Checkout).
• Receive consumer’s billing, shipping address, and
loyalty program data from the MasterPass service.
cc
MasterPass Merchant Checkout APIs
Developers are strongly encouraged to perform the
following activities:
• Read the Onboarding and Integration Guide
corresponding to your type of integration.
• Ensure that you can successfully execute the
sample application before coding.
• Familiarize yourself with the “Q/A Checklist” found
in the integration guides.
ll want to know more?
There are three types of Merchant Checkout experiences: Standard, Connected, and Express (all described in
Pairing and Pre-checkout data). All of these will require calls made to the following services:
Request Token Service
Shopping Cart Service
► Access Token Service
► Checkout Resource Service
► Postback (Transaction) Service
►
In addition, along with coding the URL to invoke the “Buy with MasterPass” button, merchants are also required
to provide a link to a “Learn More” page. This page provides more information to consumers about MasterPass.
Services and activities supporting Pairing function
To manage the wallet pairing service (available during Connected Checkout and Express Checkout), coding will
need to address the following:
• Pairing performed by the consumer during checkout requires an additional API.
• Pairing performed by the consumer outside checkout requires calling the Merchant Initialization Service, as
well as additional JavaScript and a URL to implement the “Connect with MasterPass” button and experience.
Return Checkout after pairing
Once the user has paired, on their subsequent
checkout, the merchant can invoke the return checkout
flow (including obtaining the pre-checkout data).
dd
MasterPass Onboarding and Integration Guides
XML code
tt
MasterPass - Merchant Checkout Services tabs for:
• Resources
• Sample Code
• Documentation
Most of the sample code in the SDK can be reused.
Minor customizations are all that will be needed,
including incorporating developer- and merchantspecific credentials (merchant branding and
information from keys).
• Integration Process—Service Descriptions
• MasterPass Branding
• Testing—Q/A Checklist
On the left is a sample of the API XML code for the
Shopping Cart Service Request.
Full details of how to format the code can be found
in the Resource tab in the MasterPass - Merchant
Checkout Services section on the Developer Zone.
13
MasterPass Merchant Checkout Services / Welcome to MasterPass Merchant Checkout Services / Standard Checkout—Under the Covers
Co
ns
um
er
Me
r
c
Se ha
n
r
Provice t /
vid
Ma er
ste
rPa
s
s
Standard Checkout—Under the Covers
Merchant.com
Computers
I
Electronics
I
Books
I
Sign in
Movies
I
Music
I
Video Games
I
Toys & Baby
I
Shopping Cart
I
Contact
Home & Household
I
I
More...
Your cart
proceeds to checkout, clicks
“Buy with MasterPass”
1
Order
Order Summary
An Item
Random Item description.
Shipping
Quantity
Price
Standard
1
24.65 €
Price
Items
Shipping
Tax
24.65 €
4.25 €
0.00 €
Total
28.90 €
Proceed to checkout
2
readies credentials for API calls
3
sends Request Token Service call for MasterPass system
access
Or Checkout With:
4
Learn More
Merchant.com
Computers
I
Electronics
I
Books
I
Sign in
Movies
I
Your cart
Music
I
Video Games
I
Toys & Baby
I
I
Shopping Cart
I
Contact
Home & Household
I
More...
Order
johntest@testmail.com
Order Summary
Shipping
An Item
Random Item description.
Quantity
Standard
1
Price
24.65 €
24.65 €
4.25 €
0.00 €
Total
28.90 €
Proceed to checkout
Or Checkout With:
Learn More
Merchant.com
Computers
I
Pay with
Electronics
I Books
Your cart
I
Sign in
Movies
I
John’s Main Card
**** **** **** 1234
06/2019
Ship
to
Music
I
Video Games
I
John Test
Chaussée de Tervuren 198A
1410 Waterloo
Belgium
Order Summary
Shipping
An Item
Random Item description.
Rewards
Toys & Baby
I
Shopping Cart
I
Contact
Home & Household
I
I
More...
Any Merchant
Rewards
**** **** **** 5678
Quantity
Standard
1
5
sends Shopping Cart Service call to retrieve cart data
6
invokes MasterPass Lightbox UI for consumer display
Price
Items
Shipping
Tax
signs in to MasterPass,
selects card, shipping
and loyalty preferences
displays the following to consumer: sign-in/card,
shipping, loyalty options/order for review
9
Lightbox returns Checkout URL, request token,
verifier to merchant site
sends Request Token call for MasterPass system access
10
11
Price
24.65 €
7
8
Order
Price
Items
Shipping
Tax
24.65 €
4.25 €
0.00 €
Total
28.90 €
13
Or Checkout With:
Learn More
14
Merchant.com
I
Electronics
I
Books
I
Sign in
Movies
I
Music
I
Shipping
Payment Info
Shipping To
Payment Method
John Test
Chaussée de Tervuren, 198A
1410 Waterloo
Belgium
johntest@testmail.com
**** **** **** 1234
Exp: 06/19
Video Games
I
Toys & Baby
I
Shopping Cart
I
Contact
Home & Household
I
I
More...
Summary
Billing Adress
Price
John Test
Chaussée de Tervuren, 198A
1410 Waterloo
Belgium
Items
Shipping
Tax
24.65 €
4.25 €
0.00 €
Total
28.90 €
Place your order
confirms purchase
sends return response with access approval
sends Access Token Service call to Checkout URL
to retrieve purchase data
12
Proceed to checkout
Computers
sends return response with access approval
returns Checkout Resource Service call to Merchant /
Service Provider to send card, shipping, loyalty info to merchant
calculates final price (inc. shipping/taxes)
15
16
sends transaction to acquirer, displays confirmation page
17
sends Postback Service call to MasterPass
to verify success/fail status of transaction
18
returns results to Merchant / Service Provider
► Request Token Service
called to get access to the token that
authorizes merchant or service provider
(user) for the MasterPass service.
Occurs when consumer clicks on
“Buy with MasterPass”.
► Shopping Cart Service
called during Standard Checkout and
pairing of wallet during checkout to
display shopping cart details in the
wallet to consumer.
Occurs before consumer’s actual
MasterPass login.
► Access Token Service
called to allow merchant or service
provider to retrieve checkout data
for the transaction.
Occurs after consumer has indicated
payment/shipping preferences in
MasterPass Wallet.
► Checkout Resource Service
called to retrieve consumer’s payment,
shipping address, reward and 3DS
information from MasterPass.
Occurs before consumer confirms
purchase.
► Postback(Transaction)
Service
called to send certain details of transaction to MasterPass so that success or
failure of transaction can be reported
back to merchant.
Occurs after transaction is submitted to
acquirer for processing.
14
AKA
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services
Implementing MasterPass Merchant Checkout Services
2
1
3
New
Project
Initiation
Merchant / Service Provider
Portal Registration
6
“Buy with MasterPass”
Deployment
<div 5
</div>
</body>
</html>
Approval
and Sandbox Testing
ADD A KEY
nt: Production
Sandbox
Developer
generates Keys
4
<html>
<head>
<meta h
<ti
Development
and Local Testing
15
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / Implementation Roles and Approaches
AKA
mm prerequisites
Implementation Roles and Approaches
?
Implementation roles
Merchants wanting to host MasterPass Merchant
Checkout on their site must satisfy the following
requirements:
bb
accept MasterCard-branded cards
bb
be in good standing with their acquirer
bb
be able to accept online purchases via the Internet,
.mobi (domain name for mobile devices accessing
the Internet), or a mobile app
bb
adhere to MasterPass Online Merchant Acceptable
Use Policy
bb
demonstrate PCI compliance if using the Direct
Merchant approach (not using a service provider)
ll want to know more?
There are three primary MasterPass Onboarding and
Integration Guides on the MasterCard Developer
Zone, one for each of the integration approaches:
dd
dd
dd
DM: MasterPass™—Merchant Onboarding
Integration Guide
MM: MasterPass™—Service Provider Onboarding
and Integration Guide—Merchant by Merchant
FA: MasterPass™—Service Provider Onboarding
and Integration Guide—File and API-Based
Merchant Onboarding
Three parties may potentially be involved in the MasterPass Merchant Checkout process:
PreCheckout
Data
PreCheckout
Data
Merchant: The owner of the website that will host the “Buy with MasterPass” button.
Service Provider: Third party provider of online payment solutions to merchants.
Developer: Individual that will work for either the service provider or merchant to develop a checkout solution.
Implementation approaches
There are three implementation approaches. Depending on the approach, different parties are involved:
DMMM
Direct Merchant Onboarding: Merchants work directly with MasterCard to implement the MasterPass
Merchant Checkout solution. No service provider involvement, only merchant and developers.
DMMM Merchant by Merchant Onboarding: Service providers handle most of the integration while merchants
manage their account and approve the requests made by the service provider’s developer(s). All three parties are involved.
MM FA
File-based or API-based Merchant Onboarding: Service providers handle all elements of the
implementation. There is no merchant involvement, only service provider and developers.
Who does a step apply to?
You will need to know which implementation approach (Direct Merchant - DM, Merchant by Merchant - MM, File or
API based - FA) you are using.
The legend below highlights if the step applies to your implementation approach and, if it does, which parties
(merchant, service provider, developer) are involved in that particular step.
Implementation approach:
Implementation role:
Direct
Merchant
Onboarding
Merchant
Merchant
by Merchant
Onboarding
Service Provider
File and API-based
Merchant
Onboarding
Developer
16
1
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 1. Project Initiation
initiate
MasterPass
project
jj good to know
cc
Here are some approximate timeframes you
should expect for a Standard Merchant Checkout
integration:
cc
Before integrating the MasterPass Merchant
Checkout onto your site, you should consider
questions such as:
?
1 1
You must satisfy the prerequisites listed on the previous page.
2
• Will you offer Connected or Express Checkout?
There are three primary MasterPass Onboarding
and Integration Guides on the MasterCard
Developer Zone, one for each of the integration
approaches:
dd
dd
dd
DM: MasterPass™—Merchant Onboarding
Integration Guide
MM: MasterPass™—Service Provider Onboarding
and Integration Guide—Merchant by Merchant
MasterCard sets up kick-off meeting (optional)
Depending on your situation, MasterCard may initiate a formal kick-off meeting to finalize details before you start
your MasterPass Merchant Checkout implementation.
After the meeting, your MasterCard Customer Implementation Services (CIS) Implementation Manager may
provide you with a MasterPass Implementation Plan and Checklist.
• Will you support Advanced Checkout (3D
Secure)?
ll want to know more?
Merchants and service providers can initiate a MasterPass project by either:
• Contacting a regional MasterCard representative.
• What card types (brands, region-specific,
payment types, loyalty) do you support?
• What is the process for making enhancements
to your checkout site?
Initiate MasterPass Project
• Going to the MasterPass website and clicking on Get in touch or
• What is your current checkout flow experience?
• Does your site have different checkout
experiences for mobile compared to desktop?
MasterCard
sends
invitation
codes
Project Initiation
• 12 weeks for implementation, from initial inquiry
to final deployment in production
• 40 hours for the developer to integrate the
Merchant Checkout functionality onto the
merchant’s website
MasterCard
sets up
kick-off
meeting
You must sign off on these documents before proceeding.
3
MasterCard sends Invitation Code(s)
MasterCard will send invitation code(s) via email to merchants and service providers. These are used to
create your accounts on the MasterPass Merchant and Service Provider Portal (see Merchant/Service Provider
Registration). Invitation codes cannot be reused.
Note: If you are a service provider that will be using File-based or API-based Merchant Onboarding (FA), your merchants will
not be involved in the development process with MasterCard and thus will not need an invitation code.
FA: MasterPass™—Service Provider Onboarding
and Integration Guide—File and API-Based
Merchant Onboarding
17
Legal Busin
nt:
New
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 2. Merchant/Service Provider Registration
register
as merchant
or service
provider
jj good to know
• The merchant or service provider Account
Owner (also known as Business Owner or
Administrator) is responsible for setting up the
merchant or service provider profiles.
• The Advanced Checkout option provides added
authentication using 3D Secure technology.
• To use Advanced Checkout, merchants must
already be enrolled in either the MasterCard®
SecureCode™ program or Visa’s Verified by
Visa™ program via their acquirer, and must
provide MasterPass with the Acquirer Merchant
ID and Acquirer ID (BIN).
create
your
profile
service
provider
availability
register
your
developers
identify
service
provider as
developer
Merchant/Service Provider Registration
?
1 1
Register as Merchant or Service Provider
At the MasterPass Merchant and Service Provider Portal site, select your country, click on Create an Account, and
enter the invitation code you received at the end of Project Initiation.
At Select Merchant, indicate the type of registration you’re creating, either merchant (for merchants doing Direct
Merchant or Merchant by Merchant integration) or service provider.
Note: If you are performing Merchant by Merchant (MM) Onboarding, both merchant and service provider will need to register.
2
Create your Profile
6 a
Shipping Profile
You will be prompted for information to create your profile including account information, security questions, and a
description of your business.
At the MasterPass Setup page, on 1. Set up/manage your shipping profiles, indicate the regions and countries your
merchant(s) can ship to. You can set up multiple shipping profiles, and can specify a preferred shipping option.
Note: For File-based or API-based (FA) service providers, the exact shipping profile(s) for each merchant will be specified when
the service provider uploads merchant details. The profiles to choose from must first be set up during this step.
a b
Loyalty Program
If you want to allow consumers to enter their Loyalty program details during checkout, click on Reward Program and
specify the Rewards Program and Logo to display during checkout.
Note: File-based or API-based (FA) service providers will provide this information at a later stage.
b c
Advanced Checkout (3D Secure)
If you want to enable 3D Secure (MasterCard’s SecureCode™ and Visa’s Verified by Visa™—see eligibility
requirements in “good to know”), click on Authentication Settings > Advanced Checkout.
Note: File-based or API-based (FA) service providers will provide this information at a later stage.
18
Legal Busin
nt:
New
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 2. Merchant/Service Provider Registration
jj good to know
cc
The emails sent to registered developers will also
include links to MasterPass - Merchant Checkout
Services - Documentation in the MasterCard
Developer Zone.
cc
MasterCard recommends using email addresses
specially setup for Merchant Checkout
development, to avoid access problems in the event
that anyone should leave the project.
cc
cc
Bear in mind you will need a merchant or service
provider sponsor to actively work with your code in
the production environment.
Service Provider Availability
(this applies to Merchant by Merchant [MM] service providers only)
Service providers can select the “I want merchants to be able to select me to perform their MasterPass
implementation” option. When this box is checked, merchants will see the service provider’s name in the dropdown box when inviting a third party as a developer (as mentioned below in step 5). Service providers can
uncheck this at any time.
4
Register your Developer(s)
(if you are a merchant using a service provider [Merchant by Merchant approach], complete Step 5 instead)
You will now be identifying the developer(s) who will perform coding and testing of your checkout project.
Select MasterPass Setup > 2. Add Developers > Start this Step.
Developers who are interested in writing code but
don’t have a merchant or service provider invitation
to partner with them in a Merchant Checkout
integration can still download sample MasterPass
integration code at Developer Zone > MasterPass Merchant Checkout Services > Sample Code.
ll want to know more?
dd
3
Click on the option that best describes the developers supporting you. Typically, merchants and service
providers will register their developers using the An internal or contracted developer option.
Two emails are sent to your assigned developers; one with username and one with password information. Both
emails will have links to guide the developers to the Merchant and Service Provider Portal.
Repeat this step for each developer that will be working with you.
5
Identify Service Provider as the Merchant’s Developer
(if you are a merchant using a service provider [Merchant by Merchant approach], this step replaces Step 4)
MasterPass Onboarding and Integration Guides
Select MasterPass Setup > 2. Add Developers > Start this Step.
• 3DS Overview
Select the option A third party platform provider (service provider: shopping cart provider or card payment
gateway). From the drop-down menu, select the service provider.
• Onboarding—Steps
The service provider is now known to the MasterPass system as the developer for this implementation.
19
Legal Busin
3
ADD A KEY
nt: Production
Sandbox
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 3. Developer Generates Keys
create
account
jj good to know
cc
If the developer misplaces the invitation emails, the
Merchant and Service Provider Portal’s account
owner will need to delete the developer profile and
recreate it in order to generate a new invitation.
cc
The public/private key pair is generated by the
merchant or service provider and is used to sign
API service requests sent to MasterPass; it proves
“I am who I say I am”. The public key is shared with
1
MasterPass.
cc
dd
Refer to the following sections in the MasterPass
Onboarding and Integration Guides:
generate
API key IDs
renew
API keys
anually
Developer Generates Keys
?
1
The MasterPass Sandbox and Production API
Key IDs are generated by MasterPass; they point
to the merchant or service provider’s public key
which MasterPass will use to validate the signed API
service requests.
ll want to know more?
generate
public/private
key pair
Developer creates MasterPass Developer account
In the MasterPass Merchant and Service Provider Portal, the developer logs in using the username and
password information provided in the two invitation emails generated in Section 2 (Merchant/Service Provider
Registration).
Select Manage Development > 1. Register on Developer Zone > Start This Step. You are taken to the
MasterCard Developer Zone. Complete the registration form and click Sign Up. Activate your account by
following the instructions in the confirmation email. Developer registration is now complete.
2
Developer generates public and private key pair
• Developer Registration, API Keys, Initiate
Development and Request Sandbox Approval—
Developer Activity
To generate your public/private key pair, login to the Developer Zone, select My Account > My Dashboard > My
Keys > Add a Key. Click on the link within the Certificate Request (CSR) section, or you can use a tool of your
choice. Once you’ve created the public and private keys, save them in a password-protected software keystore
file (a “P12” file).
• Developer Zone—Key Tool Utility
The tool will also generate a CSR (Certificate Signing Request) which is a PEM-encoded public key. You will
send this to MasterCard in the next step.
• Developer Zone—Key Renewal Process
3
Developer generates API Key IDs
This step is where you upload your public key (CSR) and then receive two API Key IDs—one for the Sandbox
(test) environment, and one for the Production environment—which are used to point to your public key.
On the Developer Zone home page, login and select My Account > My Dashboard > My Keys > Add a Key.
Complete the dialog box to generate a Sandbox key. It is suggested that you use the prefix SBX_ for your
Sandbox key. Select Sandbox as the environment and attach your CSR file previously created in Step 2.
You will receive a Sandbox API Key ID with an expiration date one year in the future.
20
Legal Busin
3
ADD A KEY
nt: Production
Sandbox
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 3. Developer Generates Keys
Return to your Dashboard, and repeat this process to create your Production API Key ID, making sure you select
Production Key for the environment. It is suggested that you use the prefix PRD_ for your Production key. The
same CSR should be used as was used for the Sandbox API Key ID.
jj good to know
cc
cc
The MasterPass API Key IDs expire after
one year, and must then be renewed using the
Developer Zone Key Renewal process, defined in
each of the integration guides. If you do not renew
your keys in time, your MasterPass transactions will
fail.
Key expiration notifications will be sent to
developers 30 days, 15 days, and one day before
actual expiration.
Note: Only one set of keys is needed for each checkout project, not one set per developer.
4
Renew API keys annually
In the Developer Zone, select My Account > My Dashboard > My Keys. Click on Renew a Key, and complete the
dialog box to renew your API Keys.
Note: MasterCard recommends you first create new private and public keys and a new keystore password, but that you
keep the existing Sandbox and Production API key names. You will then be able to keep using your original Sandbox and
Production API Key IDs, and only change the private key you are using when you sign your API calls.
Note: This key change is effective immediately when you select the “renew” option; therefore, you will need to manage this
change seamlessly.
21
<div 3
</div>
</body>
</html>
4
<html>
<head>
<meta h
<ti
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 4. Development and Local Testing
access
development
resources
jj good to know
cc
The MasterPass Merchant Checkout Services come
with their own software development kit (SDK)—a
set of coding tools that aid creation of applications
for a certain software package.
cc
The MasterPass SDK is available in Java, PHP, C#
.Net, and Ruby. Contact a regional MasterCard
representative if your preferred language is not
listed.
cc
cc
You can reuse most of the sample code
provided in the SDK; only minor customizations
will be needed (comprised of merchant’s branding
information, credentials needed to make API calls,
checkout configuration).
Development and Local Testing
?
1 1
ll want to know more?
dd
MasterPass Onboarding and Integration Guides
• Integration Process
• Testing
• Q/A Checklist
tt
MasterPass Support FAQs
tt
Developer Zone > MasterPass - Merchant Checkout
Services > tabs for Resources, Discussions, Sample
Code and FAQs
tt
Developer Zone > Discussion Forums > MasterPass
Merchant Forum
Download the sample applications and software development kit (SDK) from the Sample Code tab in the
MasterPass - Merchant Checkout Services page.
If you are coding to support MasterPass Merchant Checkout Services mobile on an iOS or Android app, the
MasterCard App LaunchPad in the Developer Zone has code and sample applications that will let you quickly
and easily build apps that integrate with the MasterPass Merchant Checkout Services APIs.
• Read the Onboarding and Integration Guide
corresponding to your type of integration.
• Familiarize yourself with the Q/A Checklist
found in the integration guides. It highlights key
items to validate during development.
Access development resources
MasterCard recommends you fully review the ReadMe.txt file inside the SDK. This file will step you through
setting up the SDK on your local web server, and also explain the sample API XML code. Using the sample code
application lets you observe the service calls of the MasterPass APIs as they happen.
Developers are strongly encouraged to perform
the following activities:
• Ensure that you can successfully execute the
sample application before coding.
code
and
test locally
2
Developer(s) perform coding and local testing
Using the resources above, you can now begin coding for integration. It should be complete and ready for
testing before continuing on to the next section. Your code should transition “gracefully”; for example, handling
consumer exits correctly by returning them to a valid page.
For insight into the development steps you will need to complete, consult the references listed in the “want to
know more?” section on the left.
You are highly encouraged to regularly verify your code using the Q/A checklist in the integration guides.
This checklist contains important verifications related to asset (images) placement, in-wallet experience, postwallet experience, and other general considerations.
22
4 5 <div
</div>
Production </body>
</html>
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 5. Approval and Sandbox Testing
create
and submit
checkout
project
jj good to know
cc
cc
A checkout project is how MasterPass
recognizes your Merchant Checkout
implementation. It links merchant or service
provider details (Sandbox and Production API Key
IDs, project name and description, merchant logos
and names) to the identifiers (credentials) assigned
by MasterPass.
Once the merchant or service provider approves
the developer’s checkout project, MasterPass
generates the merchant credentials and they
are then displayed to the developer. The primary
credentials are:
cc
Service providers offering Merchant by Merchant
integrations will generate one checkout project per
merchant; code may be identical across projects.
cc
Service providers using the file-based integration
approach will generate only one checkout project
per batch of merchants. Once the checkout project
is approved, additional merchants cannot be
added; a new checkout project will be required.
cc
receive
credentials
for Sandbox
Testing
Sandbox
Testing
?
1 1
Developer creates Checkout Project and submits for approval
Once you’ve completed your coding, you must create and submit a checkout project to obtain merchant credentials
(identifiers). You will then add these credentials into your API XML code.
Log into the Merchant and Service Provider Portal, and in Manage Development, click on Checkout Projects >
2. Request merchant approval along the way > Do this now. Enter your project name and a project description.
Enter both the Sandbox API Key ID and Production API Key ID you created earlier. Finally, at Include branding
for the experience, add your merchant logo and name. If you do not provide a logo, your merchant’s name will be
displayed. Click Submit.
• Checkout ID: This is a character string
identifying the merchant’s branding information.
Direct Merchants will create just one checkout
project.
review
checkout
project
Approval and Sandbox Testing
• Consumer Key: This is a character string
identifying the merchant or service provider.
cc
upload
merchant
details
Note: File-based or API-based service providers will provide merchant details during steps 2a and 2b.
2
Upload merchant details
(File-based or API-based integrations only)
Developers working on these integrations must perform this step below before submitting their checkout project.
6 a
Service providers using the Single Merchant
API-based approach will only need one checkout
project; merchant details can be added, updated,
or deleted without creating a new checkout project.
File-based Upload
Obtain details for your merchant(s), and use these to create a Merchant Upload File. If you have more than 1000
merchant records, you must create multiple files. Each file cannot exceed 10 MB.
Click Upload on the Checkout Projects screen. A message will show the number of records processed, both
successful and failed. Click Download Result File to view results.
Note: Files can be pre-validated. Click Choose File > select the file to validate > Validate Now. A message will be displayed with
“Validation complete” or with error details. These must be corrected before submitting files for further processing.
a b
API-based Upload
Once a Direct Merchant or Merchant by Merchant checkout project has been successfully submitted to production,
in Account Settings, click the Enable Auto Approval box, and click the Use Open Feed to Production Checkout
Project box.
23
4 5 <div
</div>
Production </body>
</html>
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 5. Approval and Sandbox Testing
jj good to know
cc
cc
cc
Once a developer has successfully performed
one integration, the account owner can request
that future checkout projects by that developer
be automatically approved (referred to as Auto
Approval).
3
Note: If the Auto Approval option has been set up previously, this step will be skipped (see the “good to know” section).
Note: Service providers performing File-based or API-based uploads will not see a Preview Branding screen.
Note: Service providers performing File-based or API-based uploads can click on Download Result File (showing failed records) or Download Merchant File (original merchant file uploaded) to view processing results.
4
• Initiate Development and Request Approval
• Request Access to Merchant’s Sandbox Details
dd
Developer receives merchant credentials for Sandbox testing
Once the checkout project is approved, the developer receives an email notification.
Login to the MasterPass Merchant and Service Provider Portal, and in Checkout Projects, click on the respective
project and make a note of the Sandbox Consumer Key. This character string is part of the credentials that must
be added into API calls during the Sandbox phase. Click on View Branding and make a note of the Checkout
Identifier (this value identifies the merchant).
• Set Auto Approval
MasterPass™ Service Provider Onboarding &
Integration Guide—File- and API-Based Merchant
Onboarding
You will need to add both of these in your API XML code to correctly interface with the MasterPass APIs.
• File-Based Onboarding
• API-Based Onboarding
The merchant or service provider account owner will receive an email notification that a checkout project is
pending approval.
Click on Preview Branding to view the merchant logo branding information. Based on your review, click on
Approve or Reject. If you select Reject, you must provide a reason, and the developer will be asked to modify their
checkout project and resubmit.
To enable this option, login to the MasterPass
Merchant and Service Provider Portal, and in
Account Settings, click on Enable Auto Approval.
MasterPass Onboarding and Integration Guides
Account Owner reviews Checkout Project for Sandbox credentials
The Account Owner must log on to the MasterPass Merchant and Service Provider Portal, and in MasterPass
Setup, click on Approval Request. A list of open requests appears. Click on the project name indicated in your
email notification, and in the project’s dialog box, click on View details.
The subsequent checkout projects associated
with that developer are not sent for review by
the merchant (Merchant by Merchant method)
or service provider (for File-based or API-based
merchant onboarding)—they are automatically
approved.
ll want to know more?
dd
The service provider’s system will send API XML code containing details for a single merchant record, the
checkout ID and consumer key using a Single Merchant API service call. This will automatically submit and push
merchant record adds/updates/deletes directly to production.
5
Sandbox testing
The developer proceeds with Sandbox testing using the Sandbox credentials. The Sandbox environment provides
a replica of the live MasterPass Merchant Checkout Services.
When Sandbox testing is complete, you are ready to repeat this process, as described in Section 6, “Buy with
MasterPass” Deployment.
24
wallet
5 6
MasterPass Merchant Checkout Services / Implementing MasterPass Merchant Checkout Services / 6. “Buy with MasterPass”
receive deployment
create
credentials
and submit
for Sandbox
checkout
project
Testing
<html>
<head>
<meta h
<ti
submit
checkout
project
jj good to know
cc
The production endpoint (https://api.mastercard.
com) is the location the developer includes in their
API XML code when calling MasterPass services in
production.
cc
Before proceeding with deployment, the following
must be performed:
• Ensure that you have implemented the
MasterPass button on your site or mobile app.
• Refer to the Q/A Checklist section in the
Onboarding and Integration Guides.
• As mentioned previously, this checklist contains
important verifications in the areas of asset
placement, in-wallet experience and post-wallet
experience.
For more details, see the MasterPass Onboarding
and Integration Guides, available at MasterPass Merchant Checkout Services > Documentation on
the MasterCard Developer Zone.
receive
credentials
for Production
Testing
Go-Live
“Buy with MasterPass” Deployment
?
1 1
2
ll want to know more?
cc
review
checkout
project
Developer submits Checkout Project for approval
Once Sandbox testing is complete, the developer must submit the same checkout project again for approval in
order to obtain the production credentials needed to deploy their code in production.
Account Owner reviews Checkout Project for Production credentials
(if the Auto Approval option has been set up previously, this step will be skipped)
The merchant or service provider account owner will again receive an email notification that a checkout project
is pending approval, and approves or rejects as described in the previous section.
3
Developer receives merchant credentials for Production testing
(if the Auto Approval option has been set up previously, this step will be skipped; production credentials will be
available to the developer without a second approval phase)
Once the checkout project is approved, the developer receives an email notification.
On the MasterPass Merchant and Service Provider Portal, select your project in Checkout Projects and make a
note of the Production Consumer Key. Click on View Branding and make a note of the Checkout Identifier.
These values, as well as the Production Callback URL, Keystore and Keystore password, and production
endpoint (https://api.mastercard.com) will all need to be added to your final API XML code.
4
Go-Live
The merchant’s site begins to offer MasterPass checkout as soon as the developer updates the production
endpoint in their code..
This update should be performed after the developer receives confirmation from the merchant or service
provider that they are ready to go live with MasterPass Merchant Checkout.
25
MasterPass Merchant Checkout Services / Support, Documentation and Resources, Feedback
Support
Interested in MasterPass Merchant Checkout?
• Go to the MasterPass website, and click on Get in touch. A regional MasterCard representative will contact you.
Implementation support
• For security questions and questions about using Open API, send an email to apisupport@mastercard.com.
• For other issues concerning onboarding, integrating, or testing, contact your MasterCard Implementation
Manager, a regional MasterCard representative, or send an email to merchant_testing_support@masterpass.com.
Post-implementation support
• For 30 days after go-live: contact your MasterCard Implementation Manager or a regional MasterCard
representative.
• After this 30-day period: contact MasterPass Customer Support at support@masterpass.com. Provide your Checkout Identifier, Consumer Key, and full details and screenshots.
Note: If you are using a service provider, you may need to contact them for support, based on the issue you’re experiencing.
Documentation and Resources
MasterPass documentation and helpful information is available at the following:
tt
tt
tt
tt
MasterCard Developer Zone > Services > MasterPass - Merchant Checkout Services
(includes guides, sample code, SDKs, discussions, FAQs, and resources)
MasterPass Merchant and Service Provider Portal
MasterPass website
MasterPass Branding Requirements
Feedback
If you have suggestions for improving this document, please email us at:
implementation_guide_suggestions@mastercard.com.
26