mastercard digital enablement service

Mastercard Digital

Enablement Service

Pre-Digitization

Application Programming Interface

Version 2.0.8, BUILD3

29 May 2019

© 2019 Mastercard. Proprietary and Confidential. All rights reserved.

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.8 BUILD3

2

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 manual 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.

Disclaimer

Access to this document is subject to a separate Non-Disclosure Agreement with

Mastercard.

If you are not certain that you are disclosed, or that you should have access to this

document, please stop reading now, and consult the appropriate legal resource within

your company before proceeding.

Mastercard makes no representations or warranties of any kind, express or implied, with

respect to the contents of this document. Without limitation, Mastercard specifically

disclaims all representations and warranties with respect to the document and any

intellectual property rights subsisting therein or any part thereof, including but not limited

to any and all implied warranties of title, non-infringement, or suitability for any purpose

(whether or not Mastercard has been advised, has reason to know, or is otherwise in fact

aware of any information) or achievement of any particular result. Without limitation,

Mastercard specifically disclaims all representations and warranties that any practice or

implementation of the Specification will not infringe any third party patents, copyrights,

trade secrets or other rights.



3

Summary of Changes

Description of Change Where to Look

Added new fields (tcis, auxTcis) in the Authorize Service API

response

2.5.4

Typo correction to reflect the use of a slash “/” separator

instead of a comma “,” separator between “(sign) latitude”

and (sign) longitude” in the deviceLocation parameter

A.1, A.18 -- Sample unencrypted

object

Added new fields in the Authorize Service, Request

Activation Methods, and Notify Service Activated request

which will present more information to issuer about the

cardholders association with the device and wallet provider.

The new fields will only be present in the Pre-Digitization API

if the wallet provider has supplied Mastercard with the

information

A.14 (DeviceInfo updated with

cardCaptureTechnology field)

A.13 (DecisioningInfo updated with field

accountLifeTime.)

A.1 (AccountHolderData updated with

accountHolderMobilePhoneNumber)



4

Contents

1 Introduction ......................................................................................................................... 7

1.1 What is the Mastercard Digital Enablement Service? ....................................................... 7

1.2 Document Scope ........................................................................................................... 7

1.3 Using This Document .................................................................................................... 7

2 MDES Pre-Digitization API ..................................................................................................... 8

2.1 Overview ...................................................................................................................... 8

2.1.1 Flow Diagram......................................................................................................... 8

2.1.2 API Design Principles .............................................................................................. 9

2.1.3 URL Scheme ........................................................................................................... 9

2.1.4 Security Overview and Encryption ..........................................................................10

2.1.5 API Request / Response Common Elements and Headers ........................................13

2.1.6 Retry Strategy .......................................................................................................14

2.2 RequestActivationMethods ...........................................................................................18

2.2.1 URL Endpoint ........................................................................................................18

2.2.2 HTTP Method ........................................................................................................18

2.2.3 Request Parameters ...............................................................................................19

2.2.4 Response Values ...................................................................................................21

2.2.5 Example Request Body ..........................................................................................21

2.2.6 Example Response Body ........................................................................................22

2.3 DeliverActivationCode ..................................................................................................22

2.3.1 URL Endpoint ........................................................................................................22

2.3.2 HTTP Method ........................................................................................................23


2.3.4 Response Values ...................................................................................................24



2.4 NotifyServiceActivated ..................................................................................................24

2.4.1 URL Endpoint ........................................................................................................24

2.4.2 HTTP Method ........................................................................................................25


2.4.4 Response Values ...................................................................................................29



5



2.5 AuthorizeService ..........................................................................................................31

2.5.1 URL Endpoint ........................................................................................................31

2.5.2 HTTP Method ........................................................................................................31


2.5.4 Response Values ...................................................................................................34



2.6 NotifyTokenUpdated ....................................................................................................40

2.6.1 URL Endpoint ........................................................................................................41

2.6.2 HTTP Method ........................................................................................................41


2.6.4 Response Parameters .............................................................................................42

2.6.5 Example Request Body – STATUS_UPDATE .............................................................42

2.6.6 Example Request Body – REDIGITIZATION_COMPLETE ............................................43

2.6.7 Example Request Body – DELETED_FROM_CONSUMER_APP ...................................43


2.7 ValidateActivationCode ................................................................................................44

2.7.1 URL Endpoint ........................................................................................................44

2.7.2 HTTP Method ........................................................................................................44


2.7.4 Response Values ...................................................................................................45



2.8 Get Account Information ..............................................................................................46

2.8.1 URL Endpoint ........................................................................................................46

2.8.2 HTTP Method ........................................................................................................46


2.8.4 Response Values ...................................................................................................47



A. Appendix A – Request and Response Member Objects .........................................................49



6

A.1 AccountHolderData ......................................................................................................49

A.2 AccountInformationData ..............................................................................................50

A.3 AuthorizeServiceResponseData .....................................................................................51

A.4 ActivationMethod ........................................................................................................52

A.5 BalanceInformation ......................................................................................................53

A.6 BillingAddress ..............................................................................................................53

A.7 CardAccountData ........................................................................................................54

A.8 CardAndTokenData - Deprecated .................................................................................55

A.9 CardAndTokenInfo - Deprecated ..................................................................................56

A.10 CardholderData - Deprecated ....................................................................................58

A.11 CardInfo - Deprecated ..............................................................................................59

A.12 CardInfoData - Deprecated .......................................................................................61

A.13 DecisioningInfo – MAP<String, Object> .....................................................................64

A.14 DeviceInfo – MAP<String, Object> ............................................................................65

A.15 EncryptedPayload .....................................................................................................70

A.16 FinancialAccountData ...............................................................................................71

A.17 FundingAccountData ................................................................................................72

A.18 FundingAccountInfo .................................................................................................74

A.19 Token .......................................................................................................................76

A.20 TokenData ................................................................................................................77

A.21 Phone Number .........................................................................................................77

B. Appendix B – Error Codes ....................................................................................................79

C. Appendix C – Reason Codes ................................................................................................80

C.1 Approved Reason Codes ...................................................................................................80

C.2 Require Additional Authentication or Declined Reason Codes ............................................80



7

1 Introduction

1.1 What is the Mastercard Digital Enablement Service?

The Mastercard Digital Enablement Service (MDES) is a suite of on-behalf-of (OBO) services

that supports the management and generation of digital payment tokens to enable

simpler, more secure digital payment experiences.

MDES was developed to facilitate the financial industry transition from consumer account

credentials to digital credentials. Digital credentials may be provisioned into mobile

devices, enabling consumers to perform payments via existing contactless point-of-sale

(POS) systems, or via remote payment use cases such as in-app payments. Digital

credentials may also be stored on file by merchants and digital Wallet Providers (WP),

allowing them to exchange payment cards on file with digital payment tokens.

1.2 Document Scope

This document is the controlling specification of the Application Programming Interface

(API) for the MDES Pre-Digitization API.

The MDES Pre-Digitization API supports the pre-digitization web services provided by the

Digitization Service, which must be implemented by Issuers participating in MDES.

The following diagram illustrates integration of the MDES Pre-Digitization API with an

Issuer web service complying with the API described in this document:

1.3 Using This Document

The document is a technical specification of the MDES Pre-Digitization. It is assumed that

the reader is familiar with high-level MDES use cases and MDES pre-digitization messages

in ISO format.



8

2 MDES Pre-Digitization API

2.1 Overview

The MDES Pre-Digitization API provides a set of outbound web requests to inform Issuers

of MDES services being requested by, or on-behalf of, their Account holders. Issuers may

provide information in their responses to guide or inform the Account holder’s experience

through the Wallet Provider.

2.1.1 Flow Diagram

The first diagram illustrates a web service managed by the Issuer or Service Provider that

implements pre-digitization services using the MDES Pre-Digitization API. This includes:

Authorizing the creation of a token (digitization) or activation of a service.

Authenticating the Account holder, managing the Activation Methods list and the

Activation Code Distribution Methods.

The second diagram shows a hybrid implementation of the pre-digitization services where:

The Issuer uses the Tokenization Authorization pre-digitization message for

authorizing the creation of a token (digitization).

The Issuer designates a Web Service (e.g. managed by a Service Provider)

implementing the MDES Pre-Digitization API for authentication of the Account

holder, managing both the Activation Methods list and the Activation Code

Distribution Methods.



9

2.1.2 API Design Principles

The MDES Pre-Digitization API is designed as a set of RPC style stateless web services

where each API endpoint represents an operation to be performed. All request and

response payloads are sent in the JSON (JavaScript Object Notation) data-interchange

format. Each endpoint in the API specifies the HTTP Method used to access it. All strings in

request and response objects are UTF-8 encoded. Each API URI includes the major and

minor version of API that it conforms to. This allows multiple concurrent versions of the

API to be deployed simultaneously.

All APIs return an HTTP response code of 200 if the call was successfully received and

accepted for processing. To ensure forward-compatibility, all API integrations must be

resilient to new elements being added to requests. Any errors that subsequently occur

during processing are returned in the response payload.

2.1.3 URL Scheme

All API URLs follow the format:

scheme://host[:port]/contextRoot/api/majorVer/minorVer/apiName

URL Element Definition

scheme https



10

host[:port] Hostname (and port number if required) for the environment.

e.g. www.issuersite.com

contextRoot Context root for the services. The rest of the URL must

conform to the URL Scheme exactly. e.g.

/root/directoy1/directory2/

mdes

api issuerServices

majorVer The major version of the APIs. This is not related to the

version of this document. This version of the document

corresponds to a major version of:

1

minorVer The minor version of the APIs. This version of the document

corresponds to a minor version of:

0

apiName The URL endpoint as defined in the respective section for the

API operation.

2.1.4 Security Overview and Encryption

All communication between the MDES Pre-Digitization APIs and the Issuer’s Server(s) are

secured using mutually authenticated TLS. In addition, all PCI sensitive data (such as PAN)

and all Account holder personally identifiable information (PII, such as PAR) are encrypted

for transport using a separate key. In some cases, the encrypted data may contain an

additional timestamp to specify the encrypted data validity period. This prevents the same

encrypted data from being replayed after the validity period expires.

All keys exchanges shall comply with the Mastercard Public Key Infrastructure policy.

Two security layers are used for the protection of sensitive PCI/PII information, as follows:

Communication between MDES Pre-Digitization API and Issuer web service are

secured using mutually authenticated TLS.

The PCI/PII sensitive data is encrypted using a single use encryption key (SK), which

is transported in a digital envelope encryptedKey within the TLS tunnel. The digital

envelope is created with the receiver’s Encryption Public Key as it is summarized in

the following table:



11

API Encryptio

n Public

Key

Sender Receiver Payload Encrypted

payload

API requests:

(*) RAM API,

(**) AS API ,

(***) NSA

API, (iv) GAI

API

Issuer

Encryption

Public Key

MDES Pre-

Digitization

API

Issuer web

service

fundingAccount

Data

fundingAccount

Info

(**) AS API

response

Mastercar

d

Encryption

Public Key

Issuer web

service

MDES Pre-

Digitization

API

AuthorizeService

ResponseData

encryptedPayload

(iv) GAI API

response

Mastercar

d

Encryption

Public Key

Issuer web

service

MDES Pre-

Digitization

API

Account

InformationData

encryptedPayload

(*) RAM = requestActivationMethods, (**) AS = authorizeService

(***) NSA = notifyServiceActivated, (iv) GAI =getAccountInformation

An overview of the PCI/PII payload bulk data encryption process is provided in the figure

below.



12

SK is generated by a strong pseudorandom number generator built into the HSM. SK is

wrapped with the receiver’s Encryption Public Key, in an RSA digital envelope computed

using PKCS#11’s C_WrapKey method (section 11.14), which is defined on page 178 of

the PKCS#11 v2.20 standard (https://www.cryptsoft.com/pkcs11doc/STANDARD/pkcs-

11v2-20.pdf).

The Issuer acting either as a receiver of API encrypted payloads (in RAM API request and

AS API request) or as a sender of API encrypted payloads (in AS response) must support

two unwrapping/wrapping mechanisms:

When the “oaepHashingAlgorithm” parameter is set to "NONE" during the Issuer

onboarding procedure, MDES uses the PKCS#1 v1.5 RSA mechanism (section

12.1.6) denoted CKM_RSA_PKCS, defined on page 197 of the PKCS#11 v2.20

standard, for both wrapping SK in the encryptedKey (when MDES Pre-Digitization

API is sender and Issuer web service is the receiver) and for unwrapping the

encryptedKey to recover SK (when Issuer web service is sender and MDES Pre-

Digitization API is receiver).

When the “oaepHashingAlgorithm” parameter is setup during the Issuer

onboarding procedure with either "SHA-256" or "SHA-512", MDES uses the

PKCS#1 RSA OAEP mechanism (section 12.1.8) denoted CKM_RSA_PKCS_OAEP,

defined on page 200 of the PKCS#11 v2.20 standard, for both wrapping SK in the

encryptedKey (when MDES Pre-Digitization API is sender and Issuer web service is

the receiver) and for unwrapping the encryptedKey to recover SK (when Issuer

web service is sender and MDES Pre-Digitization API is receiver).

Within the mechanism parameters table CK_RSA_PKCS_OAEP_PARAMS (section 12.1.7)

defined on page 200 of the PKCS#11 v2.20 standard, the following two parameters are

considered:

CK_MECHANISM_TYPE indicates the message digest algorithm used to calculate

the digest of the encoding parameter;

CK_RSA_PKCS_MGF_TYPE indicates the Mask Generation Function (MGF) to use

on the encoded block.

When acting as a sender, MDES Pre-Digitization API and Issuer web service fills in these

parameters as follows:



13

a) If during the onboarding Issuer has chosen “oaepHashingAlgorithm” =

“SHA256”, then sender sets CK_MECHANISM_TYPE = CKM_SHA256 and

CK_RSA_PKCS_MGF_TYPE = CKG_MGF1_SHA256.

b) If during the onboarding Issuer has chosen “oaepHashingAlgorithm” =

“SHA512”, then sender sets CK_MECHANISM_TYPE = CKM_SHA512 and

CK_RSA_PKCS_MGF_TYPE = CKG_MGF1_SHA512.

The sender exposes:

The digital envelope containing the one time key SK in encryptedKey.

The bulk encrypted data encryptedData containing the sensitive data.

The hashing algorithm used by the OAEP scheme, when chosen -

oaepHashingAlgorithm.

The public key fingerprint publicKeyFingerprint of the receiver Encryption Public

Key used by the encryption scheme for the computation of the digital envelope.

The initialization vector - iv - for the bulk encryption with AES in CBC block cipher

mode.

2.1.5 API Request / Response Common Elements and Headers

Every inbound and outbound request contains an element requestId which uniquely

identifies the request. Every response contains an element responseId which uniquely

identifies the response. The responseId may optionally use the corresponding requestId.

Note that the format and uniqueness of the requestId and responseId are not validated.

In the case of an operation reporting an error, the response (or an object within the

response) contains the element ’errorCode’ and optionally the element ’errorDescription’,

as defined in Appendix B -- Error Codes. Unless explicitly stated otherwise, no other

element (including 'Required' fields) is present if an error is reported.

The error elements can be returned in the response for any of the API calls.

2.1.5.1 Common Request Elements

requestId

Description: Unique identifier for the request.

Data Type: String

Max Length: 64

Required: Yes



14

2.1.5.2 Common Response Elements

responseId

Description: Unique identifier for the response.

Data Type: String

Max Length: 64

Required: Yes

errorCode

Description: Error code for the reason the operation failed.

Data Type: String

Max Length: 32

Required: Conditional – required if an error occurred performing the operation

errorDescription

Description: Error description of the reason the operation failed.

Data Type: String

Max Length: 256

Required: No

2.1.6 Retry Strategy

MDES will automatically retry 3 times with up to a 5-second wait between each attempt

of the DeliverActivationCode, NotifyServiceActivated, and NotifyTokenUpdated API calls

that fail with a:

Timeout

Connection failure

HTTP response code of 302, 500 or 503

If the call has not succeeded after the initial retries, MDES will attempt a second round of

3 retries with increasing time intervals between each retry. Between attempts the system

will wait 15 minutes, 30 minutes and then 2 hours. In the case of a 503, the Retry-After

header will be respected if present and will count as a retry.

The retry strategy for the RequestActivationMethods (RAM) API in combination with either

AuthorizeService (AS) API or the TokenizationAuthorization (TA) network messages

request is presented below:

1. MDES sends the AS API or the TA request and the RAM simultaneously, triggered

from the Digitize API request received from the Token Requestor.

In a normal flow, the order of receiving by the Issuer between the AS API request and the

RAM API request is not important. Regardless which of the API hits first the Issuer, its



15

server must threat the first received API independent of the second API arriving. Any of

the two flows below are “normal”, and must be always “expected”.

TR MDES Issuer

Digitize

ASRAM

Wat

ch D

og

Tim

er

(WD

T) =

5

se

con

ds

AS resp[AML1]]

RAM resp[AML2]

AML = AML2 || AML1

“Expected” order in the WDT window

TR MDES Issuer

Digitize

ASRAM

Wat

ch D

og

Tim

er

(WD

T) =

5

se

con

ds

AS resp[AML1]]

RAM resp[AML2]

AML = AML2 || AML1

RAMAS

“Un-expected” order in the WDT window

When a timeout is registered, the following flows may happen:

2. 1st Timeout:



16

a. AS/TA and RAM timeout after 5 seconds: MDES responds to the Digitize API

request with a 503 Service Unavailable with a retry after header, for the Token

Requestor to call back. At the same time MDES sends the AS/TA and the RAM

again with longer timeout. The timeout is extended to 7 seconds

TR MDES Issuer

Digitize

ASRAM

WD

T =

5 s

eco

nd

s

AS[AML1]

RAM[AML2]

503 Service Unavailable with a retry after header

WD

T = 7

sec

on

ds

AS (2nd)RAM (2nd)

...

