# Testing and Tools
source: https://developer.mastercard.com/mastercard-gateway/documentation/testing/index.md

### Overview {#overview}

This guide helps Mastercard Gateway merchants and integrators test their payment integration before going live.
By following these steps, you can confirm that your integration handles payments correctly, manages errors, and is ready for real transactions.
Testing ensures that your integration works as expected. You cannot move to a live environment or process real payments until you confirm that your integration works in all scenarios.

### Ready to begin testing? {#ready-to-begin-testing}

Before you start, ensure you have a completed basic integration, along with all required payment methods and configurations. Also implement all required features and security functionality to support thorough testing.

### Core testing steps (all integrations) {#core-testing-steps-all-integrations}

#### Prerequisites {#prerequisites}

Before you start testing your integration, complete:

* The basic integration for your chosen integration method:
  * [Hosted Checkout integration](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-checkout/integrate-hosted-checkout/index.md)
  * [Hosted Batch integration](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-batch/integrate-hosted-batch/index.md)
  * [Hosted Session integration](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/integrate-hosted-session/index.md)
  * [Direct Payment integration](https://developer.mastercard.com/mastercard-gateway/documentation/build/direct-payment/integrate-direct-payment/index.md)
  * [Mobile integration](https://developer.mastercard.com/mastercard-gateway/documentation/build/mobile-integration/integrate-mobile-payments/index.md)
* Integration for any subsequent operations supported by your chosen integration method that you want to handle in the order lifecycle:
  * [Hosted Checkout subsequent operations](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-checkout/integrate-gateway-features/index.md)
  * [Hosted Session subsequent operations](https://developer.mastercard.com/mastercard-gateway/documentation/build/hosted-session/integrate-gateway-features/index.md)
* Any customizations for the [payment methods](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/index.md) you support
* All required [features](https://developer.mastercard.com/mastercard-gateway/documentation/build/direct-payment/integrate-gateway-features/index.md) and [security-related functionality](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/index.md)

#### Testing your integration {#testing-your-integration}

Before you accept real payments, test your setup to ensure everything works as expected. This includes:

* **Connectivity testing** : Verify that your system can connect to the gateway and receive an `OPERATING` status.
* **Use test card numbers** to simulate payment scenarios such as successful, declined, and error responses.
* Test all required operations for each supported payment method.
* Test payment flows, including combinations of initial and subsequent transactions.
* **Test security features** such as 3‑D Secure (3DS) authentication or tokenization, if used.
* **Authentication methods**: Use SSL certificates or API passwords.
* **Hosted Payment Pages**: Test payer-facing forms and their interaction with the gateway.
* **Session management**: Use JavaScript libraries to test session creation and secure data collection.
* Verify that your system handles error scenarios such as invalid requests and server issues.
  * For examples, see [Common transaction failures](https://developer.mastercard.com/mastercard-gateway/documentation/testing/comm-error-and-how-to-handle/index.md).
* **Test transaction types** such as purchases, authorization, capture, refund, and void.
* Identify responses that require follow-up actions and verify that your integration handles them correctly.

#### Testing tools {#testing-tools}

To test your integration, the Mastercard Gateway provides some helpful tools:

##### Test Merchant Account Simulator {#test-merchant-account-simulator}

Use simulators available through your test merchant account to validate requests. To confirm that you are using a test account, check that your merchant ID includes the `TEST` prefix provided by your payment service provider (PSP).

All requests sent with a test merchant ID are treated as test requests. These requests are handled by simulators and are not sent to providers, issuers, or acquirers.
Warning: If your merchant ID already includes the `TEST` prefix, it is a test account. Your PSP provides a separate merchant ID for live transactions. The test account is separate from your production account and uses different API credentials or certificates. When switching environments, update both the merchant ID and authentication credentials. For payment methods that require payer approval on a provider website, the gateway provides an interactive payment simulator. For details, see the test instructions for specific payment methods and [Testing a Browser Payment Integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/test-brow-pay-int/index.md).

##### Test cards {#test-cards}

If you support card payments, use test cards to simulate scenarios such as EMV 3‑D Secure authentication. For details, see [Test Cards](https://developer.mastercard.com/mastercard-gateway/documentation/testing/test-cards/index.md) and [Testing a Browser Payment Integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/test-brow-pay-int/index.md).

##### Predictable response results {#predictable-response-results}

The test simulator generates predictable results based on the transaction request and card details. For details, see [Test Cards](https://developer.mastercard.com/mastercard-gateway/documentation/testing/test-cards/index.md) and [Testing a Browser Payment Integration](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/test-brow-pay-int/index.md).

You can trigger responses that include:

* Mastercard Gateway response codes
* Card security code (CVC) validation results
* Address Verification Service (AVS) results

This allows you to verify that your integration handles each response correctly. You can also test response behavior for features such as [wallets](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/index.md).
Tip: Start testing in the Mastercard Test Facility (MTF): `test-gateway.mastercard.com`.

## FAQs {#faqs}

The [surcharging](https://developer.mastercard.com/mastercard-gateway/documentation/gateway-features/surcharging/index.md) functionality on Mastercard Gateway allows a merchant to apply a surcharge on a transaction based on the following parameters:

* Gateway entry point such as Hosted Checkout or API.
* Payment method such as Mastercard, Visa, or American Express.
* Funding method such as Credit or Debit.
* Currency.
Yes, you can configure the [IP Country filtering rules](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/risk-management/transc-filtering/index.md) in Merchant Administration. Your payment service provider can configure rules for you in Merchant Manager, in addition to rules that apply to all their merchants. This will allow you to reject or review transactions that originate from the IP addresses associated with high-risk countries. [Refunds](https://developer.mastercard.com/mastercard-gateway/documentation/build/direct-payment/integrate-direct-payment/transaction-operations/index.md) can be performed only when a funds transfer is completed either through a Pay or a Capture. Void (Cancel) can be performed only on transactions that have not been sent to the bank by the acquirer for processing at the end of the day. Yes, you can set a recurring payment with a variable amount, for example, payment of post-paid bills. You need to update the amountVariability parameter value according to the requirements. For more information, see [Credential On File Transactions](https://developer.mastercard.com/mastercard-gateway/documentation/security-and-fraud/cred-file-transc/index.md). The maximum value is constrained by the 32‑bit integer limit, resulting in a maximum valid amount of 21,474,836.47 in any currency. Mastercard Gateway only accepts an amount field with a maximum length of 10 characters, including the decimal point. This depends on the financial institution who issued the card to the payer. Each card issuer defines the authorization expiry period in which they hold the funds on the payer's account, while they wait for the arrival of the capture transaction. Generally, it is 5-8 processing days, before the authorization purges from the payer account and access to the funds are released back to the payer. See [Multiple Card Details Precedence Rules](https://developer.mastercard.com/mastercard-gateway/documentation/build/direct-payment/integrate-gateway-features/using-multiple-sources-of-payment/index.md). Merchant Administration is a web-based interface that allows merchants to easily view and manage their orders. The merchants can search and view their order/transaction details, download CSV reports, check 3-D Secure results, set up risk controls, create orders manually, manage refunds, and much more. Refer to Merchant Administration User Guide for more details.

Merchants need to be boarded on the gateway and have their merchant profile configured successfully to access Merchant Administration.
The issuer or card network may provide additional information in the form of a Merchant Advice Code, which will help you understand the reason for declining the transaction. When a transaction is declined for insufficient funds, the advice code may recommend a retry time frame to merchants in which an authorization approval is likely to be successful. For more information about Merchant Advice Codes for declined transactions, see the [Code and Formats](https://developer.mastercard.com/mastercard-gateway/documentation/code-and-formats/index.md#merchant-advice-codes-1d) section. Merchants can perform testing in the following environments:

MTF environment using a TEST prefix merchant ID. This configuration allows merchants to use the test cards listed in the [Integration guide](https://developer.mastercard.com/mastercard-gateway/documentation/index.md). The gateway generates simulated responses without sending requests to the network.
Production environment using a TEST prefix merchant ID. In this setup, the gateway continues to generate simulated responses. Use this option only if the MTF environment does not support the required test scenarios.
Digital wallets in the production environment with a TEST prefix merchant ID:

* [Apple Pay](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/apple-pay/index.md)
* [Google Pay](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/google-pay/index.md)
* [Samsung Pay](https://developer.mastercard.com/mastercard-gateway/documentation/payment-methods/digital-wallets/samsung-pay/index.md)
**Usage limitations:**
This setup is required only when merchants need to generate a Draft Capture File (DCF). It is a specialised configuration and is used infrequently. Only use this option when explicitly arranged as part of your implementation.

**Gateway behavior:**
In this configuration, the gateway does not simulate responses. Instead, it routes transaction data to the authorization system. The scheme then forwards the request to the issuer test host.

**Testing constraints:**
The gateway does not provide specific test PANs for this environment. It cannot guarantee that a card will return the same response in repeated tests.
Using gateway test cards in this environment may result in the following response codes:

* 14 --- Invalid Card Number
* 15 --- Invalid Issuer
This response typically occurs when the MTF environment or issuer test host is unavailable.

**MTF environment maintenance:**
The Mastercard MTF environment undergoes regular maintenance and gateway updates. These activities may cause transaction failures during testing.

**Support and escalation:**
If you have an open CIS testing project, contact your CIS implementations manager.
If you do not have an open CIS project, contact your technical account manager.

**Testing guidance:**
Your manager can provide information about available end to end testing windows. They can also advise on the current status of the MTF environment and its readiness for testing. Use this guidance to plan your testing activities and reduce disruptions to your schedule.
**Credentials and endpoint configuration:**

The merchant must use the correct API credentials and URL for each environment.
Credentials for an MTF TEST prefix account differ from:

* An MTF non TEST prefix account
* A PRODUCTION TEST prefix account Using incorrect credentials or URLs results in an INVALID_REQUEST response.

**Error responses:**

The gateway may return the following responses:

* Invalid credentials: The authentication details in the request are incorrect.
* Authenticated entity not authorized to perform operation: The merchant ID in the URL does not match the authentication details in the request.
Refer to the Setting up API Credentials section in the [Integration guide](https://developer.mastercard.com/mastercard-gateway/documentation/index.md).