MDES DevZone Onboarding Process PreDig
MDES DevZone Onboarding Process PreDig
Pre-Digitization API
Client ID and Encryption Key Generation Procedure
MTF and Production Environments
Version 2.3
24 July 2017
MDES – Developer Zone Onboarding – Pre-Digitization
Version 2.3
Version Control
2.0 04/26/2017 Russ Forney Updates for formatting and content changes.
2.1 05/25/2017 Russ Forney Updates to the list of MasterCard Trusted Certificates.
Updated list of supported TLS/SSL cipher suites.
2.2 07/11/2017 Russ Forney Updates to Developer Zone onboarding and key
generation process, to more closely align with user
experience.
Acronyms / Definitions
Acronym Definition
API Application Programming Interface
CA Certificate Authority
CIS Customer Implementation Services
CSR Certificate Signing Request
IM Implementation Manager
IP Internet Protocol
KMS Key Management Services
MC MasterCard
MDES MasterCard Digital Enablement Service
MTF MasterCard Test Facility. This is MasterCard's customer-facing test
environment. This environment may also be referenced as Sandbox.
SSL Secure Socket Layer
TLS Transport Layer Security
XMLGW MasterCard XML Gateway. This gateway is used by external customers, to
access authorized MasterCard systems and resources.
Overview
This document describes the process an MDES Customer must follow for their developers to register
with the MasterCard Developer Zone, create an MDES Pre-Digitization project, and generate the needed
keys for the appropriate MasterCard environments.
Pre-Setup Information
The following information will be needed to describe the MDES Pre-Digitization setup in the Developer
Zone portal.
This section describes the high-level steps that should take place, to implement an MDES Pre-
Digitization project, through Developer Zone.
e. Click the “I agree to the Developer Program Agreement and Privacy Policy ” terms and
conditions checkbox.
f. For additional help with the sign up process, use the additional links provided on the
right side of the screen.
4. Specify that your project will be using the MDES Pre-Digitization APIs, by performing the
following steps:
a. Select MDES Pre-digitization from the Choose API dropdown list. This is the API for the
Production environment.
b. Click the Add another API link, to select the API for the MTF environment.
c. Select MDES Pre-digitization MTF from the Choose API dropdown list.
d. Click the Continue button, to start creating your Pre-digitization project.
5. Enter a descriptive name for your project and click the Create My Project button.
6. A pop-up will be displayed, informing you that your Pre-Digitization project has been created.
Ignore the information about Keystore Password and Alias and click the Okay Button.
7. At the bottom of the project creation screen, prompts will be displayed that allow downloading
and storing of the Developer Zone Sandbox environment key that was generated for the project.
Pre-Digitization API services are not available in the Sandbox environment, so this certificate is
not needed. Click the Cancel button to proceed without saving the Sandbox key.
1. The user should validate that the newly created Pre-Digitization project, is displayed on the
screen, before proceeding. The project name should appear in the left navigation bar and be
displayed at the top of the Project screen.
2. The user should also validate that both the MDES Pre-digitization and MDES Pre-digitization
MTF APIs are associated to the project, by looking in the My APIs portion of the Project screen.
3. The project exists in the Developer Zone Sandbox environment (as noted at the top of the
Project screen) and must be moved to Production. To start this process, click the Move to
Production button, in the upper right portion of the screen.
4. When prompted to move the application to the production environment, click the Okay, got it
button.
1. In the Name section, enter your First Name and Last Name.
2. Enter your Company Name.
3. In the Address section, provide valid address details for your company.
4. Enter a valid Phone Number where you can be reached, in the Contact field.
5. Click the Next button, to proceed to the next step in the process.
NOTE: It is critical that the customer enters valid and complete company information in this section.
Mastercard may need to periodically contact registered Developer Zone participants and
needs accurate contact information to do so.
1. Enter a valid endpoint (URL + TCP Port + Context Root) for MDES to use, when sending
Production pre-digitization messages to the customer in the MDES Pre-Digitization field. An
example might look like: https://www.mycompany.com:8543/prodweb
2. Enter a valid endpoint (URL + TCP Port + Context Root) for MDES to use, when sending MTF pre-
digitization messages to the customer in the MDES Pre-Digitization MTF field. An example
might look like: https://www.mycompany.com:4044/testweb
3. Click the Next button, to proceed to the next step in the process.
NOTE: It’s critical that the customer enters valid working endpoints in this step. Any
configuration changes to the endpoints after they are provided in this step will take 10
business days at minimum to be completed.
1. Upload your own CSR (preferred method), by using your key management system to generate the
private keys in some secure hardware store.
a. Select the Upload Existing CSR instead link.
b. Enter a descriptive name for the key, which identifies it purpose and environment, in
the Key Alias field. An example might look like: MyCompany-PreDig-ProdMTF.
c. Click the Browse button to find and upload that CSR file.
d. Click the Next button to upload the CSR, to generate a 2048-bit key pair that will be used
for Pre-Digitization.
2. Use the Mastercard Open API browser-based key generator in the screen below and allow MC
Open API to generate a key for you.
a. Enter a descriptive name for the key, which identifies it purpose and environment, in
the Key Alias field.
b. Enter a password that will be used to encrypt the keys that the customer will receive, in the
Keystore Password field.
c. Click the Next button to generate a 2048-bit key pair that will be used for Pre-Digitization.
NOTE: Although this key is not “directly” used by the customer (i.e. Pre-Digitization API only
supports MDES outbound initiated requests to the customer), a portion of this key is used
“indirectly” by Mastercard, as a configuration parameter within the MDES database.
Hence, the customer is required to generate it.
1. Upload your own CSR (preferred method), by using your key management system to generate the
private keys in some secure hardware store.
a. Select the Upload Existing CSR instead link.
b. Enter a descriptive name for the key, which identifies it purpose and environment, in
the Key Alias field. An example might look like: MyCompany-EncryptKey-PreDig-Prod.
c. Click the Browse button to find and upload that CSR file.
d. Click the Next button to upload the CSR, to generate a 2048-bit key pair that will be used
for Pre-Digitization.
2. Use the Mastercard Open API browser-based key generator in the screen below and allow MC
Open API to generate a key for you.
a. Enter a descriptive name for the key, which identifies it purpose and environment, in
the Key Alias field.
b. Enter a password that will be used to encrypt the keys that the customer will receive, in the
Keystore Password field.
c. Click the Next button to generate a 2048-bit key pair that will be used for Pre-Digitization.
1. Upload your own CSR (preferred method), by using your key management system to generate the
private keys in some secure hardware store.
a. Select the Upload Existing CSR instead link.
b. Enter a descriptive name for the key, which identifies it purpose and environment, in
the Key Alias field. An example might look like: MyCompany-EncryptKey-PreDig-MTF.
c. Click the Browse button to find and upload that CSR file.
d. Click the Next button to upload the CSR, to generate a 2048-bit key pair that will be used
for Pre-Digitization.
2. Use the Mastercard Open API browser-based key generator in the screen below and allow MC
Open API to generate a key for you (process illustrated below).
a. Enter a descriptive name for the key, which identifies it purpose and environment, in
the Key Alias field.
b. Enter a password that will be used to encrypt the keys that the customer will receive, in the
Keystore Password field.
c. Click the Next button to generate a 2048-bit key pair that will be used for Pre-Digitization.
2. The following acknowledgement screen will appear, along with an e-mail (examples below) sent
to your e-mail address. Click the OK button to complete the Pre-Digitization project wizard.
3. MasterCard will review the request and upon approval, you should expect to receive an e-mail
similar to the following, indicating access that your certificate requests have been approved.
4. Until your API service requests have been reviewed and approved, the summary page for your
Developer Zone project will indicate a status of Pending Production Request. Once the API
requests have been reviewed and approved, this status will change to In Production.
Your API requests will also show a Pending status, until all approvals are complete.
2. The zip file should contain your Production/MTF key, as well as the Production and MTF
encryption keys. The Production/MTF key (production.p12 key) can be ignored, since it is not
needed for Pre-Digitization. The encryption keys (encryption-mc.p12) are used by the customer
to decrypt the incoming Pre-Digitization requests from Mastercard. These should each be
imported into the keystore for the appropriate environment (Prod -> Prod and MTF -> MTF), at
the customer’s location.
1. From the Developer Zone Project Summary page, go to the Production Keys section, click on the
Actions dropdown button, and select the Copy key option.
2. Paste the key value into an e-mail and send it to your CIS IM. Be sure to clearly state which
project the key is for. The first 48 characters of this key value (up to the exclamation point) will
be the Mastercard API Client ID, which will be used in both the MTF and Production
environments. An example of the key value, with Client ID highlighted in red, might be:
YmGQWCX2b-h0XFIH0F0-ld0X7gK96hpOgukp03pj38ef6a4f!90499c1d80c4417
a824aedcec14ea6c00000000000000000
1. From the Developer Zone Project Summary page, go to the Mastercard Encryption Keys section,
click on the Actions dropdown button, and select the Copy fingerprint option.
2. Paste copied value into a document (Notepad, Word, etc.) and note that it is the
publicKeyFingerprint for the Production environment.
3. Associate that publicKeyFingerprint (from the Mastercard Production Encryption Key) to your
Production Private Key, so you will know which Private Key to use when performing
unwrap/decrypt operations on incoming Pre-Digitization requests in Production.
4. From the Developer Zone Project Summary page, go to the Mastercard MTF Encryption Keys
section, click on the Actions dropdown button, and select the Copy fingerprint option.
5. Paste copied value into a document (Notepad, Word, etc.) and note that it is the
publicKeyFingerprint for the MTF environment.
6. Associate that publicKeyFingerprint (from the Mastercard MTF Encryption Key) to your MTF
Private Key, so you will know which Private Key to use when performing unwrap/decrypt
operations on incoming Pre-Digitization requests in MTF.
Step 13 – Ensure your Internet Appliance has access to Entrust Certificate Authority L1K
Certificate Chain
1. MasterCard will need to establish a mutual TLS connection with your Internet-facing appliance,
in order to initiate outbound web service calls to your previously designated endpoint.
2. In order for you to validate the MasterCard XMLGW Client certificate (when presented), you will
need to ensure your Internet appliance has access to a trustore containing the Entrust
Certificate Authority L1k certificate chain (which is the CA chain that issued the MasterCard
XMLGW Client certificate). Should you need to obtain this CA Chain, you may download it from
the Entrust website (https://www.entrust.com/get-support/ssl-certificate-support/root-
certificate-downloads/) and import it into the appropriate trustore.
a. If you are accessing the Entrust site from the appliance containing the trustore and you
simply want to install the certificates, you may simply click on the following buttons
below from the Entrust site.
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_RSA_WITH_AES_256_CBC_SHA256
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA384
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384
TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
TLS_RSA_WITH_AES_256_CBC_SHA
TLS_ECDH_ECDSA_WITH_AES_256_CBC_SHA
TLS_ECDH_RSA_WITH_AES_256_CBC_SHA
TLS_DHE_RSA_WITH_AES_256_CBC_SHA
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
TLS_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA256
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256
TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
TLS_RSA_WITH_AES_128_CBC_SHA
TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA
TLS_ECDH_RSA_WITH_AES_128_CBC_SHA
TLS_DHE_RSA_WITH_AES_128_CBC_SHA
TLS_ECDHE_ECDSA_WITH_RC4_128_SHA
TLS_ECDHE_RSA_WITH_RC4_128_SHA
SSL_RSA_WITH_RC4_128_SHA
TLS_ECDH_ECDSA_WITH_RC4_128_SHA
TLS_ECDH_RSA_WITH_RC4_128_SHA
TLS_ECDHE_ECDSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDH_ECDSA_WITH_3DES_EDE_CBC_SHA
TLS_ECDH_RSA_WITH_3DES_EDE_CBC_SHA
SSL_DHE_RSA_WITH_3DES_EDE_CBC_SHA
SSL_RSA_WITH_RC4_128_MD5
SSL_RSA_WITH_DES_CBC_SHA
SSL_DHE_RSA_WITH_DES_CBC_SHA