b. AS/TA timeout, RAM response received: We still return the 503 and send the AS/TA

with the longer timeout. We retain the RAM response and do not send it again.



17

TR MDES Issuer

Digitize

ASRAM

WD

T =

5 s

eco

nd

s

AS[AML1]

RAM[AML2]

503 Service Unavailable with a retry after header

AS (2nd)

Store AML2

WD

T = 7

sec

on

ds

...

c. RAM timeout, AS/TA response received: MDES uses the decision from AS/TA. In

the case of yellow path MDES uses the Activation Methods List configured in MDES

or returned on the AS/TA. RAM is not resent.

TR MDES Issuer

Digitize

ASRAM

WD

T =

5

se

con

ds

RAM[AML2]Use decision from AS

AS[AML1]

In case of yellow path, use the AML configured in MDES or returned on

AS (AML2) ...

3. 2nd

timeout: If the AS/TA times out on the 2nd

attempt then MDES runs the rules

engine to get a decision. If the RAM times out on the 2nd

attempt then MDES uses the

AML in the database.



18

AS resp[AML1] (2nd)

Decision from Rules

TR MDES Issuer

WD

T =

7 s

eco

nd

s 2

RAM[AML2]

1Decision from Issuer Response

...

2.2 RequestActivationMethods

RequestActivationMethods advises an Issuer that a service activation has been requested

and that an Issuer should provide Activation Methods for the Account holder. The

Activation Methods will be presented to the Account holder so they may select their

preferred delivery channel to receive an Activation Code only when the card eligibility

decision is “Require Authentication.” If there are no methods to return then an empty

ActivationMethods array is returned. If verification of the card data provided in the

request fails then an empty ActivationMethods array should be returned. This includes an

unknown PAN or if the expiration date or the CVC2 do not match. This call is made as

part of the service activation flow and may be subject to strict time constraints based on

the service.

If applicable to the service, when no methods are returned or in case of service failure the

MDES system will use the methods returned by the pre-digitization network messages or

the default methods for the account range. The methods returned from this API will be

combined with the activation methods returned from the pre-digitization network

messages and any methods configured as forced.

2.2.1 URL Endpoint

/requestActivationMethods

2.2.2 HTTP Method

POST



19

2.2.3 Request Parameters

services

Description: Array of services that are being requested for the account.

Value Request

DIGITIZATION Provision the Funding Account to a device.

Data Type: Array[String]

Max Length: N/A

Required: Yes

cardInfo

Description: Contains card information of the card to be digitized.

Data Type: CardInfo object.

Max Length: N/A

Required: Deprecated – use fundingAccountInfo instead.

fundingAccountInfo

Description: Contains the information of the funding account to be tokenized. This

could be a credit card, debit card, bank account, or other type of

financial account. The token information will not be included.

Data Type: FundingAccountInfo object

Max Length: N/A

Required: Yes

correlationId

Description: Value linking pre-digitization messages generated during provisioning.

Data Type: String

Max Length: 14

Required: Yes

tokenRequestorId

Description: The party that requested the digitization.

Data Type: String(Numeric)

Max Length: 11(Exact)

Required: Conditional - Required if tokens are assigned by MDES.



20

walletId

Description: The identifier of the Wallet Provider who requested the digitization.

Only present when the token is provided to a Wallet Provider.

Data Type: String

Max Length: 3

Required: No

paymentAppInstanceId

Description: The identifier of the Payment App instance within a device that will be

provisioned with a token. Only present when supplied by a Wallet

Provider.

Data Type: String

Max Length: 48

Required: No

accountIdHash

Description: SHA-256 hash of the Account holder’s account ID with the Payment

App Provider. Typically expected to be an email address.

Data Type: String (Alpha-Numeric). Hex-encoded data (case-insensitive).

Max Length: 64

Required: No

mobileNumberSuffix

Description: The last few digits (typically four) of the device’s mobile phone number.

Data Type: String (Numeric)

Max Length: 32

Required: No

tokenType

Description: The type of token requested for this digitization.

Valid values are:

Value Meaning

EMBEDDED_SE Embedded Secure Element

CLOUD Mastercard Cloud-Based Payments

STATIC Static token

Data Type: String

Max Length: 16

Required: Yes



21

2.2.4 Response Values

activationMethods

Description: The activation methods to be used for this digitization. Return empty array if

no methods are to be returned.

Data Type: Array[ActivationMethod]

Required: Yes

2.2.5 Example Request Body

{

"requestId" : "123456",

"services" : [

"DIGITIZATION"

],

"fundingAccountInfo" : {

"encryptedPayload" : {

"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D

815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E82

4AA55BA67BF6A",

"publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b",

"encryptedKey" : "A1B2C3D4E5F6112233445566",

"oaepHashingAlgorithm" : "SHA512",

"iv" : "31323334353637383930313233343536"

}

"panUniqueReference" : "FWSPMC000000000159f71f703d2141efaf04dd26803f922b"

},

"correlationId" : "D98765432104",

"tokenRequestorId" : “12345678901”,

"walletId" : "123",

"paymentAppInstanceId" :

"1b24f24a24ba98e27d43e345b532a245e4723d7a9c4f624e93452c",

“accountIdHash” :

“5ae9c9890b326bd23bfa9db9672298ae3b10a9388e56ec17a001e191f24572aa”,

"mobileNumberSuffix" : "1234",

"tokenType" : "CLOUD"

}



22

2.2.6 Example Response Body

{

"responseId" : "123456",

"activationMethods" : [

{ "type" : "TEXT_TO_CARDHOLDER_NUMBER", "value" : "12X-XXX-XX32" }, { "type" : "CARDHOLDER_TO_CALL_AUTOMATED_NUMBER", "value" : "1-800-BANK-NUMBER" }, { "type" : "CARDHOLDER_TO_USE_MOBILE_APP", "value": "App Name" }

]

}

2.3 DeliverActivationCode

DeliverActivationCode is used to request an Activation Code be sent to authenticate the

Account holder.

MDES generates an Activation Code and delivers it, along with the chosen Activation

Code Distribution Method, to the Issuer for transmission to the Account holder.

Alternately if the Issuer wishes to generate the Activation Code, MDES will deliver the

chosen Activation Code Distribution Method to the Issuer and the Issuer will generate the

Activation code and transmit it to the account holder. The Account holder will then enter

the Activation Code into the Mobile Payment App.

Once an Activation Code has been generated, it will be valid for a limited activation

period, after which the code will expire. Once a code expires, the Issuer can request a new

Activation Code via the Customer Service Portal/API, or remotely activate the token via the

Customer Service Portal/API.

The Account holder may request the Activation Code again with the same or a different

Activation Code Distribution Method. This will trigger another request as long as the

activation period has not expired. It will not cause the Activation Code to be regenerated

nor extend the validity period of the Activation Code.

2.3.1 URL Endpoint

/deliverActivationCode



23

2.3.2 HTTP Method

POST


tokenUniqueReference

Description: A unique reference assigned following the allocation of a token used to

identify the token for the duration of its lifetime.

Data Type: String

Max Length: 64

Required: Yes

correlationId


Data Type: String

Max Length: 14

Required: Yes

activationCode

Description: The Activation Code to be distributed for the digitization.

Data Type: String

Max Length 32

Required: Conditional - only present if Mastercard generates the activationCode

expirationDateTime

Description: The DateTime when the Activation Code is no longer valid. Expressed in

ISO 8601 extended format as one of the following:

YYYY-MM-DDThh:mm:ss[.sss]Z

YYYY-MM-DDThh:mm:ss[.sss]±hh:mm

Where [.sss] is optional and can be 1 to 3 digits.

Data Type: String

Max Length 29

Required: Conditional - only present if Mastercard generates the activationCode



24

activationMethod

Description: The activation method selected by the Account holder.

Data Type: ActivationMethod

Max Length: NA

Required: Yes


Only common response elements


{

"requestId" : "123456",

"tokenUniqueReference" :

"DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",


"activationCode" : "A1B2C3D4",

"expirationDateTime" : "2016-07-04T12:08:56.123-07:00",

"activationMethod" : {

"type" : "CARDHOLDER_TO_CALL_AUTOMATED_NUMBER",

"value" : "1-800-BANK-NUMBER"

}

}


{

"responseId" : "123456"

}

2.4 NotifyServiceActivated

NotifyServiceActivated is used to receive notifications that the provisioning and activation

of a token for a Funding Account has been completed by the digitization service.

2.4.1 URL Endpoint

/notifyServiceActivated



25

2.4.2 HTTP Method

POST


services


Value Request



Max Length: N/A

Required: Yes

cardAndToken

Description: Contains card and token information of the card to be digitized.

Data Type: CardAndTokenInfo object.

Max Length: N/A


fundingAccountInfo



financial account. The token information will also be included.


Max Length: N/A

Required: Yes

deviceInfo

Description: Contains information about the target device to be provisioned.

Data Type: Map (DeviceInfo).

Max Length: N/A

Required: No



26

correlationId


Data Type: String

Max Length: 14

Required: Yes

tokenRequestorId




Required: Yes

walletId



Data Type: String

Max Length: 3

Required: No




Provider.

Data Type: String

Max Length: 48

Required: No

tokenType


Valid values are:

Value Meaning



STATIC Static token

Data Type: String

Max Length: 16

Required: Yes



27

secureElementId

Description: The identifier of the Secure Element to be provisioned with the token.

Present only when the token is provisioned to a Secure Element and

when provided by the Wallet Provider.

Data Type: String

Max Length: 128

Required: No

accountPanSuffix

Description: The last few digits (typically four) of the Account PAN being digitized.

Data Type: String

Max Length: 8

Required: Yes

serviceRequestDateTime

Description: The date and time the service for the PAN was requested. Expressed in

ISO 8601 extended format as one of the following:




Data Type: String

Max Length: 29

Required: Yes

termsAndConditionsAssetId

Description: The Terms and Conditions as presented to and accepted by the Account

holder.

Data Type: String

Max Length: 64

Required: No

termsAndConditionsAcceptedTimestamp

Description: The date and time the Terms and Conditions were accepted by the

Account holder. Expressed in ISO 8601 extended format as one of the

following:




Data Type: String

Max Length: 29

Required: No



28

productConfigurationId

Description: Freeform identifier for the product configuration as assigned by the

Issuer.

Data Type: String

Max Length: 64

Required: No

consumerLanguage

Description: Language preference selected by the consumer. Formatted as an ISO-

639-1 two-letter language code.

Data Type: String

Max Length: 2

Required: No

decision

Description: The authorization decision for the service request.

Must be one of:

Value Meaning

APPROVED Service request was approved.

REQUIRE_ADDITIONAL_AUTHENTICATION Service request requires

additional authentication to be

approved.

One or more Activation Methods

will be provided.

Data Type: String

Max Length: 64

Required: Yes

decisionMadeBy

Description: The process that determined the final authorization decision for the

request. Must be one of:

Value Meaning

ELIGIBILITY_REQUEST The decision was made by the

eligibility request to the Issuer.

AUTHORIZATION_REQUEST The decision was made by the

authorization request to the

Issuer.

RULES The decision was made by the

rule engine.

Data Type: String

Max Length: 32

Required: No



29

tokenActivatedDateTime

Description: Expressed in ISO 8601 extended format as one of the following:




Data Type: String

Max Length: 29

Required: Yes

numberOfActivationAttempts

Description: The number of times an Activation Code was received to activate the

token.

Data Type: Number

Max Length: 1

Required: No

numberOfActiveTokens

Description: The number of active tokens for the Funding Account. Valid values are

0-99. A value of 99 means there are 99 or more active tokens. Tokens

that have been deleted from the wallet are excluded from the count.

Data Type: Number

Max Length: 2

Required: No

tokenAssuranceLevel

Description: The assurance level assigned to the token.

Data Type: Number

Max Length: 2

Required: No




{

"requestId" : "123456",

"services" : [

"DIGITIZATION"

],





30

"encryptedData":"4545433044323232363739304532433610DE1D1461475

BEB6D815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469

537FE461E824AA55BA67BF6A",




"iv" : "31323334353637383930313233343536",

},



"panUniqueReference" :

"FWSPMC000000000159f71f703d2141efaf04dd26803f922b"

},

deviceInfo" : {

"deviceName" : "My Phone",

"serialNumber" : "2F6D63",

"formFactor" : "PHONE",

"isoDeviceType" : "09",

"osName" : "ANDROID",

"osVersion" : "4.4",

"imei" : "352099001761481",

"msisdn" : "7307406945",

"paymentTypes" : ["NFC"],

"storageTechnology" : "SE"

"cardCaptureTechnology" : "CAMERA"

},



"walletId" : "123",



"tokenType" : "CLOUD",

"secureElementId" :

"1b24f24a24ba98e27d43e345b532a245e4723d7a9c4f624e93452c"

"accountPanSuffix": "1234",

"serviceRequestDateTime": "2015-07-04T12:08:56.123-07:00",

"termsAndConditionsAssetId" : " a9f027e5-629d-11e3-949a-0800200c9a66",

"termsAndConditionsAcceptedTimestamp" : "2015-07-04T12:09:56.123-07:00",

"productConfigurationId" : "1234",

"consumerLanguage" : "en",

"decision" : "REQUIRE_ADDITIONAL_AUTHENTICATION",

"decisionMadeBy" : "RULES”,



31

"tokenActivatedDateTime" : "2015-07-04T12:09:57.123-07:00",

"numberOfActivationAttempts" : 1,

"numberOfActiveTokens" : 2,

"tokenAssuranceLevel": 1

}


{


}

2.5 AuthorizeService

AuthorizeService requests an Issuer to authorize a Funding Account for a Mastercard

service or set of services. Information about the service request will be provided to assist

with authorization of the account.

If additional authentication is required the Issuer may return a list of Activation Methods.

The Activation Methods will be presented to the Account holder so they may select their

preferred delivery channel to receive an Activation Code. If there are no methods to

return the field may be omitted. This call is made as part of the service activation flow

and may be subject to strict time constraints based on the service.

2.5.1 URL Endpoint

/authorizeService

2.5.2 HTTP Method

POST



32


services


Value Request



Max Length: N/A

Required: Yes

cardInfo

Description: Contains card information of the card to be digitized.

Data Type: CardInfo object.

Max Length: N/A


fundingAccountInfo





Max Length: N/A

Required: Yes

correlationId


Data Type: String

Max Length: 14

Required: Yes

tokenRequestorId




Required: Conditional - Required if tokens are assigned by MDES.



33

walletId



Data Type: String

Max Length: 3

Required: No




Provider.

Data Type: String

Max Length: 48

Required: No

accountIdHash

Description: SHA-256 hash of the Account holder’s account ID with the Payment

App Provider. Typically expected to be an email address.

Data Type: String (Alpha-Numeric). Hex-encoded data (case-insensitive).

Max Length: 64

Required: No

mobileNumberSuffix

Description: The last few digits (typically four) of the device’s mobile phone number.


Max Length: 32

Required: No

deviceInfo

Description: Contains information about the target device to be provisioned.

Data Type: Map (DeviceInfo).

Max Length: N/A

Required: No

walletProviderDecisioningInfo

Description: Contains information about the decision recommended by the Wallet

Provider.

Data Type: Map (DecisioningInfo).

Max Length: N/A

Required: No



34

activeTokenCount

Description: The number of active tokens that already exist for the Funding Account

based on the token type. Secure Element and Cloud tokens are

counted together. Valid values are 0-99. A value of 99 means there

are 99 or more active tokens. Tokens that have been deleted from the

wallet are excluded from the count.

Data Type: String (Numeric).

Max Length: 2

Required: No

tokenType


Valid values are:

Value Meaning



STATIC Static token

Data Type: String

Max Length: 16

Required: Yes


services

Description: Array of services for the account that the authorization decision applies

to. Must be a subset of the services in the request object. Services that

are not approved for the account will be omitted.

Value Request



Max Length: N/A

Required: Yes



35

decision

Description: The authorization decision for the authorization of the requested

services.

Must be one of:

Value Meaning

APPROVED Services request was approved.

DECLINED Services request was declined.

REQUIRE_ADDITIONAL_AUTHENTICATION Services request requires


approved.

One or more Activation Methods

may be provided.

Data Type: String

Max Length: 64

Required: Yes

activationMethods

Description: The activation methods to be used for this digitization. Return empty array if

no methods are to be returned.

Data Type: Array[ActivationMethod]

Required: No

panSequenceNumber

Description: The pan sequence number for the card. Acceptable values are in the range

000 – 099.

Data Type: String(numeric)

Max Length: 3

Required: No

issuerProductConfigId

Description: The unique Issuer identifier assigned to the product configuration in BPMS. It is

provided for the Digitization service only.

Data Type: String

Max Length: 10

Required: No



36

encryptedPayload

Description: Contains the encrypted AuthorizeServiceResponseData object.

Data Type: EncryptedPayload object containing an AuthorizeServiceResponseData

object.

Sample unencrypted object:

{

"paymentAccountReference":"512381d9f8e0629211e3949a08002",

"externalToken" : {

"token" : "5345678901234521",

"expiryMonth" : "10",

"expiryYear" : "17",

"sequenceNumber" : "01"

},

"alternateAccountIdentifier" : "GB82WEST12345698765432"

}

Max Length: N/A

Required: No

cvcResponse

Description: The result of the CVC2 validation performed against the value provided

by the account holder.

Must be one of:

Value Meaning

MATCH Valid CVC2

INVALID Invalid CVC2

NOT_PROCESSED CVC2 was not processed (issuer

temporarily unavailable).

Data Type: String

Max Length: 32

Required: No



37

avsResponse

Description: The result of the address validation performed against the values

provided by the account holder.

Must be one of:

Value Meaning

POSTAL_DOES_NOT_MATCH Address matches, postal code does not.

ADDRESS_AND_POSTAL_DO_NOT_MATCH Neither address nor postal code matches.

RETRY Retry, system unable to process.

AVS_NOT_SUPPORTED AVS currently not supported.

