Error codes for card-present transactions

Here are the common errors in card-present transactions and how to resolve them

HTTP Status codes

Below, we present the most common HTTP status codes, their associated standard messages, and a description of the response.

Here are the codes you might receive.

Code	Message	Detail
200	OK	The process was successful; it worked as expected, according to the HTTP method.
400	Bad Request	The server cannot interpret the request (incorrect syntax, too large size, missing parameters).
401	Authorization Required	The credentials must be authenticated, or authentication failed.
403	Forbidden	You do not have the necessary permissions to perform this action.
404	Not Found	Resource or page not found.
409	Conflict	The request cannot be processed due to a conflict with the resource (e.g., multiple simultaneous updates).
410	Gone	The requested resource has been deleted from the server and will no longer be available.
412	Precondition failed	It indicates that access to the target resource has been denied.
429	Too Many Requests	Too many requests have been sent in a short period of time.
430	Request Header Fields Too Large	This status code indicates that the server is unwilling to process the request because its header fields are too large.
500	Internal Server Error	An unexpected error occurred on the server.
502	Bad Gateway	The server (acting as a proxy or gateway) received an invalid response from the upstream server.
503	Service Temporarily Unavailable	The server is not available (usually because it is undergoing maintenance or because it is overloaded).
504	Gateway Timeout	The server (acting as a proxy or gateway) did not receive a timely response from the other server.

Kushki pre-processing codes

The following error codes are generated directly by Kushki during the internal validation stage, before the transaction is sent to the processor or the card brand.

These codes are usually related to payload validation, business rules, time limits, or the status of previous transactions in our database.

When one of these errors occurs, you will receive it in the response body with a structure similar to the following:

{
  "code": "E047",
  "details": {
    "Origin": "Process Reverse | Transaction",
    "Message": "Code: K007, Message: \"Error al obtener la transacción actualizada\", StatusCode: 500, Reverse: false"
  },
  "message": "Unreachable processor timeout"
}

Code	Message	Description	Suggestion / What to do?
E001	Invalid request body.	Occurs when one or more mandatory fields are not sent in the request body.	Review the Kushki documentation detailing the mandatory and optional fields for this endpoint.
E001	An error occurred while saving the transaction to the database.	An error occurred during the initial saving of the transaction in DynamoDB.	Review the internal logs to verify the error returned by the database.
E002	An error occurred while sending and/or getting the transaction from the gateway.	The gateways responded with an error other than K007.	Check which error code the gateways returned in the response.
E002	An unexpected error has occurred.	An error occurred other than those mentioned in the standard documentation.	Review the transaction Lambda function logs for more details.
E006	An error occurred while retrieving the transaction from the database.	An error occurred while querying the original transaction. This is common when attempting Void, Refund, or Capture operations.	Review the logs to validate DynamoDB's response when querying the record.
E011	An error occurred while updating the transaction.	Error (other than Timeout) when trying to update the transaction status in DynamoDB.	Review the update trx Lambda function logs.
E014	An error occurred while validating the original transaction.	Occurs only in Reauthorizations, when the previous transaction is not a preauthorization/reauthorization or is not available.	Verify that the transaction sent for reauthorization meets the described criteria.
E015	The previous transaction is not approved.	Occurs in Void, Refund, or Capture requests when the linked original transaction is not in an approved status.	Make sure to send void, refund, or capture operations only for successful transactions.
E016	Refund not available.	Occurs due to: The minimum allowed time (1 day) to execute a Refund has not yet passed. The transaction date exceeds the allowed days limit (varies by country). The original transaction is NOT a Charge, Capture, Checkout, or PosTip.	Validate that the transaction meets the allowed time and type conditions for refunds.
E017	Transaction not available for voiding.	An attempt is made to void a transaction with an amount greater than the sale. Unlike E023, it can occur if 2 voids come in simultaneously.	Verify the remaining amount available to void and avoid sending duplicate requests.
E018	Void not available.	A request is made to void a transaction type not supported for this operation.	You can only void transaction types: Charge, Preauth, Reauth, Capture, CheckIn, CheckOut, Tip, or PosTip.
E020	Transaction not available for capture.	An attempt is made to capture a transaction whose time limit has already expired (the limit varies by processing country).	Make sure not to exceed the stipulated time window to make the capture.
E023	Void amount exceeds sale amount.	A Void (total or partial) or a Refund is sent for a value that exceeds the original sale amount.	Adjust the request amount; it must not exceed the original value.
E024	Invalid card reading data.	The track data (magnetic stripe/chip) sent is incorrect or poorly formatted.	Validate and send the card reading data correctly.
E041	Operation not allowed.	Occurs due to: Capture on a transaction that is not a preauthorization. The capture amount exceeds the total + n% of the original preauthorization. Attempted partial Void of a preauthorization. Use of an unsupported `transaction_type`. Transaction directed to an unknown brand.	Adjust the request parameters according to the business rules of the desired operation.
E042	The currency code is different from the initial transaction.	A subsequent operation (Void, Refund, or Capture) is sent where the `currency` field does not match the original sale.	The `currency` field must be exactly the same as the one used in the Sale.
E044	Void not allowed.	An attempt is made to perform a Void directly on a Reauthorization.	Reauthorizations do not support direct voids.
E046	Reversal not available due to time excess.	An attempt is made to process a manual reversal after the maximum allowed time (29 seconds from the original transaction).	Do not attempt manual reversals once the 29 seconds have elapsed.
E047	Unreachable processor timeout.	The gateways returned `K007` (Timeout waiting for a response from the brand), or the database exceeded the allowed time to update.	Review the API or gateway logs to identify the bottleneck.
E048	The previous transaction is already reversed.	Attempted Void or Refund on a previously reversed transaction. It also applies if a duplicate Smart Void is sent (same `client_transaction_id`).	Validate the current status of the transaction before trying to void it again.
E049	Transaction not available for cashback.	The transaction does not meet the required characteristics to process a cash withdrawal (Cashback).	Cashback requires: Charge type, Approved via Chip/Contactless, Visa/Mastercard brand, domestic transaction, and NOT deferred.
E055	Currency type not allowed.	A currency code (`currency`) is sent that differs from the local currency of the country where the merchant operates.	Configure the official `currency` corresponding to the country of your merchant credential.
E322	An error occurred processing the transaction (Security Rule).	A failure occurred in the intermediate layer of the `SecurityRule` middleware.	Escalate the incident and review the logs of the corresponding Lambda function.

