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.

​
Features

Mastercard Gateway supports the following features:
  • Delayed capture - Authorize a payment and capture it at a later time
  • Partial capture - Capture a portion of the authorized amount
  • Partial refunds - Refund a portion of the captured amount
  • Refunds - Refund a captured payment
  • Void - Cancel an authorized transaction before capture
  • Zero auth - Verify a card without charging it
  • Over capture - Capture more than the originally authorized amount
  • Digital wallets - Support for Apple Pay, Google Pay, and other wallet integrations
  • Network tokens - Network tokenization is enabled by default
  • Transaction sync - Synchronize transaction status with Mastercard Gateway
  • 3-D Secure - Pass-through 3DS authentication
  • Webhooks required - Webhooks are required for status updates

​
Supported countries

Mastercard Gateway supports transactions from buyers in the following countries:
Country codeCountry codeCountry codeCountry codeCountry codeCountry codeCountry codeCountry code
AEALAMAOARATAUAW
AZBABBBDBEBGBHBM
BNBOBRBSBWBYBZCA
CHCNCOCRCUCYCZDE
DJDKDODZEEEGESET
FIFJFKFRGBGEGHGI
GMGNGRGTGYHKHNHR
HTHUIEILINIQISIT
JMJOJPKEKGKHKMKR
KWKYKZLALBLKLTLU
LVLYMAMDMKMMMNMO
MRMTMUMVMWMXMYMZ
NANGNINLNONPNZOM
PAPEPGPHPKPLPTPY
QARORSRURWSASBSC
SESGSHSISKSLSOSR
STSVSZTHTNTOTRTT
TWTZUAUGUSUYUZVE
VNVUWSYEZAZM

​
Supported currencies

Mastercard Gateway supports processing payments in the following currencies:
Currency codeCurrency codeCurrency codeCurrency codeCurrency codeCurrency codeCurrency codeCurrency codeCurrency codeCurrency code
AEDAFNALLAMDAOAARSAUDAWGAZNBAM
BBDBDTBGNBHDBIFBMDBNDBOBBOVBRL
BSDBTNBWPBYNBZDCADCDFCHECHFCHW
CLFCLPCNYCOPCOUCRCCUPCVECZKDJF
DKKDOPDZDEGPERNETBEURFJDFKPGBP
GELGHSGIPGMDGNFGTQGYDHKDHNLHTG
HUFIDRILSINRIQDIRRISKJMDJODJPY
KESKGSKHRKMFKPWKRWKWDKYDKZTLAK
LBPLKRLRDLSLLYDMADMDLMGAMKDMMK
MNTMOPMRUMURMVRMWKMXNMXVMYRMZN
NADNGNNIONOKNPRNZDOMRPABPENPGK
PHPPKRPLNPYGQARRONRSDRUBRWFSAR
SBDSCRSDGSEKSGDSHPSLESOSSRDSSP
STNSVCSYPSZLTHBTJSTMTTNDTOPTRY
TTDTWDTZSUAHUGXUSDUSNUYIUYUUYW
UZSVEDVESVNDVUVWSTXAFXCDXCGXOF
XPFYERZARZMWZWG

​
Limitations

The following features are not supported by this connector:
  • 3-D Secure hosted - Hosted 3DS flows are not supported
  • Create session - Session creation is not supported
  • Partial authorization - Partial authorization is not supported
  • Payment method tokenization - Storing payment methods outside of transactions using a separate tokenization flow
Additional limitations include:
  • 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/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.