NO_DATA No data from issuer/Authorization Platform

ADDRESS_DOES_NOT_MATCH W = For U.S. addresses, nine-digit postal code matches, address does not; for address outside the U.S., postal code matches, address does not.

ADDRESS_AND_POSTAL_MATCH X = For U.S. addresses, nine-digit postal code and address matches; for addresses outside the U.S., postal code and address match.

US5_ADDRESS_AND_POSTAL_MATCH Y = For U.S. addresses, five-digit postal code and address matches.

US5_ ADDRESS_DOES_NOT_MATCH Z = For U.S. addresses, five-digit postal code matches, address does not.

Data Type: String

Max Length: 32

Required: No



38

tokenRequestorId




Required: Conditional - required if tokens are generated by external provider, not

present otherwise.

tcis

Description: Array of terminal capability TCIs.


Max Length: NA

Required: No

auxTcis

Description: Array of auxiliary terminal capability TCIs.


Max Length: NA

Required: No


{

"requestId" : "123456",

"services" : [

"DIGITIZATION"

],




BEB6D815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469

537FE461E824AA55BA67BF6A",




"iv" : "31323334353637383930313233343536"

}

"panUniqueReference" :

"FWSPMC000000000159f71f703d2141efaf04dd26803f922b"

},




39


"walletId" : "123",



"accountIdHash" :

"5ae9c9890b326bd23bfa9db9672298ae3b10a9388e56ec17a001e191f24572aa",

"mobileNumberSuffix" : "1234",

"activeTokenCount" : "3",

"deviceInfo" : {

"deviceName" : "My Phone",

"serialNumber" : "2F6D63",

"formFactor" : "PHONE",

"isoDeviceType" : "09",

"osName" : "ANDROID",

"osVersion" : "4.4",

"imei" : "352099001761481",

"msisdn" : "7307406945",

"paymentTypes" : ["NFC"],

"storageTechnology" : "SE"

"cardCaptureTechnology" : "CAMERA"

},

"walletProviderDecisioningInfo" : {

"recommendedDecision" : "REQUIRE_ADDITIONAL_AUTHENTICATION",

"recommendationStandardVersion" : "1.0.0",

"deviceScore" : "3",

"accountScore" : "4",

"recommendationReasons" : ["ACCOUNT_TOO_NEW",

"DEVICE_RECENTLY_LOST", "OUTSIDE_HOME_TERRITORY"]

},

"tokenType" : "CLOUD"

}


{


"services" : ["DIGITIZATION"],

"decision" : "REQUIRE_ADDITIONAL_AUTHENTICATION",

"activationMethods" : [

{



40

"type" : "TEXT_TO_CARDHOLDER_NUMBER",

"value" : "12X-XXX-XX32"

},

{

"type" : "CARDHOLDER_TO_CALL_AUTOMATED_NUMBER",

"value" : "1-800-BANK-NUMBER"

},

{

"type" : "CARDHOLDER_TO_USE_MOBILE_APP",

"value": "App Name"

}

],

"panSequenceNumber" : "001",

"issuerProductConfigId" : "I1234D7890",



75BEB6D815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE32

1469537FE461E824AA55BA67BF6A",

"publicKeyFingerprint" :

"4c4ead5927f0df8117f178eea9308daa58e27c2b",



"iv" : "31323334353637383930313233343536"

},

"cvcResponse" : "MATCH",

"avsResponse" : "ADDRESS_AND_POSTAL_MATCH"

}

2.6 NotifyTokenUpdated

NotifyTokenUpdated is used by MDES to notify the Issuer of significant token updates, such

as when the token is activated, suspended, unsuspended or deleted; or when information

about the token or its product configuration has changed.

It may be triggered as a result of Service Provider update (for example, the provider suspends

or deletes the token), or if MDES changes the state of a token (for example, when Account

holder activates the token using an Activation Code).

The state transition diagram used by MDES is presented in the figure below:



41

2.6.1 URL Endpoint

/notifyTokenUpdated

2.6.2 HTTP Method

POST


tokens

Description: Contains the Tokens which were updated.

Data Type: Array[Token object]

Max Length: N/A

Required: Yes

Digitize

Inactive

Active

Deactivated

Provision

Activate

Delete

Suspended

Suspend

3rd Unsuspend(S1, S3)

Delete

Delete

NSA

NTU (Staus=Deactivated)

NTU(Status=Suspended, SuspendedBy[S1, S2])

NTU(Status=Active)

Update

Update

NTU(Status = Deactivated)

NTU(Status=Deactivated)

NTU(Status=Suspended,

SuspendedBy[S1])

NTU(Status=Suspended,

SuspendedBy[S1, S3])

2nd Suspend (S3)

1st Unsuspend (S2)

CS PAN SWAP

0302 PAN SWAP

Update

CS PAN SWAP

0302 PAN SWAP

Update

Token Configuration Update


Update


NTU(Re-Digitized)

Update Token Expiry

NTU(Re-Digitized)

Update Token Expiry



42

reasonCode

Description: The reason code for why the notification is being sent. This applies to

all tokens in the Tokens array.

Must be one of:

Value Meaning

STATUS_UPDATE The status of the token has been

changed.

REDIGITIZATION_COMPLETE The token has been re-digitized

to the device.

DELETED_FROM_CONSUMER_APP The token has been deleted from

the consumer application. The

token may still be active.

Data Type: String

Max Length: 32

Required: Yes

2.6.4 Response Parameters


2.6.5 Example Request Body – STATUS_UPDATE

{ "requestId" : "123456", "tokens" : [

{ "tokenUniqueReference" : "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45", "status" : "ACTIVE" }, { "tokenUniqueReference" : "DWSPMC00000000032d72d4ffcb2f4136a0532d32d72d4fcb", "status" : "ACTIVE"

}, { "tokenUniqueReference" : "DWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532", "status" : "SUSPENDED",

"suspendedBy" : ["TOKEN_REQUESTOR"] } ], "reasonCode" : "STATUS_UPDATE"

}



43

2.6.6 Example Request Body – REDIGITIZATION_COMPLETE


{ "tokenUniqueReference" : "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45", "tokenExpiry" : "0520" }, { "tokenUniqueReference" : "DWSPMC00000000032d72d4ffcb2f4136a0532d32d72d4fcb", "tokenExpiry" : "0620"

}, { "tokenUniqueReference" : "DWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532", "tokenExpiry" : "0720"

} ], "reasonCode" : "REDIGITIZATION_COMPLETE"

}

2.6.7 Example Request Body – DELETED_FROM_CONSUMER_APP


{ "tokenUniqueReference" : "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45" }, { "tokenUniqueReference" : "DWSPMC00000000032d72d4ffcb2f4136a0532d32d72d4fcb"

}, { "tokenUniqueReference" : "DWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532" } ], "reasonCode" : "DELETED_FROM_CONSUMER_APP"

}


{


}



44

2.7 ValidateActivationCode

This API is used to activate a Token for first-time use if the digitization decision was to

‘Require Additional Authentication’ in the Digitize response.

A Token may be activated via this API when activation is requested with activationCode

and Issuer have chosen the option to validate the code self.

If activation code validation is successful, MDES will complete the provisioning process and

will notify the Token Requestor when the Token is ready to transact, using the Notify

Token Updated API

Note that the user is only given a limited number of attempts to enter a correct Activation

Code (typically 3 attempts), after which the Activation Code becomes invalid. In this event,

it may be possible to request a new Activation Code directly from the Issuer via customer

service or otherwise. This is dependent on individual Issuer implementation and out of

scope of this API.

2.7.1 URL Endpoint

/validateActivationCode

2.7.2 HTTP Method

POST





Data Type: String

Max Length: 64

Required: Yes

correlationId


Data Type: String

Max Length: 14

Required: Yes



45

activationCode

Description: The Activation Code entered by the consumer.

Data Type: String (Alpha-Numeric)

Max Length 32

Required: Yes


result

Description: Whether the activation request was successful.

Success will result in MDES attempting to complete the provisioning

process. MDES will notify the Token Requestor when the Token is ready

to transact.

Must be one of:

Value Request

SUCCESS Activation was successful

INCORRECT_CODE Activation Code was incorrect and

rejected. Retries permitted.

INCORRECT_CODE_RETRIES_EXCEEDED Activation Code was incorrect and the

maximum number of retries now

exceeded.

EXPIRED_CODE Activation Code has expired or was

invalidated.

Data Type: String

Max Length: 32

Required: Yes


{

"requestId" : "123456",




"activationCode" : "A1B2C3D4"

}



46


{


"result" : "SUCCESS"

}

2.8 Get Account Information

Get Account Information requests an Issuer to return information about a funding

account for a Mastercard service or set of services. Balance information and the status of

the funding account can be returned by the transit operator. Only applicable to transit

operators.

2.8.1 URL Endpoint

/getAccountInformation

2.8.2 HTTP Method

POST


fundingAccountInfo





Max Length: N/A

Required: Yes



47


encryptedPayload

Description: Contains the encrypted AccountInformationData object

Data Type: EncryptedPayload object containing an AccountInformationData object.


