MasterCard issues security certificates for API integration purposes, including for their MATCH Pro services. These security certificates are pivotal in ensuring connectivity between NMI (ScanX) and MasterCard (MATCH Pro) is secure and active. The MATCH Pro API is used with the MATCH Lookup scoring rule on ScanX scorecards. The security keys expire every two years.
This documentation gives a cursory guide on what steps to perform if MasterCard notifies the developer account owner when the expiry of their MATCH Pro security certificate is imminent.
E-mail notification received by MasterCard
MasterCard Developers notifies the administrator or owner of the MasterCard developer account of the imminent expiry by e-mail. This happens at intervals of 90, 60, 15 and 7 days. The email will have information about the
- project name
- key expiry date
- key alias
- an alpha-numeric unique key id
- a key type indicator
- environment (sandbox / production)
along with a link to the developer portal log-in and a link to a guide on managing keys on the MasterCard developer portal.
The email may look like this:
The link to the instructions can be followed to complete the change on MasterCard side. The steps for OAuth Key is to be followed in their documentation. However, this document will include the steps that can be performed to both renew or rotate the key and also to perform changes on the ScanX platform side.
Managing the security key on the MasterCard Developer portal
MasterCard offers the option to rotate or renew the security key on their developer portal. This section describes the steps to be performed to achieve rotation:
- Log-in at https://developers.mastercard.com as the account owner that received the email notification. Log-in can be performed via entering e-mail address and password. The developer portal log-in password is not equal to the security key password.
For support regarding your MasterCard developer account, please reach out to MasterCard directly. NMI is unable to assist you regarding the identity of the owner or password of the account.
- If not already there, select Projects and then click on the project name that was indicated in the e-mail. Example:
- If not already there, on the left side menu click on Production under the credentials section.
- Identify the key in the list by its name and then select the Rotate Key option from the three-dot menu.
- The UI will offer rotation of the security certificate. However if the key is not expired yet, it will also offer renewal, which extends the period again for another set of years, up to a set maximum.
If compliance and security policy allow for key renewal, it is recommended to do so. Renewing the key completes the procedure and no further steps are necessary on ScanX side.
- If Rotate key was selected, the UI will offer to generate a new private key, or use existing ones in various forms.
The later two are to be used at a professional's discretion. For the purposes of demonstration in this guide, "Generate a new private key" was selected.
-
Enter a new, descriptive key alias, and a password for the keystore.
IMPORTANT!! The keystore password should not equal the password used for logging in to the MasterCard developer portal. It should be entirely unique to the key itself. It is recommended to avoid saving it in the browser! - Download the key file arhive via the "Download key file button. Then extract the archive and/or store the contents in a secure location.
This concludes the actions on the MasterCard developer portal.
Updating the security keys on the ScanX Scorecards
Pre-requisite: Company Administrator with ScanX Admin security profile.
In order for the rotated security keys from MasterCard to work in conjunction with the ScanX MATCH Pro API integration, the keys will need to be stored on each individual Scorecard within the ScanX platform. Below are the steps to achieve that:
- From the ScanX Workspace open Administation -> Scorecards option.
- Identify a Scorecard with the MATCH integration by opening the latest active template in the versioning.
- Navigate to the Credentials tab and click the Key icon next to the MATCH section.
- Click on REMOVE CERTIFICATE, SAVE and confirm the action.
- Click UPLOAD CERTIFICATE and select the new security key (p12) file from the extracted archive.
- Update the MC_KEY_PASSWORD field with the password of the new security key that was set during the key creation process.
- Update the MC_KEY_ALIAS field with the Key Name from the MasterCard Developer portal.
- Update the MC_CONSUMER_KEY field with the Consumer Key from the MasterCard Developer portal.
- SAVE, Confirm and finally save the scorecard with the floppy disk icon.
Repeat steps 2 - 9 for every other potential scorecard that has the MATCH scoring rules present.