# Transaction Errors source: https://developer.mastercard.com/mastercard-gateway/documentation/testing/trans-error/index.md ### API response handling {#api-response-handling} Use the API response field result to determine the API operation outcome: * `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. * `FAILURE` - The request is declined or was unable to be processed. For failure details, see the response.gatewayCode field. * `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. Perform a retrieve transaction operation or hold the webhook notifications after the typical processing period to obtain an updated outcome. * `UNKNOWN` - The gateway is unable to determine the outcome with the acquirer. * `ERROR` - An error occurred either due to a validation error or a processing error. See [Handling API Errors](https://developer.mastercard.com/mastercard-gateway/documentation/testing/trans-error/index.md#handling-api-errors). ### Handling API errors {#handling-api-errors} A response result field value of `ERROR` indicates that the request resulted in one of the error scenarios. Use the `result.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 Validation and error handling 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. | | `SERVER_FAILED` | There is an internal system failure. | You may attempt the API request again several minutes later. | ### Reattempting a transaction {#reattempting-a-transaction} If the gateway responded with a `SERVER_BUSY` or `SERVER_FAILED` error, you may resubmit an identical request after several minutes. 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. ### Validation and error handling {#validation-and-error-handling} If your API request failed due to an API validation error, the response body from the gateway contains the following fields: * `result` field with the value set to `ERROR`. * `error.cause` with the value set to `INVALID_REQUEST`. An API validation error occurs if the request has an incorrect structure, or if any field values do not match the API requirements. For example, a value is too short or long, or contains unsupported characters. Most commonly, a validation error occurs because the payer has not provided their details correctly. In such a scenario, you must inform the payer of their mistake and ask them to re-enter their data. Use the following fields to identify the validation errors to display a graceful message to the payer: * `error.field` - the name of the API field that failed validation. * `error.validationType` - the type of validation error. The `error.explanation` field contains human-readable error text giving further information about the error, such as minimum or expected length. However, do not automatically display these details to the payer, as the format for this text cannot be guaranteed. ### No merchant acquirer link errors {#no-merchant-acquirer-link-errors} Your merchant account is configured for specific acquirers, such as, banks or payment method providers. If you receive a `no merchant acquirer link` error: 1. Confirm the card type and currency combination used in your request. 2. For more information, contact your payment service provider. The error parameters return when validation fails at the API. The error cause determines what other error fields are returned. If the payment engine has registered the transaction but it fails downstream processing, such as, internal system error, timeout, and so on, then the error parameters will not be returned in the response. If your transaction fails for any reason during processing at the gateway, the response body from the gateway contains the following fields: * `resultfield` with the value set to ERROR. * `errorobject` with various child fields providing additional data about the error. Study the fields carefully to determine why the request failed and how you can fix it. If you cannot determine the error and need further support to solve it, contact your support team at your payment service provider or Mastercard Gateway and provide them the `error.supportCode` field value from the response of the failed transaction. The following sections provide tips for dealing with specific kinds of transaction error situations. ## Reporting validation errors to the payer {#reporting-validation-errors-to-the-payer} A validation error occurs if the request has an incorrect structure, or if any field values do not match the API requirements. For example, a value is too short or long, or contains unsupported characters. Most commonly, a validation error occurs because the payer has not provided their details correctly. In such a scenario, you must inform the payer of their mistake and ask them to re-enter their data. Use the following fields to identify the validation errors to display a graceful message to the payer: * `error.field` * `error.validationType` The `error.explanation` field contains human-readable error text giving further information about the error, such as, minimum or expected length. However, do not automatically display these details to the payer, as the format for this text cannot be guaranteed. ## Resubmitting a transaction by accident or after no response {#resubmitting-a-transaction-by-accident-or-after-no-response} The following list describes how the gateway supports idempotent Operations: * If a new order or transaction is created by the merchant integration with the gateway each time the payer clicks the pay button, then the order or transaction will have a new ID, will not be considered a repeat, and will be processed again. * If the gateway has already received your request, it will return the original response. These scenarios are not errors and require no actions. All API Operations are idempotent, which means that when the API receives a transaction that is identical to an earlier transaction, the API returns the same response as the first time and does not handle the request as a new transaction. So, you can be assured that the transaction will not be repeated with your or the payer's bank. ## Managing orders in error situations {#managing-orders-in-error-situations} When you submit the first transaction for a new order, you must assign an order ID for that order. The ID is used throughout the order lifecycle to track the progress between your system, the gateway, and your bank. If the initial transaction for an order fails, you can submit a new initial transaction with the original order ID. However, you must use a new transaction ID. ## Managing acquirer errors {#managing-acquirer-errors} Your merchant account is configured for specific acquirers, such as, banks or payment method providers. If you receive a `No merchant acquirer link` error for an acquirer your account is configured for, then contact your payment service provider. Your merchant acquirer link for your merchant account has not been configured for the required card type and currency combinations. ## Reacting to declined transactions {#reacting-to-declined-transactions} If your transaction gets declined by the issuer or card network, the `response.gatewayCode` field in the response has a value that does not contain `APPROVED`. Depending on the reason for the decline, the issuer or card network can provide additional information in the form of a merchant advice code, such as, the `authorizationResponse.merchantAdviceCode` field. For example, if a transaction is declined due to insufficient funds, the advice code can recommend a retry time frame that helps you to determine when an authorization approval is likely to be successful and consequently when to resend the request. The following table defines the various available merchant advice codes and the recommended actions. **Table: Merchant advice codes** | 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. | The `response.gatewayCode` provides a summary interpretation of the response from the issuer, acquirer, or service provider of the outcome of transaction processing which is unified across all merchant acquirer link integrations. For financial transactions, it is mapped from the raw response data provided in the `response.acquirerCode` field. See the `authorizationResponse.merchantAdviceCode` for further information from the issuer or the card network on the reason for declining a Mastercard or Visa transaction. Merchants can use this information to determine the best action to take. See \[Troubleshooting and FAQs\] for the list of values and their meaning. | 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. | Cancelled | | FAILURE | `CANCELLED` | The payer has cancelled the transaction. Only applies to payment types where a payer interaction with the acquirer or service provider takes place. | Cancelled | | 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 |