{

" balanceInformation " : {

"amount": 25.36,

"currencyCode" : "USD",

"balanceDateTime" : "2018-07-04T12:08:56.123-07:00"

},

"accountStatus" : "ACTIVE"

}

Max Length: N/A

Required: No


{

"requestId" : "123456",



"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D

815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E82

4AA55BA67BF6A",




"iv" : "31323334353637383930313233343536"

}

"panUniqueReference" : "FWSPMC000000000159f71f703d2141efaf04dd26803f922b"

},

}


{



"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D815F

31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E824AA55B

A67BF6A",



48




"iv" : "31323334353637383930313233343536"

},

}



49

A. Appendix A – Request and Response Member Objects

A.1 AccountHolderData

accountHolderName

Description: The name of the account holder in the format LASTNAME/FIRSTNAME

or FIRSTNAME LASTNAME.

Data Type: String

Max Length: 27

Required: No

accountHolderAddress

Description: The address for the account holder. Verified as part of reaching the

digitization decision.

Data Type: BillingAddress object

Max Length: N/A

Required: No

sourceIp

Description: The IP of the device initiating the request.

Data Type: String

Max Length: 64

Required: No

deviceLocation

Description: Latitude and longitude where the device the consumer is attempting to

authorize is located. In the format “(sign) latitude/(sign) longitude”

with a precision of 2 decimal places. Ex: "38.63/-90.2" Latitude is

between -90 and 90. Longitude between -180 and 180.

Data Type: String

Max Length: 64

Required: No

consumerIdentifier

Description: Consumer Identifier provided by the token requestor.

Data Type: String

Max Length: 88

Required: No – Optionally present in AuthorizeService when provided by the

wallet provider



50

accountHolderEmailAddress

Description: The email address of the account holder.

Data Type: String

Max Length: 320

Required: No. Optionally present in pushAccount request. Not present otherwise.

accountHolderMobilePhoneNumber

Description: The mobile phone number of the account holder.

Data Type: PhoneNumber

Max Length: NA

Required: No.

A.2 AccountInformationData

balanceInformation

Description: The balance information for the account.

Data Type: BalanceInformation object

Max Length: NA

Required: Yes

accountStatus

Description: The status of the account.

Must be one of:

Value Meaning

ACTIVE The account is active.

EXPIRED The account is expired.

INVALID The account is not recognized.

UNKNOWN The account is in an unknown state.

CANCELLED The account is cancelled.

Data Type: String

Max Length: 24

Required: Yes



51

A.3 AuthorizeServiceResponseData

paymentAccountReference

Description: The payment account reference assigned to the PAN. This should only

be returned if Mastercard is not the BIN controller. It will be ignored if

Mastercard is the BIN controller for the PAN.

Data Type: String(AlpahNumeric)

Max Length: 29 (Exact)

Required: No

externalToken

Description: The token information

Data Type: TokenData

Max Length: NA

Required: No

alternateAccountIdentifier

Description: Account holder-friendly reference to a bank account. Typically used when the account holder is not aware of their Account PAN.

Data Type: String(Spaces not allowed)

Max Length: 64 (min length 9)

Required: No

dataValidUntilTimestamp

Description: The date/time after which this encrypted payload object is considered

invalid. If present, all systems must reject this encrypted object after this

time and treat it as invalid data.

Must be expressed in ISO 8601 extended format as one of the

following:




Must be a value no more than 30 days in the future. Mastercard

recommends using a value of (Current Time + 30 minutes).

Data Type: String

Max Length: 29

Required: No



52

A.4 ActivationMethod

Type

Description: Specifies the activation method type.

Must be one of:

Type Meaning Value

Required

TEXT_TO_CARDHOLDER_NUMBER Text message to Account holder's

mobile phone number.

Value will be the Account holder’s

masked mobile phone number.

Yes

EMAIL_TO_CARDHOLDER_ADDRESS Email to Account holder's email

address.


masked email address.

Yes

CARDHOLDER_TO_CALL_AUTOMATED_NUMBER Account holder-initiated call to

automated call center phone number.

Value will be the phone number for the

Account holder to call.

Yes

CARDHOLDER_TO_CALL_MANNED_NUMBER Account holder-initiated call to manned

call center phone number.

Value will be the phone number for the

Account holder to call.

Yes

CARDHOLDER_TO_VISIT_WEBSITE Account holder to visit a website.

Value will be the website URL.

Yes

CARDHOLDER_TO_USE_MOBILE_APP Account holder to use a specific mobile

app to activate token.

Value will be replaced by a formatted

string.

Yes

ISSUER_TO_CALL_CARDHOLDER_NUMBER Issuer-initiated voice call to Account

holder’s phone.


masked voice call phone number.

Yes

Data Type: String

Max

Length:

64

Required: Yes

value

Description: Specifies the activation method value (meaning varies depending on the

activation method type).

Data Type: String

Max Length: 64

Required: Yes



53

A.5 BalanceInformation

amount

Description: The amount of the balance. Numeric including the decimal positions.

Data Type: Number

Max Length: 16

Required: Yes

currencyCode

Description: The currency code defined using ISO 4217.

Data Type: String

Max Length: 3

Required: Yes

balanceDateTime

Description: The DateTime when the balance was checked. Expressed in ISO 8601

extended format as one of the following:




Data Type: String

Max Length: 29

Required: Yes

A.6 BillingAddress

line1

Description: First line of the billing address.

Data Type: String

Max Length: 64

Required: No

line2

Description: Second line of the billing address.

Data Type: String

Max Length: 64

Required: No



54

city

Description: The city of the billing address.

Data Type: String

Max Length: 32

Required: No

countrySubdivision

Description: The country subdivision (for example, the state in the U.S.) of the billing

address.

Data Type: String

Max Length: 12

Required: No

postalCode

Description: The postal code (for example, zipcode in the U.S.) of the billing address.

Data Type: String

Max Length: 16

Required: No

country

Description: The country of the billing address. Expressed as a 3-letter (alpha-3)

country code as defined in ISO 3166-1.

Data Type: String


Required: No

A.7 CardAccountData

accountNumber

Description: The Account Primary Account Number of the card to be digitized



Required: Yes



55

expiryMonth

Description: The month of the expiration date of the card to be digitized. Note that

the expiry date may not be in the past.

May be omitted if the card does not have an expiry date.



Required: No.

expiryYear

Description: The year of the expiration date of the card to be digitized. Note that the

expiry date may not be in the past.




Required: No.

securityCode

Description: The CVC2 for the card to be digitized, as entered by the Cardholder.

Verified as part of reaching the digitization decision.



Required: No

A.8 CardAndTokenData - Deprecated

card

Description: The account PAN information

Data Type: CardInfoData

Max Length: NA

Required: Yes

token

Description: The token information


Max Length: NA

Required: Yes



56


Description: The unique account reference assigned to the PAN.

Data Type: String


Required: No

A.9 CardAndTokenInfo - Deprecated

panUniqueReference

Description: Reference to the PAN that is unique per Wallet Provider.

Data Type: String

Max Length: 64

Required: Yes


Description: Unique reference to the token to be designated when digitization is complete.

Data Type: String

Max Length: 64

Required: Yes

publicKeyFingerprint

Description:

The fingerprint of the public key used to encrypt the ephemeral AES

key.

Data Type: String. Hex-encoded data (case-insensitive).

Max Length: 64

Required: Yes

encryptedKey

Description: One-time use AES key encrypted by the Issuer's public key (as

identified by 'publicKeyFingerprint') using the OAEP scheme.

Requirement is for a 128-bit key (with 256-bit key supported as an

option).


Max Length: 512

Required: Yes



57

oaepHashingAlgorithm

Description: Hashing algorithm used with the OAEP scheme.

If omitted, then the RSA Encryption Standard PKCS #1 v1.5 will be used.

Must be one of:

Value Meaning

SHA256 Use the SHA-256 algorithm


Data Type: String

Max Length: 6

Required: No

iv

Description: The initialization vector used when encrypting data using the one-time

use AES key. Must be exactly 16 bytes (32 character hex string) to

match the block size.

If not present, an IV of zero is assumed.



Required: No



58

encryptedData

Description: Contains the encrypted CardAndTokenData object containing the Account

PAN and token information. Encrypted by the ephemeral AES key using

CBC mode (IV as provided in 'iv', or zero if none provided) and PKCS#7

padding.


{

"card" : {

"accountNumber" : "5123456789012345",



"source" : "CARD_ON_FILE",

"cardholderName" : "John Doe",

"securityCode" : "123",

“cardholderData”: {

"sourceIp" : "127.0.0.1",

"deviceLocation" : "38.63/-90.2"

}

},

"token" : {

"token" : "5345678901234521",



"sequenceNumber" : "01

},

"paymentAccountReference" :

"5001a9f027e5629d11e3949a0800a"

}


Max

Length:

256K

Required: Yes

A.10 CardholderData - Deprecated

sourceIp

Description: The IP of the device initiating the request.

Data Type: String



59

Max Length: 64

Required: No

deviceLocation

Description: Latitude and longitude where the device the consumer is attempting to

