Skip to main content
Mastercard Gateway is a payment processing platform that provides card payment processing solutions for merchants worldwide. It supports advanced features like network tokenization, over-capture, and recurring payments.

​
Setup

Speak to your Mastercard account manager to obtain your credentials.

​
Connector configuration

After setting up your Mastercard Gateway connector in the dashboard, configure how transactions are routed to it. Choose one of the following options:
  • Using Flow - Configure Mastercard Gateway as the target connector in Flow to automatically route card transactions to this connector
  • Using the API - Explicitly set the payment_service_id parameter to the Mastercard Gateway connector ID when creating transactions. This overrides any Flow routing rules.
The connector ID can be found in the dashboard under Connections -> Configured connections.

​
Credentials

When setting up Mastercard Gateway in the dashboard, configure the following credentials.
  • Merchant ID - The Mastercard merchant ID shared by your account manager. To access the Mastercard Gateway test simulator, add the prefix TEST to your merchant ID.
  • Password - The API password created in the Mastercard dashboard (not your dashboard login password). This field is optional and can be left empty when using PKI authentication.
  • Sandbox hostname - A custom hostname for connecting to the test Mastercard gateway.
  • Notification secret - The secret used to sign webhook notifications. Webhooks are not verified if not provided.
  • Skip the automatic void of the authorization remainder after a partial capture - When enabled, prevents automatic voiding of remaining authorization after a partial capture.

​
Sandbox hostname

By default the connection connects to Mastercard’s production hostname, ap-gateway.mastercard.com. This domain is used both in the 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 the 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 find the “May Configure email and Webhook Notifications” option.

​
Capabilities

​
Supported countries

​
Supported currencies

​
Limitations

  • Automatic void after partial capture - By default, Mastercard Gateway automatically voids the remaining authorization after a partial capture. You can turn off this behavior in the connector credentials.
  • Merchant privileges required - Some features require specific configuration by your Mastercard account manager, including 3DS pass-through, Apple Pay and Google Pay token pass-through, over-capture, recurring payments, and webhook notifications.

​
Integration

To accept card payments with Mastercard Gateway, use one of Gr4vy’s client-side integration methods to securely collect card details. Due to PCI compliance requirements, card data should never be sent directly to your servers. You can integrate using:
  • Embed - A pre-built, customizable payment form that handles the complete payment flow
  • Secure Fields - Embed card input fields for building custom payment forms while maintaining PCI compliance
  • Mobile SDKs - Native SDKs for iOS, Android, React Native, and other platforms
These methods handle card data collection and tokenization. Once the card details are collected and tokenized, create a transaction through the Gr4vy API, which routes the payment to your configured Mastercard Gateway connection based on your Flow rules or explicit payment_service_id parameter.

​
Recurring payments

In order to facilitate recurring payments, the system requires 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, the system receives a transactionIdentifier for every Mastercard, Visa, American Express, JCB, and other transactions, as well as an additional financialNetworkCode and financialNetworkDate for Mastercard payments. The system sends 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 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 the dashboard, and the connector automatically uses PKI authentication. Mastercard also provides a test PKI gateway that can be used in the 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.