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.