Error Handling

Client (HTTP 4XX) errors and Server (HTTP 5XX) errors can occure in everyday use. With different transaction types different error handling scenarios should be used (described below).

1. HTTP Response Codes

HTTP 2XX

• if action code < 100 (starting with “0”)

Transaction is successful.

HTTP 4XX

• if transaction processing failed with a client error
• if action code >= 100 and < 900 (not implemented yet, currently returns 2XX)

Transaction failed with client error, do not re-submit.

HTTP 5XX

• if transaction processing failed with a server error
• if action code >= 900

Transaction failed with server error, please re-submit (example re-submitting flow below)

2. Acquirer Action Codes

Acquirer actions codes are returned by the acquiring bank as a response to the transaction. In order to understand if the transaction sent to Sfey was successful two options can be used:

1. transactionResultData.approved - true/false.

2. transactionResultData.actionCode - action code returned by the acquiring bank. Action codes starting with "0" can be considered as successful.

Action Code Explanations

Code	Explanation
000	Approved OK
001	Approved with identification only
002	Approved partially (only for a device that has a partial dispense capability; amount from response)
003	Approved, OK (VIP)
100	Do not honor
101	Expired card
102	Fraud suspected, do not honor
104	Restricted card (ATM only)
105	Call the NETS
106	Allowable PIN tries exceeded
109	Invalid Merchant
110	Invalid Amount
111	Invalid Card Number
112	PIN required
116	Not sufficient funds
117	Incorrect PIN
118	Unknown Card
119	Transaction not permitted to cardholder
120	Transaction not permitted to terminal
121	Exceeds withdrawal amount limit
123	Exceeds withdrawal frequency limit
125	Card is not effective
126	Invalid PIN block
127	PIN length error
128	PIN key synch error
129	Negative online CAM, dCVV, iCVV, CVV,CAVV, dCVV2, TAVV or DTVV results Or Offline PIN authentication interrupted (Visa only)
160	SCA required (Visa)
161	Closed account [do not retry]
162	Blocked (first used or tmp blocked)
163	Life Cycle, read card update from MC ABU DE48.84=01
163	Life Cycle, no update in MC ABU [do not retry] DE48.84=03
164	Policy, read card update from MC ABU DE48.84=01
164	Policy, no update in MC ABU [do not retry] DE48.84=03
165	Authentication required DE48.84=01
165	Suspected fraud [do not retry] DE48.84=03
166	Violation of law
200	Do not honor
201	Expired card
202	Fraud suspected
203	Merchant contact NETS
204	Restricted card
205	Call the police
206	Allowable PIN tries exceeded
208	Lost card
209	Stolen card
210	Suspected counterfeit card
902	Invalid transaction
903	Re-enter transaction
904	Format error
907	Issuer is Signed Off
908	Destination of message unknown
909	System malfunction
911	Card issuer timed out
913	Duplicate transmission
918	Missing transportation keys
920	Security device error, try again
921	Security device error
923	Request already in progress
933	Bad DateTime in reversal
934	Format error in response (for use only in offline transaction log and reversal)
935	Chip declined (for use only in offline transaction log)

3. Sfey Internal Error Codes

Following HTTP 4XX & 5XX error codes can be returned by Sfey TPS:

