Receiving Feedback Messages using Clearent's iOS Framework

Clearent’s iOS framework sends feedback messages to the card reader about Bluetooth connectivity when customers use the card reader to start a transaction. The framework also sends instructional feedback messages when users interact with the card reader to process the payment transaction. For example, the card reader displays a feedback message to warn users when they swipe or insert the card incorrectly. The framework also sends feedback messages to the card reader that display helpful information for users during payment transactions.

Clearent’s iOS framework offers the the following enum type that defines different types of feedback messages:

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
            };

The following table provides information about the feedback types included in Clearent’s iOS Framework:

Feedback Type	Enum	Description
User Action	CLEARENT_FEEDBACK_USER_ACTION	This feedback type allows displaying instructions to users through the card reader during a transaction.
General Information	CLEARENT_FEEDBACK_INFO	This feedback type allows displaying information to users through the card reader during a transaction.
Bluetooth Information	CLEARENT_FEEDBACK_BLUETOOTH	This feedback type allows displaying information related to Bluetooth connectivity.
Errors	CLEARENT_FEEDBACK_ERROR	This feedback type allows displaying errors to users through the card reader during a transaction. Errors may occur due to an incorrect card swipe, a damaged chip, failed interaction between the card and the reader, or contactless failures. This feedback type provides error messages to guide users when they face unsuccessful attempts to enter card details manually.
Not classified	CLEARENT_FEEDBACK_TYPE_UNKNOWN	This feedback type allows displaying information if Clearent’s iOS framework cannot classify unknown errors returned from the IDTech framework.

The following sections provide the information about feedback messages included in the feedback types:

User Actions

The following tables provide information about the feedback messages included in User Actions feedback type:

General

Feedback Message	Description
PRESS BUTTON ON READER	This message instructs users to press the button on the card reader. This action connects the card reader via Bluetooth to start a new transaction.
PLEASE SWIPE, TAP, OR INSERT	This message instructs users to provide the card data using any of the following actions: Swipe: Swipe the card using the card slot of the reader. Tap: Tap the card on the contactless side of the card reader. Note: Tap action only works when the card has a contactless symbol on it. Insert: Insert the EMV chip side of the card into the card slot of the reader.
INSERT/SWIPE CARD	This message instructs users to provide the card data using any of the following actions: Insert: Insert the EMV chip side of the card into the card slot of the reader. Swipe: Swipe the card using the card slot of the reader.
BLUETOOTH CONNECTED	This message informs users that the card reader has successfully connected via Bluetooth.
USE MAGSTRIPE	This message instructs users to use magstripe to swipe the card.
CARD INSERTED	This message informs users that the card has been inserted into the reader.
CARD READ OK, REMOVE CARD	This message informs users that the card has been successfully read and instructs users to remove the card from the reader.
TRY MSR AGAIN	This message informs users to swipe the card again if Clearent’s iOS framework fails to read the card.
TAP FAILED. INSERT/SWIPE	This message instructs users to insert or swipe the card again if contactless interaction fails and informs to them that they cannot use the contactless feature for a new transaction.
RETRY TAP	This message instructs users to tap the card again if contactless interaction fails due to incorrect tap on the card reader.
CARD HAS CHIP. TRY INSERT	This message instructs users to insert the card with the EMV chip side first into the card slot of the reader.
USE CHIP READER	This message instructs users to insert the card with the chip side into the card slot of the reader.
INSERT CARD	This message instructs users to insert the card with the chip side into the card slot of the reader.
CARD READ ERROR	This message informs users that something went wrong while Clearent’s iOS framework was reading the card and start a new transaction.
FAILED TO READ CARD. TRY INSERT/SWIPE	This message informs users to swipe the card again if Clearent’s iOS framework fails to read the card and instructs users to insert or swipe the card again.
FALLBACK_TO_SWIPE_REQUEST	This message informs users to swipe the card again if Clearent’s iOS framework fails to read the card and instructs users to swipe the card again.
BAD CHIP, PULL CARD OUT, WAIT FOR GREEN LED, TRY SWIPE	This message informs users that the inserted card’s chip is in bad condition. It instructs users to wait for the green LED to flash to start a new transaction. Additionally, it instructs users to swipe the card again.
FAILED TO START SWIPE. TRY AGAIN BUT THIS TIME PULL CARD OUT WHEN INSTRUCTED	This message informs users when Clearent’s iOS framework fails to process the card data after swiping the card into the reader. Additionally, it instructs users to insert the card and not remove it until the next instruction.
TIMEOUT	This message informs users that the transaction has timed out in the process and instructs users to start a new transaction.

