ADD_TIP
Last updated: 07-Apr-2025
This command adds tip or modifies TIP on an existing CAPTURE transaction. Add Tip will overwrite any previous tip amount.
Device UI Required: No
Request Packet
| Field | Rule | Type | Minimum | Maximum | Value(s) | Description |
|---|---|---|---|---|---|---|
| FUNCTION_TYPE | Required | Static value | N/A | N/A | PAYMENT | Type of function |
| COMMAND | Required | Static value | N/A | N/A | ADD_TIP | Command name |
| PAYMENT_TYPE | Required | List | N/A | N/A | CREDIT DEBIT GIFT |
Payment types. NOTE: PAYMENT_TYPE field is mandatory for card token based transactions. |
| CTROUTD | Required | Numeric | 1 | 16 | This is the transaction ID to which Tip will be attached. CTROUTD is a sequence number for PAYMENT transactions (always enabled) that is generated per Client ID. Each Client ID has its own CTROUTD sequence counter. NOTE: This is not used for SVS. SVS requires swiped track data or keyed account number. Example: 123456 | |
| ENCRYPT | Conditional | Binary | N/A | N/A | TRUE FALSE |
This field is required to encrypt the PAN details before passing it on to processor/gateway. In case of P2PE encryption, this field needs to be set to TRUE as value. NOTE: If this field is not present, then the application will internally treat this field as a value TRUE when the device encryption is ADE/VSD. |
| TIP_AMOUNT | Required | Floating point number (decimal) | 1(2) | 6(2) | Tip amount to be added. Example: 5.03 | |
| COL_3, COL_4, COL_5, COL_6, COL_7, COL_8, COL_9, COL_10 | Optional | Character | 1 | 255 | These fields represent Column 3 to Column 10. These fields are expected for the Merchants internal POS System, which will record any additional data and link those to the PWC CLIENT_ID and CTROUTD. When a value for COL_n is passed in, that same value will be returned in the response. These COL_n values are not indexed, or searchable in any command report. These fields are not sent to any payment processor. Example: Merchant defined data | |
| POS_RECON | Optional | Character | 1 | 30 | POS reconciliation. POS Reconciliation field to be echoed back in response to POS. Example: RetailPOS1 | |
| 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 | N/A | N/A | N/A | 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>PAYMENT</FUNCTION_TYPE>
<COMMAND>ADD_TIP</COMMAND>
<COUNTER>1</COUNTER>
<MAC> … </MAC>
<MAC_LABEL>REG2</MAC_LABEL>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<CTROUTD>5</CTROUTD>
<ENCRYPT>TRUE</ENCRYPT>
<TIP_AMOUNT>2.00</TIP_AMOUNT>
</TRANSACTION>
Response Packet
| Field | Type | Value | Description |
|---|---|---|---|
| RESPONSE_TEXT | Character | Processor response text. Example: TIP MODIFIED :A :AP | |
| RESULT | Character | Commonly TIP MODIFIED or DECLINED or CAPTURED. Example: TIP MODIFIED | |
| RESULT_CODE | Numeric | Expected result code: 4, 6, 17 | This indicates the result code. |
| TERMINATION_STATUS | Character | SUCCESS and 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. |
| POS_RECON | Character | POS reconciliation field echoed back if sent in request. Example: RetailPOS1 | |
| COUNTER | Numeric | Echoes counter sent in the request. Example: 100 | |
| MERCHID | Numeric | Merchant ID. Example: 900000000123 | |
| TERMID | Numeric | Merchant ID. Example: 001 | |
| TRANS_SEQ_NUM | Numeric | Processor/Batch trans sequence number. Example: 5 | |
| INTRN_SEQ_NUM | Numeric | PWC transaction ID. Example: 123456789 | |
| TRACE_NUM | Numeric | This field is sent from the Host Response. This field contains the Interac Sequence number from the host. Example: 1400040000000004001951 | |
| TROUTD | Numeric | Transaction routing ID. Example: 123456789 | |
| CTROUTD | Numeric | CTROUTD is a sequence number for PAYMENT transactions (always enabled) that is generated per Client ID. Each Client ID has its own CTROUTD sequence counter. Example: 45 | |
| APPROVED_AMOUNT | Floating point number (decimal) | Amount approved. Example: 30.00 | |
| PAYMENT_MEDIA | Character | Medium of payment. Commonly VISA/MC/DISC/AMEX/DEBIT. Example: MC | |
| PAYMENT_TYPE | Character | Payment type returned. Example: CREDIT | |
| AUTH_CODE | Character | Processor authorization number. Example: 123123. | |
| RECEIPT_DATA | Character | Receipt Data. | |
| TRANS_DATE | Character | Transaction date returned. Example: 2016.09.20 | |
| TRANS_TIME | Character | Transaction time returned. Example: 09:16:25 | |
| BANK_USERDATA | Character | Bank User Data. Example: MC | |
| SERVER_ID | Numeric | Echoes what is sent in START request. Example: 10 | |
| VSP_CODE | Numeric | If present, returns the VSP code. Example: 910 | |
| VSP_RESULTDESC | Character | If present, returns the VSP result description. Example: VSP NOT APPLICABLE | |
| VSP_TRXID | Numeric | If present, returns the VSP transaction ID. Example: 0 | |
| AUTH_REF_NUMBER | Character | Example: 123456789012345; Or, it can be empty | This tag returns in the host response with the value for the particular transaction. This is used by some merchants to refer to the transaction at the host side. Currently this is applicable only for Worldpay processor. |
| COL_3, COL_4, COL_5, COL_6, COL_7, COL_8, COL_9, COL_10 | Character | Column 3 to Column 10 fields value will be echoed in POS response. These fields are not sent to any payment processor. |
Transaction Performance Metric
Note
These fields are returned, if SCAPERFMETRIC parameter (Application Parameters) is enabled.
| Field | Type | Value | Description |
|---|---|---|---|
| UI_TIME | Time | This indicates the time duration, for which the device screen is displayed (like error message, prompt screen, remove card screen) till any user action is performed in the command execution flow. This field is not applicable to capture the time for the Processing, Authorizing and transaction status screen. The format of the returned value would be S.sss, where S is seconds (this can be 0 to any positive integer) and sss is milliseconds. In case of any insignificant time or 0.000 value, will not be returned in the response. Example: <UI_TIME>44.028</UI_TIME> |
|
| HOST_TIME | Time | This indicates the time taken for the Connection to the host, sending request and receives data from the host. This field also take the cumulative time for multiple requests which may sent to the host during the transaction including two legged transactions, timeout requests, Auto Last Tran requests, DCC, Credit app proxy. The format of the returned value would be S.sss, where S is seconds (this can be 0 to any positive integer) and sss is milliseconds. In case of any insignificant time or 0.000 value, will not be returned in the response. Example: <HOST_TIME>1.389</HOST_TIME> |
|
| CMD_TIME | Time | This field indicates the total amount of time for a command, which is executed by the application from request received to the response sent. The format of the returned value would be S.sss, where S is seconds (this can be 0 to any positive integer) and sss is milliseconds. In case of any insignificant time or 0.000 value, will not be returned in the response. Example: <CMD_TIME>70.765</CMD_TIME> |
Example
Following is an example of response packet
<RESPONSE>
<APPROVED_AMOUNT>10.00</APPROVED_AMOUNT >
<AUTH_CODE>090435</AUTH_CODE>
<BANK_USERDATA>MC</BANK_USERDATA>
<CTROUTD>34</CTROUTD>
<INTRN_SEQ_NUM>50408</INTRN_SEQ_NUM>
<MERCHID>100010001</MERCHID>
<PAYMENT_MEDIA>MC</PAYMENT_MEDIA>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<RESPONSE_TEXT>TIP MODIFIED : A : AP</RESPONSE_TEXT>
<RESULT>TIP MODIFIED </RESULT>
<RESULT_CODE>17</RESULT_CODE>
<TERMID>001</TERMID>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<TRANS_DATE>2017.08.20</TRANS_DATE>
<TRANS_SEQ_NUM>3</TRANS_SEQ_NUM>
<TRANS_TIME>09:16:25</TRANS_TIME>
<TROUTD>523</TROUTD>
<VSP_CODE>910</VSP_CODE>
<VSP_RESULTDESC>VSP NOT APPLICABLE</VSP_RESULTDESC>
<VSP_TRXID>0</VSP_TRXID>
</RESPONSE>
Rate this article:
