# Code and Formats source: https://developer.mastercard.com/mastercard-gateway/documentation/code-and-formats/index.md This section explains how to interpret Mastercard Gateway API responses and determine the appropriate action. Response handling is organized into three layers, the HTTP status code, the gateway result, and detailed response fields such as `response.gatewayCode` and the error object. Review the sections in sequence. 1. Verify whether the request was processed successfully at the API level. 2. Evaluate the high-level gateway result. 3. Examine the detailed response fields to determine the transaction outcome, identify retry conditions, or troubleshoot configuration and integration issues. ## HTTP status codes/reason codes {#http-status-codesreason-codes} Resource requests use HTTP response codes to provide a coarse-grain indication of the result of each request. The most common expected response codes for the supported HTTP methods are: | HTTP status code | Reason code | Response description | Resolution tips | |-----------------------------|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| | 201 (CREATED) | N/A | The request is received, the request is valid, and the request is mapped to a supported API operation. **Note:** A 201 response does not mean that the transaction succeeded. The transaction may still be declined. | Review the transaction response to determine whether the transaction succeeded or was declined. | | 400 (BAD REQUEST) | INVALID_REQUEST | The request is malformed or missing required fields. | Validate the request and ensure that all required fields are provided. | | 401 (UNAUTHORIZED) | INVALID_REQUEST | Authentication failed. The `error.cause` field provides additional information about the failure. | Verify the authentication credentials used in the request. Always check the HTTP status code to identify the issue. | | 500 (Internal Server Error) | N/A | The gateway failed to process the request. | Retry after a few seconds, and increase the interval between retries if the issue continues. Contact support if the problem persists for more than 1 hour. | ## API validation errors {#api-validation-errors} An API validation error occurs when the request has an incorrect structure or contains field values that do not meet API requirements. For example: * A value is too short or too long * A value contains unsupported characters In most cases, this error occurs because the payer entered incorrect details. ### Response format {#response-format} If a validation error occurs, the gateway returns: * `result`: ERROR * `error.cause`: INVALID_REQUEST ### Error response fields {#error-response-fields} Use these response fields to identify the validation error and build an appropriate message for the payer. | Field | Description | |------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `error.field` | The name of the field that failed validation. | | `error.validationType` | The type of validation error (for example, length or format). | | `error.explanation` | A human-readable description of the error. Do not display `error.explanation` directly to the payer. Its format is not guaranteed and may not be suitable for end users. | ### How to handle the error {#how-to-handle-the-error} You should: 1. Identify the invalid field. 2. Show a clear and simple message to the payer. 3. Ask the payer to correct their input and resubmit. Do not expose raw API error messages directly to the payer. ### Example response {#example-response} ```json { "result": "ERROR", "error": { "cause": "INVALID_REQUEST", "field": "card.number", "validationType": "INVALID_LENGTH", "explanation": "Card number must be between 13 and 19 digits" } } ``` ### Example payer message {#example-payer-message} Instead of showing the raw explanation, display a simple message such as *Please enter a valid card number*. ## Transaction outcomes and response fields {#transaction-outcomes-and-response-fields} When you send a transaction request to the Mastercard Gateway, the gateway returns a response that tells you: * If the request was processed * If the payment was successful * What action you need to take next Use these fields to interpret the response: | Field | Purpose | |------------------------|---------------------------------------------------------| | `result` | High-level outcome of the request. | | `response.gatewayCode` | Detailed transaction result used for payment decisions. | | `error.cause` | Error reason. Returned only when `result`=ERROR. | ### Duplicate and retried transactions {#duplicate-and-retried-transactions} The Mastercard Gateway supports idempotent operations. This means that if the same request is sent more than once, the gateway returns the same response and does not process the transaction multiple times. ##### Transaction scenarios {#transaction-scenarios} | Scenario | Behavior | |---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | New transaction | If your integration generates a new order ID or transaction ID each time the payer clicks the Pay button, the request is treated as a new transaction and is processed again. | | Retried transaction | If the same request is resent, for example due to a timeout or no response, the gateway recognizes it as a duplicate request, returns the original response, and does not process the transaction again. | These scenarios are expected behavior and not errors. No corrective action is required, and duplicate processing at the gateway or issuer level is prevented. ##### Retry guidance {#retry-guidance} To safely handle retries: * Use a consistent order ID or transaction ID when retrying a request. * Retry requests only when there is no response or when a network timeout occurs. * Avoid generating a new ID unless you intend to create a new transaction. You can safely retry a transaction request without risking duplicate charges, provided the request remains unchanged. ### Orders and transaction IDs in error situations {#orders-and-transaction-ids-in-error-situations} When you create a new order, you must assign an order ID. The order ID is used to track the order across: * Your system * The gateway * The bank All transactions related to the same order must use this order ID. ##### If the initial transaction fails {#if-the-initial-transaction-fails} | Scenario | Action | |-------------------------------------------|--------------------------------------------------| | Retry after timeout or no response | Send the same request with the same identifiers. | | New payment attempt after a known failure | Use the same order ID and a new transaction ID. | ##### Why this is required {#why-this-is-required} | Identifier | Purpose | |----------------|-----------------------------------------------------------------| | order ID | Keeps all attempts linked to the same order. | | transaction ID | Ensures that each attempt is treated as a separate transaction. | ### Acquirer configuration errors {#acquirer-configuration-errors} Your merchant account is configured to use one or more acquirers (for example, banks or payment providers). If the gateway cannot find a valid acquirer link for a transaction, it returns a "No merchant acquirer link" error. ##### Why this error occurs {#why-this-error-occurs} This error occurs when the merchant account is not configured for: * The card type used in the transaction (for example, Visa or Mastercard) * The currency used in the request (for example, EUR or USD) ##### What to do {#what-to-do} If you receive this error: * Verify that your request uses a supported card type. * Verify that your request uses a supported currency. * Check that your merchant account is configured for these combinations. * If the issue continues, contact your payment service provider to update your configuration. ## Declined transactions and merchant advice codes {#declined-transactions-and-merchant-advice-codes} If a transaction is declined by the issuer or card network, the `response.gatewayCode` will not be APPROVED. The gateway code shows the outcome of the transaction. ### Merchant Advice Codes {#merchant-advice-codes} In some cases, the issuer or card network provides additional guidance using a merchant advice code, returned in the `authorizationResponse.merchantAdviceCode` field. The merchant advice code helps you decide what to do next. For example, if a transaction is declined due to insufficient funds, the advice code may recommend when to retry the transaction. ### Response fields {#response-fields} | Field | Description | |--------------------------------------------|-------------------------------------------------------------------------------------------| | `response.gatewayCode` | Shows the outcome of the transaction. | | `authorizationResponse.merchantAdviceCode` | Provides additional guidance from the issuer or card network on what action to take next. | ### What to do {#what-to-do-1} When a transaction is declined: 1. Check the `response.gatewayCode` to confirm the outcome. 2. Check the `authorizationResponse.merchantAdviceCode` (if present). 3. Follow the recommended action based on the advice code. ### Merchant advice codes {#merchant-advice-codes-1} The table lists the available merchant advice codes and the recommended actions for each. | Merchant advice code | Scheme recommendation | |----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 01 | New account information available You can receive this code when you send a transaction with stored account details, and the gateway determines that the payer account no longer exists. Contact the payer for new account details. | | 02 | Cannot approve at this time, try again later | | 03 | Do not try again | | 04 | Token requirements not fulfilled for this token type | | 05 | Negotiated value not approved You can receive this code when the issuer does not accept the conversion rate used for the currency exchange in your transaction. Ask the payer to use a different card. | | 21 | Payment cancellation | | 22 | Merchant does not qualify for product code | | 24 | Retry after 1 hour | | 25 | Retry after 24 hours | | 26 | Retry after two days | | 27 | Retry after four days | | 28 | Retry after six days | | 29 | Retry after eight days | | 30 | Retry after 10 days | | 40 | Consumer non-reloadable prepaid card | | 41 | Consumer single-use virtual card number | | 43 | Consumer multi-use virtual card number | | R0 | Stop payment order If you receive this code, do not process the payment related to the current payer agreement. | | R1 | Revocation of authorization order If you receive this code, do not process any more payments related to the current payer agreement. | | R3 | Revocation of all authorizations order If you receive this code, do not process any more payments related to any payer agreement. | ## Transaction response field reference {#transaction-response-field-reference} These fields help you interpret transaction responses returned by Mastercard Gateway. ### Response fields {#response-fields-1} | Field | Description | |--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `response.gatewayCode` | Provides a standardized summary of the transaction outcome. It is derived from the response returned by the issuer, acquirer, or service provider. For financial transactions, this value is mapped from the raw response in the `response.acquirerCode` field. This allows you to handle responses consistently across all integrations. | | `response.acquirerCode` | Contains the original response code returned by the acquirer. Use this field when you need detailed or scheme-specific information about the transaction result. | | `authorizationResponse.merchantAdviceCode` | For declined Mastercard or Visa transactions, the issuer or card network may provide additional guidance in this field. This code helps you determine the best next action, such as whether to retry the transaction. | ### What to do {#what-to-do-2} When processing a transaction response: 1. Check `response.gatewayCode` for the overall outcome. 2. Use `response.acquirerCode` for detailed diagnostics, if needed. 3. Check `authorizationResponse.merchantAdviceCode`, if present, for recommended actions. ## API error response reference {#api-error-response-reference} Use the result response field to determine the API operation outcome. ### Result values {#result-values} | Result value | Description | |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | SUCCESS | The request is successfully processed, but it may not be fully complete or approved. For a more detailed outcome, see the [response.gatewayCode field](https://developer.mastercard.com/mastercard-gateway/documentation/code-and-formats/index.md#transaction-response-field-reference). | | FAILURE | The request is declined or was unable to be processed. For failure details, see the [response.gatewayCode field](https://developer.mastercard.com/mastercard-gateway/documentation/code-and-formats/index.md#transaction-response-field-reference). | | PENDING | The gateway has submitted the request to the acquirer but has not yet received a response indicating the outcome. This response is typically returned for browser-based payments. | | UNKNOWN | The gateway is unable to determine the outcome with the acquirer. | | ERROR | An error occurred due to a validation error or a processing error. When `result` = ERROR, the response includes an error object. See [Error Object Fields](https://developer.mastercard.com/mastercard-gateway/documentation/code-and-formats/index.md#error-object-fields). | Note: `result` = SUCCESS means that the gateway processed the request. It does not always mean that the payment was approved. ### Error object fields {#error-object-fields} A result field value of ERROR indicates that the request resulted in an error scenario. Use the `error.cause` field value to determine the cause and next action. | `Error.cause` value | Description | Next action | |---------------------|---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_REQUEST | The request is rejected because it does not conform to the API protocol. | Review the errors and resubmit an updated API request. See the [API Validation Errors](https://developer.mastercard.com/mastercard-gateway/documentation/code-and-formats/index.md#api-validation-errors) section. | | REQUEST_REJECTED | The request is rejected due to security reasons such as firewall rules, expired certificate, and so on. | Review the authentication credentials you supplied. | | SERVER_BUSY | The server does not have enough resources to process the request at the moment. | You may attempt the API request again several minutes later. The bank transaction will not be repeated, and no duplicate funds will be transferred. You will receive the same response as you would have received for the first request. | | SERVER_FAILED | There is an internal system failure. | You may attempt the API request again several minutes later. The bank transaction will not be repeated, and no duplicate funds will be transferred. You will receive the same response as you would have received for the first request. | ## Gateway and Acquirer response code reference {#gateway-and-acquirer-response-code-reference} | Result | Response gateway code | Gateway advice | Category | |---------|-------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------| | SUCCESS | APPROVED | The transaction had been approved. | Approved | | SUCCESS | APPROVED_AUTO | The transaction was automatically approved by the gateway. It was not submitted to the acquirer. | Approved | | SUCCESS | APPROVED_PENDING_SETTLEMENT | For file settlement acquirers this gateway Response Code is set when: * The transaction has been successfully added to the batch for the merchant and the acquirer, and not yet submitted for settlement. * The file is submitted to the acquirer for settlement but a response from the acquirer is pending. * A response has been received from the acquirer, but the status of the transaction has not yet been updated. Depending on the acquirer, the gateway code is subsequently updated either when: * The acquirer acknowledges receipt of the batch/file for processing. * A settlement response file is returned indicating the outcome of transaction processing. | Pending | | SUCCESS | SUBMITTED | A payer interaction with the acquirer or Service Provider has successfully been initiated for this transaction. However, the gateway has not yet received details about the status of the payer interaction (and therefore the success of the payment). Only applicable to browser payments. | Pending | | SUCCESS | PARTIALLY_APPROVED | The transaction has been approved; however, the approved transaction amount differs from the requested transaction amount. | Approved | | SUCCESS | AUTHENTICATION_IN_PROGRESS | The operation determined that payer authentication is possible for the given card, but this has not been completed and requires further action by the merchant to proceed. | In Progress | | PENDING | PENDING | The gateway is waiting for a response from the acquirer about the result of the transaction. Applicable for: * Browser payments, for example, PayPal returns 'Pending' while a risk assessment is happening, which may take up to 24 hours. * Instant refunds when the gateway receives a 'PENDING' response from MC Send. The gateway polls for final response from MC Send and updates the result to SUCCESS or FAILURE accordingly. Return later to find out about the success or otherwise of the payment. Not used for Authorizations or Payments where the payer is present, as it means that the merchant cannot tell the payer the result of the transaction. | Pending | | FAILURE | DECLINED | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | EXPIRED_CARD | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | DECLINED_INVALID_PIN | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | DECLINED_PIN_REQUIRED | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | AUTHENTICATION_FAILED | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | INVALID_CSC | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | NOT_ENROLLED_3D_SECURE | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | DECLINED_DO_NOT_CONTACT | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | DEFERRED_TRANSACTION_RECEIVED | DEPRECATED. DECLINED returned instead. | Hard Decline | | FAILURE | DECLINED_AVS | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | DECLINED_CSC | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | DECLINED_AVS_CSC | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | DECLINED_PAYMENT_PLAN | The issuer, acquirer, or other Payment Service Provider has declined the transaction. Ask the payer for another method of payment. | Hard Decline | | FAILURE | INSUFFICIENT_FUNDS | The issuer, acquirer, or other Payment Service Provider has declined the transaction. The problem might be resolved by retrying the request later with a new transaction ID. | Soft Decline | | FAILURE | SYSTEM_ERROR | The transaction was not able to be submitted downstream to the acquirer as a technical error occurred during processing of the transaction. A later retry attempt with a new transaction ID may succeed. | Processing Error | | FAILURE | LOCK_FAILURE | DEPRECATED. UNSPECIFIED_FAILURE returned instead. | Processing Error | | FAILURE | EXCEEDED_RETRY_LIMIT | DEPRECATED. UNSPECIFIED_FAILURE returned instead. | Processing Error | | FAILURE | TIMED_OUT | The gateway has timed out the request to the issuer, acquirer, or other Payment Service Provider as no response was received within a defined interval. A later retry attempt with a new transaction ID may succeed. | Processing Error | | FAILURE | ACQUIRER_SYSTEM_ERROR | The issuer, acquirer, or other Payment Service Provider was not able to process the transaction. Treat as declined. A later retry attempt with a new transaction ID may succeed. | Processing Error | | FAILURE | DUPLICATE_BATCH | DEPRECATED. | Processing Error | | FAILURE | UNKNOWN | The gateway timed out the request to the acquirer, as no response was received within a defined interval. The gateway is still trying to find out about the transaction result. | Processing Error | | FAILURE | ABORTED | DEPRECATED. CANCELLED returned instead. | Canceled | | FAILURE | CANCELLED | The payer has canceled the transaction. Only applies to payment types where a payer interaction with the acquirer or service provider takes place. | Canceled | | FAILURE | BLOCKED | The transaction has been blocked as a result of a risk assessment. You may be able to override the risk decision to reject the transaction. | Blocked | | FAILURE | REFERRED | The transaction has been declined, and the merchant is asked to contact the issuer. The issuer may provide the merchant with an Authorization Code. | Referred | | FAILURE | NOT_SUPPORTED | The transaction request could not be processed. Reasons include unsupported functionality or missing mandatory fields. A later retry will not succeed. | Not Supported | | FAILURE | UNSPECIFIED_FAILURE | Something went wrong while processing the transaction. The gateway does not know the result of the transaction. | Unspecified Failure | | SUCCESS | BALANCE_AVAILABLE | A balance amount is available for the card, and the payer can redeem points. | Approved | | SUCCESS | BALANCE_UNKNOWN | A balance amount might be available for the card. Points redemption should be offered to the payer. | Approved | | FAILURE | NO_BALANCE | A balance amount is not available for the card. The payer cannot redeem points. Ask the payer for another method of payment. | Hard Decline |