Contactless

Feedback Message	Description
This type (MSD) of contactless is not supported. Insert card with chip first, then start transaction.	This message informs users when Clearent’s iOS framework does not support the MSD contactless feature. It instructs users to insert the card with the chip side first into the card slot of the reader. This action disables the contactless interface for a new transaction.
PRESENT ONE CARD ONLY	This message informs users when they enter the contactless NFC field with two different contactless cards simultaneously, causing confusion for Clearent’s iOS framework. It instructs users to enter the contactless NFC field with only one card.
TAP FAILED. INSERT CHIP CARD FIRST BEFORE TRYING AGAIN. IF PHONE TRY AGAIN OR ASK FOR CARD.	This message instructs users to insert the card with the chip side first again if contactless interaction fails to read the card. Additionally, it instructs users to try again if they use an iPhone to provide the card data and Clearent’s iOS framework fails to process. This message also informs users to use another form of payment to process the transaction.
SEE PHONE	This message instructs users to complete any security feature on their iPhone to use the contactless interface of Clearent’s iOS framework for the transaction.

Audio Jack

Feedback Message	Description
PLUGIN AUDIO JACK	This message instructs users to insert the audio jack into the device when Clearent’s iOS framework configures the connection for the audio jack.
DISCONNECTING BLUETOOTH. PLUG IN AUDIO JACK	This message instructs users to insert the audio jack into the device when Clearent’s iOS framework configures the connection for the audio jack. It also informs users that the Bluetooth is disconnecting in the card reader.
UNPLUG AUDIO JACK BEFORE CONNECTING TO BLUETOOTH	This message instructs users to remove the audio jack from the device and connect the reader via Bluetooth.
AUDIO JACK CONNECTED	This message informs users that the audio jack is connected.
AUDIO JACK LOW VOLUME. TURN UP VOLUME AND RECONNECT	This message instructs users to turn up the volume to use the audio jack reader with Clearent’s iOS framework.

Additional Bluetooth

Feedback Message	Description
NEW BLUETOOTH CONNECTION REQUESTED. DISCONNECT CURRENT BLUETOOTH	This message instructs users to disconnect Bluetooth from the current device and informs users that a new Bluetooth connection has been discovered.
BLUETOOTH DISCONNECTED	This message informs users that Bluetooth is disconnected.
DEVICE NOT CONNECTED	This message informs users when Clearent’s iOS framework has an issue with the device.
PAYMENT REQUEST AND CONNECTION REQUIRED	This message informs users when Clearent’s iOS framework encounters an issue with the connection of the payment request. It also instructs users to cancel the transaction and start it again.

Uncommon

Feedback Message	Description
DEVICE NOT CONNECTED	This message informs users when Clearent’s iOS framework has an issue with the device.
PAYMENT REQUEST AND CONNECTION REQUIRED	This message informs users when Clearent’s iOS framework encounters an issue with the connection of the payment request. It also instructs users to cancel the transaction and start it again.

Informational

The following tables provide information about the feedback messages included in Information feedback type:

General

Feedback Message	Description
SEARCHING FOR POWERED ON BLUETOOTH READERS	This message informs users when Clearent’s iOS framework searches for the card reader to connect via Bluetooth search.
CARD READ OK	This message informs users when Clearent’s iOS framework successfully read the card data.
CARD SECURED	This message informs users when Clearent’s iOS framework receives the card data and sends the transaction token (JSON Web-based Token) to your iOS app for processing the payment.
GOING ONLINE	This message informs users when the iOS framework calls to the Clearent to secure the card data.
DECLINED RECEIPT SENT, REMOVE CARD	This message informs users when the transaction is declined and the email describing the transaction send to the user’s email address, provided during the transaction. It also instructs users to remove the card from the card reader.
Device Firmware version not found	This message informs users when Clearent’s iOS framework cannot communicate with the card reader to identify its firmware version. Note: This message appears to users when using the card reader firmware version 151 or earlier and contactless feature.
Device Kernel Version Unknown	This message informs users when Clearent’s iOS framework cannot communicate with the card reader to identify its kernel version.
Reader configured and ready	This message informs users when the card reader is ready to use.
TRANSACTION STARTED	This message informs users when Clearent’s iOS framework starts the payment process.
TRANSACTION FAILED	This message informs users when Clearent’s iOS framework failed to process the payment.
CHIP NOT RECOGNIZED, PULL CARD OUT, WAIT FOR GREEN LED, TRY SWIPE	This message informs users when Clearent’s iOS framework cannot identify the chip of the card to read the card data. It also instructs users to remove the card from the card reader and wait until the Green LED flashes before swiping again.
Device connected. Waiting for configuration to complete...	This message informs users when Clearent’s iOS framework connects to the device and to wait to complete the configuration of the device.

