> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gr4vy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mastercard Gateway - Card

> Connect to Mastercard Gateway to accept card payments.

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](/guides/dashboard/flow/overview) 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 code | Country code | Country code | Country code | Country code | Country code | Country code | Country code |
| ------------ | ------------ | ------------ | ------------ | ------------ | ------------ | ------------ | ------------ |
| `AE`         | `AL`         | `AM`         | `AO`         | `AR`         | `AT`         | `AU`         | `AW`         |
| `AZ`         | `BA`         | `BB`         | `BD`         | `BE`         | `BG`         | `BH`         | `BM`         |
| `BN`         | `BO`         | `BR`         | `BS`         | `BW`         | `BY`         | `BZ`         | `CA`         |
| `CH`         | `CN`         | `CO`         | `CR`         | `CU`         | `CY`         | `CZ`         | `DE`         |
| `DJ`         | `DK`         | `DO`         | `DZ`         | `EE`         | `EG`         | `ES`         | `ET`         |
| `FI`         | `FJ`         | `FK`         | `FR`         | `GB`         | `GE`         | `GH`         | `GI`         |
| `GM`         | `GN`         | `GR`         | `GT`         | `GY`         | `HK`         | `HN`         | `HR`         |
| `HT`         | `HU`         | `IE`         | `IL`         | `IN`         | `IQ`         | `IS`         | `IT`         |
| `JM`         | `JO`         | `JP`         | `KE`         | `KG`         | `KH`         | `KM`         | `KR`         |
| `KW`         | `KY`         | `KZ`         | `LA`         | `LB`         | `LK`         | `LT`         | `LU`         |
| `LV`         | `LY`         | `MA`         | `MD`         | `MK`         | `MM`         | `MN`         | `MO`         |
| `MR`         | `MT`         | `MU`         | `MV`         | `MW`         | `MX`         | `MY`         | `MZ`         |
| `NA`         | `NG`         | `NI`         | `NL`         | `NO`         | `NP`         | `NZ`         | `OM`         |
| `PA`         | `PE`         | `PG`         | `PH`         | `PK`         | `PL`         | `PT`         | `PY`         |
| `QA`         | `RO`         | `RS`         | `RU`         | `RW`         | `SA`         | `SB`         | `SC`         |
| `SE`         | `SG`         | `SH`         | `SI`         | `SK`         | `SL`         | `SO`         | `SR`         |
| `ST`         | `SV`         | `SZ`         | `TH`         | `TN`         | `TO`         | `TR`         | `TT`         |
| `TW`         | `TZ`         | `UA`         | `UG`         | `US`         | `UY`         | `UZ`         | `VE`         |
| `VN`         | `VU`         | `WS`         | `YE`         | `ZA`         | `ZM`         |              |              |

## Supported currencies

Mastercard Gateway supports processing payments in the following currencies:

| Currency code | Currency code | Currency code | Currency code | Currency code | Currency code | Currency code | Currency code |
| ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- | ------------- |
| `AED`         | `AFN`         | `ALL`         | `AMD`         | `AOA`         | `ARS`         | `AUD`         | `AWG`         |
| `AZN`         | `BAM`         | `BBD`         | `BDT`         | `BHD`         | `BIF`         | `BMD`         | `BND`         |
| `BOB`         | `BOV`         | `BRL`         | `BSD`         | `BTN`         | `BWP`         | `BYN`         | `BZD`         |
| `CAD`         | `CDF`         | `CHE`         | `CHF`         | `CHW`         | `CLF`         | `CLP`         | `CNY`         |
| `COP`         | `COU`         | `CRC`         | `CUP`         | `CVE`         | `CZK`         | `DJF`         | `DKK`         |
| `DOP`         | `DZD`         | `EGP`         | `ERN`         | `ETB`         | `EUR`         | `FJD`         | `FKP`         |
| `GBP`         | `GEL`         | `GHS`         | `GIP`         | `GMD`         | `GNF`         | `GTQ`         | `GYD`         |
| `HKD`         | `HNL`         | `HTG`         | `HUF`         | `IDR`         | `ILS`         | `INR`         | `IQD`         |
| `IRR`         | `ISK`         | `JMD`         | `JOD`         | `JPY`         | `KES`         | `KGS`         | `KHR`         |
| `KMF`         | `KPW`         | `KRW`         | `KWD`         | `KYD`         | `KZT`         | `LAK`         | `LBP`         |
| `LKR`         | `LRD`         | `LSL`         | `LYD`         | `MAD`         | `MDL`         | `MGA`         | `MKD`         |
| `MMK`         | `MNT`         | `MOP`         | `MRU`         | `MUR`         | `MVR`         | `MWK`         | `MXN`         |
| `MXV`         | `MYR`         | `MZN`         | `NAD`         | `NGN`         | `NIO`         | `NOK`         | `NPR`         |
| `NZD`         | `OMR`         | `PAB`         | `PEN`         | `PGK`         | `PHP`         | `PKR`         | `PLN`         |
| `PYG`         | `QAR`         | `RON`         | `RSD`         | `RUB`         | `RWF`         | `SAR`         | `SBD`         |
| `SCR`         | `SDG`         | `SEK`         | `SGD`         | `SHP`         | `SLE`         | `SOS`         | `SRD`         |
| `SSP`         | `STN`         | `SVC`         | `SYP`         | `SZL`         | `THB`         | `TJS`         | `TMT`         |
| `TND`         | `TOP`         | `TRY`         | `TTD`         | `TWD`         | `TZS`         | `UAH`         | `UGX`         |
| `USD`         | `USN`         | `UYI`         | `UYU`         | `UYW`         | `UZS`         | `VED`         | `VES`         |
| `VND`         | `VUV`         | `WST`         | `XAF`         | `XCD`         | `XCG`         | `XOF`         | `XPF`         |
| `YER`         | `ZAR`         | `ZMW`         | `ZWG`         |               |               |               |               |

## 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](/guides/payments/embed/quick-start)** - A pre-built, customizable
  payment form that handles the complete payment flow
* **[Secure Fields](/guides/payments/secure-fields/quick-start)** - Embed card
  input fields for building custom payment forms while maintaining PCI
  compliance
* **[Mobile SDKs](/guides/get-started#sdks-and-plugins)** - 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](https://test-gateway.mastercard.com/api/documentation/integrationGuidelines/supportedFeatures/testAndGoLive.html)
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.