ADD_TIP
Last updated: 09-Dec-2024
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 | |
| 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. |
| 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. |
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:
