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. |
| 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. |