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. If the error returned is a business validation error, e.g. "insufficient funds" or "invalid transaction", then http code 422 is returned.

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:

errorCode

string

The unique code for the error

errorDescription

string

Explanatory message that mentions the attribute of the error

errorGroup

string

(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 IPv4	If IPv4 definition is mandatory in Virtual POS, please make defined Craftgate IPv4 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.