API — The Foundation

Mastercard Customer Implementation Services

Implementation Quick Reference Guide series
©2021 Mastercard
Proprietary and Confidential. All rights reserved.
November 2021

Application Programming Interface (API)

The Foundation
1 2 3 Implementation Quick Reference Guide
API — The Foundation

? How to read this document

Implementation Quick Reference Guide /
How to read this document

WHO NEEDS IT? This page gives you a brief description of the different sections you will find in this document.
Explains who the topic applies to.

PREREQUISITES
What is it?
Lists the processes or actions that must be completed Gives a description and high-level overview of the topic.
before you start a specific process.

ALSO KNOWN AS
Lists the alternative names that are used for certain
terms.

GOOD TO KNOW
Provides additional background information to help
you better understand the topic.

WANT TO KNOW MORE?

Provides information on helpful Mastercard
documentation, available either from your
Mastercard representative, or at Technical Resource
Center/References on Mastercard ConnectTM. You
can find a specific manual by using the search
function.
API — The Foundation

Contents
Implementation Quick Reference Guide /
Contents

1 2
Understanding Mastercard API
API Platforms
5 9

Mastercard Digital Mastercard API Support &

Transformation in Action Feedback
5 9 12

What is API Example— Glossary

an API? Location Services 13

? 6 10

API Security Mastercard Other Quick

at High Level Developers Reference Guides
7 11 1 2 3
14
 4

Welcome to Application Programming Interface (API)—

API — The Foundation
Implementation Quick Reference Guide /

The Foundation
Welcome to Application Programming Interface
(API) – The Foundation

PREREQUISITES This document provides a broad introduction to Application Programming Interfaces (APIs)—how APIs work, why APIs are important
• Access to Mastercard ConnectTM for Mastercard, and Mastercard’s API Platform.
• Access to Mastercard Developers The primary intended audience of this guide is anyone wanting to learn the foundation of API.
The document is split into two sections:

Understanding API
We introduce the importance of APIs for Mastercard, including why Mastercard is focusing on APIs. We also explain in
detail what an API is, why we need APIs and its security at high level.

Mastercard API Platforms

We introduce Mastercard API, Mastercard Developers—how it works and the availability of Mastercard Software
Development Kits (SDKs).

This document provides a relatively high-level overview with links to additional information where relevant.
 5
API — The Foundation

Understanding API
Implementation Quick Reference Guide /
Understanding API

Mastercard Digital Transformation

At the core of Mastercard’s digital revolution is our Application Programming Interface (API) strategy, centered on simplifying customer
integration and driving innovation at scale.
GOOD TO KNOW:
Mastercard has data and services that can help our partners achieve their business goals by delivering custom applications for their
• The API platform allows Mastercard to seamlessly
integrate its products into customer applications. customers. In short, API is the means of connecting our partners to our data and services.
• API products are easier to build and globally scalable.
They can be used by customers, regardless of industry
or size, anywhere the internet exists.
PARTNER
WANT TO KNOW MORE:
• Mastercard Labs—API
• Why Mastercard is focusing on APIs?
PARTNER
DATA

data & services Mastercard API app

Mastercard APIs enable our customers to easily integrate our services into digital solutions, and fundamentally transform the way we
work with our customers and how our services are accessed.
Our APIs provide our customers a direct connection to Mastercard various platforms, such as:

MATCH MATCH Masterpass Masterpass In Control In Control

Mastercard Digital
Rewards Rewards MDES Enablement Service MoneySend MoneySend
(MDES)

and so much more…

 6
API — The Foundation

?
Implementation Quick Reference Guide /
Understanding API / What is an API?
What is an API?

When a company has a resource (such as data, like AT M locations) or function (such as payment processing) it wants to share (or sell) to
its partners, the company hires internal developers to create web services that serve the resource or perform the function.
These web services are then made available over the public internet, and are called APIs or Application Programming Interfaces.
These APIs, as their name suggests, enable programs to interface with other applications.
WHO NEEDS IT?
An API is used by our partners to build software applications, and essential for connecting developers to Mastercard services.
To speak plainly, an API is the messenger that runs and delivers requests to the API service provider ❶, and then delivers the response
back to the requestor (or client) ❷.

• Developers at issuers, acquirers, processors, and To give you a familiar example, think of an API as a waiter in a restaurant. Let’s imagine that, at the table, a client is ordering from a
technology companies. menu of choices, and the kitchen (Mastercard) is the service provider who will fulfill their order.

ALSO KNOWN AS
• Web Services

