Error Groups

Craftgate API returns a response in a certain format in case of a systematic or fictional error while executing a transaction or query. As stated in the Failed Transactions section on the API documentation home page, in such cases, only a field named errors is included in the response to be returned. The parameters of this object, which contains the details of the error that occurs, are as follows:

Parameter Name Type Always Exist Description
errorCode string Yes The unique code for the error
errorDescription string Yes Explanatory message that mentions the attribute of the error
errorGroup string No (see: Payment Error Groups) Error group sent in case of an error is occurred that is payment related

In case of an error, merchants can use the errorCode and errorGroup fields to execute their own business rules and/or display localized error messages according to the user.

Important Note: For errors related to payment, absolutely use the errorGroup field.

Sample 1 Error returned for a payment attempt that received an insufficient credit card limit error

{
    "errors": {
        "errorCode": "10051",
        "errorDescription": "Insufficient card limit, insufficient balance",
        "errorGroup": "NOT_SUFFICIENT_FUNDS"
    }
}

Sample 2 The error returned when the expiry date field in the entered card information is incorrect

{
    "errors": {
        "errorCode": "4152",
        "errorDescription": "Invalid card expiry year \"2010\" "
    }
}

Error Groups

Among the errors returned by Craftgate, those with error codes greater than 10000 are payment errors, and those less than 10000 are validation errors.

Validation Errors (Integration Based)

Craftgate API checks the request parameters sent by the merchant before communicating with the bank or payment institution in transactions such as payment receipt, cancellation/refund application. During these checks, if a parameter that is malformed or does not comply with the business rules is detected (incorrect card number, past expiration date, missing payment information, etc.), the request is marked as validation error and an error message is sent. Such errors are errors with error codes less than 10000. The error group value of these errors is not sent.

In order to keep your payment performance rates as high as possible, it is recommended that you detect such errors before going live and set up your systems in such a way that they do not encounter these errors. If the integration has been completed successfully, it is expected that it will never be seen in the live environment. However, in order to prevent the user from encountering with possible integration problems, merchants integrated with Craftgate should catch errors with error codes less than 10000 and should not allow the user to see them.

Payment Errors (Payment Based)

Payment related errors are listed in the table below with their errorGroup equivalence and descriptions. These error groups are designed in accordance with the error messages returned to Craftgate from banks and payment and e-money institutions. Each error group listed here has a code (errorCode) in the format 10xxx.

Error Group (errorGroup) Description
NOT_SUFFICIENT_FUNDS Insufficient card limit, insufficient balance
DO_NOT_HONOUR The transaction has not been approved. Please try with another card
INVALID_TRANSACTION Invalid transaction. Please try with another card
LOST_CARD Lost card, pickup the card
STOLEN_CARD Stolen card, pickup the card
EXPIRED_CARD Incorrect expiration date
INVALID_CVC2 Cvc2 information is invalid
NOT_PERMITTED_TO_CARDHOLDER The cardholder cannot do this transaction. Please try with another card
NOT_PERMITTED_TO_TERMINAL The terminal is not authorized to perform this transaction
FRAUD_SUSPECT The payment fails to pass the security check
RESTRICTED_BY_LAW Your card is closed to e-commerce transactions. Call your bank.
CARD_NOT_PERMITTED The card does not allow the transaction
UNKNOWN An error occurred during the payment process
APPROVED_COMPLETED Pre-approved transaction
INVALID_CHARS_IN_EMAIL Email is not in valid format
INVALID_CVC2_LENGTH CVC length is invalid
REFER_TO_CARD_ISSUER Get approval from your bank
INVALID_MERCHANT_OR_SP Merchant category code is incorrect
BLOCKED_CARD Card is blocked
INVALID_CAVV Invalid CAVV information
INVALID_ECI Invalid ECI information
CVC2_MAX_ATTEMPT CVC2 incorrect entry attempts exceeded
BIN_NOT_FOUND BIN not found
COMMUNICATION_OR_SYSTEM_ERROR Communication or system error
INVALID_CARD_NUMBER Invalid card number
NO_SUCH_ISSUER Bank not found
DEBIT_CARDS_REQUIRES_3DS Debit cards can only be used in 3D Secure transaction
DEBIT_CARDS_INSTALLMENT_NOT_ALLOWED Installments cannot be made with debit cards.
REQUEST_TIMEOUT Request sent to bank timed out
DECLINED Payment declined
NOT_PERMITTED_TO_FOREIGN_CARD Terminal is closed to international cards
NOT_PERMITTED_TO_INSTALLMENT Terminal does not allow installment
REQUIRES_DAY_END Cash up must be done
EXCEEDS_WITHDRAWAL_AMOUNT_LIMIT Withdrawal limit exceeded
RESTRICTED_CARD Restricted card
EXCEEDS_ALLOWABLE_PIN_TRIES Allowed number of PIN entries exceeded
INVALID_PIN Invalid PIN
ISSUER_OR_SWITCH_INOPERATIVE Bank or terminal fail to process
INVALID_EXPIRE_YEAR_MONTH Invalid expiration date
REQUEST_BLOCKED_BY_BANK The request received an error from the bank
SALES_AMOUNT_LESS_THAN_AWARD The sales amount cannot be lower than the award points
INVALID_AMOUNT Invalid amount
INVALID_CARD_TYPE Invalid card type
NOT_SUFFICIENT_AWARD Insufficient award points
AMEX_CAN_USE_ONLY_MR American Express card error
NO_RESPONSE A general error occurred during the payment process
REFUND_NOT_ALLOWED_FOR_THIS_DEBIT_CARD No refunds on debit card transactions
PICKUP_CARD Pickup the card
CVC_REQUIRED CVC is required
INVALID_IP Invalid IP
MAY_HAVE_ALREADY_REFUNDED The amount to be refunded must be less than the total paid amount. This payment may have been previously refunded.
ORDER_ID_ALREADY_USED The order number (orderId) has already been used. Order numbers must be unique for successful sales.
THREEDS_INIT_ERROR 3D Secure payment cannot be initialized
APM_ERROR APM Payment declined
FRAUD_CHECK_BLOCK Payment blocked due to fraud check rules
POS_BALANCE_NOT_SUFFICIENT Virtual Pos balance is not sufficient