​
Sign-up

Speak to your Mastercard account manager to obtain your credentials.

​
Credentials

When setting up Mastercard in the dashboard you will need to configure the following credentials.

  • Merchant ID: The Mastercard merchant that was shared with you by your Mastercard account manager. To access the Mastercard Gateway test simulator the Merchant ID will need to have the prefix TEST added to it.
  • Password: This will be the API password created in the Mastercard dashboard. This is not the dashboard password that was may have been shared with you by your Mastercard account manager. This field is optional and can be left empty when using PKI authentication.
  • Sandbox hostname: Allows for setting a custom hostname to allow for connecting to the test Mastercard gateway.
  • Notification secret: The secret used to sign the webhook notifications. This is an optional field. Webhooks will not be verified if not provided.

​
Gateway hostname

By default we will connect to Mastercard’s production hostname, ap-gateway.mastercard.com. This domain is used both in our sandbox and production environments, regardless of whether a test merchant ID or regular merchant ID is used.

Mastercard also provides a test gateway that can be used in our sandbox by setting the Sandbox host to test-gateway.mastercard.com.

​
Merchant Privileges

You might need to request the activation of some privileges on your Mastercard account manager depending on your setup.

The following features are known to require specific configuration.

  • 3DS pass-through.
  • Apple Pay/Google Pay token pass-through.
  • Over-capture (Excessive capture)
  • Recurring payments
  • Webhooks notifications

​
Webhooks

Besides requesting the merchant privileges, you might need to activate the webhook notification on the Mastercard dashboard. This can be done by clicking the “Webhooks Notifications” option of the “Admin” dropdown and clicking “Enabled”

If this option is not shown in the dropdown then you might need to enable the option to that specific operator. This can be done by clicking the “Operators” option of the “Admin” dropdown and editing that operator, where you will find the “May Configure Email and Webhook Notifications” option.

​
Recurring payments

In order to facilitate recurring payments, our system will require a scheme transaction ID (trace ID) to be return by Mastercard. This is a feature that needs to be enabled by Mastercard.

Once set up, our system will receive a transactionIdentifier for every Mastercard, Visa, Amex, JCB, and other transactions, as well as an additional financialNetworkCode and financialNetworkDate for Mastercard payments.

Our system will send these values to the Mastercard gateway as a traceId on subsequent calls to facilitate recurring payments. An error may be raised by the gateway if passing in the traceId has not been enabled Please contact Mastercard to have this feature enabled.

​
PKI authentication

Mastercard offers PKI authentication (mutual SSL) as an alternative to username and password authentication, which allows one platform to authenticate on behalf of many merchants.

To set up PKI authentication, please register a certificate with a Mastercard accepted certificate authority and provide us with the certificate, certificate chain, and the private key. Then register the certificate in the Mastercard dashboard.

Once set up, you can leave the password empty when setting up the Mastercard connector in our dashboard, and the connector will automatically use PKI authentication.

Mastercard also provides a test PKI gateway that can be used in our sandbox by setting the Sandbox host to pki.mtf.gateway.mastercard.com.

​
Test cards

Please use the test cards by Mastercard. Please note that these only work for TEST merchant IDs. In a non-test environment, when using the test gateways some additional test cards are available. Please work directly with Mastercard to get these test values.