Contactless

Feedback Message	Description
AMOUNT IS OVER MAXIMUM LIMIT ALLOWED FOR TAP	This message informs users when Clearent's iOS framework identifies that an amount available over the maximum limit to use the contactless feature.

Audio Jack

Feedback Message	Description
AUDIO JACK ATTACHED	This message informs users when Clearent's iOS framework identifies that an audio jack has been attached to the device.
CONNECTING AUDIO JACK	This message informs users when Clearent's iOS framework identifies that an audio jack is connecting to the device.
AUDIO JACK REMOVED	This message informs users when Clearent's iOS framework identifies that an audio jack has been removed from the device.
AUDIO JACK DISCONNECTED	This message informs users when Clearent's iOS framework identifies that an audio jack has been disconnected from the device.
Powering up reader...	This message informs users when Clearent's iOS framework identifies that an audio jack is powering up to the device.

Errors

The following tables provide information about the feedback messages included in the Errors feedback type:

General

Feedback Message	Description
Card read error	This message informs users when Clearent’s iOS framework has encountered an error during the card read.
CVM Unsupported. Insert card with chip first, then start transaction. Or try swipe.	This message informs users when Clearent’s iOS framework cannot support the Cardholder Verification Method. It also instructs users to insert the card with chip side first or swipe the card and start the transaction process.
Card declined	This message informs users when Clearent’s iOS framework declines the card offline.
TIMEOUT	This message informs users when Clearent’s iOS framework has timed out the request during the payment process.
Create Transaction Token Failed	This message informs users when Clearent’s iOS framework cannot secure the card data and cannot send the transaction token (JSON Web-based Token) to your iOS app for processing the payment.
Sending Declined Receipt Failed	This message informs users when Clearent’s iOS framework has declined the payment process and failed to connect to Clearent’s servers to send an email to the customer. The email request process is separate from the payment process and can also fail due to slow or no internet connection.
Failed to read card	This message informs users when Clearent iOS framework has failed to read the card.
DISABLE CONFIGURATION REQUEST TO RUN TRANSACTION	This message instructs users to stop configuration request when Clearent iOS framework is starting the transaction process during the configuration.
READER NOT CONFIGURED	This message informs users when Clearent iOS framework has determined that the card reader is not configured.
TRANSACTION FAILED	This message informs users when Clearent iOS framework failed to process the payment.
UNABLE TO GO ONLINE	This message informs users when Clearent iOS framework cannot connect Clearent servers due to slow or no internet connection.
PAYMENT REQUEST NOT FOUND	This message informs users when Clearent iOS framework cannot determine the payment request.
TERMINATED	This message informs users when transaction cannot succeed and has been terminated from the IDTech framework perspective. It also instructs users to disable the contactless interface as the IDTech framework has indicated that the contactless interface cannot work. The Clearent iOS framework will restart the transaction.
CARD UNSUPPORTED	This message informs users when the IDTech framework has determined the card is unsupported.
UNABLE TO GO ONLINE, FAILED TO SEND DECLINED RECEIPT	This message informs users when Clearent’s iOS framework has failed to connect Clearent servers to send an email to the customer. The email request process is separate from the payment process and can also fail due to slow or no internet connection.

Bluetooth

Feedback Message	Description
Bluetooth friendly name required	This message informs users when Clearent's iOS framework identifies that an amount available over the maximum limit to use the contactless feature.

Contactless

Feedback Message	Description
Contactless not supported. Insert card with chip first, then start transaction	This message informs users when the Clearent iOS framework has identified that the contactless interface has been disabled. It also instructs users to insert the card with the chip side into the card reader to start the transaction.
TAP FAILED	This message instructs users to insert or swipe the card again if contactless interaction fails and informs users that they cannot use the contactless feature for a new transaction.
CARD BLOCKED	This message informs users when the Clearent iOS framework cannot read the card data for some unknown reason when they use the contactless interface feature during the payment process.
CARD EXPIRED	This message informs users when the Clearent iOS framework cannot read the card data for some unknown reason when they use the contactless interface feature during the payment process.