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 Detail
AMEX_CAN_USE_ONLY_MR American Express card error An error occurred while making payment transaction with an American Express card.
APM_ERROR APM Payment declined APM Payment declined.
APPROVED_COMPLETED Pre-approved transaction The order number (orderId) was previously used during another successful checkout. Successful payment transaction should be checked, if you think that the payment has not been made, the payment should be tried again with a new order number.
BIN_NOT_FOUND BIN not found The first 8 digits of the card number identify the BIN number. A valid BIN number could not be found from the entered card number. Buyer should check the card number and try to pay again.
BLOCKED_CARD Card is blocked Card is blocked. Buyer should contact to the bank.
CARD_NOT_PERMITTED The card does not allow the transaction No transaction can be made with this card. Payment can be made by trying a different card information.
COMMUNICATION_OR_SYSTEM_ERROR Communication or system error Bank could not respond within the expected time, there may have been a temporary interruption.
CVC2_MAX_ATTEMPT CVC2 incorrect entry attempts exceeded The security code has been entered incorrectly repeatedly and the payment was rejected because the number of incorect payment attempts was exceeded.
CVC_REQUIRED CVC is required Payment cannot be made through the POS without the CVC security code. The payment should be tried again, making sure that the security code information is entered.
DEBIT_CARDS_INSTALLMENT_NOT_ALLOWED Installments cannot be made with debit cards. Installment cannot be made with debit cards. In order for the payment to be successful, payment should be done with single installment.
DEBIT_CARDS_REQUIRES_3DS Debit cards can only be used in 3D Secure transaction With debit cards, 3D Secure payment should be done. If buyer has entered a debit card as the card number, it should be directed to 3D Secure payment process.
DECLINED Payment declined Payment transaction is declined. The cardholder should contact to the bank.
DO_NOT_HONOUR The transaction has not been approved. Please try with another card Bank of card rejected the payment transaction. Daily transaction limit/count may be exceeded or an error may have been received because many attempts were made. Buyer should contact to the bank.
EXCEEDS_ALLOWABLE_PIN_TRIES Allowed number of PIN entries exceeded Max PIN tries exceeded.
EXCEEDS_WITHDRAWAL_AMOUNT_LIMIT Withdrawal limit exceeded The number of daily transactions or daily limit may have been exceeded.
EXPIRED_CARD Incorrect expiration date The expiry date of the card is incorrect. Buyer can try to pay again by correcting the expiry date.
FRAUD_CHECK_BLOCK Payment blocked due to fraud check rules Payment blocked due to fraud check rules.
FRAUD_SUSPECT The payment fails to pass the security check Bank of card rejected the payment transaction for security reasons. There is a suspicion of fraud or an error may have been received because many attempts were made. The payment transaction detail should be checked and payment may be requested to be tried again by contacting the buyer.
INVALID_AMOUNT Invalid amount Invalid amount, check the payment amount. The number of daily transactions or daily limit may have been exceeded. Please contact to the bank for detailed information.
INVALID_CARD_NUMBER Invalid card number Card number not accepted by the bank. The card number should be checked and the payment should be tried again.
INVALID_CARD_TYPE Invalid card type Invalid card type, please check card number. Please contact to the bank for detailed information.
INVALID_CAVV Invalid CAVV information Incorrect CAVV information. Buyer should contact to the bank.
INVALID_CHARS_IN_EMAIL Email is not in valid format Email is invalid. Email information should be checked.
INVALID_CVC2_LENGTH CVC length is invalid The security code (CVC2) of the card is incorrect. Buyer can try to pay again by correcting the security code.
INVALID_CVC2 Cvc2 information is invalid The length of the security code (CVC) entered with the card is invalid. Buyer can try to pay again by correcting the security code.
INVALID_ECI Invalid ECI information Incorrect ECI. Buyer should contact to the bank.
INVALID_EXPIRE_YEAR_MONTH Invalid expiration date The expiry date of the card entered is invalid. Buyer should check the card information entered.
INVALID_IP Invalid IP If IP definition is mandatory in Virtual POS, please make defined Craftgate IP addresses by contacting to the bank.
INVALID_MERCHANT_OR_SP Merchant category code is incorrect Merchant category is incorrect. It is necessary to make a correction to merchant category by contacting the bank.
INVALID_PIN Invalid PIN Invalid PIN. Buyer should contact to the bank.
INVALID_TRANSACTION Invalid transaction. Please try with another card Invalid transaction. Please check the payment transaction detail, buyer should contact to the bank for detailed information.
ISSUER_OR_SWITCH_INOPERATIVE Bank or terminal fail to process The bank or POS cannot perform any payment transaction, a temporary interruption may have occurred.
LOST_CARD Lost card, pickup the card Lost card. Transactions cannot be made with this card. Payment attempt may be suspected of fraud.
MAY_HAVE_ALREADY_REFUNDED The amount to be refunded must be less than the total paid amount. This payment may have been previously refunded. The amount to be refunded must be less than the sales amount. This payment may have been previously refunded.
NOT_PERMITTED_TO_CARDHOLDER The cardholder cannot do this transaction. Please try with another card No transaction can be made with this card. Payment can be made by trying a different card information.
NOT_PERMITTED_TO_FOREIGN_CARD Terminal is closed to international cards POS has not authorization for international card transactions. POS authorization should be checked.
NOT_PERMITTED_TO_INSTALLMENT Terminal does not allow installment POS has not authorization for installments. POS authorization should be checked.
NOT_PERMITTED_TO_TERMINAL The terminal is not authorized to perform this transaction POS has not authorization for this operation. POS authorization should be checked.
NOT_SUFFICIENT_AWARD Insufficient award points The reward point to be used is higher than the point amount belong to the card. Since there is not enough reward point, the amount of point should be updated and payment should be tried again.
NOT_SUFFICIENT_FUNDS Insufficient card limit, insufficient balance Buyer’s card does not have sufficient balance for payment. Buyer should contact to the bank.
NO_RESPONSE A general error occurred during the payment process Bank could not respond within the expected time, there may have been a temporary interruption.
NO_SUCH_ISSUER Bank not found Bank of card not found. The card number should be checked and the payment should be tried again.
ORDER_ID_ALREADY_USED The order number (orderId) has already been used. Order numbers must be unique for successful sales. The order number (orderId) was previously used during another successful checkout. Successful payment transaction should be checked, if you think that the payment has not been made, the payment should be tried again with a new order number.
PICKUP_CARD Pickup the card Bank of card refused the payment due to security/fraud suspicion. Payment transaction cannot be made with this card.
POS_BALANCE_NOT_SUFFICIENT Virtual Pos balance is not sufficient Virtual Pos balance is not sufficient.
REFER_TO_CARD_ISSUER Get approval from your bank Bank of card did not approve the payment. Buyer should contact to the bank for manual confirmation.
REQUEST_BLOCKED_BY_BANK The request received an error from the bank Payment request is blocked by bank.
REQUEST_TIMEOUT Request sent to bank timed out Bank could not respond within the expected time, there may have been a temporary interruption.
REQUIRES_DAY_END Cash up must be done With the POS, this transaction cannot be done before the end of the day operation.
RESTRICTED_BY_LAW Your card is closed to e-commerce transactions. Call your bank. The card is not permitted to e-commerce payments. Buyer should contact to the bank and authorize this card for e-commerce payment transactions.
RESTRICTED_CARD Restricted card The payment was not completed due to a restriction. Buyer can try again with different card information.
SALES_AMOUNT_LESS_THAN_AWARD The sales amount cannot be lower than the award points The reward points to be used cannot be higher than the payment amount. The point amount to be used should be updated to be equal to or less than the payment amount.
STOLEN_CARD Stolen card, pickup the card Stolen card. Transactions cannot be made with this card. Payment attempt may be suspected of fraud.
THREEDS_INIT_ERROR 3D Secure payment cannot be initialized 3D Secure init request is failed, contact to the bank for more details.
UNKNOWN An error occurred during the payment process Payment failed, error group not detected.