Transaction Errors
API response handling
Use the API response field result to determine the API operation outcome:
SUCCESS- The request is successfully processed, but in some circumstances, it may not be fully complete or approved. For a more detailed outcome, see theresponse.gatewayCodefield.FAILURE- The request is declined or was unable to be processed. For failure details, see theresponse.gatewayCodefield.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 a validation error or a processing error. See API Error.
Handling API errors
A response result field value of ERROR indicates 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 Validation Error 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
If the gateway responded with a SERVER_BUSY or SERVER_FAILED error cause 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 error handling
If your API request failed due to an API validation error, the response body from the gateway contains the following fields:
resultfield with the value set to ERROR.error.causewith 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 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
Your merchant account is configured for specific acquirers, such as, banks or payment method providers.
If you receive a No merchant acquirer link error:
- Confirm the card type and currency combination used in your request.
- For more information, contact your payment service provider.
The error parameters returns 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 toERROR.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
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 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.fielderror.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
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
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
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
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 2 days |
| 27 | Retry after 4 days |
| 28 | Retry after 6 days |
| 29 | Retry after 8 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.gatewayCode | 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:
Depending on the acquirer, the gateway code is subsequently updated either when:
|
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:
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 (e.g. for insufficient funds the merchant may contact the payer and retry once the payer has indicated that funds are now available). | 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 (e.g. connectivity issue). 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 and the recovery action for this transaction type is REVERSAL.
The gateway will make every possible attempt to ensure it was either declined by the acquirer or is reversed by the gateway. 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 and the recovery action for this transaction type is REPEAT (Capture and Refunds transactions only). The gateway is still trying to find out about the transaction result from the issuer, acquirer or other Payment Service Provider. Come back later to find out what has happened to the transaction. | 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 (e.g. browser payments). |
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. If not, treat as declined. |
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 that will allow the merchant to subsequently capture the funds for the transaction. | Referred |
| FAILURE | NOT_SUPPORTED | The transaction request could not be processed. Reasons include the requested functionality not being supported by the issuer, acquirer or other Payment Service Provider, missing request fields that are mandatory for processing the request, and failed issuer, acquirer, or other Payment Service Provider specific validation. A later retry will not succeed. Update your integration to comply with the processor specific requirements. |
Not Supported |
| FAILURE | UNSPECIFIED_FAILURE | Something went wrong while processing the transaction. The gateway does not know the result of the transaction. Reasons include merchant requests that cannot be processed due to a gateway internal error, the gateway being unable to retrieve a response from the issuer, acquirer or other Payment Service Provider (after exhausting all REPEAT or REVERSAL attempts), or receiving a response that is not understood by the gateway. Contact your acquirer to find out the success or otherwise of the payment. |
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 |