GOOD TO KNOW
• APIs are simply how separate services work together
to deliver a solution.
• APIs are quickly becoming the de facto standard, 1
where companies exchange data and build consistent
cross-channel customer experiences.
2
• A good API makes it easier to develop a program by
providing all the building blocks. The programmer
then can easily put the blocks together.
• A developer may use any number of APIs to build What is missing is the critical link (the messenger) to communicate the order to the kitchen and deliver the food (resource) back to the
their user facing application, including APIs outside
table. That’s where the waiter (or API) comes in. The waiter takes the order, delivers it to the kitchen ❶, and then delivers the food back
of Mastercard, such as Facebook, Google, or
Twitter. to you ❷. Note: API resources are the resources that a provider makes available so that other applications can interface with it.

WANT TO KNOW MORE? VERIFY TRANSACTION

VERIFY TRANSACTION

• What are APIs and how do they work? REQUEST

• 50 most useful APIs for Developers

DATA
• An example of other APIs in Financial and PARTNER
Payments Specific
1

An API connects business processes, services, content, and data to channel partners, internal teams, and independent developers in an
easy and secure way. In short, API enable applications to talk to each other.
 7
API — The Foundation
Implementation Quick Reference Guide /
Understanding API / API Security at High Level
API Security at High Level

Public vs Private APIs

APIs can be either public or private.
Public APIs are used when information and services are open to the general public.
GOOD TO KNOW:
Private APIs will typically use multiple layers of security, including keys and certificates, to ensure that only valid partners
Authentication (who you are) are able to access the information and services provided by the API. Private APIs are used whenever the information or
service in question is sensitive, or whenever there is a cost associated with the information or services.
Authentication is used to reliably
determine the identity of an end user.

Why do we need API Security?

Authorization (what you can do)
Since the APIs are available on the internet, it is important to make sure that only the right partners access the data and services
Authorization is used to determine offered by the API service provider. When a request (message) leaves the client, it goes through multiple internet providers. Along any of
what resources the identified user has these hops across the internet, someone acting maliciously could intercept the request or the response.
access to.
API keys are used for authentication (verifies the identity of the caller) and authorization (determines whether the
• Encryption is generally used to hide information from caller has the permission to work with a resource) so that the service provider can ensure that the partner requesting an API has been
those not authorized to view it. approved and has access to the requested service. The API key uniquely identifies the partner, and it acts like a password allowing the
• On the internet, often Secure Socket Layers (SSL) is partner to access the service.
used to encrypt Hypertext Transfer Protocol (HTTP) The request (message) itself is encrypted (makes the data readable only by authorized parties) and can be further secured by adding a
messages, sent and received either by web browsers
digital signature which ensures that the message received by the service provider is exactly what the client sent and to ensure that no
or API clients.
other parties tampered with the message.
 8
API — The Foundation
Implementation Quick Reference Guide /
Understanding API / Keys and Certificates
Keys and Certificates

A key is similar to a password that gives the key-holder access to a particular resource or API.
A certificate contains a key, information about the key, its validity (for example, key expiration date), the key holder, and other
security related information. Certificates are signed by a third party responsible for ensuring the certificate and key are valid, also
known as a Certificate Authority (CA).
GOOD TO KNOW:
Below are some examples of keys and certificates and their roles during API connections:
• A certificate is an electronic document used to
identify an individual, a server, a company, or other
entity, and to bind that identity with a public key. MDES
• A certificate always includes: XML Gateway Client Certificate Client Authentication to XML Gateway
• A public key and the name of the entity it identifies
Wrapping Key or Digitize Public Key Transport key used with the MDES Digitize API to encrypt one-time use AES Key
• An expiration date (one-time key will be used during payment)
• A serial number Mastercard Public Key Used to encrypt the cardinfo object sent through the MDES Digitize API
• The digital signature and name of the issuing (Mastercard Key Encipherment)
Certificate Authority (CA) KekID Transport key used to encrypt specific RawTransactionCredential
(only required for non- Mastercard CMS-D)
ccmKeyID Used to encrypt transaction credentials sent through MDES Credentials
(only required for non-Mastercard CMS-D) Management API during token provisioning
CMS-D Public Key Wrapping key used to encrypt the AES key sent through the MDES Credentials
(required for all new Wallet Providers) Management API during token provisioning

In Control
Signing Certificate During API call, used to ensure integrity of the message
Client Certificate During API call, used to authenticate a client when he establishes a SSL connection
Server Certificate During API call, used to authenticate a server when it establishes a SSL connection

Mastercard Rewards System (MRS)

