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

  • 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 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:

  1. Confirm the card type and currency combination used in your request.
  2. 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 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 CommWeb payment 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 Copied to Clipboard

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.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 Copied to Clipboard

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 Copied to Clipboard

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 Copied to Clipboard

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 Copied to Clipboard

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:
  • 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 (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