Mastercard Digital Enablement

Service
Pre-Digitization
Application Programming Interface
Version 2.0.6, BUILD2
12 February 2019
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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
2
Summary of Changes
Description of Change Where to Look
Added new fields (tcis, auxTcis) in the Authorize Service API 2.5.4
response
Typo correction to reflect the use of a slash “/” separator A.1, A.18 -- Sample unencrypted object
instead of a comma “,” separator between “(sign) latitude” and
(sign) longitude” in the deviceLocation parameter

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
3
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....................................................................................................................... 23
2.3.2 HTTP Method ...................................................................................................................... 23
2.3.3 Request Parameters ............................................................................................................ 23
2.3.4 Response Values ................................................................................................................. 24
2.3.5 Example Request Body........................................................................................................ 24
2.3.6 Example Response Body ..................................................................................................... 24
2.4 NotifyServiceActivated................................................................................................................ 24
2.4.1 URL Endpoint....................................................................................................................... 25
2.4.2 HTTP Method ...................................................................................................................... 25
2.4.3 Request Parameters ............................................................................................................ 25
© 2019 Mastercard. Proprietary and Confidential. All rights reserved.
Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
4
 2.4.4 Response Values ................................................................................................................. 30
2.4.5 Example Request Body........................................................................................................ 30
2.4.6 Example Response Body ..................................................................................................... 32
2.5 AuthorizeService ......................................................................................................................... 32
2.5.1 URL Endpoint....................................................................................................................... 32
2.5.2 HTTP Method ...................................................................................................................... 32
2.5.3 Request Parameters ............................................................................................................ 32
2.5.4 Response Values ................................................................................................................. 35
2.5.5 Example Request Body........................................................................................................ 39
2.5.6 Example Response Body ..................................................................................................... 40
2.6 NotifyTokenUpdated................................................................................................................... 41
2.6.1 URL Endpoint....................................................................................................................... 42
2.6.2 HTTP Method ...................................................................................................................... 42
2.6.3 Request Parameters ............................................................................................................ 42
2.6.4 Response Parameters ......................................................................................................... 43
2.6.5 Example Request Body – STATUS_UPDATE ........................................................................ 43
2.6.6 Example Request Body – REDIGITIZATION_COMPLETE ...................................................... 44
2.6.7 Example Request Body – DELETED_FROM_CONSUMER_APP ............................................ 44
2.6.8 Example Response Body ..................................................................................................... 44
2.7 ValidateActivationCode .............................................................................................................. 45
2.7.1 URL Endpoint....................................................................................................................... 45
2.7.2 HTTP Method ...................................................................................................................... 45
2.7.3 Request Parameters ............................................................................................................ 45
2.7.4 Response Values ................................................................................................................. 46
2.7.5 Example Request Body........................................................................................................ 46
2.7.6 Example Response Body ..................................................................................................... 47
2.8 Get Account Information ............................................................................................................ 47
2.8.1 URL Endpoint....................................................................................................................... 47
2.8.2 HTTP Method ...................................................................................................................... 47
2.8.3 Request Parameters ............................................................................................................ 47
2.8.4 Response Values ................................................................................................................. 48
2.8.5 Example Request Body........................................................................................................ 48
© 2019 Mastercard. Proprietary and Confidential. All rights reserved.
Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
5
 2.8.6 Example Response Body ..................................................................................................... 48
A. Appendix A – Request and Response Member Objects ..................................................................... 50
A.1 AccountHolderData..................................................................................................................... 50
A.2 AccountInformationData ............................................................................................................ 51
A.3 AuthorizeServiceResponseData .................................................................................................. 51
A.4 ActivationMethod ....................................................................................................................... 52
A.5 BalanceInformation .................................................................................................................... 53
A.6 BillingAddress .............................................................................................................................. 54
A.7 CardAccountData ........................................................................................................................ 55
A.8 CardAndTokenData - Deprecated ............................................................................................... 56
A.9 CardAndTokenInfo - Deprecated ................................................................................................ 57
A.10 CardholderData - Deprecated ................................................................................................. 59
A.11 CardInfo - Deprecated............................................................................................................. 60
A.12 CardInfoData - Deprecated ..................................................................................................... 62
A.13 DecisioningInfo – MAP<String, Object> .................................................................................. 65
A.14 DeviceInfo – MAP<String, Object> .......................................................................................... 66
A.15 EncryptedPayload ................................................................................................................... 69
A.16 FinancialAccountData ............................................................................................................. 71
A.17 FundingAccountData............................................................................................................... 72
A.18 FundingAccountInfo ................................................................................................................ 74
A.19 Token....................................................................................................................................... 76
A.20 TokenData ............................................................................................................................... 77
B. Appendix B – Error Codes ................................................................................................................... 78
C. Appendix C – Reason Codes ................................................................................................................ 79
C.1 Approved Reason Codes ................................................................................................................... 79
C.2 Require Additional Authentication or Declined Reason Codes ........................................................ 79

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
6
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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
7
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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
8
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
9
 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:

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
10
 API Encryption Sender Receiver Payload Encrypted payload
