Secure Your Integration with Passwords or Certificates

You can authenticate to the MasterCard Payment Gateway using passwords or SSL certificates.

Password Authentication

You can enable secure access to the MasterCard Payment GatewayAPI and Batch integrations via passwords. The system-generated password is a 16 byte, randomly generated value that is encoded as a hex string. Though it is of sufficient length and quality to resist brute force guessing, it should be secured in the same manner as user passwords and other sensitive data.

Your password is a secret and should be known only by you and MasterCard. It is important to keep it confidential to protect your account.

Generate Password for API

You can generate the password in Merchant Administration. As a prerequisite, your merchant profile must be enabled for API, Batch, and "Use Password Authentication" privilege.

The operator must have "May Configure Integration Settings" privilege to generate the password.
  1. Navigate to Admin > Web Services API Integration Settings > Edit.
  2. Click Generate New.
  3. Select the Enable Integration Access Via Password box.
  4. Copy the password to the clipboard and/or a text file. You will need it later.
  5. Click Submit.

You must always have at least one password generated and enabled but you may have up to two passwords set up. For security, you should change the password periodically. Only one password must be used for configuring your application, the second one working as a standby for password rolling purposes.

Once the password is generated you must include it in all the transaction requests directed to the MasterCard Payment Gateway. If the request is sent using the REST-JSON protocol, then the request must contain the userid and the password in the standard HTTP basic authentication header. With NVP, you must supply additional parameters in the request, apiUsername and apiPassword, to use the API.

To authenticate as a merchant, the name (apiUsername for NVP and userid for REST-JSON) and the password (apiPassword for NVP and password for REST-JSON) must contain 'merchant.<your gateway merchant ID>' and the system-generated password respectively.

Supplying both the name and the password are mandatory from API v13 onwards. Prior to v13 it was mandatory to leave the name blank and supply only the password.

Password API Reference [REST][NVP]

Certificate Authentication

Certificate Authentication is currently not supported with Batch or Reporting.

With Certificate Authentication, you must present a certificate to authenticate yourself to the MasterCard Payment Gateway. Certificates are typically issued from one of many organizations that act as Certificate Authorities (CAs). This model of authentication is a component of Public Key Infrastructure (PKI) where security is achieved through confidentiality, integrity, non-repudiation, and authentication. The CA claims that the public key attached to the certificate is correct, belongs to the person or entity claimed (i.e., is 'authentic'), and has not been tampered with or replaced by a malicious third party.

The authentication mechanism for Certificate Authentication requires both the client (your Web Server) and the server (MasterCard Payment Gateway HTTP Server) to present certificates to authenticate themselves. This is termed as mutual authentication, the workflow for which is illustrated below.

Certificate Authentication

When connecting to the MasterCard Payment Gateway using Certificate Authentication, the following things occur:

  1. The client requests connection to a protected resource on the server. This takes place for every transaction request initiated by the client.
  2. The server presents its certificate chain to the client.
  3. The client verifies the server's certificate using a trust store, which contains the trusted root CAs. The client validates the certificate path to a trusted CA root certificate.
  4. If successful, the client sends its certificate chain to the server, which is contained in a key store.
  5. Depending on the Web Server client software, the trust store and key store are often the same.
  6. The server verifies the client's certificate using the full set of trusted/approved CA root certificates that are loaded on to the server. The following checks are performed:
    1. Checks if the certificate is in X.509 certificate format.
    2. Validates the certificate path to a trusted CA root certificate.
    3. Performs CRL or OCSP (Online Certificate Status Protocol) checking to ensure the certificate has not been revoked.
    4. Checks if the certificate has not expired.

    Once the HTTP Server has successfully validated the client certificate, the full client certificate chain is passed on to API for verification. If not, standard SSL certificate error messages are returned by the HTTP Server.

    Verification occurs at both the HTTP Server and the API levels. The HTTP Server performs full SSL certificate validation and API performs business-level certificate authentication.
  7. The API performs the following checks:
    1. Extracts the subject common name of the client certificate and confirms it matches the subject common name recorded against the merchant in the database. The subject common name of the certificate must contain the legal business name of the merchant.
    2. Verifies that the client certificate has a Key-Usage extension, marked critical that includes client authentication as a permissible use of the certificate.
    3. Performs a simple validation of the client certificate to a CA root certificate contained in the set of allowed CAs. This means the API application must hold the CA's root certificate that was used to issue and sign the client certificate.
      The initial set of allowable CAs is determined by MasterCard.
    4. Checks if the presented certificate matches the status of the merchant profile. A production profile will only accept production certificates whereas a test profile will accept either test or production certificates.

    If steps 1-4 are successful, then the merchant authentication is deemed successful, otherwise the connection is rejected by returning an appropriate error message.

  8. If all the checks outlined in step 5 and 6 are successful, then the server accepts the connection and allows the operation request to proceed.

