> ## 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. export const connector = { displayName: "Mastercard Gateway", method: "card", features: "create_token create_transaction delayed_capture delete_token digital_wallets direct_capture network_tokens_default open_loop over_capture partial_capture partial_refunds refunds requires_void_after_final_capture requires_void_after_partial_capture requires_webhook_setup three_d_secure_pass_through transaction_sync verify_credentials void zero_auth", supportedCountries: "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", supportedCurrencies: "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" }; export const ConnectorRegions = ({data, kind, name: nameOverride}) => { const [query, setQuery] = useState(""); const [open, setOpen] = useState(false); const isCountries = kind === "countries"; const raw = data && (isCountries ? data.supportedCountries : data.supportedCurrencies); const codes = typeof raw === "string" ? raw.split(/\s+/).filter(Boolean) : Array.isArray(raw) ? raw : []; const DISPLAY_NAME_OVERRIDES = { authorizenet: "Authorize.net", cardpointe: "Fiserv CardPointe", dlocal: "dLocal", shift4i4go: "Shift4 i4go", tokenex: "TokenEx" }; const rawName = data && data.displayName || ""; const name = nameOverride || DISPLAY_NAME_OVERRIDES[rawName.toLowerCase()] || rawName || "This connector"; const verb = isCountries ? "supports transactions from buyers in" : "supports processing payments in"; const noun = isCountries ? "countries" : "currencies"; if (codes.length === 0) return null; let displayNames = null; try { displayNames = new Intl.DisplayNames(["en"], { type: isCountries ? "region" : "currency" }); } catch (e) { displayNames = null; } const resolve = code => { if (!displayNames) return null; try { const resolved = displayNames.of(code); return resolved && resolved !== code ? resolved : null; } catch (e) { return null; } }; const MAJOR_CURRENCIES = ["USD", "EUR", "GBP", "CAD", "AUD", "JPY", "CHF", "CNY", "SGD", "HKD", "NZD", "SEK", "NOK", "DKK", "MXN", "BRL", "INR"]; const items = codes.map(code => ({ code, label: resolve(code) })); if (isCountries) { items.sort((a, b) => (a.label || a.code).localeCompare(b.label || b.code)); } else { const rank = code => { const i = MAJOR_CURRENCIES.indexOf(code); return i === -1 ? MAJOR_CURRENCIES.length : i; }; items.sort((a, b) => rank(a.code) - rank(b.code) || a.code.localeCompare(b.code)); } if (codes.length <= 3) { const parts = items.map(it => isCountries || !it.label ? it.label || it.code : `${it.label} (${it.code})`); const joined = parts.length === 1 ? parts[0] : parts.length === 2 ? `${parts[0]} and ${parts[1]}` : `${parts.slice(0, -1).join(", ")}, and ${parts[parts.length - 1]}`; return

{name} {verb} {joined}.

; } const chipStyle = { display: "inline-flex", alignItems: "baseline", gap: "0.4rem", padding: "0.15rem 0.55rem", borderRadius: "0.375rem", border: "1px solid rgba(128, 128, 128, 0.25)", fontSize: "0.875rem", lineHeight: 1.5 }; const codeStyle = { fontFamily: "var(--font-mono, ui-monospace, monospace)", fontWeight: 600, fontSize: "0.8125rem" }; const controlStyle = { color: "inherit", background: "transparent", border: "1px solid rgba(128, 128, 128, 0.3)", borderRadius: "0.5rem", fontSize: "0.875rem" }; const renderChip = it => {isCountries ? it.label || it.code : {it.code}} {!isCountries && it.label ? {it.label} : null} ; const PREVIEW = 5; const collapsible = items.length > PREVIEW; const q = query.trim().toLowerCase(); const filtered = q ? items.filter(it => it.code.toLowerCase().includes(q) || it.label && it.label.toLowerCase().includes(q)) : items; const expanded = open || q !== ""; const visible = !collapsible ? items : expanded ? filtered : items.slice(0, PREVIEW); const toggle = () => { const next = !open; setOpen(next); if (!next) setQuery(""); }; return

{name} {verb} the following {codes.length} {noun}:

