Set Up API Credentials
You can generate a password if you want to use password authentication, or set up your Public Key Infrastructure (PKI) if you want to use SSL certificate authentication.
Generate a password
You can generate your API password in the Merchant Administration (MA).
Prerequisites
Ensure that the following prerequisites are met.
- Your merchant profile must be enabled for API, Batch, and Use Password Authentication privileges. If unsure, check with your payment service provider.
- Your payment service provider provides your login credentials for the MA when you are successfully boarded onto Mastercard Gateway. As an administrator, you can create new operators in the MA and give them permissions to generate the API password.
To generate a password:
- Log in to https://test-nbkpayment.mtf.gateway.mastercard.com/ma with your login credentials.
- Go to Admin > Operators.
- Create a new operator by entering values for all mandatory fields. Assign the May Configure Integration Settings privilege to enable the operator to generate the API password.
- Log in again in the MA portal as a new operator.
- Go to Admin > Integration Settings > Edit.
- Select Generate New, and then select the Enable Integration Access Via Password checkbox.
Note the API password that you must use to authenticate API requests made from your web server to the gateway.
- Select Submit.
You must always have at least one password generated and enabled. You can have upto two passwords set up. For security, change the password periodically. Only one password must be used for configuring your app, the second one working as a standby for password rolling purposes.
Once the password is generated, you must include it in all the API requests directed to the gateway. If the request is sent using the REST-JSON protocol, then the request must contain your merchant ID and password in the standard HTTP basic Authorization header:
Basic <base64-encoded string of “merchant.<merchant_ID>:<password>”>
Set up PKI for your certificates
To set up your PKI, you must:
- Procure the needed certificates.
- Request your payment service provider to configure your certificates.
- Integrate a certificate in your app.
You can conveniently roll certificates if you need to move from one certificate to a another without any break in the service.
Step 1. Procure a test and production certificates from a Certificate Authority (CA)
Before going live with your production certificate, you can develop and test PKI authentication with a test certificate. This may be useful if you do not want to share the production certificate and private key with a third-party web integrator.
The SSL certificate that you procure from your chosen CA must meet the following Mastercard requirements:
- 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, which can be with or without a wildcard, of the website for which the certificate is being purchased.
- The subject Organization (O) field must contain the organization of the merchant.
Step 2: Request certificate configuration
After procuring your certificates, contact your payment service provider and ask them to configure your certificates in the Merchant Manager (MM) website as part of configuring all the API settings for your merchant profile on the gateway.
If required by your business model, one certificate can be linked to multiple merchant profiles from the same business or across businesses.
The MM website controls the list of acceptable CA root certificates that are used to verify certificates. To enable certificate verification, the system collects the PEM-encoded version of the production certificate through the MM. The subject CN is extracted from this certificate and verified against the subject CN of the presented certificate during the SSL handshake.
Step 3: Integrate the SSL certificate in your app
After your payment service provider has configured your certificate against your merchant profile, you must install that certificate in your environment:
- Make the private key and the certificate available to the SSL client software that makes the SSL connection to the 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. Consult your software documentation for supported formats.
For Java and .NET environments, it is recommended 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 gateway during the SSL handshake to enable the gateway for validation of your certificate. Follow your SSL client software's instructions about how and where to place these certificates.
- Perform a simple test to check whether you have all the necessary certificates. Load them into a web browser, such as, Edge, Firefox, Safari, and browse the Check Gateway API request's URL and retrieve the gateway status.
If the certificates are correctly loaded, accessing the Check Gateway URL causes the browser to prompt you to select and accept the certificate to use for connecting to the gateway. If your browser prompts you and a successful connection is achieved, you get the following response:
{status: "OPERATING"}.Most browsers also require the converted PEM-formatted certificates. The preceding test also confirms whether you have successfully converted the certificates to the appropriate format.
Edge supported formats are PKCS#12, PKCS#7, and Microsoft Serialized Certificate Store. The OpenSSL utility is an excellent tool for converting PEM formats and PKCS-based formats.
Rolling certificates
You can roll from the existing certificate to a new certificate for various reasons. For example, upgrading a certificate for a change in the 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 to the MM website as a primary certificate while the old certificate becomes an additional certificate. You can have one or more additional certificates.
After configuring to use the new certificate, you can 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 are upgraded to use the new certificate and the additional certificate can be removed from the MM website.