You may choose to present your client certificate or a different certificate to authenticate yourself when the payer accesses your application. In this interaction, your Web Server acts as a server and the payer as a client. Integrating with this authentication mechanism can give your payers the added assurance that they are transacting with a legitimate enterprise.

Procuring the Production Certificate from a CA

It's important that the certificate you procure from your chosen CA meets MasterCard's requirements of certificate implementation. Here are some key points to consider when you procure your SSL certificate.

  • The certificate must be in X.509 certificate format.
  • The certificate must have a Key-Usage extension marked as critical, and include client authentication as a permissible use of the certificate.
  • The certificate must be issued by a CA approved by MasterCard. Contact MasterCard to get a list of approved CAs.
  • The subject common name (CN) of the certificate must contain the fully qualified domain name (with or without a wildcard) of the website the certificate is being purchased for.
  • The subject organization (O) field must contain the legal business name of the merchant.
Configuring Merchant Certificates in Merchant Manager

After procuring the certificate from a reputable CA, your payment service provider must configure your certificate in Merchant Manager as part of configuring all the API settings for your merchant profile on the gateway. If required, a merchant certificate may be linked to multiple merchant profiles from the same business or across businesses. For more information on how to configure merchant certificates in Merchant Manager, see the Integration Configuration section in the Merchant Manager User Guide.

The site controls the list of acceptable CA root certificates that are used to verify merchant certificates. To enable certificate verification, the system collects the PEM encoded version of the production certificate through Merchant Manager. The Subject Common Name is extracted from this certificate and verified against the Subject Common Name of the presented certificate during the SSL handshake.

As long as you renew your certificate with the same subject name as the expired certificate you need not update the configuration in Merchant Manager. This is because the system only saves the Subject Common Name of the certificate as a means to validate the certificate.
Integrating the SSL Certificate into your Application

After configuring the certificate against your merchant profile, you must perform the following steps to install the certificate in your environment.

  1. Make the private key and the certificate available to the SSL client software that makes the SSL connection to the MasterCard Payment Gateway. Depending on the software, the private key, certificate and associated certificate chain may need conversion to a supported format. For example, private keys and  certificates are often provided in text files, in PEM format, with the private key protected by a password. In Java, these files are typically loaded into a Java key store. Please consult your software documentation for supported formats.
    For Java and .NET environments, we recommend that you convert the PEM files to PKCS12.
  2. In almost all cases, the issuing CA for your certificate also provides additional certificates known as a certificate chain. You must provide these to the MasterCard Payment Gateway during the SSL handshake to enable the gateway to validate your certificate. Your SSL client software will have instructions on how and where to place these certificates.
  3. A simple test to check whether you have all the necessary certificates is to load them into a web browser such as
    Internet Explorer, Firefox or Safari and browse to the gateway API Check Gateway URL and retrieve the gateway status. If the certificates are correctly loaded, accessing the Check Gateway URL will cause the browser to prompt you to select/accept the certificate to use for connecting with the gateway. If your browser prompts you and a successful connection is achieved you will get the following response: {status: "OPERATING"}.
  4. Most browsers will also require the PEM formatted certificates to be converted. So, using the browser to test the correct certificates will also confirm you can successfully convert the certificates to the appropriate format. Internet Explorer supports the following formats, PKCS#12, PKCS#7 and Microsoft Serialized Certificate Store. The OpenSSL utility is an excellent tool for converting between PEM formats and PKCS based formats.

