Card via Mastercard Gateway
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 host: Allows for setting a custom hostname to allow for connecting to the test Mastercard gateway.
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.