{collapsible ? setQuery(e.target.value)} placeholder={`Filter ${noun}…`} aria-label={`Filter ${noun}`} style={{ ...controlStyle, display: "block", width: "100%", maxWidth: "22rem", padding: "0.4rem 0.7rem", margin: "0 0 0.75rem" }} /> : null}
{visible.map(renderChip)}
{q && filtered.length === 0 ?

No {noun} match “{query.trim()}”.

: null} {q && filtered.length > 0 ?

Showing {filtered.length} of {items.length}.

: null} {collapsible && !q ? : null}
; }; export const ConnectorCapabilities = ({data}) => { const CAPABILITIES = [{ keys: ["three_d_secure_hosted"], label: "3-D Secure (hosted)", description: "Gr4vy-hosted 3DS authentication flow.", cardOnly: true }, { keys: ["three_d_secure_pass_through"], label: "3-D Secure (pass-through)", description: "Pass through 3DS data authenticated by a third party.", cardOnly: true }, { keys: ["partial_authorization"], label: "Partial authorization", description: "Support partial approval responses." }, { keys: ["zero_auth"], label: "Zero auth", description: "Verify a card without charging it." }, { keys: ["void"], label: "Void", description: "Cancel an authorized transaction before capture." }, { keys: ["direct_capture"], label: "Direct capture", description: "Capture a payment immediately at authorization.", hideWhenUnsupported: true }, { keys: ["delayed_capture"], label: "Delayed capture", description: "Authorize a payment and capture it at a later time." }, { keys: ["partial_capture"], label: "Partial capture", description: "Capture a portion of the authorized amount." }, { keys: ["over_capture"], label: "Over capture", description: "Capture more than the originally authorized amount." }, { keys: ["refunds"], label: "Refunds", description: "Refund a captured payment." }, { keys: ["partial_refunds"], label: "Partial refunds", description: "Refund a portion of the captured amount." }, { keys: ["settlement_reporting"], label: "Settlement reporting", description: "Automatic settlement and reconciliation reporting." }, { keys: ["create_session"], label: "Create session", description: "Create a connector session for client-side flows." }, { keys: ["network_tokens_default", "network_tokens_toggle"], label: "Network tokens", description: "Network-level tokenization for improved approval rates.", cardOnly: true }, { keys: ["digital_wallets"], label: "Digital wallets", description: "Apple Pay, Google Pay, and other wallet integrations." }, { keys: ["payment_method_tokenization", "payment_method_tokenization_toggle"], label: "Payment method tokenization", description: "Store payment methods outside of transactions." }, { keys: ["transaction_sync"], label: "Transaction sync", description: "Synchronize transaction state from the connector." }, { keys: ["create_token"], label: "Tokenization", description: "Create a token from card details collected via Secure Fields.", hideWhenUnsupported: true }, { keys: ["delete_token"], label: "Delete token", description: "Delete a stored token.", hideWhenUnsupported: true }, { keys: ["verify_credentials"], label: "Verify credentials", description: "Validate the configured credentials against the connector.", hideWhenUnsupported: true }]; const raw = data && data.features; const enabled = typeof raw === "string" ? new Set(raw.split(/\s+/).filter(Boolean)) : Array.isArray(raw) ? new Set(raw) : new Set(Object.keys(raw || ({})).filter(key => raw[key])); const isOn = entry => entry.keys.some(key => enabled.has(key)); const isNonCard = data && data.method && data.method !== "card"; const renderGroup = (title, entries, supported) => { if (entries.length === 0) return null; const mark = supported ? "✓" : "✕"; const markColor = supported ? "#16a34a" : "#9ca3af"; return
{title}
{}
{entries.map(entry =>
{entry.label} {entry.description ? — {entry.description} : null}
)}
; }; const visible = isNonCard ? CAPABILITIES.filter(entry => !entry.cardOnly) : CAPABILITIES; const supported = visible.filter(isOn); const unsupported = visible.filter(entry => !isOn(entry) && !entry.hideWhenUnsupported); return
{renderGroup("Supported", supported, true)} {renderGroup("Not supported", unsupported, false)}
; }; 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. ## 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](/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.