Signing Certificate During API call, used to ensure integrity of the message
Client Certificate During API call, used to authenticate a client when he establishes a SSL connection
Server Certificate During API call, used to authenticate a server when it establishes a SSL connection

MoneySend
Signing Certificate During API call, used to ensure integrity of the message
Client Certificate During API call, used to authenticate a client when he establishes a SSL connection
Server Certificate During API call, used to authenticate a server when it establishes a SSL connection
 9
API — The Foundation

Mastercard API Platforms

Implementation Quick Reference Guide /
Mastercard API Platforms

Mastercard API in Action

Mastercard has data and services ❶ that its partners would value.
ALSO KNOWN AS
Mastercard partners know that with Mastercard Data and Services, they can provide a comprehensive solution for their end users
• Transport Layer Security (TLS) was previously (cardholders and consumers).
known as Secure Socket Layer (SSL).

GOOD TO KNOW:
• The SSL or TLS provides security which ensures that
the information transmitted between the partner and service provider client user
(Mastercard) (partner / issuer / DAC / acquirer) (cardholder)
the service provider is encrypted and not readable by
anyone that might intercept the message.
• A gateway typically provides additional security,
standards, and reporting.
❶ ❷ ❸ ❹ ❺
• An API Gateway perform multiple roles including load
balancing, throttling, security, and translation between
the partner’s application and Mastercard applications.
DATA

data
• While a gateway is the entry point for the application PARTNER

itself, Mastercard Developers (described further in

this guide) is the entry point to information about services application API/XML the Internet firewall application firewall the Internet user
Mastercard APIs for users. server Gateway services device

• The two API gateways at Mastercard are Mastercard

API (formerly known as OpenAPI) and the XML
Gateway.
Mastercard development Since the data and services Once the Mastercard APIs are After the partner has
teams create applications ❷ provided are sensitive and available online, Mastercard developed their application,
to provide APIs in relation to require security, Mastercard partners can request keys to cardholders or users connect
its data and services. uses the Mastercard API the APIs and develop ❹ their to it via a secure HTTPs
Gateway ❸ as the secure application to connect to the connection, on an internet
proxy connecting it to the Mastercard Data and Services enabled device ❺.
internet. via the API.
As the cardholder interacts
The API Gateway uses keys with the partner’s application,
and SSL or TLS to ensure that the partner’s application in
any partner that connects has turn interacts with Mastercard
a secure connection. via the API.

Over time, Mastercard creates more applications to serve more APIs for more products and features. Mastercard also has multiple
gateways, each with their own security benefits. All Mastercard partners can leverage these services to expand their offerings.
 10
API — The Foundation
Implementation Quick Reference Guide /
Mastercard API Platforms / API Example—Location Services
API Example - Location Services

Problem
You are creating a mobile application to show the user where nearby ATMs are located.

Solution
Mastercard has developed an API called Location Services. By using this API, you can easily add functionality to your application to find
the ATM closest to the user.

How does it work?

ANY WALLET

ATM FINDER ATM FINDER

ATM ATM
ATM ATM

ATM ATM
? ATM ATM

App determines App sends API calls Mastercard sends App displays
position The mobile application sends data information
Using the GPS included in your an API call to Mastercard Mastercard ATM database The app displays the positions
smartphone, the GPS is able Location Services. sends the position of the of the ATMs overlaid on a map.
to locate your current location. The API calls include: ATMs in the user’s area back
to the app.
• Signing and client
certificates, as required for
authentication
• Other info, such as file
identifiers and timestamp
• The body of the message
contains the action to be
performed by the API, that
is to check where the ATMs
are located in the area.
 11
API — The Foundation
Implementation Quick Reference Guide /
Mastercard API Platforms / Mastercard Developers
Mastercard Developers

