START SESSION
Last updated: 04-Dec-2024
This command is used to start a new session. The session can be for a payment transaction or to display line item information.
Device UI Required: Yes
Request Packet
| Field | Rule | Type | Minimum | Maximum | Value(s) | Description |
|---|---|---|---|---|---|---|
| FUNCTION_TYPE | Required | Static Value | N/A | N/A | SESSION | Type of function. |
| COMMAND | Required | Static Value | N/A | N/A | START | Command name. |
| INVOICE | Required | Character | 1 | 40 | Merchant invoice number. Maximum 40 characters supported (A-Z, a-z, 0-9) and this not case sensitive. All the special characters are supported in INVOICE field. NOTE: POS system should handle the maximum character limit for invoice, based on the respective end host used in the environment in case the limit is less than 40. Worldpaly allows numeric only; the value may not be all zeroes. Example: TA1234 | |
| SWIPE_AHEAD | Optional | Binary | 1 | 1 |
|
SWIPE_AHEAD is used to enable preswipe functionality. NOTE: Value being sent in SWIPE_AHEAD will have precedence over IDLECARDENTRYENABLED parameter value (Application Parameters). |
| STORE_NUM | Optional | Character | 1 | 6 | Store number. Example: 203 | |
| LANE | Optional | Numeric | 1 | 8 | Used to identify the retail lane. Example: 1 | |
| CASHIER_ID | Optional | Character | 1 | 10 | Cashier performing the transaction. Example: 560 | |
| SERVER_ID | Optional | Numeric | 1 | 10 | Server performing the transaction. NOTE: FD RC Engage allows maximum of 5 digits. Example: 560 | |
| SHIFT_ID | Optional | Character | 1 | 1 | Shift at the store. Example: 2 | |
| TABLE_NUM | Optional | Numeric | 1 | 5 | Table number. Collected for receipts. Example: 10 | |
| BUSINESSDATE | Optional | Numeric | 8 | 8 | YYYYMMDD format Example: 20161129 | |
| PURCHASE_ID | Conditional | Character | 1 | 25 | Required for Level II processing. P.O. Number or Customer Code. NOTE: All the special characters are supported in PURCHASE_ID. Example: 1 | |
| USER_DEFINED1 | Optional | Character | 1 | 35 | User defined field. This is applicable to Worldpay Only. | |
| USER_DEFINED2 | Optional | Character | 1 | 35 | User defined field. This is applicable to Worldpay Only. NOTE: Will be truncated to 20. | |
| USER_DEFINED3 | Optional | Character | 1 | 35 | User defined field. This is applicable to Worldpay Only. NOTE: Will be truncated to 20. | |
| POS_IP | Optional | Character | For Consumer Unsolicited Responses to POS. POS IP listening address. Example: 192.168.31.100 | |||
| POS_PORT | Optional | Numeric | 4 | 4 | For Consumer Unsolicited Responses to POS. POS listening port. Example: 5016 | |
| TRAINING_MODE | Optional | List |
|
Include this field to turn on Training Mode for the session. Transactions are routed to HIF Test for host simulation and results are mocked for approvals. NOTE: Refer to TestHost.XML Used for specifics. This is not supported by Worldpay SCA 4.0. When DEMO parameter is 1 (enabled), transactions will be performed in Training Mode without the need to pass <TRAINING_MODE>ON</TRAINING_MODE> from POS. |
||
| NOTIFY_SCA_EVENTS | Optional | Binary |
|
If TRUE, return event broadcasts as play by play of what is occurring on the device when interacting with consumer and host as Unsolicited Consumer Selection response. NOTE: POS_IP and POS_PORT must be sent. Broadcast events should be used as information only and not as a condition for stopping or resuming a transaction. The exception would be in case where consumer interaction has lapsed for certain duration and POS elects to CANCEL on secondary port. | ||
| COUNTER | Required | Numeric | 1 | 10 | COUNTER is used for a given MAC label. Each COUNTER should be higher than the last one. This is used to authenticate the POS. Example: 100 | |
| MAC | Required | Base64 Encoded Data | Message Authentication Code. This is used to authenticate the POS. | |||
| MAC_LABEL | Required | Character | 1 | 50 | Associated label that tells the device which MAC_KEY to use to decrypt the value of MAC. This is used to authenticate the POS. Example: REG1 |
Example
Following is an example of request packet
<TRANSACTION>
<FUNCTION_TYPE>SESSION</FUNCTION_TYPE>
<COMMAND>START</COMMAND>
<COUNTER>1</COUNTER>
<MAC> … </MAC>
<MAC_LABEL>REG2</MAC_LABEL>
<LANE>3</LANE>
<STORE_NUM>203</STORE_NUM>
<INVOICE>TA1234</INVOICE>
<SWIPE_AHEAD>1</SWIPE_AHEAD>
</TRANSACTION>
Response Packet
| Field | Type | Value | Description |
|---|---|---|---|
| RESPONSE_TEXT | Character | Processor response text. Example: Session started / SESSION started | |
| RESULT | Character | OK | This indicates the Result details. |
| RESULT_CODE | Numeric | Expected result code: -1, 59003 | This indicates the result code. Refer to Result/Error Codes for details. |
| TERMINATION_STATUS | Character | SUCCESS or FAILURE | This indicates the transaction termination status. This is the overall status of the transaction irrespective of approved or declined. Like, if the output is generated then the status is SUCCESS and if no output is generated then the status will be FAILURE. |
| COUNTER | Numeric | Echoes counter sent in the request. Example: 100 |
Example
<RESPONSE>
<RESPONSE_TEXT>SESSION started</RESPONSE_TEXT>
<RESULT>OK</RESULT>
<RESULT_CODE>-1</RESULT_CODE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<COUNTER>2</COUNTER>
</RESPONSE>
TestHost.XML Used in TRAINING_MODE
TRAINING_MODE can be included either in the START session request (where it would be ON or OFF for the whole session) or in a transaction request. TRAINING_MODE will be echoed in response.
Note
Training mode will return EMV fields in response if applicable.
TestHost XML
Note
As of this publication, all transaction amount values are receiving approvals from test host. This section is for information purposes only and is subject to change.
| Operation ID | Command | Transaction Amount | FIELD SET (Expected Response) |
|---|---|---|---|
| 1 | CAPTURE (Sale) | 1.01 | 1 |
| 1 | CAPTURE (Sale) | Other | 1 |
| 4 | AUTH | 20.00 | 2 |
| 4 | AUTH | Other | 2 |
| 5 | CLOSE_TAB NOTE: Use with OPEN_TAB amount 1.01 | 1.01 | Refer to CLOSE_TAB Response. |
| 5 | CLOSE_TAB | Other | |
| 7 | SETTLE | Any | 3 |
| 16 | CREDIT | Any | 2 |
| 45 | VOID | Any | 2 |
| 106 | ADD_VALUE | Any | 2 |
| 107 | ACTIVATE | Any | 2 |
Field set 1
| Field | Value |
|---|---|
| AUTH_CODE | TAS684 |
| INTRN_SEQ_NUM | 50407 |
| RESPONSE_TEXT | APPROVAL TAS684 |
| RESULT | CAPTURED |
| RESULT_CODE | 4 |
| TERMINATION_STATUS | SUCCESS |
| TRANS_DATE | YYYY.MM.DD |
| TRANS_TIME | HH:MM:SS |
| TROUTD | 50409 |
| APPROVED_AMOUNT | Equals transaction amount |
| AVAILABLE_BALANCE | 0.00 |
| TRAINING_MODE | ON |
Field set 2
| Field | Value |
|---|---|
| AUTH_CODE | TAS316 |
| INTRN_SEQ_NUM | 50408 |
| TRANS_SEQ_NUM | 7 |
| RESULT | CAPTURED |
| RESULT_CODE | 4 |
| TERMINATION_STATUS | SUCCESS |
| TRANS_DATE | YYYY.MM.DD |
| TRANS_TIME | HH:MM:SS |
| TROUTD | 50408 |
| APPROVED_AMOUNT | varies |
| AVAILABLE_BALANCE | If applicable |
| TRAINING_MODE | ON |
Field set 3
| Field | Value |
|---|---|
| RESPONSE_TEXT | Settlement Scheduled |
| TERMINATION_STATUS | SUCCESS |
Example Request (TRAINING MODE = ON in START session request)
<TRANSACTION>
<FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
<COMMAND>CAPTURE</COMMAND>
<PAYMENT_TYPE />
<TRANS_AMOUNT>1.01</TRANS_AMOUNT>
<MAC_LABEL>P_7RZOMW</MAC_LABEL>
<COUNTER>2</COUNTER>
<MAC> ... </MAC>
</TRANSACTION>
Example Response
<RESPONSE>
<RESPONSE_TEXT>APPROVAL TAS684</RESPONSE_TEXT>
<RESULT>CAPTURED</RESULT>
<RESULT_CODE>4</RESULT_CODE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<TROUTD>50409</TROUTD>
<CTROUTD>1</CTROUTD>
<INTRN_SEQ_NUM>50407</INTRN_SEQ_NUM>
<TRANS_DATE>2016.11.22</TRANS_DATE>
<TRANS_TIME>13:50:25</TRANS_TIME>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<PAYMENT_MEDIA>MASTERCARD</PAYMENT_MEDIA>
<ACCT_NUM>545454******5454</ACCT_NUM>
<AUTH_CODE>TAS684</AUTH_CODE>
<APPROVED_AMOUNT>1.01</APPROVED_AMOUNT>
<AVAILABLE_BALANCE>0.00</AVAILABLE_BALANCE>
<CARDHOLDER>FDCS TEST CARD MASTERCARD</CARDHOLDER>
<CARD_EXP_MONTH>04</CARD_EXP_MONTH>
<CARD_EXP_YEAR>20</CARD_EXP_YEAR>
<TRAINING_MODE>ON</TRAINING_MODE>
<COUNTER>2</COUNTER>
</RESPONSE>
Example CLOSE_TAB Response
<RESPONSE>
<RESPONSE_TEXT>Transaction Approved</RESPONSE_TEXT>
<RESULT>APPROVED</RESULT>
<RESULT_CODE>5</RESULT_CODE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<TRANS_DATE>2016.11.22</TRANS_DATE>
<TRANS_TIME>13:56:39</TRANS_TIME>
<CTROUTD>1</CTROUTD>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<APPROVED_AMOUNT>1.01</APPROVED_AMOUNT>
<TRAINING_MODE>ON</TRAINING_MODE>
<COUNTER>17</COUNTER>
</RESPONSE>
Rate this article:
