Feedback (User actions, info, and errors)
The framework will send back messages related to bluetooth connectivity and when the User is interacting with the reader during a transaction. Some of these can be monitored and handled without the User's knowledge. The minimum feedback all Users should see are the User Actions since the framework can give feedback related to how they are interacting with the reader. An example would be if the User swiped a chip card or inserted a chip card wrong. Some of the informational messages are still helpful so if the design can represent those as well it is recommended.
This enum defines the types of feedback.
typedef NS_ENUM(NSUInteger, CLEARENT_FEEDBACK_MESSAGE_TYPE) {
CLEARENT_FEEDBACK_USER_ACTION = 1,
CLEARENT_FEEDBACK_INFO = 2,
CLEARENT_FEEDBACK_BLUETOOTH = 3,
CLEARENT_FEEDBACK_ERROR = 4,
CLEARENT_FEEDBACK_TYPE_UNKNOWN = 0
};
| Feedback Type | Feedback Enum | Notes |
| User Action | CLEARENT_FEEDBACK_USER_ACTION | The framework needs to communicate with the User as they interact with the reader. Or, the Clearent framework has considered it important enough to display now and not treat just as informational. |
| General Information | CLEARENT_FEEDBACK_INFO | These are more less breadcrumbs allowing you to see more of what is going on. Streaming these as well might help with support but probably isn't too helpful for your average User. |
| Bluetooth Information | CLEARENT_FEEDBACK_BLUETOOTH | These are informational but associated with only bluetooth |
| Errors | CLEARENT_FEEDBACK_ERROR | These are returned when an error occurs. Some errors are related to the transaction. Transactions can fail for various reasons - bad swipes, bad chips, chip is good but reader fails to interact with it, contactless failures, etc. The errors can be communicated back to the User. In some cases the only course of action for the User is to try again and if they are unsuccessful to enter the card manually. |
| Not classified | CLEARENT_FEEDBACK_TYPE_UNKNOWN | This is returned if the IDtech framework returns an error the Clearent framework does not know how to classify |
| Feedback Message | Notes |
| PRESS BUTTON ON READER | During bluetooth interaction, this message will be sent back every time a transaction is started instructing the User to press the button on the reader. |
| PLEASE SWIPE, TAP, OR INSERT | Reader is 3 in 1 mode. User can insert a card with an EMV chip, swipe the card, or if the card has the contactless symbol on it , or a phone is being used, can use the contactless feature by hovering over the contactless side of the reader. |
| INSERT/SWIPE CARD | Reader is 2 in 1 mode. The contactless interface has been disabled. User can insert a card with an EMV chip or swipe the card |
| BLUETOOTH CONNECTED | Tells the User the bluetooth reader is connected. We could have sent this back under as bluetooth informational but we found a lot of Users wanted this feedback |
| USE MAGSTRIPE | User is told to swipe the card. |
| CARD INSERTED | Card has been inserted. |
| CARD READ OK, REMOVE CARD | The framework has read the card and it is okay to remove the card if it has been inserted. |
| TRY MSR AGAIN | User attempted to swipe the card but it failed. They should try again. |
| TAP FAILED. INSERT/SWIPE | Contactless interaction failed and the framework determined the User could not use the contactless interface. The framework starts up a new transaction and instructs the User to insert or swipe (contactless interface is disabled) |
| RETRY TAP | The contactless interface failed, maybe because the hovering happened too quickly, so the framework instructs the User to try again. |
| CARD HAS CHIP. TRY INSERT | User swiped a card with an EMV chip. User should get used to inspecting the card first and attempt inserting all EMV chip cards first. The framework will eventually allow a swipe of a chip card, which is considered a 'fallback swipe' |
| USE CHIP READER | Instructs user to try to insert the card |
| INSERT CARD | Instructs user to try to insert the card. Similar to USE CHIP READER. |
| CARD READ ERROR | Something went wrong reading the card. Try again or restart the transaction. |
| FAILED TO READ CARD. TRY INSERT/SWIPE | Something went wrong reading the card. Try insert or swipe. |
| FALLBACK_TO_SWIPE_REQUEST | Something went wrong reading the card. Try swipe. |
| BAD CHIP, PULL CARD OUT, WAIT FOR GREEN LED, TRY SWIPE | Bad EMV chip. The framework will restart a new transaction. Try swiping the card. |
| FAILED TO START SWIPE. TRY AGAIN BUT THIS TIME PULL CARD OUT WHEN INSTRUCTED | Uncommon scenario. The framework failed to process the card. This message 'BAD CHIP, PULL CARD OUT, WAIT FOR GREEN LED, TRY SWIPE' was presented but the user didn't pull the card out. |
| TIMEOUT | Transaction has timed out. Try a new transaction. |
| Feedback Message | Notes |
| This type (MSD) of contactless is not supported. Insert card with chip first, then start transaction. | THE MSD contactless specification is not supported. Inserting the card first will disable the contactless interface so you can bypass this issue. |
| PRESENT ONE CARD ONLY | Two contactless cards have entered the contactless NFC field and the framework is confused. Only present one card at a time. |
| TAP FAILED. INSERT CHIP CARD FIRST BEFORE TRYING AGAIN. IF PHONE TRY AGAIN OR ASK FOR CARD. | Attempt to user contactless interface failed. Try inserting the card first before starting the transaction. If it's phone related you can try again but if it fails you'll need to request the User use their back up credit card (or some other form of payment). |
| SEE PHONE | The Customer is in the middle of using their phone with the contactless interface and the framework is now asking the them to look at their phone to complete Biometrics or whatever security feature is in place. |
| Feedback Message | Notes |
| PLUGIN AUDIO JACK | The framework knows the connection has been configured for audio jack and is instructing the audio jack is plugged into the device. |
| DISCONNECTING BLUETOOTH. PLUG IN AUDIO JACK | The framework knows the connection has been configured for audio jack but it's currently connected to a bluetooth reader. Disconnect from bluetooth first then plug the audio jack in. |
| UNPLUG AUDIO JACK BEFORE CONNECTING TO BLUETOOTH | The framework knows its plugged into an audio jack reader but has been asked to connect to a bluetooth device. Unplug the audio jack reader and try to connect. |
| AUDIO JACK CONNECTED | The audio jack is now connected. |
| AUDIO JACK LOW VOLUME. TURN UP VOLUME AND RECONNECT | The volume should be turned up all the way to use the audio jack reader. |
| Feedback Message | Notes |
| NEW BLUETOOTH CONNECTION REQUESTED. DISCONNECT CURRENT BLUETOOTH | The framework has determined you want to disconnect to a different reader than what is currently connected to |
| BLUETOOTH DISCONNECTED | The bluetooth reader was disconnected. |
| DEVICE NOT CONNECTED | The framework has an issue with the device. |
| PAYMENT REQUEST AND CONNECTION REQUIRED | The framework got itself into a state where either something happened with the connection of the payment request itself could not be determined. Cancel the transaction and try again. |
| Feedback Message | Notes |
| DEVICE NOT CONNECTED | The framework has an issue with the device. |
| PAYMENT REQUEST AND CONNECTION REQUIRED | The framework got itself into a state where either something happened with the connection of the payment request itself could not be determined. Cancel the transaction and try again. |
| Feedback Message | Notes |
| SEARCHING FOR POWERED ON BLUETOOTH READERS | Bluetooth search has been started and the framework is looking for readers. |
| CARD READ OK | Card was read okay. |
| CARD SECURED | The card data has been sent to Clearent's servers and the transaction token (JWT) has been returned for your App to process. |
| GOING ONLINE | The framework is about to call Clearent to secure the card. |
| DECLINED RECEIPT SENT, REMOVE CARD | When an email address is provided to the framework at transaction time, if the transaction is declined the user will be sent an email describing the transaction. |
| Device Firmware version not found | The framework could not communicate with the reader at a given point to to identify its firmware version. This should only impact readers on versions .151 or older and the contactless feature. |
| Device Kernel Version Unknown | Kernel version could not be identified (rare). |
| Reader configured and ready | This is telling you the reader is ready for use. The mention of the reader being configured is a leftover from our initial release that would configure the reader prior to starting a transaction. (A flow that is now discouraged). |
| TRANSACTION STARTED | Transaction started |
| TRANSACTION FAILED | Transaction failed |
| CHIP NOT RECOGNIZED, PULL CARD OUT, WAIT FOR GREEN LED, TRY SWIPE | Try swipe again when a bad chip is recognized. TBD - might be a duplicate message of a User Action. |
| Device connected. Waiting for configuration to complete... | Try swipe again when a bad chip is recognized. TBD - might be a duplicate message of a User Action. |
| Feedback Message | Notes |
| AMOUNT IS OVER MAXIMUM LIMIT ALLOWED FOR TAP | There is a maximum amount allowed using the contactless interface. TBD if this should be a User Action |
| Feedback Message | Notes |
| AUDIO JACK ATTACHED | Audio jack attached |
| CONNECTING AUDIO JACK | Framework is in the process of connecting to the audio jack |
| AUDIO JACK REMOVED | Audio jack has been removed |
| AUDIO JACK DISCONNECTED | Audio jack was disconnected |
| Powering up reader... | Audio jack is powering up |
| Feedback Message | Notes |
| Card read error | Card read error. Try transaction again if framework did not restart one for you (you can tell by the other messages the framework sends back) |
| CVM Unsupported. Insert card with chip first, then start transaction. Or try swipe. | Cardholder verifification method unsupported. Try inserting or swiping. |
| Card declined | This is an offline decline and should be rare. Try manually entering the card. |
| TIME OUT | Transaction timed out (deprecated message). |
| TIMEOUT | The transaction timed out. Try again |
| Create Transaction Token Failed | Card was read successfully but at some point the card could not be secured and the transation token (JWT) could not be sent back to app. Make sure wifi is enabled and try transaction again. |
| Sending Declined Receipt Failed | When an email address is provided and the transaction is declined the framework will attempt to contact Clearent's servers to request an email be sent to the customer. This is telling you the process failed.This is independent of the processing of the transaction but could be failing for similar reasons such as slow/no internet connection. |
| Failed to read card | Simmiar to Card Read Error. Card failed to read. If the framework has not restarted the transaction for you then you'll have to restart a transaction. |
| DISABLE CONFIGURATION REQUEST TO RUN TRANSACTION | An attempt was made to start a transaction when configuration was running. |
| READER NOT CONFIGURED | Framework determined the reader is not configured. (This isn't a comprehensive check but could indicate an issue) |
| TRANSACTION FAILED | Duplicate of the User Action. It means the transaction failed. Try another transaction. |
| UNABLE TO GO ONLINE | Could not contact Clearent servers. This usually indicates a slow/no internet connection. Check wifi and try again. |
| PAYMENT REQUEST NOT FOUND | This indicates the framework was put in a bad state and could not determine what the payment request was. Try transaction again. |
| TERMINATED | This is an IDTech specific message we pass back. It indicates from the IDTech framework perspective the transaction could not succeed and was terminated (cancelled). Sometimes this message is not true when it comes to processing swipes or contactless transactions. Our part of the framework will restart a transaction in a different state depending on the scenario (example is restarting in '2 in 1' mode and disabling the contactless interface when we know the IDTech framework has told us contactless will not work). Because of the nature of the asynchronous messaging these are are still sent back. |
| TERMINATE | Same as TERMINATED but deprecated. |
| CARD UNSUPPORTED | The IDTech framework has determined the card is unsupported. Try manually entering the card. |
| UNABLE TO GO ONLINE, FAILED TO SEND DECLINED RECEIPT | When an email address is provided and the transaction is declined the framework will attempt to contact Clearent's servers to request an email be sent to the customer. This is telling you the process failed.This is independent of the processing of the transaction but could be failing for similar reasons such as slow/no internet connection. |
| Feedback Message | Notes |
| Bluetooth friendly name required | A request to connect to a bluetooth reader was made but no friendly name was provided. |
| Feedback Message | Notes |
| Contactless not supported. Insert card with chip first, then start transaction | You have contactless disabled. Insert card first to process. |
| TAP FAILED | Contactless failed. The framework might start up a tranasaction so monitor for related messages. If it does not start a new transaction and try inserting the card or if the phone was used ask the Customer for a back up payment method. |
| CARD BLOCKED | This should only come back during contactless interaction. The card cannot be used for some unknown reason. Try manually entering the card. |
| CARD EXPIRED | This should only come back during contactless interaction. Try manually entering the card. |