Codes returned by Kushki in card-present transactions

The response codes received from processors and issuers will appear in thekushki_response object, as shown in the following example.

"kushki_response": {
        "code": "01",
        "message": "Refer to card issuer"
    },

Error 006

This error code appears when Kushki blocks the card, for example if the brand is not supported.

"kushki_response": {
        "code": "006",
        "message": "Card brand not supported"
    },

In case this code comes from the Card franchises (Visa, Mastercard or Prosa (Mexico), it will have two digits. Below you will find the most common response codes, including declinations:

ISO Error Code	Description	Source
00	Approved or completed successfully	Visa, Mastercard, Prosa
01	Refer to card issuer	Visa, Mastercard, Prosa
02	Refer to card issuer, special condition	Visa, Prosa
03	Invalid merchant	Visa, Mastercard, Prosa
04	Pick up card (no fraud)	Visa, Mastercard, Prosa
05	Do not honor	Visa, Mastercard, Prosa
06	Error	Visa, Prosa
07	Pick up card, special condition (fraud account)	Visa, Prosa
08	Honor with ID	Mastercard
09	Request in progress (duplicate)	Prosa
10	Partial Approval	Visa, Mastercard, Prosa
11	Approved (VIP)	Visa, Prosa
12	Invalid transaction	Visa, Mastercard, Prosa
13	Invalid amount	Visa, Mastercard, Prosa
14	Invalid card number	Visa, Mastercard, Prosa
15	Invalid issuer	Visa, Mastercard, Prosa
19	Re-enter transaction	Visa
21	No action taken	Visa
22	Suspected malfunction	Prosa
25	Unable to locate record in file	Visa
28	File is temporarily unavailable for update or inquiry	Visa
30	Format error	Visa, Mastercard, Prosa
31	Bank not supported by switch	Prosa
33	Expired card	Prosa
34	Suspected fraud	Prosa
35	Card acceptor contact acquirer	Prosa
36	Restricted card	Prosa
37	Card acceptor call acquirer security	Prosa
38	Allowable PIN tries exceeded	Prosa
39	No credit account	Visa, Prosa
40	Command rejected	Prosa
41	Lost card	Visa, Mastercard, Prosa
43	Stolen card	Visa, Mastercard, Prosa
46	Closed account	Visa
51	Insufficient funds/over credit limit	Visa, Mastercard, Prosa
52	No checking account	Visa
53	No savings account	Visa
54	Expired card or expiration date missing	Visa, Mastercard, Prosa
55	Invalid PIN	Visa, Mastercard, Prosa
56	No card record	Prosa
57	Transaction not permitted to issuer/cardholder	Visa, Mastercard, Prosa
58	Transaction not permitted to acquirer/terminal	Visa, Mastercard, Prosa
59	Suspected fraud	Visa
61	Exceeds withdrawal amount limit	Visa, Mastercard, Prosa
62	Restricted card	Visa, Mastercard, Prosa
63	Security violation	Visa, Mastercard
64	Transaction does not fulfill AML requirement	Visa
65	Exceeds withdrawal count limit	Visa, Mastercard, Prosa
68	Response received too late	Prosa
70	PIN data required	Visa
71	Issuer PIN Not Changed	Mastercard
74	Different value than that used for PIN encryption errors	Visa
75	Allowable number of PIN-entry tries exceeded	Visa, Mastercard, Prosa
76	Unsolicited reversal	Visa, Mastercard, Prosa
77	Invalid/nonexistent 'From Account' specified	Mastercard
78	Blocked, first used or special condition	Visa, Mastercard
79	Reversed (by switch)	Visa
80	No financial impact	Visa
81	Cryptographic error	Visa, Mastercard, Prosa
82	Policy / Negative online authentication failure	Visa, Mastercard, Prosa
83	Fraud/Security	Mastercard
84	Invalid Authorization Life Cycle	Mastercard
85	Not declined, valid for all zero amount transactions	Visa, Mastercard
86	Cannot verify PIN	Visa, Mastercard
87	Purchase Amount Only, No Cash Back Allowed	Mastercard
88	Cryptographic failure	Mastercard
89	Unacceptable PIN	Mastercard
91	Authorization System or issuer system inoperative	Visa, Mastercard, Prosa
92	Unable to route transaction	Visa, Mastercard, Prosa
93	Transaction cannot be completed—violation of law	Visa
94	Duplicate transmission detected	Visa, Mastercard, Prosa
95	Reconcile error	Prosa
96	System error	Visa, Mastercard, Prosa
N0	Force STIP / Unable to authorize	Visa, Prosa
N3	Cash service not available	Visa, Prosa
N4	Cash request exceeds issuer or approved limit	Visa
N7	Decline for CVV2 failure	Visa, Prosa
N8	Transaction amount exceeds pre-authorized approval amount	Visa
R0	Stop payment order	Visa, Prosa
R1	Revocation of authorization order	Visa, Prosa
R2	Transaction does not qualify for Visa PIN	Visa, Prosa
R3	Revocation of all authorizations order	Visa
Z3	Unable to go online; offline-declined	Visa

Response codes returned by Kushki for cancellations and reversal attempts

The response codes received from processors and issuers will appear in the kushki_response object, as shown in the following example.

"kushki_response": {
        "code": "01",
        "message": "Refer to card issuer"
    },

Below you will find information on the codes and messages sent by Kushki to describe the response codes for requests made with card-present transactions. In the "What to Do?" column, you will find a detailed explanation of the causes and the procedure you should follow.

Code	Message	Detail
000	Approved Transaction	Indicates that the transaction was successfully approved.
01	Refer to card issuer	The cardholder should contact their card issuer to understand why the transaction was declined.
04	Capture card	The cardholder should try the transaction again.
05	Do not honor	The cardholder should try the transaction again.
12	Invalid transaction	The transaction is not allowed by the payment processor or the card issuer. Please contact the card issuer.
32	Expired card	The cardholder should use an alternative card.
41	Lost card	The cardholder should contact their card issuer to review the case.
57	Transaction not permitted to cardholder	The cardholder should contact their card issuer to review the case.
62	Restricted card	The cardholder should contact their card issuer to review the case.
91	Authorization System or issuer system inoperative )	The cardholder should try the transaction again.
92	Unable to route transaction	The cardholder should try again or contact the issuer.
6P	Verification data failed	Retry the transaction.
E016	Refund not available	Check that the refund is within the allowed timeframe.

Test Data

Make any necessary adjustments to your system using the test data.

Error codes for card-present transactions

HTTP Status codes#

Kushki pre-processing codes#

Codes returned by Kushki in card-present transactions#

Error 006#

Response codes returned by Kushki for cancellations and reversal attempts#

HTTP Status codes

Kushki pre-processing codes

Codes returned by Kushki in card-present transactions

Error 006

Response codes returned by Kushki for cancellations and reversal attempts