Public Key

(*) RAM Issuer MDES Pre- Issuer web fundingAccountData fundingAccountInfo

API Encryption Digitization service
request, Public Key API
(**) AS
API
request

(***) NSA Issuer MDES Pre- Issuer web fundingAccountData fundingAccountInfo

API Encryption Digitization service
request Public Key API

(**) AS Mastercard Issuer web MDES Pre- AuthorizeService encryptedPayload

API Encryption service Digitization
ResponseData
response Public Key API

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

(***) NSA = notifyServiceActivated
An overview of the PCI/PII payload bulk data encryption process is provided in the figure
below.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
11
 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:

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
12
 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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
13
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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
14
 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 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
AS
Watch Dog Timer (WDT) = RAM
5 seconds

AS resp[AML1]]

RAM
resp[AML2]

AML = AML2 || AML1

“Expected” order in the WDT window

TR MDES Issuer

Digitize
AS
RAM
Watch Dog Timer (WDT) =

RAM
AS
5 seconds

RAM
resp[AML2]

AML = AML2 || AML1 AS resp[AML1]]

“Un-expected” order in the

WDT window

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
15
 When a timeout is registered, the following flows may happen:
2. 1st Timeout:
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
AS
RAM

5 seconds
WDT =
503 Service
Unavailable with a
retry after header RAM[AML2]
AS[AML1]
AS (2
n
RAM d)
(2n
d)
WDT = 7 seconds

...

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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
16
 TR MDES Issuer

Digitize
AS
RAM

5 seconds
WDT =
RAM[AML2]
Store AML2
503 Service AS[AML1]
Unavailable with a
retry after header
AS (2n
d )

WDT = 7 seconds
...

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
AS
RAM
5 seconds
WDT =

AS[AML1]

Use decision from AS

RAM[AML2]
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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
17
 TR MDES Issuer

WDT = 7 seconds
...
RAM[AML2]

Decision from Issuer Response 1

nd)
L1] (2
sp[AM
AS re
Decision from Rules
2

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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
18
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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
19
 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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
20
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":"4545433044323232363739304532433610DE1D1461475BEB6D815F31
764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E824AA55BA67BF
6A",
"publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b",
"encryptedKey" : "A1B2C3D4E5F6112233445566",
"oaepHashingAlgorithm" : "SHA512",
"iv" : "31323334353637383930313233343536"
}
"panUniqueReference" : "FWSPMC000000000159f71f703d2141efaf04dd26803f922b"
},
"correlationId" : "D98765432104",
"tokenRequestorId" : “12345678901”,
"walletId" : "123",
"paymentAppInstanceId" : "1b24f24a24ba98e27d43e345b532a245e4723d7a9c4f624e93452c",
“accountIdHash” : “5ae9c9890b326bd23bfa9db9672298ae3b10a9388e56ec17a001e191f24572aa”,
"mobileNumberSuffix" : "1234",
"tokenType" : "CLOUD"
}

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
21
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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
22
2.3.1 URL Endpoint
/deliverActivationCode

2.3.2 HTTP Method

POST

2.3.3 Request Parameters

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
Description: Value linking pre-digitization messages generated during provisioning.
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
© 2019 Mastercard. Proprietary and Confidential. All rights reserved.
Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
23
 activationMethod
Description: The activation method selected by the Account holder.
Data Type: ActivationMethod
Max Length: NA
Required: Yes

2.3.4 Response Values

Only common response elements

2.3.5 Example Request Body

{
"requestId" : "123456",
"tokenUniqueReference" :
"DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
"correlationId" : "D98765432104",
"activationCode" : "A1B2C3D4",
"expirationDateTime" : "2016-07-04T12:08:56.123-07:00",
"activationMethod" : {
"type" : "CARDHOLDER_TO_CALL_AUTOMATED_NUMBER",
"value" : "1-800-BANK-NUMBER"
}
}

2.3.6 Example Response Body

{
"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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
24
2.4.1 URL Endpoint
/notifyServiceActivated

2.4.2 HTTP Method

POST

2.4.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
cardAndToken
Description: Contains card and token information of the card to be digitized.
Data Type: CardAndTokenInfo 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 also be included.
Data Type: FundingAccountInfo object
Max Length: N/A
Required: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
25
 deviceInfo
Description: Contains information about the target device to be provisioned.
Data Type: Map (DeviceInfo).
Max Length: N/A
Required: No
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: Yes
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
26
 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
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:
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: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
27
 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:
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: No
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
28
 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
tokenActivatedDateTime
Description: 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: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
29
 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

2.4.4 Response Values

Only common response elements

2.4.5 Example Request Body

{
"requestId" : "123456",
"services" : [
"DIGITIZATION"
],
"fundingAccountInfo" : {
"encryptedPayload" : {
"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D
815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E8
24AA55BA67BF6A",
"publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b",
"encryptedKey" : "A1B2C3D4E5F6112233445566",
"oaepHashingAlgorithm" : "SHA512",
"iv" : "31323334353637383930313233343536",
},

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
30
 "tokenUniqueReference" :
"DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
"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"
},
"correlationId" : "D98765432104",
"tokenRequestorId" : “12345678901”,
"walletId" : "123",
"paymentAppInstanceId" :
"1b24f24a24ba98e27d43e345b532a245e4723d7a9c4f624e93452c",
"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”,
"tokenActivatedDateTime" : "2015-07-04T12:09:57.123-07:00",
"numberOfActivationAttempts" : 1,
"numberOfActiveTokens" : 2,
"tokenAssuranceLevel": 1
}

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
31
2.4.6 Example Response Body
{
"responseId" : "123456"
}

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

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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
32
 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.
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
33
 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
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
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
34
 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

2.5.4 Response Values

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

DIGITIZATION Provision the Funding Account to a device.

Data Type: Array[String]

Max Length: N/A
Required: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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
additional authentication to be
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
38
 tokenRequestorId
Description: The party that requested the digitization.
Data Type: String(Numeric)
Max Length: 11(Exact)
Required: Conditional - required if tokens are generated by external provider, not
present otherwise.
tcis
Description: Array of terminal capability TCIs.
Data Type: Array[String]
Max Length: NA

Required: No
auxTcis
Description: Array of auxiliary terminal capability TCIs.
Data Type: Array[String]
Max Length: NA

Required: No

2.5.5 Example Request Body

{
"requestId" : "123456",
"services" : [
"DIGITIZATION"
],
"fundingAccountInfo" : {
"encryptedPayload" : {
"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D
815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E8
24AA55BA67BF6A",
"publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b",
"encryptedKey" : "A1B2C3D4E5F6112233445566",
"oaepHashingAlgorithm" : "SHA512",
"iv" : "31323334353637383930313233343536"
}
"panUniqueReference" : "FWSPMC000000000159f71f703d2141efaf04dd26803f922b"
},
"correlationId" : "D98765432104",
© 2019 Mastercard. Proprietary and Confidential. All rights reserved.
Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
39
 "tokenRequestorId" : “12345678901”,
"walletId" : "123",
"paymentAppInstanceId" :
"1b24f24a24ba98e27d43e345b532a245e4723d7a9c4f624e93452c",
"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"
},
"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"
}

2.5.6 Example Response Body