Mastercard Developers (https://developer.mastercard.com) is the entry

point for developers to learn about Mastercard APIs. Mastercard Developers
provides a single source of information for our partners to access and learn
about a diverse range of Mastercard API services across payments, data,
and security.
ALSO KNOWN AS
• Mastercard Developers was formerly known as Developers will enjoy a streamlined experience across Mastercard APIs
Mastercard Developer Zone with features and functionalities focused on helping developers speed up
• SDKs are also known as Development Kits (devkits) the integration process. Mastercard Developers is equipped with a clear,
developer-friendly documentation with APIs supported by Software
Development Kits (SDKs), developer tools and sample code for the top six
GOOD TO KNOW programming languages.
• Not all Mastercard APIs are public APIs. To access
Mastercard private APIs, developers need to send a
specific request through Mastercard Developers.
Software Development Kits
• Other APIs (such as In Control, Rewards) are not
currently offered via Mastercard Developers. To obtain A Software Development Kit (SDK) is a set of software development tools that allows the creation of applications or apps for a
access to these APIs, contact your local Mastercard specific platform. The SDKs come in the form of pre-written code that leverages Mastercard APIs.
representative.
Developers can speed up development with Mastercard Software Development Kits (SDKs). While technically a developer could utilize
• An SDK typically includes one or more APIs,
the APIs from scratch, using the SDK is like using a cake mix, where all of the hard parts are already done, and developers only need to
programming tools, and documentation.
tailor specific components for their implementation. Benefits of using Mastercard SDKs are:
• To use Mastercard APIs, it is highly recommended to
use one of our SDKs. • They have been proven to work by Mastercard
• SDK Languages Usage, based on the survey • They simplify support by ensuring consistency in implementation
conducted by Stack Overflow in 2016 In short, the Software Development Kits simplify the development process and provide a shortcut for customers to quickly launch a
(56K developers in 173 countries):
product using the Mastercard APIs.
• JavaScript - 55.4%
• SQL - 49.1%
• Java - 36.3% SDKs and Languages
• C# - 30.9%
While APIs are ubiquitous and can be accessed using any web enabled programming language, Mastercard supports SDKs and sample
• PHP - 25.9%
code in six of the most popular programming languages. The SDK languages supported by Mastercard are:
• Python - 24.9%
• C++ - 19.4%
• AngularJS - 17.9% (JavaScript framework)
• Node.js - 17.2% (server-side JavaScript)
• C - 15.5%

WANT TO KNOW MORE:

Java C/C++ JavaScript PHP Python Ruby
• Mastercard Developers—Quick Start
Guide
• Mastercard Labs—API Developers using one of these languages will generally experience a much faster time-to-market than using an unsupported
• Mastercard SDK guides available on programming language.
Mastercard Developers
 12
API — The Foundation

Support & Feedback

Implementation Quick Reference Guide /
Contact & Support

Support
• If you have questions about API, contact your Mastercard representative.
• During implementation, contact your assigned Implementation Manager.

Feedback
If you have suggestions for improving this document, please email us at:
[email protected]
 13
API — The Foundation

Glossary
Implementation Quick Reference Guide /
Glossary

Terms Definition
Secure Socket Layers (SSL) The standard security technology for establishing an encrypted link between a client and a service
provider.
Hypertext Transfer Protocol How websites and APIs communicate over the internet, it is underlying protocol used by the World
(HTTP) Wide Web that defines how messages are formatted and transmitted.
The HTTP Methods are:
• GET: Retrieving data
• POST & PUT : Creating or updating data
• DELETE : Deleting data
Data Interchange Format A set of rules for transmitting data that is both human-readable and machine-readable.
• Extensible Markup Language XML and JSON are both Data Interchange Formats; both attempt to accomplish the same goal, but
(XML) JSON is newer and quickly replacing XML, primarily because JSON messages are smaller than XML
• JavaScript Object Notation messages. The following table shows the same information presented in XML and JSON.
(JSON)

XML JSON

<AddressBook> {
<Contact> “AddressBook” : [
<FirstName>John</FirstName> “Contact” : {
<LastName>Doe</LastName> “FirstName” : “John”;
<Email>[email protected]</Email> “LastName” : “Doe”;
</Contact> “Email” : “[email protected]”
<Contact> },
<FirstName>Jane</Firstname> “Contact” : {
<LastName>Doe</LastName> “FirstName” : “Jane”;
<Email>[email protected]</Email> “LastName” : “Doe”;
</Contact> “Email” : “[email protected]”
</AddressBook> }
]
}
 14
API — The Foundation

Other Quick Reference Guides

Implementation Quick Reference Guide /
1 2 3
Other Quick Reference Guides

If you like this guide, you can find similar ones in the Implementation Quick Reference Guides 1 2 3
series.
The Implementation Quick Reference Guides demystify complex subjects into easy-to-understand content.
All of the following guides are available at Technical Resource Center/References on Mastercard ConnectTM :

These guides come in the form of PDF manuals.

API - APW -
The manuals provide full details on the topic and a Customer
Application Automated Parameter
high-level overview of its process, and links to related Testing
Programming Interface Worksheet
manuals.

It will provide an insight into what

you will need to know to complete
the implementation process for the
desired topic. MDES -
File Key
Mastercard Digital
Transfer Management
Enablement Service

Mastercard Project
Network Implementation Settlement
Connectivity with Mastercard