Secure Your Integration with Passwords or Certificates
You can authenticate to the Mastercard Gateway using passwords or SSL certificates.
Password Authentication
You can enable secure access to the Mastercard GatewayDirectAPI 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 DirectAPI
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.
- Log in to https://eu-gateway.mastercard.com/ma with your administrator login credentials.
- Navigate to Admin > Operators
- 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.
- Log out of Merchant Administration, and log in back into Merchant Administration as the new operator.
- Navigate to Admin > Web Services API Integration Settings > Edit.
- Click Generate New, and select the Enable Integration Access Via Password box.
- This is the API password you will use to authenticate API requests made from your web server to the gateway.
- 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 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
Note that the host name for certificate authentication is different from https://eu-gateway.mastercard.com/api. Please contact your payment service provider for the host name.
You must present a certificate to authenticate yourself to the Mastercard Gateway with certificate authentication. 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 which 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 Gateway) to present certificates to authenticate themselves. This is termed as mutual authentication, the workflow for which is illustrated below.
The steps for connecting to the Mastercard Gateway using certificate authentication are:
- The client requests a connection to a protected resource on the server.
- The server presents its certificate chain back to the client.
- The client verifies the server's certificate using a trust store, which contains the trusted root CAs. The client validates the server certificate path to a trusted CA root certificate.
- If successful, the client sends its certificate chain to the server. The client stores its certificate in a key store.
- The gateway 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:
- Checks if the certificate is in X.509 certificate format.
- Validates the certificate path to a trusted CA root certificate.
- Checks if the certificate has not expired.
- Verifies that the client certificate has a Key-Usage extension, marked critical that includes client authentication as a permissible use of the certificate.
- The subject common name of the client certificate is confirmed to match the subject common name configured for the merchant in the gateway.
The subject common name of the certificate must contain the legal business name of the merchant.
- Checks if the presented certificate matches the status of the merchant profile. A production profile only accepts production certificates whereas a test profile accepts either test or production certificates.
If these steps are successful, then the merchant authentication is deemed successful, otherwise the connection is rejected by returning an appropriate error message.
- If all the checks outlined in step 5 are successful, then the server accepts the connection and allows the request to proceed.
Procuring Test and Production Certificate from a CA
Before going live with your production certificate, you can develop and test PKI authentication with a test certificate. This may be useful, for example, where you do not wish to share the production certificate and private key with a third-party web integrator.
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 organization of the merchant.
Configuring Merchant Certificates in Merchant Manager
After procuring the certificate from a reputable CA, your payment service provider must configure your test and/or production 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 API 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.
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.
- Make the private key and the certificate available to the SSL client software that makes the SSL connection to
the Mastercard 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.
- 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 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.
- 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 DirectAPI 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"}.
Check Gateway URL API Reference [REST][NVP]
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 to a production certificate.
To roll to a new certificate, your payment service provider must add the new certificate as a primary certificate while the old certificate becomes an additional certificate. You can have one or more additional certificates. Merchants that are configured to use the new certificate may authenticate to the DirectAPI 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 add additional certificates, see the API Configuration section in the Merchant Manager User Guide.
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:
- Create a session by submitting a API Create Session request from your server to the gateway server. This operation returns a Session Id.
- Submit the Update Session request using session-authentication to add any relevant data to the session created in Step 1.
- 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
- billing.address.city
- billing.address.company
- billing.address.country
- billing.address.postcodeZip
- billing.address.stateProvince
- billing.address.stateProvinceCode
- billing.address.street
- billing.address.street2
- browserPayment.preferredLanguage
- correlationId
- customer.dateOfBirth
- customer.email
- customer.firstName
- customer.lastName
- customer.mobilePhone
- customer.nationalId
- customer.phone
- customer.taxRegistrationId
- device.browser
- device.browserDetails.3DSecureChallengeWindowSize
- device.browserDetails.acceptHeaders
- device.browserDetails.colorDepth
- device.browserDetails.javaEnabled
- device.browserDetails.language
- device.browserDetails.screenHeight
- device.browserDetails.screenWidth
- device.browserDetails.timeZone
- device.fingerprint
- device.hostname
- device.ipAddress
- device.mobilePhoneModel
- gatewayEntryPoint
- locale
- merchant
- order.id
- order.walletProvider
- session.version
- shipping.contact.email
- shipping.contact.firstName
- shipping.contact.lastName
- shipping.contact.mobilePhone
- shipping.contact.phone
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.expiry.month
- sourceOfFunds.provided.card.expiry.year
- sourceOfFunds.provided.card.mobileWallet.emv.emvData
- sourceOfFunds.provided.card.nameOnCard
- sourceOfFunds.provided.card.number
- sourceOfFunds.provided.card.provided.card.prefix
- sourceOfFunds.provided.card.securityCode
- sourceOfFunds.token
- sourceOfFunds.type
- transaction.acquirer.customData
- transaction.acquirer.traceId
- transaction.id
- correlationId
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.amount
- order.currency
- order.customerNote
- order.customerReference
- order.invoiceNumber
- result
- session.updateStatus
- session.version
Initiate Authentication
- apiOperation
- correlationId
- order.walletProvider
- session.id
- session.version
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.number
- sourceOfFunds.token
- sourceOfFunds.type
- authentication.3ds2.methodCompleted
- authentication.3ds2.methodSupported
- authentication.redirect.customized.3DS.methodPostData
- authentication.redirect.customized.3DS.methodUrl
- authentication.redirectHtml
- authentication.version
- correlationId
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.authenticationStatus
- order.currency
- order.status
- response.gatewayCode
- response.gatewayRecommendation
- result
- sourceOfFunds.provided.card.number
- sourceOfFunds.type
- transaction.authenticationStatus
- version
Authenticate Payer
- apiOperation
- billing.address.city
- billing.address.company
- billing.address.country
- billing.address.postcodeZip
- billing.address.stateProvince
- billing.address.stateProvinceCode
- billing.address.street
- billing.address.street2
- correlationId
- device.browser
- device.browserDetails.3DSecureChallengeWindowSize
- device.browserDetails.acceptHeaders
- device.browserDetails.colorDepth
- device.browserDetails.javaEnabled
- device.browserDetails.language
- device.browserDetails.screenHeight
- device.browserDetails.screenWidth
- device.browserDetails.timeZone
- device.ipAddress
- order.walletProvider
- session.id
- session.version
- sourceOfFunds.provided.card.devicePayment.3DSecure.eciIndicator
- sourceOfFunds.provided.card.devicePayment.3DSecure.onlinePaymentCryptogram
- sourceOfFunds.provided.card.devicePayment.cryptogramFormat
- sourceOfFunds.provided.card.devicePayment.emv.emvData
- sourceOfFunds.provided.card.devicePayment.paymentToken
- sourceOfFunds.provided.card.expiry.month
- sourceOfFunds.provided.card.expiry.year
- sourceOfFunds.provided.card.number
- sourceOfFunds.provided.card.securityCode
- authentication.3ds2.acsReference
- authentication.3ds2.challenge.signedContent
- authentication.3ds2.methodCompleted
- authentication.3ds2.methodSupported
- authentication.3ds2.sdk.interface
- authentication.3ds2.sdk.timeout
- authentication.3ds2.sdk.uiType
- authentication.payerInteraction
- authentication.redirect.customized.3DS.acsUrl
- authentication.redirect.customized.3DS.cReq
- authentication.redirect.domainName
- authentication.redirectHtml
- authentication.version
- correlationId
- encryptedData.ciphertext
- encryptedData.nonce
- encryptedData.tag
- error.cause
- error.field
- error.supportCode
- error.validationType
- order.authenticationStatus
- order.currency
- order.status
- response.gatewayCode
- response.gatewayRecommendation
- result
- sourceOfFunds.provided.card.number
- sourceOfFunds.type
- transaction.authenticationStatus
- version
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 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?
Whenever an Internet browser connects to a web server (website) over https:// - this signifies that the communication with the Mastercard 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 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). |