Check Gateway URL API Reference [REST][NVP]

Using Test Certificates

Test certificates provide you with a way to develop and test PKI authentication without requiring a live certificate. This may be useful, for example, where a certificate has not yet been purchased; or where you do not wish to share the certificate and private key with a third-party web integrator.

Test certificates contain merchant profile data to tightly bind the test certificate with the merchant. You can download test certificates from Merchant Administration, which get generated on download with a short expiry of six to twelve months from the date of download.  To renew a test certificate before the expiry date, you must download the certificate again from Merchant Administration. In cases where multiple merchant profiles are configured to use the same certificate set, then the test certificate may be downloaded only once.

Test certificates can only be used with test merchant profiles and not with production merchant profiles.
The password for the test certificate is the identifier of the merchant's test profile. For example, if the test merchant profile ID is TESTTNSDEMO01 then the password for the certificate is TESTTNSDEMO01.
Rolling Certificates

You may wish to roll from the existing certificate to a new certificate for various reasons. For example, upgrading certificate for a change in company name or rolling from a test certificate (if any) to a production certificate.

"Rolling" involves setting up a new certificate set containing the details for both the old and the new certificates. Merchants that are configured to use the new certificate set may authenticate to the API using either the old certificate or the new certificate. This is meant to be an interim configuration until such time as all integrations have been upgraded to use the new certificate. For more information on how to roll certificates, see the Integration Configuration section in the Merchant Manager User Guide.

Protecting Payer Information using SSL

All websites collecting sensitive or confidential information need to protect the data passed between the payer's Internet browser, the application and the MasterCard Payment Gateway.

SSL is a security technology that is used to secure web server to Internet browser transactions. This includes the securing of any information (such as a payer's credit card number) passed by an Internet browser to a web server (such as your web 'Shop & Buy' application). SSL protects data submitted over the Internet from being intercepted and viewed by unintended recipients.

When implementing the Direct Payment you must ensure your application presents a secure form using SSL. You should also consider using a secure form in your application when collecting confidential information such as payer addresses.

How Do My Payers Know If My Site is Using SSL?

When a payer connects to your application using SSL they will see that the http:// changes to https:// and also a small gold padlock will appear in their Internet browser, for example:


Whenever an Internet browser connects to a web server (website) over https:// - this signifies that the communication with the MasterCard Payment Gateway will be encrypted and secure. You can alert your payers to this fact so they know what to look for when transacting on your website.

Reference Table of Key Differences Between Security Models

The following table outlines some key differences between password and certificate authentication models with the intent of helping you choose the authentication solution that best meets your business' authentication requirements.

  Password Authentication Certificate Authentication
When to Use
With small businesses where simple authentication meets the requirements. With large enterprises where the cost of infrastructure to implement PKI is minimal against the security gained using a higher level of authentication.
Technical Skills Required
Requires knowledge of basic HTTP authentication Requires knowledge of mutual authentication and PKI using Certificate Authorities
Ease of Integration
Easy to integrate Setting up the keystore file and other infrastructure can add to the complexity of the integration.
Level of Authentication Moderate High
Cost Least expensive authentication method to use. Involves additional cost, such as the certifying authority's subscription cost for issuing the SSL certificates.
Benefits Ideal for smaller merchants where the cost of integration is an important factor and business models do not require higher security levels. SSL mutual authentication provides very high security and is considered an industry best practice.
It optimizes authentication performance by using the existing SSL connection, which is typically created anyway. The extra overhead of sending the client certificate is minimal.
Disadvantages Password is embedded as cleartext in the HTTP authentication header and must only ever be sent over SSL. The MasterCard Payment Gateway only accepts SSL- protected connections thereby protecting the password from disclosure; however, it is very important to the security of the connection that proper server authentication be performed to prevent accidental disclosure to rogue servers. None
Support for Sharing Credentials Across Multiple Merchant Profiles Cannot share passwords across multiple merchant profiles Allows you to share a Certificate Set ID with multiple merchant profiles within and across MSOs (privilege-based).

Copyright © 2019 MasterCard