{
"responseId" : "123456",
"services" : ["DIGITIZATION"],
"decision" : "REQUIRE_ADDITIONAL_AUTHENTICATION",
"activationMethods" : [

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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",
"encryptedPayload" : {
"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6
D815F31764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE46
1E824AA55BA67BF6A",
"publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b",
"encryptedKey" : "A1B2C3D4E5F6112233445566",
"oaepHashingAlgorithm" : "SHA512",
"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:

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
41
 Digitize

Update Provision

Token Configuration
Update Update
Token Configuration
Update
Inactive
CS PAN SWAP
0302 PAN SWAP

NSA
Update Token Expiry
Activate NTU
Update
(Re-Digitized)
Delete Token Configuration Update
Update
NTU(Status=
CS PAN SWAP Suspend Suspended,
NTU(Status=Suspended
0302 PAN SWAP , SuspendedBy[S1, S2]) SuspendedBy[S1])

Suspended 1st Unsuspend (S2)

Active
NTU(Status =
Deactivated) NTU(Status=Active) 2nd Suspend
Update
Update 3rd Unsuspend (S3)
Token Expiry NTU(Status=
(S1, S3) Suspended,
NTU(Re-Digitized) SuspendedBy[S1, S3])

Delete
Delete
NTU
(Staus=Deactivated)

NTU(Status=Deactivated)

Deactivated

2.6.1 URL Endpoint

/notifyTokenUpdated

2.6.2 HTTP Method

POST

2.6.3 Request Parameters

tokens
Description: Contains the Tokens which were updated.
Data Type: Array[Token object]
Max Length: N/A
Required: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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

Only common response elements

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"
}

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
43
2.6.6 Example Request Body – REDIGITIZATION_COMPLETE
{
"requestId" : "123456",
"tokens" : [
{
"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

{
"requestId" : "123456",
"tokens" : [
{
"tokenUniqueReference" :
"DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45"
},
{
"tokenUniqueReference" :
"DWSPMC00000000032d72d4ffcb2f4136a0532d32d72d4fcb"
},
{
"tokenUniqueReference" :
"DWSPMC000000000fcb2f4136b2f4136a0532d2f4136a0532"
}
],
"reasonCode" : "DELETED_FROM_CONSUMER_APP"
}

2.6.8 Example Response Body

{
"responseId" : "123456"
}

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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

2.7.3 Request Parameters

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
Description: Value linking pre-digitization messages generated during provisioning.
Data Type: String
Max Length: 14
Required: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
45
 activationCode
Description: The Activation Code entered by the consumer.
Data Type: String (Alpha-Numeric)
Max Length 32
Required: Yes

2.7.4 Response Values

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

2.7.5 Example Request Body

{
"requestId" : "123456",
"tokenUniqueReference" :
"DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
"correlationId" : "D98765432104",
"activationCode" : "A1B2C3D4"

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
46
 }

2.7.6 Example Response Body

{
"responseId" : "123456",
"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. .

2.8.1 URL Endpoint

/getAccountInformation

2.8.2 HTTP Method

POST

2.8.3 Request Parameters

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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
47
2.8.4 Response Values
encryptedPayload
Description: Contains the encrypted AccountInformationData object
Data Type: EncryptedPayload object containing an AccountInformationData object.
Sample unencrypted object:
{
" balanceInformation " : {
"amount": 25.36,
"currencyCode" : "USD",
"balanceDateTime" : "2018-07-04T12:08:56.123-07:00"
},
"accountStatus" : "ACTIVE"
}
Max Length: N/A
Required: No

2.8.5 Example Request Body

{
"requestId" : "123456",
"fundingAccountInfo" : {
"encryptedPayload" : {
"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D815F31
764DDC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E824AA55BA67BF
6A",
"publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b",
"encryptedKey" : "A1B2C3D4E5F6112233445566",
"oaepHashingAlgorithm" : "SHA512",
"iv" : "31323334353637383930313233343536"
}
"panUniqueReference" : "FWSPMC000000000159f71f703d2141efaf04dd26803f922b"
},
}

2.8.6 Example Response Body

{
"responseId" : "123456",
"encryptedPayload" : {
"encryptedData":"4545433044323232363739304532433610DE1D1461475BEB6D815F31764D
DC20298BD779FBE37EE5AB3CBDA9F9825E1DDE321469537FE461E824AA55BA67BF6A",
© 2019 Mastercard. Proprietary and Confidential. All rights reserved.
Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
48
 "publicKeyFingerprint" : "4c4ead5927f0df8117f178eea9308daa58e27c2b",
"encryptedKey" : "A1B2C3D4E5F6112233445566",
"oaepHashingAlgorithm" : "SHA512",
"iv" : "31323334353637383930313233343536"
},
}

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
50
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

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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
51
 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:
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.
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

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 Yes
phone number.
Value will be the Account holder’s
masked mobile phone number.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
52
 EMAIL_TO_CARDHOLDER_ADDRESS Email to Account holder's email address. Yes
Value will be the Account holder’s
masked email address.
CARDHOLDER_TO_CALL_AUTOMATED_NUMBER Account holder-initiated call to Yes
automated call center phone number.
Value will be the phone number for the
Account holder to call.
CARDHOLDER_TO_CALL_MANNED_NUMBER Account holder-initiated call to manned Yes
call center phone number.
Value will be the phone number for the
Account holder to call.
CARDHOLDER_TO_VISIT_WEBSITE Account holder to visit a website. Yes
Value will be the website URL.

CARDHOLDER_TO_USE_MOBILE_APP Account holder to use a specific mobile Yes

app to activate token.
Value will be replaced by a formatted
string.
ISSUER_TO_CALL_CARDHOLDER_NUMBER Issuer-initiated voice call to Account Yes
holder’s phone.
Value will be the Account holder’s
masked voice call phone number.

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

A.5 BalanceInformation
amount
Description: The amount of the balance. Numeric including the decimal positions.
Data Type: Number
Max Length: 16
Required: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
53
 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:
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: 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
city
Description: The city of the billing address.
Data Type: String
Max Length: 32
Required: No

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
54
 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
Max Length: 3 (Exact)
Required: No

A.7 CardAccountData
accountNumber
Description: The Account Primary Account Number of the card to be digitized
Data Type: String (Numeric)
Max Length: 19 (min length 9)
Required: Yes
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.
Data Type: String (Numeric)
Max Length: 2 (Exact)
Required: No.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
55
 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.
May be omitted if the card does not have an expiry date.
Data Type: String (Numeric)
Max Length: 2 (Exact)
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.
Data Type: String (Numeric)
Max Length: 3 (Exact)
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

Data Type: TokenData

Max Length: NA

Required: Yes
paymentAccountReference
Description: The unique account reference assigned to the PAN.
Data Type: String
Max Length: 29(Exact)
Required: No

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
56
A.9 CardAndTokenInfo - Deprecated
panUniqueReference

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

Data Type: String

Max Length: 64

Required: Yes
tokenUniqueReference
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).

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

Max Length: 512

Required: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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

SHA512 Use the SHA-512 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.

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

Max Length: 32 (Exact)

Required: No

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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.
Sample unencrypted object:
{
"card" : {
"accountNumber" : "5123456789012345",
"expiryMonth" : "12",
"expiryYear" : "15",
"source" : "CARD_ON_FILE",
"cardholderName" : "John Doe",
"securityCode" : "123",
“cardholderData”: {
"sourceIp" : "127.0.0.1",
"deviceLocation" : "38.63/-90.2"
}
},
"token" : {
"token" : "5345678901234521",
"expiryMonth" : "10",
"expiryYear" : "17",
"sequenceNumber" : "01
},
"paymentAccountReference" : "5001a9f027e5629d11e3949a0800a"

}
Data Type: String. Hex-encoded data (case-insensitive).
Max Length: 256K
Required: Yes

A.10 CardholderData - Deprecated

sourceIp
Description: The IP of the device initiating the request.
Data Type: String
Max Length: 64

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
59
 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

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

Data Type: String

Max Length: 64

Required: No

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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
60
 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).

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

Max Length: 512

Required: Yes

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

SHA512 Use the SHA-512 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.

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

Max Length: 32 (Exact)

Required: No

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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.
Sample unencrypted object:
{
"accountNumber" : "5123456789012345",
"expiryMonth" : "12",
"expiryYear" : "15",
"source" : "CARD_ON_FILE",
"cardholderName" : "John Doe",
"securityCode" : "123",
“cardholderData”: {
"sourceIp" : "127.0.0.1",
"deviceLocation" : "38.63/-90.2"
}
}
Data Type: String. Hex-encoded data (case-insensitive).
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.

Data Type: String (Numeric)

Max Length: 19 (min length 12)

Required: Yes

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.

Data Type: String (Numeric)

Max Length: 2 (Exact)

Required: No

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
62
 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.
May be omitted if the card does not have an expiry date.

Data Type: String (Numeric)

Max Length: 2 (Exact)

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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
63
 securityCode

Description: The CVC2 for the card to be digitized, as entered by the Cardholder.
Verified as part of reaching the digitization decision.

Data Type: String(Numeric)

Max Length: 3 (Exact)

Required: No

dataValidUntilTimestamp

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.
Must be 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.
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

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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
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
additional authentication to be
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
Data Type: String(Numeric)
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
recommendationReasons
Description: Reasons provided to the Wallet Provider on how the recommended
decision was reached. Values for reason codes are defined in Appendix C.
Data Type: Array[String]
Max Length: NA
Required: No
© 2019 Mastercard. Proprietary and Confidential. All rights reserved.
Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
65
 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

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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
66
 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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
67
 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_ FitPay embedded operating system
OS
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
68
 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.

Data Type: Array[String]

Max Length: N/A
Required: No
imei
Description: The IMEI number of the device being provisioned.
Data Type: String
Max Length: 15 (Exact)
Required: No
msisdn
Description: The MSISDN of the device being provisioned.
Data Type: String
Max Length: 15
Required: No

A.15 EncryptedPayload
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
69
 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'.
Requirement is for a 128-bit key (with 256-bit key supported as an option).
Data Type: String. Hex-encoded data (case-insensitive).
Max Length: 512
Required: Yes
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

SHA512 Use the SHA-512 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.
Data Type: String. Hex-encoded data (case-insensitive).
Max Length: 32 (Exact)
Required: No

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
70
 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.
Data Type: String. Hex-encoded data (case-insensitive).
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)
Max Length: 64 (min length 9)
Required: Yes
interbankCardAssociationId
Description: The id assigned by Mastercard to the financial institution.
Data Type: Number
Max Length: 11 (min length 3)
Required: Yes
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
Max Length: 3 (Exact)
Required: Yes

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
71
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.

Data Type: TokenData

Max Length: NA

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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
72
 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
paymentAccountReference
Description: The unique account reference assigned to the PAN.
Data Type: String
Max Length: 29(Exact)
Required: No
dataValidUntilTimestamp
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.
Must be 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.
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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
73
A.18 FundingAccountInfo
panUniqueReference
Description: Reference to the PAN that is unique per Wallet Provider.
Data Type: String
Max Length: 64
Required: No.
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: Conditional – Required in NotifyServiceActivated, not present otherwise.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
74
 encryptedPayload
Description: Contains an encrypted object.
Sample unencrypted 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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
75
A.19 Token
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 – 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

Data Type: Array[String]

Max Length: N/A
Required: Conditional – required if status = SUSPENDED.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
76
 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.
Data Type: String (Numeric)
Max Length: 19 (min length 12)
Required: Yes
expiryMonth
Description: The month of the expiration date.
Data Type: String (Numeric)
Max Length: 2 (Exact)
Required: Yes
expiryYear
Description: The year of the expiration date.
Data Type: String (Numeric)
Max Length: 2 (Exact)
Required: Yes
sequenceNumber
Description: Sequence number of the Token
Data Type: String (Numeric)
Max Length: 2 (Exact)
Required: Conditional – required in AuthorizeServiceResponseData. Optional
otherwise.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
77
 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 A required field is missing.

Field - {fieldName}

INVALID_FIELD_FORMAT Invalid Field Format - The field is not in the correct

{fieldName} format. For instance, it
should be a number but is a
string.

INVALID_FIELD_LENGTH Invalid Field Length - The value does not fall

{fieldName} between the minimum and
maximum length for the
field.

INVALID_FIELD_VALUE Invalid Field Value - The value is not allowed for

{fieldName} the field.

CRYPTOGRAPHY_ERROR Cryptography Error There was an error

decrypting the encrypted
payload.

INTERNAL_SERVICE_FAILURE The system had an System had an internal

internal exception 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.

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
78
 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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
79
 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

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

Mastercard Digital Enablement Service - Pre-Digitization API Specification • Version 2.0.6 BUILD2
80