Command 0x1001 - Start Transaction
The host uses this command to start a payment transaction.
The sequence of events for transactions with card readers enabled is roughly as follows.
Initial conditions / Pre-start
(MCE Only) The sequence for Manual Entry Mode is provided further below.
If the device is configured to enable user action event notifications using Property 1.2.7.1.2.1 User Event Notification Controls Enable, the cardholder may present a card or payment device before the host calls this command. In that case the device sends Notification 0x1001 - Device Information Update to the host to indicate it should call this command to start a transaction.
(MSR Only) If the cardholder swiped before the transaction started, the device temporarily stores the card swipe data for the period specified by Property 1.2.7.1.2.2 User Event Notification MSR Data Timeout (MSR Only) to make it available during the transaction. Later, when the device would ordinarily prompt the cardholder to swipe/insert/tap, the device briefly shows the same prompt and then proceeds automatically using the stored card data.
(EMV Contact Only | EMV Contactless Only) If the cardholder inserted or tapped before the transaction started, the host should call this command as quickly as possible while the card is still in the slot or within tap range. The device does not begin contact or contactless reads until the host invokes this command and does not store any data from the pre-start action.
Card presented event
After the cardholder presents payment, the device sends Notification 0x0101 - Transaction Information Update to report the payment technology being used / Card Event.
(MSR Only) If Property 1.2.1.1.1.1 Device-Driven Fallback Behavior (MSR Only) is configured so the device automatically performs fallback operations, it performs them at this time (device-driven fallback occurs within one iteration of this command).
EMV contact — application selection
(EMV Contact Only) If the cardholder inserted a chip card and there is more than one application the device and card mutually support:
(Display Only) The device prompts the cardholder to select the application to use.
(No Display Only) The device sends Notification 0x1803 - User Interface Host Action Request to report Cardholder Selection Request / Notification Payload. The host should show the prompt, receive input from the cardholder, and call Command 0x1802 - Report Cardholder Selection to report the selection result to the device.
Quick Chip Transaction Flow (if specified by host)
If the host specified Quick Chip Transaction Flow in the Transaction Flow parameter:
The device immediately constructs its own internal ARPC Response (with tag 8A set to 'Z3') and sends Notification 0x0105 - Transaction Operation Complete to report the payment technology being used / Kernel Outcome / Quick Chip Deferred / outcome detail. A Transaction Option parameter can be set to display on amount or not.
The device notifies the cardholder that the card can be removed:
(Display Only) The device shows the message "REMOVE CARD".
(No Display Only) The device sends Notification 0x1803 - User Interface Host Action Request to report Display / Display Message / Data Attached with message to notify the cardholder the card can be removed.
The host should then process the ARQC message data, replace the default amount with the final transaction amount as needed, and coordinate with the transaction processor to retrieve a final transaction result. Because the device is not involved in determining the final transaction result, it does not send a notification to the host to show APPROVED or DECLINED.
(Display Only) The host should call Command 0x1803 - Display Message (Display Only) to show APPROVED or DECLINED based on the final transaction result.
(No Display Only) The host should use its local display to show the appropriate APPROVED or DECLINED message to the cardholder.
EMV Transaction Flow (if specified by host)
If the host specified EMV Transaction Flow in the Transaction Flow parameter:
The host processes the ARQC message data and uses it to coordinate with the transaction processor to receive an ARPC Response, which it processes and sends to the device using Command 0x1004 - Resume Transaction.
The device waits up to the period specified in Property 1.1.1.1.1.5 ARPC Receive Timeout. If an ARPC timeout occurs, the device will send the ARQC again based on Property 1.1.1.1.1.6 ARPC Retry Attempts.
(EMV Contact Only) If the cardholder inserted a contact chip card, the device communicates with the card to determine whether to approve or decline the transaction.
The device sends Notification 0x0105 - Transaction Operation Complete to report the payment technology being used / Kernel Outcome / Approved or Declined / outcome.
(Display Only) The device shows the transaction result to notify the cardholder (APPROVED or DECLINED).
(No Display Only) The device sends Notification 0x1803 - User Interface Host Action Request to report Display / Display Message / Data Attached with the message to notify the cardholder of the transaction result.
Signature capture
(Touch Only) If the card requires a signature and Property 1.2.1.1.2.1 Signature Capture Control is set to Device-driven Signature Capture (and if Signature Capture Control (MSR Only) command parameter does not apply), the device prompts the cardholder to sign.
The device sends Notification 0x0101 - Transaction Information Update to report the payment technology used / Data Update / Batch Data / Data Attached. (Touch Only) Depending on Property 1.2.1.1.2.2 Include Signature Data in EMV Batch Data (Touch Only), the device includes any acquired signature data with the batch data.
Transaction completion
The device sends Notification 0x0105 - Transaction Operation Complete to report the payment technology used / Outcome / the final result of the transaction.
(MSR Only) If Property 1.2.1.1.1.1 Device-Driven Fallback Behavior (MSR Only) is configured so the device does not perform fallback operations, and if the solution design requires payment brand fallback logic, the host may implement fallback flow using the contents of notifications above. The rules below mimic automatic fallback; the primary difference is the host must track its own final Fallback Indicator instead of receiving it from the device in the EMV ARQC Type.
If the transaction was successful and notification indicates Payment Technology is EMV Contact or EMV Contactless: no fallback required.
If successful and notification indicates Payment Technology is Magnetic Stripe Reader:
Check Card Type (tag DFDF52 in EMV ARQC Type):
If Card Type is NOT "MSR Financial and Contact Chip Card (ICC)", continue with the current transaction using magnetic stripe data.
If Card Type is "MSR Financial and Contact Chip Card (ICC)" and the host has restarted the same transaction because a previous attempt failed with notification indicating MSR Fallback, the chip card and device already communicated and determined they are not compatible — the host may continue current transaction using magnetic stripe data.
If Card Type is "MSR Financial and Contact Chip Card (ICC)" and the host has NOT restarted the same transaction three times and failed with notification indicating Technical Fallback, the host should guide the cardholder to use the chip reader: send Command 0x1803 - Display Message to display "USE CHIP READER", then repeat Command 0x1001 - Start Transaction and arm the device with contact interface enabled (optionally arm contactless).
If Card Type is "MSR Financial and Contact Chip Card (ICC)" and the host has restarted the same transaction three times and failed with notification indicating Technical Fallback, the host may continue current transaction using magnetic stripe data.
If the transaction failed and notification indicates Payment Technology is None: something failed at the very beginning (e.g., host canceled). The host may end attempts or repeat the original transaction with the same payment technologies enabled.
If the transaction failed and notification indicates Payment Technology is EMV Contact:
If notification indicates MSR Fallback: the chip card and the device have determined they are not compatible. The host should guide the cardholder to use the magnetic stripe interface by sending Command 0x1803 - Display Message to display "USE MAGSTRIPE", then repeat Command 0x1001 - Start Transaction and arm the device with MSR interface enabled (optionally arm contactless).
If the host has NOT restarted the same transaction three times and failed with notification indicating a Technical Fallback: the host should guide the cardholder to re-insert the chip card by sending Command 0x1803 - Display Message to display "AGAIN", then repeat Command 0x1001 - Start Transaction and arm the device with the contact interface enabled (optionally arm contactless).
If the host has restarted the same transaction three times and failed with notification reporting Technical Fallback: guide the cardholder to use the magnetic stripe reader by sending Command 0x1803 - Display Message to display "MAGSTRIPE", then repeat Command 0x1001 - Start Transaction and arm the device with MSR interface enabled (optionally arm contactless).
Host-driven signature capture (Touch Only)
If Property 1.2.1.1.2.1 Signature Capture Control is set to Host-driven Signature Capture and the card requires a signature, the host should perform host-driven signature capture at this time.
The device waits for the time specified by 1.2.1.1.2.3 Signature Timing Window (Touch Only), providing a window for the host to end the transaction by sending Command 0x1801 - Request Cardholder Signature. If the host does not call that command before the window ends, the device returns to idle.
EMV Contactless / NFC Tag (EMV Contactless Only)
For NFC Tag:
Use Start Transaction command with NFC enabled in Contactless Reader Mode.
If an NFC Tag is detected:
The terminal sends a notification that identifies the NFC card type (Notification 0x0101 - Transaction Information Update).
The terminal sends another notification with the UID as payload (see Table 314 - Notification Payload for Data Update, ARQC Update (Quick Chip), Data Attached). If a card is configured with a random ID, its value will change each detection; the host is responsible to retrieve the real UID.
No ARQC or BATCH data will be sent for NFC Tag interactions.
The host application can continue interfacing with the NFC tag by sending pass-through commands.
When the NFC Tag leaves the field, the terminal sends Notification 0x0105 – 20 05 00 00 (PICC, NFC Tag, Tag Removed, Reserved) indicating the tag has been removed.
MCE (Manual Card Entry) flow
(MCE Only) For manual card entry:
The host composes a command request with Manual Entry Mode parameters defined and other reader modes empty and sends it to the device. The host may cancel the transaction by calling Command 0x1008 - Cancel Transaction.
The device creates Track 1 and Track 2 data based on entered values.
The device sends instances of Notification 0x0101 - Transaction Information Update to report each of the following:
Manual Card Entry, Card Event, Data Entered, Reserved
Manual Card Entry, Data Update, ARQC Update, Data Attached
Manual Card Entry, Data Update, Batch Update, Data Attached
The device sends Notification 0x0105 - Transaction Operation Complete to report Manual Card Entry, Transaction Completed, Reserved, Reserved.
Tip Feature (Touch Only)
Tip operations have multiple use cases and modes.
Tip Operation Use Case Mode 1A
Use Tag A4 for Tip and Tax Options.
Use Byte 1 of Tag 81 under A4 to specify Tip mode:
0x01 = Use % mode
0x02 = Use Amount mode
Bytes 2 through 31 of Tag 81 specify the % or $ values to show for Buttons 1 thru 6. There is a button mode to control whether the button will show $/%, CUSTOM, NO TIP, or is disabled.
Tag 82 is the Tax Amount to display.
DF5D = Tip Amount, DF5E = Tax Amount are used for reporting back to the host application.
If available, tags DF5D and DF5E will be sent in the ARQC Data (see Table 19 - EMV ARQC (DynaPro Format) Type).
The value of Tag 9F02 provided in command 0x1001 will be updated by the Device by adding TIP and TAX before passing that value to the kernels.
See Tip & Tax Display Limits (Touch Only) for display limitations.
Tip Operation Use Case Mode 1B
If Property 1.1.1.1.1.1B Interac Contact Card Terminal Capability ONLINE PIN Support Disable is Enabled, and there is a socket connection with the host, the device will show the START SALE button.
When the cardholder touches the button, the device will automatically start a START SALE transaction by asking the cardholder to enter the transaction amount. The device will show the CUSTOM AMOUNT screen. Press ENTER to set transaction amount. The Start Transaction ENTER parameters are taken from the settings of these properties.
Relevant properties (Touch Only)
Property 1.1.1.1.2.2 Tip Mode (Touch Only)
Property 1.1.1.1.2.6 Tip Mode Enable Submit on Amount Button Press`
Property 1.1.1.1.3.2 Reader Options (Touch Only)
Property 1.1.1.1.3.3 Transaction Options (Touch Only)
Flow summary (Touch Only):
The device automatically sends a Notification – Transaction Information Update when a transaction has started (Table 313 - Notification Detail Codes).
If the button is touched, the device automatically sends a Notification – Transaction Information Update that a transaction is canceled (Table 313 - Notification Detail Codes).
After amount is entered, the device checks Property 1.1.1.1.2.2 Tip Mode (Touch Only) to determine if TIP mode is enabled and the TIP parameters. The device will show TIP / CUSTOM AMT / SUBMIT or SUMMARY SCREEN per cardholder selection.
The device checks Property 1.1.1.1.2.3 Tax Rate (Touch Only) to determine if taxes need to be calculated. If enabled, device calculates Taxes per the tax rate specified.
If tax function is enabled, the device checks Property 1.1.1.1.2.4 Display Tax or Surcharge (Touch Only) to determine whether to label it tax or surcharge in the SUMMARY SCREEN.
Tax is calculated only on the entered amount (excluding TIP).
Total Amount = Amount + Tip + Tax. Total Amount is used for Tag 9F02 of the transaction flow.
See Tip & Tax Display Limits (Touch Only) for display limitations.
Audio transducer / NFC beep flow (notes)
Upon NFC tag detection, notify host.
Host sends 0x1001 to Start Transaction.
After NFC is activated - No beep.
Host goes through several pass-through commands to read/write NFC.
A parameter will be added to the Pass-Through command API to indicate if this is the last command.
If this is the last command, Device -> Single Beep to indicate "CARD CAN BE REMOVED" and Turn-Off RF to shut down card.
If an error condition is detected, the device will end session, double-beep, Turn-Off RF to shut down the card.
The host uses this command to start a payment transaction with an option to display a page and a green functional button Right (e.g. Service Request button).
Present a Card
When the cardholder presses the button, the device will send a notification, show:
Service Request, and await the next command from the host.
PLEASE WAIT
If the battery charge is five percent or less, a response is returned indicating that the command has not been executed. See Table 73 - Response Example for Command 0x1001 – Start Transaction Command not executed due to Battery Charge State.
Table - Request Data for Command 0x1001 - Start Transaction
— wrappers —
Beginning of any wrappers, at minimum including Request Message
1001
Command 0x1001 - Start Transaction
81
01
Reserved
O
82
01
Transaction Timeout, in seconds. This parameter defines how long the device waits for the cardholder to take action on any cardholder input, for example, when waiting for the cardholder to present payment after the host starts the transaction.
0x00 = No timeout
0x01 to 0xFF = 1 to 255 seconds
B
R
A3
var
Reader Options. The parameters inside this TLV data object allow the host to enable and disable the various payment method interfaces.
T
O
/81
01
Magnetic Stripe Reader Mode (MSR Only)
0x00 = Disabled
0x01 = EMV
0x80 = Non-EMV (disables other readers) (MAGTEK INTERNAL ONLY FOR NOW)
B
O
0x01
/82
01
Contact Reader Mode (EMV Contact Only)
0x00 = Disabled
0x01 = EMV
B
O
0x01
/83
01
Contactless Reader Mode (EMV Contactless Only)
0x00 = Disabled
0x01 = EMV
0x02 = NFC
0x03 = EMV and NFC
B
O
0x01
/84
03
Manual Entry Mode (Touch Only). Populate this parameter to enable manual card entry. When using this feature, all other Reader Mode parameters must be set to Disabled. Byte 1 Card Number Valid Format
0x00 = PAN min 8, max 21 digits
Byte 2 User Interface Sequence
0x00 = Based on the setting of Property 1.2.1.1.5.1 MCE Mode Setting
Byte 3 Beeper Feedback
0x00 = On keypress sound disabled
0x01 = On keypress sound enabled
B
O
/85
02
Barcode Reader Mode (BCR Only). Populate this parameter to enable the device’s barcode reader. This feature can be enabled alongside all other reader modes except Manual Entry Mode. Byte 1 Barcode Reader Enable
0x00 = Disabled
0x01 = Enabled
Byte 2 Encrypt Non-EMV Barcode Data
0x00 = Disabled
0x01 = Enabled
B
O
0x0000
/86
01
PIN Block Format (Touch Only)
0x00 = ISO Format 0
0x03 = ISO Format 3
0x04 = ISO Format 4
B
O
0x00
A4
var
Tip and Tax Options
B
O
/81
1F
Byte 1 Tip Mode
0x00 – Disable Tip Mode
0x01 – Show Tip GUI immediately using % value
0x02 – Show Tip GUI immediately using $ amount
0x11 - Enable Read Channel(s), with +Tip Button, %value
0x12 - Enable Read Channel(s), with +Tip Button, $ Amount
Other bytes define display modes and values for up to 6 buttons. See Property 1.1.1.1.2.2 Tip Mode (Touch Only) for suggested defaults.
B
O
/82
06
Tax or Surcharge Amount to Display. See Property 1.1.1.1.2.4 Display Tax or Surcharge (Touch Only) to configure display Tax or Surcharge.
B
O
A5
var
Customer Options.
/81
2
Transact transaction flow. Do not configure this tag if the Host wants to run NFC passthrough commands. Byte 1 Transaction Mode bits:
Bit 0 = Enable Mifare Classic (1K/4K) Physical Card
Bit 1 = Enable Mifare DESFire EV1/EV2/EV3 Physical Card
Bit 2 = Enable Apple Wallet Mobile DESfire Card (when set, set Transaction Option Tag 84 to Apple ECP2 Mode)
Bit 3 = Enable Mifare2Go Mobile DESFire Card
Byte 2 Read Data Mode
0x00 = Read ASCII Number
0x01 = Read Binary Card Number
B
O
0x0000
84
02
Transaction Options. Bitmask that sets device behaviors affecting transaction flow and result reporting. Details include Apple/Google VAS modes, wallet modes, protocol mode, and transaction flow control (e.g., Quick Chip). See table content for full bit definitions.
B
O
0x0003
85
var
Apple ECP2 frame from Byte 2 to Byte N (Min N = 4, Max N = 19). By default Byte 2-N = 0xC3020003FFFF. Host can configure this parameter to set Apple ECP2 frame. See Apple ECP2.0 spec.
B
O
86
var
Transaction TLV. A list of TLV data objects defining basic transaction parameters. May contain EMV tags; at minimum must contain 9C and 9F02 (and 9F03 if cash back). Optional for Manual Entry; include 9F02 and 5F2A to show transaction amount for Manual Entry. Common tags:
9C Transaction Type
9F02 Amount Authorized
9F03 Amount Other
9F7C Merchant Custom Data
5F2A Transaction Currency Code
5F36 Transaction Currency Exponent
9F53 Transaction Category Code
9F15 Merchant Category Code
9F16 Merchant ID
B
R/O
A8
00
(MAGTEK INTERNAL ONLY FOR NOW) Tag Lists
O
8A
(MAGTEK INTERNAL ONLY FOR NOW) Notification Options
AC
var
User Interface Options
T
O
null
/81
00
Suppress Thank You Message. By default devices with a display show “THANK YOU,” then “WELCOME.” Include this to suppress “THANK YOU” for this transaction.
T
O
null
/82
01
Override Final Transaction Message. Choose a Display String ID (see section 4.3 Display Strings). Overrides idle page behavior until next transaction, power cycle, or similar state change.
B
O
null
/83
02
Functional button Right option. String ID = enable the present card page with a green functional Right button (label is a String ID, ~15 chars). When user presses this button, device sends notification to host: Notification 0x1803 - User Interface Host Action Request. If host wants to disable this button, do not include this tag.
B
O
null
— wrappers —
End of any wrappers, at minimum including Response Message
Table - Response Data for Command 0x1001 - Start Transaction
— wrappers —
Beginning of any wrappers, at minimum including Request Message
1001
Command 0x1001 - Start Transaction
—
—
No parameters.
— wrappers —
End of any wrappers, at minimum including Response Message
Table - Response Example for Command 0x1001 – Start Transaction Command not executed due to Battery Charge State
If the request started successfully, the Request Status in the message wrapper is: OK, Started / Running, All good / requested operation was successful
Table - Request Examples
Table - Request Example:
Table - Response Example
Example (Hex):
Last updated