• Integration Guidelines
• Supported Features (Security)
• Secure Your Integration with Passwords or Certificates

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.

Generate Password for API

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

To access Merchant Administration, you need your login credentials. Administrator login credentials will be provided to you by your payment service provider when you are successfully boarded onto the gateway. As an administrator, you can create a new operator with permissions to generate the API password.

1. Log in to https://na.gateway.mastercard.com/ma with your administrator login credentials.
2. Navigate to Admin > Operators
3. Create a new operator by entering all the mandatory fields. Assign "May Configure Integration Settings" privilege to enable the operator to generate the API password.
4. Log out of Merchant Administration, and log in back into Merchant Administration as the new operator.
5. Navigate to Admin > Web Services API Integration Settings > Edit.
6. Click Generate New, and select the Enable Integration Access Via Password box.
7. This is the API password you will use to authenticate API requests made from your web server to the gateway.
8. 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.

Password API Reference [REST][NVP]

Certificate Authentication

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.

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.
Depending on the Web Server client software, the trust store and key store are often the same.
5. 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.
6. 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.

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

Session Authentication

Session authentication uses the gateway payment session, a temporary container for request fields, to authenticate the merchant. Because the payment session is created by an authenticated merchant (using password/certificate authentication), the payer can use it for gateway interactions such as performing authentication operations.

This authentication mechanism allows payers to provide their payment details directly to the gateway. The payer data is obtained via a client-side interaction with the gateway, either through the payer's browser or an app on the payer's mobile device. It provides a simple integration model to securely obtain the required payer data as the API requests to the gateway are performed directly from the client than from your server.

It uses basic HTTP authentication mechanism (similar to password authentication) where you must provide 'merchant.<your gateway merchant ID>;> in the userid portion and the session Id in the password portion.

To use this authentication type:

1. Create a session by submitting a API Create Session request from your server to the gateway server. This operation returns a Session Id.
2. Submit the Update Session request using session-authentication to add any relevant data to the session created in Step 1.
3. Provide the session to the payer.

Supported Transactions

The following operations support authentication using a session ID.

• Update Session
• Initiate Authentication
• Authenticate Payer

Payer Input and Payer Output Fields

In session-authenticated interactions with the gateway, the payer is restricted to a subset of fields within an API operation. These are referred to as payer input fields. If you provide fields other than payer input fields in a session-authenticated request, the request is rejected. For example, the payer cannot submit data such as the order amount.

Similar to payer input fields, the gateway allows only certain fields to be returned in the response for a session-authenticated interactions with the gateway. These are referred to as payer output fields — only fields that are required to be displayed to a payer on a browser or an app to perform a transaction are returned. For example, security sensitive data such as the session Id is not returned.

Update Session

Initiate Authentication

Authenticate Payer

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.