authorize is located. In the format “(sign) latitude/(sign) longitude”

with a precision of 2 decimal places. Ex: "38.63/ -90.2" Latitude is

between -90 and 90. Longitude between -180 and 180.

Data Type: String

Max Length: 64

Required: No

consumerIdentifier

Description: Consumer Identifier provided by the token requestor.

Data Type: String

Max Length: 88

Required: No – Optionally present in AuthorizeService when provided by the

wallet provider

A.11 CardInfo - Deprecated

panUniqueReference


Data Type: String

Max Length: 64

Required: No


Description: The fingerprint of the public key used to encrypt the ephemeral AES key.


Max Length: 64

Required: Yes



60

encryptedKey

Description: One-time use AES key encrypted by the Issuer's public key (as identified

by 'publicKeyFingerprint') using the OAEP scheme.


option).


Max Length: 512

Required: Yes



If omitted, then the RSA Encryption Standard PKCS #1 v1.5 will be

used.Must be one of:

Value Meaning



Data Type: String

Max Length: 6

Required: No

iv







Required: No



61

encryptedData

Description: Contains the encrypted CardInfoData object containing the Account PAN

information. Encrypted by the ephemeral AES key using CBC mode (IV as

provided in 'iv', or zero if none provided) and PKCS#7 padding.


{

"accountNumber" : "5123456789012345",



"source" : "CARD_ON_FILE",

"cardholderName" : "John Doe",

"securityCode" : "123",

“cardholderData”: {

"sourceIp" : "127.0.0.1",

"deviceLocation" : "38.63/-90.2"

}

}


Max

Length:

256 K

Required: Yes

A.12 CardInfoData - Deprecated

accountNumber

Description: The Account PAN of the card associated with the service or the token

PAN.



Required: Yes

expiryMonth

Description: The month of the expiration date of the card to be digitized. Note that





Required: No



62

expiryYear

Description: The year of the expiration date of the card to be digitized. Note that





Required: No

source

Description: The source of this card information. Must be one of:

Value Meaning

CARD_ON_FILE Source was an existing card on

file.

CARD_ADDED_MANUALLY Source was a new card entered

manually be the Cardholder.

CARD_ADDED_VIA_APPLICATION Source was a new card added

by another application (for

example, Issuer banking app).

Data Type: String

Max Length: 32

Required: No – Optionally present for Account PAN.

cardholderName

Description: The name of the Cardholder in the format LASTNAME/FIRSTNAME or

FIRSTNAME LASTNAME.

Data Type: String

Max Length: 27

Required: No – Optionally present for Account PAN.



63

securityCode

Description: The CVC2 for the card to be digitized, as entered by the

Cardholder. Verified as part of reaching the digitization decision.



Required: No


Description: The date/time after which this CardInfoData object is considered

invalid. If present, all systems should reject this CardInfoData

object after this time and treat it as invalid data.


following:






Data Type: String

Max Length: 29

Required: No

billingAddress

Description: Cardholder billing address information.

Data Type: BillingAddress

Required: No

cardholderData

Description: Cardholder information used for authorizing the account.

Data Type: CardHolderData

Required: No



64

A.13 DecisioningInfo – MAP<String, Object>

recommendedDecision

Description: The decision recommended by the Wallet Provider.

Must be one of:

Value Meaning

APPROVED Services request was approved.

DECLINED Services request was declined.

REQUIRE_ADDITIONAL_AUTHENTICATION Services request requires


approved.

Data Type: String

Max Length: 64

Required: No

recommendationStandardVersion

Description: The standards version used by the Wallet Provider to determine the

recommended decision.

Data Type: String

Max Length: 64

Required: No

deviceScore

Description: Score given to the device by the Wallet Provider. Value between 1 and 5


Max Length: 64

Required: No

accountScore

Description: Score given to the account by the Wallet Provider. Value between 1 and

5

Data Type: String

Max Length: 64

Required: No



65

recommendationReasons

Description: Reasons provided to the Wallet Provider on how the recommended

decision was reached. Values for reason codes are defined in Appendix

C.


Max Length: NA

Required: No

phoneNumberScore

Description: Score given to the phone number by the Wallet Provider. Value

between 1 and 5

Data Type: String

Max Length: 64

Required: No

accountLifeTime

Description: The lifetime of the account with the Token Requestor.


Max Length: 2

Required: No

A.14 DeviceInfo – MAP<String, Object>

deviceName

Description: The name that the Account holder has associated to the device with the

Payment App Provider.

Data Type: String

Max Length: 64

Required: No

serialNumber

Description: The serial number of the device. May be masked.

Data Type: String

Max Length: 64

Required: No



66

isoDeviceType

Description: The 2 digit device type provided on the iso messages that the token is

being provisioned to. Only present when provided by a Wallet Provider.

See Global Communication bulletins for values.

Data Type: String

Max Length: 2

Required: No



67

formFactor

Description: The form factor of the device to be provisioned. New values can be

added without notice and should be accepted.

Must be one of:

Value Meaning

PHONE Mobile phone.

TABLET Tablet computer

TABLET_OR_EREADER Tablet computer or e-reader.

WATCH Watch

WATCH_OR_WRISTBAND Watch or wristband, including a fitness band,

smart strap, disposable band, watch add-on,

security / ID Band

CARD Card

STICKER Sticker

PC PC or Laptop

DEVICE_PERIPHERAL Device peripherals, such as a mobile phone case or

sleeve

TAG Tag, such as a key fob or mobile tag

JEWELRY Jewelry, such as a ring, bracelet, necklace and cuff

links

FASHION_ACCESSORY Fashion accessory, such as a handbag, bag charm,

glasses

GARMENT Garment, such as a dress

DOMESTIC_APPLIANCE Domestic appliance, such as a refrigerator,

washing machine

VEHICLE Vehicle, including vehicle attached devices

MEDIA_OR_GAMING_DEVICE Media or gaming device, including a set top box,

media player, television

UNDEFINED Device type that is not yet defined. Used for

wallets introducing a new device type that is not

yet public knowledge.

Data Type: String

Max Length: 64

Required: No



68

storageTechnology

Description:

The architecture or technology used for token storage.

Must be one of:

Value Meaning

DEVICE_MEMORY Device memory.

DEVICE_MEMORY_PROTECTED_TPM Device memory using a protected trust

platform module.

TEE Trusted execution environment.

SE Secure element.

SERVER Server host.

VEE Virtual Execution Environment

Data Type: String

Max Length: 32

Required: No

osName

Description: The name of the device operating system.

Must be one of:

Value Meaning

ANDROID Google Android operating system.

WINDOWS Microsoft Windows operating system.

TIZEN Tizen operating system.

IOS Apple iOS operation system.

PAGARE_EMBEDDED

_OS

FitPay embedded operating system

ANDROID_WEAR Android wear operating system

EMBEDDED_OS All Embedded operating system and Real time Operating

systems

Data Type: String

Max Length: 32

Required: No

osVersion

Description: The version of the device operating system.

Data Type: String (supports numbers and decimals).

Max Length: 32

Required: No



69

paymentTypes

Description: Different types of Payments supported for the token.

Must be one of:

Value Meaning

NFC The token is NFC capable

DSRP The token is DSRP capable

ECOMMERCE The token can be used for e-commerce transactions.


Max Length: N/A

Required: No

imei

Description: The IMEI number of the device being provisioned.

Data Type: String


Required: No

msisdn

Description: The MSISDN of the device being provisioned.

Data Type: String

Max Length: 15

Required: No

cardCaptureTechnology

Description: The technology used to capture the card details. New values can be

added at any time and must not result in an error.

Must be one of:

Value Meaning

CAMERA The card details were captured using the device camera.

MANUAL The card details were manually entered.

UNKNOWN It is not known how the card details were entered.

READER_MODE The card details were captured using reader mode.

Data Type: String

Max Length: 32

Required: No



70

A.15 EncryptedPayload


Description: The fingerprint of the public key used to encrypt the ephemeral AES

key.


Max Length: 64

Required: Yes

encryptedKey

Description: One-time use AES key encrypted by the Mastercard public key (as

identified by 'publicKeyFingerprint') using the OAEP or RSA Encryption

Standard PKCS #1 v1.5 (depending on the value of

'oaepHashingAlgorithm'.


option).


Max Length: 512

Required: Yes



If omitted, then the RSA Encryption Standard PKCS #1 v1.5 will be

used.

Must be one of:

Value Meaning



Data Type: String

Max Length: 6

Required: No.



71

iv







Required: No

encryptedData

Description: Contains an encrypted json object. Encrypted by the ephemeral AES key

using CBC mode (IV as provided in 'iv', or zero if none provided) and

PKCS#7 padding. The JSON object being encrypted will be defined in

the context of the API call.


Max Length: 256 K

Required: Yes

A.16 FinancialAccountData

financialAccountId

Description: The identifier of the financial account being tokenized. This could be a

bank account number or other types of financial accounts.

Data Type: String(Spaces not allowed)


Required: Yes

interbankCardAssociationId

Description: The id assigned by Mastercard to the financial institution.

