Error Codes

Learn about common error codes and how to solve them

Learn how to manage different types of error messages received during transactions for each payment method.

What types of response codes does Kushki return?

Kushki will return two different response codes to indicate the success or failure of a transaction: processorError and code. The code field returns generic messages. On the other side, the field processorError indicates that the transaction has passed through the processor and has probably been mapped by Kushki in order to provide a specific explanation of the reason why your transaction could not be completed.

Generic Error Codes

Kushki’s API will perform validations before sending a transaction to the processors. If this is the case, the field processorError will not appear in the response and you will only see the field code. An example of a message returned by Kushki’s API is shown below:

{"message": "ID de comercio o credencial no válido",
"code": "K004" }

In the table below, generic error codes returned through the code field are summarized.

codemessageWhat to do?
K001Invalid body requestReview the request body
K002An unexpected error has occurredRetry the transaction; in case the error persists, get in touch with Kushki’s support team so that we can review your case.
K003Card not enabled by the issuerEnter a different card number and retry
K004Invalid trade ID or credentialCheck the public merchant ID or the private merchant ID and retry
K005Expired TokenThe token has been previously used or has expired
K006Amount is not equal to the expected valueReview the value sent in the amount field and retry
K007This receipt has been already paidReview the payment reference and retry
K008This receipt has already been cancelledReview the payment reference
K009Expired ReceiptReview the payment reference and retry
K010Invalid ticket numberReview the ticket number entered and retry
K011Invalid credentialsCheck the public merchant ID or the private merchant ID and retry
K012Unauthorized accessThe token has been previously used or has expired
K013Transaction tokenized as delayedVerify that installments information has already been sent in the retrieval request
K014Invalid TokenCheck the token delivered and retry
K020Rejected transactionRetry the transaction; if the error persists, get in touch with Kushki’s support team so that we can review your case
K021Rejected transactionThis message appears when the anti-fraud validation engine declines the transaction
K023Amount of void higher than saleThis message occurs when trying to make a partial void but the amount is higher than the sale amount
K322Rejected TransactionThe transaction was declined by a Kushki’s security rule. Contact Kushki’s support team so that we can review your case

Error Codes in Credit Card Payments

Below we describe error codes returned through the processorError field, so that you can use them to map your application messages.

In the processorError and message columns of the table, the error code and message sent by Kushki are shown. In the column What to do? we give you a more detailed explanation of the causes and the possible procedure to follow.