systemCode	systemCodeDescription	Explanation
2	MATCHING_AUTHORIZATION_SCHEMA_NOT_FOUND	card schema configuration missing on our side
3	ACQUIRER_REQUEST_FAILED	general error when handling ISO-8583 messages or communicating with acquirer, most likely a bug on our side
4	AUTHORIZATION_PROHIBITED	authorization not allowed for the initial transaction in debt recovery
7	INVALID_AUTHORIZATION_RESPONSE	data from ISO-8583 response does not match request
8	SERIALIZATION_FAILED	incorrectly formatted JSON string
9	DESERIALIZATION_FAILED	failed to deserialize JSON data
10	INVALID_STOCK_LOCATION_ID	terminal location ID does not match location ID in request
11	INVALID_COMPANY_ID	organization ID is either invalid, does not exist, or does not match a given terminal/device
12	INVALID_VALIDATOR_DATA	unable to parse EMV data or required tags are missing
13	AUTHORIZATION_ACTION_CODE_ERROR	no response or invalid response received from the acquiring/issuing bank
17	CARD_NOT_FOUND	debt recovery needs CPAN, but it is missing
19	KEY_CONTAINER_EXCEPTION	failed to encrypt or decrypt data
20	KEY_NOT_FOUND_EXCEPTION	encryption key with a provided ID does not exist
21	AUTHORIZATION_NOT_FOUND	original transaction that caused the debt not found
22	POS_NOT_FOUND	no terminal exists for a given validator
24	REQUIRED_PROPERTY_NOT_FOUND	missing configuration propery on our side
27	INVALID_REPEAT_REQUEST	data or fields in repeat request do not match the initial request
35	INVALID_REQUEST_PARAMETERS	missing/invalid data in request
39	INVALID_PAN_TOKEN	PAN token in request does not match the token generated using tag data
41	VALIDATOR_NOT_FOUND	validator with a given serial number and type either does not exist or is inactive
42	VALIDATOR_TYPE_NOT_FOUND	validator type with a given name does not exist
47	DEBT_RECOVERY_NOT_POSSIBLE	debt recovery not possible. possible reasons: no debt card found with the given CPAN token and company ID, authorization schema missing, no initial authorization causing the debt found for the card, the initial authorization having returned an acquirer technical error
48	CARD_NOT_FOUND_FOR_DEBT_RECOVERY	there is no card in debt that can be recovered from debt with merchant-initiated manual debt recovery
59	INVALID_VALIDATION_STATUS	transaction validation status from request is not OK
60	INVALID_VALIDATOR_DATA_TAG	mandatory EMV tags in DFFF8401-DFFF8405 range are missing or empty
63	CARD_EXPIRED	the card to be recovered from debt is expired
65	AFC_TRANSACTION_EVENT_REQUEST_MISSING	AFC transaction events not configured to be saved
86	ACQUIRER_TECHNICAL_ERROR	technical error in acquirer system
301	GENERAL_MISSING_DATA	usually happens due to a bug in Sfey system
302	GENERAL_OTHER	usually happens due to a bug or incorrect configuration in Sfey system
303	IN_PROGRESS	a transaction with a given transactionUuid is currently being processed

4. How to Process Transactions in Case of HTTP 5XX Errors

Deferred (MTT/KFT) Errors

1. Service provider tries to send tap to the TPS.
2. If sending fails then the service provider tries to send tap 3 times, using 1 minute delay between attempts.
3. If sending fails then the service provider tries to send tap 3 times, using 15 minute delay between attempts (OPTIONAL).
4. If sending fails then the service provider tries to send tap 3 times, using 60 minute delay between attempts (OPTIONAL).
5. If sending fails then the service provider tries to send tap 3 times, using 360 minute delay between attempts (OPTIONAL).
6. If sending fails then the service provider considers the transactions as "permanently failed" and sends e-mail notification to the address [email protected]

Realtime (KFT/Retail) Errors

Simplest solution - in case of errors the transaction is denied and relevant error is displayed to the customer. Transaction will not be processed - it will just be saved to the logs.

Retail Check-In/Check-Out Errors

If error occurs during CHECK_IN then the rental period should not be started and relevant error should be displayed to the customer.

Recommended behaviour in case of failing CHECK_OUT:

1. If TPS returns error response for the CHECK_OUT then an error should be displayed to the customer.
2. Customer should be able to tap the card and initiate CHECK_OUT again for a total of 3 times.
3. If all 3 CHECK_OUT requests fail then the travel period should be ended and indicated to the customer that CHECK_OUT transaction failed - customer support should be contacted.
4. Service provider should be able to send manual CHECK_OUT request later on if needed.