Data Type: Number


Required: Yes



72

countryCode

Description: The country of the financial account. Expressed as a 3-letter (alpha-3)

country code as defined in ISO 3166-1.

Data Type: String


Required: Yes

A.17 FundingAccountData

cardAccountData

Description: The credit or debit card information for the account that is being

tokenized.

Data Type: CardAccountData

Max Length: N/A

Required: Yes

financialAccountData

Description: The financial account information for the account that is being

tokenized. This could be a bank account or other type of financial

account.

Data Type: FinancialAccountData

Max Length: N/A

Required: Conditional – Required if there is a bank account or other type of

financial account being tokenized.

accountHolderData

Description: Additional information that can be used to identify the account holder,

such as name, address, etc.

Data Type: AccountHolderData

Max Length: N/A

Required: No.

tokenData

Description: The token information.


Max Length: NA

Required: Conditional – required in NotifyServiceActivated, not present otherwise.



73

source

Description: The source of the account information.

Must be one of:

Value Meaning

ACCOUNT_ON_FILE Source was an existing account on file.

ACCOUNT _ADDED_MANUALLY Source was new account entered manually

by the account holder.

ACCOUNT_ADDED_VIA_APPLICATION Source was new account added by another

application (for example, Issuer banking

app).

Data Type: String

Max Length: 32

Required: No


Description: The unique account reference assigned to the PAN.

Data Type: String


Required: No


Description: The date/time after which this encrypted object is considered invalid. If

present, all systems must reject this encrypted object after this time and

treat it as invalid data.


following:






Data Type: String

Max Length: 29

Required: No



74

A.18 FundingAccountInfo

panUniqueReference


Data Type: String

Max Length: 64

Required: No.




Data Type: String

Max Length: 64

Required: Conditional – Required in NotifyServiceActivated, not present otherwise.



75

encryptedPayload

Description: Contains an encrypted object.


{ "cardAccountData" : { "accountNumber" : "5123456789012345", "expiryMonth" : "12", "expiryYear" : "15", "securityCode" : "123" }, "financialAccountData" : { "financialAccountId" : "5123456789012345", "interbankCardAssociationId" : "1234", "countryCode" : "GBR" }, "accountHolderData" : {

"accountHolderName" : "John Doe",

"sourceIp" : "127.0.0.1",

"deviceLocation" : "38.63/-90.2",

"accountHolderAddress" : { "line1" : "100 1st Street", "line2" : "Apt. 4B", "city" : "St. Louis", "countrySubdivision" : "MO", "postalCode" : "61000", "country" : "USA" }

}, "tokenData" : { "token" : "5345678901234521", "expiryMonth" : "10", "expiryYear" : "17", "sequenceNumber" : "01 }, "source" : "ACCOUNT_ON_FILE", "paymentAccountReference":"512381d9f8e0629211e3949a08002" }

Data Type: EncryptedPayload object containing a FundingAccountData object.

Max Length: N/A

Required: Yes.



76

A.19 Token




Data Type: String

Max Length: 64

Required: Yes – always present even when an error occurs.

status

Description: The current status of token. Must be one of:

Value Meaning

INACTIVE Token has not yet been activated

ACTIVE Token is active and ready to transact

SUSPENDED Token is suspended and unable to transact

DEACTIVATED Token has been permanently deactivated

Data Type: String

Max Length: 32

Required: Conditional – required for notifyTokenUpdated if reasonCode =

"STATUS_UPDATE". Not present otherwise.

.

suspendedBy

Description: Who or what caused the token to be suspended.

One or more values of:

Value Meaning

ISSUER Suspended by the Issuer. Payment App Provider

unable to unsuspend this Token.

PAYMENT_APP_PROVIDER Deprecated- Suspended by the Payment App

Provider.

TOKEN_REQUESTOR Suspended by the token requestor.

MOBILE_PIN_LOCKED Suspended due to the Mobile PIN being locked.

CARDHOLDER Suspended by the Cardholder


Max Length: N/A

Required: Conditional – required if status = SUSPENDED.



77

tokenExpiry

Description: The expiry of the Token PAN, given in MMYY format.

Data Type: String

Max Length: 4

Required: Conditional – required for notifyTokenUpdated if reasonCode =

"REDIGITIZATION_COMPLETE". Not present otherwise.

A.20 TokenData

token

Description: The token issued for this service request.



Required: Yes

expiryMonth

Description: The month of the expiration date.



Required: Yes

expiryYear

Description: The year of the expiration date.



Required: Yes

sequenceNumber

Description: Sequence number of the Token



Required: Conditional – required in AuthorizeServiceResponseData. Optional

otherwise.

A.21 Phone Number

countryDialInCode

Description: The country code for the phone number. E.g. 1 for US or 44 for UK


Max Length: 4

Required: Conditonal - required in PushAccount. Optional otherwise

phoneNumber

Description: The phone number, may contain country code along with phone

number when countryDialInCode is not present


Max Length: 20

Required: Yes



78

expiryYear

Description: The year of the expiration date.



Required: Yes

sequenceNumber

Description: Sequence number of the Token



Required: Conditional – required in AuthorizeServiceResponseData. Optional

otherwise.



79

B. Appendix B – Error Codes

Error Code Error Description Error Circumstances

INVALID_JSON Invalid JSON The JSON could not be

parsed.

MISSING_REQUIRED_FIELD Missing Required

Field - {fieldName}

A required field is missing.

INVALID_FIELD_FORMAT Invalid Field Format -

{fieldName}

The field is not in the

correct format. For

instance, it should be a

number but is a string.

INVALID_FIELD_LENGTH Invalid Field Length -

{fieldName}

The value does not fall

between the minimum and

maximum length for the

field.

INVALID_FIELD_VALUE Invalid Field Value -

{fieldName}

The value is not allowed

for the field.

CRYPTOGRAPHY_ERROR Cryptography Error There was an error

decrypting the encrypted

payload.

INTERNAL_SERVICE_FAILURE The system had an

internal exception

System had an internal

exception.

MISSING_EXPIRY_DATE Missing Expiry Date The expiry date is required

for this product but was

missing. Retry the request

supplying the expiry date

for this card.



80

C. Appendix C – Reason Codes

C.1 Approved Reason Codes

Recommendation reasons for an 'APPROVED' recommendation must be one of:

Value Meaning

LONG_ACCOUNT_TENURE Account has existed for an extended period of not less than one year.

A Payment App Provider may determine a longer account tenure to

qualify for this reason.

GOOD_ACTIVITY_HISTORY There has been financial activity linked to the account for at least and

within a period of not less than six months; no suspicious activity is

linked to the account within a period of at least one year.

CARDHOLDER_UNAVAILABLE The cardholder is not actively participating in the request to tokenize

the PAN.

AUTHENTICATION_NOT_SUPPORTED The Token Requestor does not support account holder authentication.

ADDITIONAL_DEVICE The digitization is for an additional device for the same Account PAN

and consumer account. There must be a currently active (not

suspended) Token that was previously digitized and activated on an

existing device for the same Account PAN and consumer account.

SOFTWARE_UPDATE The digitization has been requested due to an authenticated operating

system or other software update being installed on the device, causing

mobile payment data to be wiped and unable to be restored.

This digitization must be for the same paymentAppInstanceId to which

a Token was previously digitized and activated for the same Account

PAN and consumer account.

C.2 Require Additional Authentication or Declined Reason Codes

Recommendation reasons for a 'REQUIRE_ADDITIONAL_AUTHENTICATION' or 'DECLINED'

recommendation must be one of:

Value Meaning

ACCOUNT_TOO_NEW_SINCE_LAUNCH Account is considered new relative to Payment

App Provider service launch



81

ACCOUNT_TOO_NEW Account is considered new relative to

provisioning request

ACCOUNT_CARD_TOO_NEW Account/card is considered new relative to

provisioning request

ACCOUNT_RECENTLY_CHANGED Changes have recently been made to account

data

SUSPICIOUS_ACTIVITY Suspicious activity has been linked to this

account

INACTIVE_ACCOUNT Inactive account

HAS_SUSPENDED_TOKENS Device contains suspended tokens

DEVICE_RECENTLY_LOST Device has recently been reported lost

TOO_MANY_RECENT_ATTEMPTS Excessive recent tokenization attempts to this

device

TOO_MANY_RECENT_TOKENS Excessive recent tokenization to this device

TOO_MANY_DIFFERENT_CARDHOLDERS Excessive non-matching Cardholder names

within the device

LOW_DEVICE_SCORE Low device score

LOW_ACCOUNT_SCORE Low account score

OUTSIDE_HOME_TERRITORY Non-domestic tokenization attempt

UNABLE_TO_ASSESS Unable to provide recommendation due to

system issues.

HIGH_RISK High fraud risk identified. Enhanced

verification recommended.

CARDHOLDER_UNAVAILABLE The cardholder is not actively participating in

the request to tokenize the PAN.

AUTHENTICATION_NOT_SUPPORTED The Token Requestor does not support

account holder authentication.

LOW_PHONE_NUMBER_SCORE Low phone number score

mastercard digital enablement service

Documents