processorErrormessageWhat to do?
501Rejected transaction. Contact your card issuerThe cardholder must contact his/her card issuer to understand why the transaction was rejected
503The business number is not registeredThe endpoint number or business code is not registered or enabled in the payment processor. Contact Kushki’s support team so we can review your case.
504The card entered has been reported.The cardholder must use a different card to process the transaction and contact his/her card issuer for them to review the case.
505The transaction was declined by the processor or issuer.The cardholder must wait a couple of minutes and retry; otherwise, he/she must use an alternative card.
512Transaction not allowed by the issuer.The transaction is not allowed by the payment processor or the card issuer. The cardholder should use an alternative card.
513The amount entered contains an invalid syntaxIt is necessary to verify the amount entered and retry. For example, it is possible that unallowed characters have been entered in the amount field, as , instead of . to separate decimals.
514The card number entered is not validThe cardholder must verify that the card number has been entered correctly and retry.
515The card issuer cannot authorize this transactionThe payment processor or card network rejected the submitted BIN. The cardholder should use another card.
518An expired card has been enteredThe card is expired or the date is incorrect. The cardholder must check that the date is correct or retry using another card.
519An error occurred when processing the operation. Try againThe cardholder must retry the transaction.
520The cardholder name entered is not correctEnter again the cardholder name and retry.
521The cardholder last name entered is not correctEnter again the cardholder last name and retry.
522The email address entered is not valid.Enter again the cardholder’s email address and retry.
523The IP address number is incorrect.Verify that the transaction is taking place from a valid IP address.
524The identification number entered is incorrect.Enter again the cardholder’s type and identification number and retry.
525The encrypted information is not validThe process of information encryption was not correctly completed. Contact Kushki’s support team so we can review your case.
526This business has no permission to process transactionsThis is caused by a restriction of a business by the payment processor. Contact Kushki’s support team so we can review your case.
527The entered amount cannot be zeroThe amount for this transaction cannot be zero. A different amount must be entered and retry.
528The transaction amount is different to the initial sale amountThe amount entered in the token must be equal to that of the purchase. It will be necessary to ensure that the amount to pay is correct.
529It has not been possible to find the transactionWhen reversing or cancelling a transaction it was not possible to find the original message. Contact Kushki’s support team so we can review your case.
530Transaction rejected due to a formatting errorAt the time of making the transaction a format error occured. Contact Kushki’s support team so we can review your case.
541This card has been reported as lostThe cardholder must use a different card to process the transaction and contact the card issuer to review the case.
543This card has been reported as stolenThe cardholder must use a different card to process the transaction and contact the card issuer to review the case.
551There are not enough funds to complete the operation.The cardholder must use a different card to process the transaction as the card entered does not have enough funds the transaction to be processed.
552The type of account entered is not validThe cardholder must verify the type of account selected and try again.
553The card is not compatibleThe card brand entered is not compatible for its authorization. The cardholder must use a different card to process the transaction.
554The type of currency is not validThe payment processor or card issuer does not accept transactions in the selected currency. Contact Kushki’s support team so we can review your case.
555The request is not validA request issue has occurred for the transaction made. Contact Kushki’s support team so we can review your case.
556The transaction has been canceledThe transaction that is being reverted or cancelled has already been cancelled
557The card issuer cannot authorize this transactionDue to some issuer restrictions, it is not possible to authorize the transaction. The cardholder must change the card or payment method and get in touch with the card issuer to review the case.
558Transaction not allowed for this businessDue to restrictions by the payment processor it is not possible to authorize the transaction for this business. Contact Kushki’s support team so we can review your case.
559The transaction has been considered as potentially fraudulentThe transaction made was declined by the payment processor or card issuer due to fraud suspicions.
560The amount entered is lower or greater than allowedThe amount in the transaction is lower or greater than the limits that have been established. The cardholder must verify the transaction amount and retry.
561The daily transaction limit has been exceededThe cardholder has exceeded the activity limit in number or amount of daily transactions
562Card restricted by the issuing bankThe card issuer has declined the transaction because it has applied restrictions to the cardholder. The cardholder must contact the card issuing bank to review his/her case.
563Operation rejected due to security breachThe card issuer or payment processor declined the transaction because a security breach occurred.
564The entered token is not valid or has expiredThe token that is being used does not have a valid format, it does not exist or was already used in a transaction
565The transaction was declined according to security rulesThe transactions is being declined because security rules have been established for the card or the business
566The token is not valid, or was already used in another transactionThe token that is being used does not have a valid format, it does not exist or was already used in a transaction. Contact Kushki’s support team so we can review your case.
567The transaction amount is requiredIt is mandatory to enter a value in the field “amount”.
568The transaction ticket number is not validEnter again the ticket number; if the issue persists, contact Kushki’s support team so we can review your case.
579The expiration date entered is incorrectThe cardholder must enter again the expiration date and try again.
580The deferred payment is not correctThe type or format of the deferred payment that is being used is not correct. Contact Kushki’s support team so we can review your case.
581Credentials are not correctVerify your entered credentials and try again
582The security number (CVV2) is not correctThe cardholder must enter again the security code and retry the transaction.
583The operation was already cancelled or the maximum time for reversal has been reachedIt is not possible to cancel or reverse the transaction because it has been already canceled, the original transaction was not found, or the maximum time allowed to reverse the transaction has ended. Contact Kushki’s support team so we can review your case.
591Unauthorized Transaction. Inoperative card issuerThe cardholder must wait a couple of minutes and retry; otherwise, an alternative card should be used.
594The rejected transaction seems to be a duplicate operationThe transaction was declined because a coincidence was found with another previous transaction. This usually happens because a repeated reference number is being entered.
596The card issuer has had a problem when authorizing the transaction.The cardholder must wait a couple of minutes and retry; otherwise, an alternative card should be used, or the cardholder should get in contact with the card issuer to verify the case.

Error codes received during anti-fraud validation

For the security of your business, Kushki’s fraud prevention team will ask you in certain cases or for certain amounts, to activate identity validation when receiving card payments.

Validation is performed through a specialized external service when sending the charge or by creating a subscription.

The following is an example of the response you will get when performing an anti-fraud validation:

"rules": [
{
"code": "322",
"message": "No coinciden datos."
}
]

As you can see, the response of the validation service will be obtained in the rules object. This will come with three possible response codes:

  • 000: you will receive this code when the anti-fraud validation has been approved.

  • 006: This code will appear when the validation was not possible, probably because the validation service was not available at the time the request was made.

  • 322: Validation was performed and the validator rejected the transaction.

For the third case, you will get one of the following rejection messages:

codemessageComments
322There is no identificationIn this case, continuing with the transaction will be possible by sending the ignoreWarnings parameter as true
322Data does not matchCheck if the secondLastName has been collected and sent in the contactDetails object
322Document not valid
322Wrong Document TypeThe only valid types of documents are C.C (citizenship card) and C.E. (Foreigner ID). In this case, continuing with the transaction will be possible by sending the ignoreWarnings parameter to true
322Card number does not correspond to the provided IDIn this case, continuing with the transaction will be possible by sending the ignoreWarnings parameter true
322Card is not valid for tradingIn this case, continuing with the transaction will be possible by sending the ignoreWarnings parameter true
322Number is not a credit cardIn this case, continuing with the transaction will be possible by sending the ignoreWarnings parameter true
322Address does not match
322Phone number does not match
322Email does not match
322Validation error
322General Error
322ID type error
322ID number error
322Invalid first last name
322Invalid name
322Invalid account
322Invalid address
322Invalid email address
322Invalid phone number
322Inactive card