TOKEN_QUERY
Last updated: 09-Dec-2024
This command directs the device to retrieve card token information for a given card for the purpose of customer identification, purchase history or to validate a return.
Device UI Required: Yes
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 | TOKEN_QUERY | Command name |
| PAYMENT_TYPE | Required | List | N/A | N/A | CREDIT EBT GIFT |
Payment type field for EBT. NOTE: PAYMENT_TYPE field is mandatory for card token based transactions. |
| MANUAL_ENTRY | Optional | Boolean | N/A | N/A | TRUE FALSE |
This is to instruct SCA to collect the account information through the keypad on the device. If the value is set to FALSE then the device will prompt for card swipe/insert/tap. |
| ACCT_NUM | Optional | Numeric | 1 | 25 | This field is to enter the account number manually. For this MANUAL_ENTRY must be set to TRUE. Example: 67823456781313 | |
| CARD_EXP_MONTH | Optional | Numeric | 2 | 2 | Card expiry month. Example: 12 | |
| CARD_EXP_YEAR | Optional | Numeric | 2 | 2 | Card expiry year. Example: 49 | |
| MANUAL_PROMPT_OPTIONS | Optional | Character | 1 | 50 | Valid value: ZIP | This field is applicable when MANUAL_ENTRY = TRUE and the payment type is Credit. When this is present, SCA will prompt for customer zip code. The zip code that is entered will be returned in the CUSTOMER_ZIP field in the response. |
| TOKEN_TYPE | Optional | Character | LVT (Low Value Token) | Token type. A limited used token called Low Value Token (LVT) is introduced. This is a transactional token that has 24-hour duration for expiration. This LVT can be used the same manner as the current High Value Token/Omni-Token (HVT) is used. If this field is not sent, then HVT will be used by default. If TOKENIZE is set to ‘0’ and the POS sends a command request with TOKEN_TYPE=LVT then the terminal will request an LVT token. This field is applicable for Worldpay Direct only. Refer to Application Parameters table for more details on TOKENIZE parameter. | ||
| TKN_RENEW | Conditional | Character | 1 | Valid value: 1 | Application will send this field to the Gateway, requesting for Token renewal. As of this publication, this is applicable for UGP only. | |
| 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 | 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>TOKEN_QUERY</COMMAND>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<ENCRYPT>TRUE</ENCRYPT>
<COUNTER>1</COUNTER>
<MAC> … </MAC>
<MAC_LABEL>REG2</MAC_LABEL>
</TRANSACTION>
Response Packet
| Field | Type | Value | Description |
|---|---|---|---|
| RESPONSE_TEXT | Character | Processor response text. Example: SUCCESS or APPROVAL (Engage) | |
| RESULT | Character | This indicates the Result details. Example: OK or APPROVED (Engage) | |
| RESULT_CODE | Numeric | Expected result code: -1, 5 (Engage), 59006, 59001, 59007 and 59040 | 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. |
| TRANS_SEQ_NUM | Numeric | Processor/Batch trans sequence number. Example: 5 | |
| INTRN_SEQ_NUM | Numeric | PWC transaction ID. Example: 123456789 | |
| MERCHID | Numeric | Merchant ID. Example: 900000000123 | |
| TERMID | Numeric | Terminal ID. Example: 001 | |
| COUNTER | Numeric | Echoes counter sent in the request. Example: 100 | |
| TROUTD | Numeric | Transaction routing ID. Example: 157 | |
| CTROUTD | Numeric | Client-specific Transaction routing ID. Example: 28 | |
| CARD_TOKEN | Character | Proxy set of numbers representing a unique card. Example: 7987654321098765 | |
| ACCT_NUM | Numeric | Returned the masked account number. Example: 600649******9147 | |
| CARDHOLDER | Character | This field will return the Cardholder name. Example: JOHN DOE | |
| CARD_EXP_MONTH | Numeric | This field will return the Card expiration month. Example: 06 | |
| CARD_EXP_YEAR | Numeric | Card expiration year. Example: 17 | |
| CUSTOMER_ZIP | Numeric | Returns when zip code is captured with MANUAL_PROMPT_OPTIONS in request. Example: 02134 | |
| TOKEN_TYPE | Character | Returns low value token type, if sent as the query request field. This field is applicable for Worldpay Direct only. | |
| TKN_EXPDATE | Token expiration date. May be sent on Payment Transaction or Token Query transaction to override default expiration date assigned to the Token. Example: 07022021 | ||
| TKN_MATCHING | Matching Token. This is a non-reversible token used for matching purposes. For example, loyalty tracking. Example: 3278483765646148999 | ||
| TKN_USED |
|
Whether the Token is used. | |
| BANK_USERDATA | Character | Bank User Data, normally returned with CARD_TOKEN. Maximum 50 alphanumeric. Example: /CustData`JANE`K`DOE`````00` | |
| CARD_ENTRY_MODE | Character | Returns card entry mode values. Example: Swiped | |
| TRAN_LANG_CODE | Character | en – English fr – French es – Spanish |
This field contains the language code for the current transaction which is finalized based on the configured language on terminal and language preference from the card. This field will be returned only whenever the Card data is captured from cardholder during transaction flow. If Language code is not available from card, then terminal language will be returned. This field needs to be added for the below transaction flows. |
| 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. |
| AVAILABLE_BALANCE | Floating point number | Ex: 1.00 | Available balance on the card used for transaction. This field will be returned to POS, when the Host returns the Available Balance data. SCA application sends <BALANCE_ENQ> as Host request field and based on the processor, it returns the Available Balance, and SCA will send it back to POS. |
| 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. | |
| POS_RECON | Character | POS reconciliation field echoed back if sent in request. Example: RetailPOS1 |
Example
Following is an example of response packet
<RESPONSE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<COUNTER>1</COUNTER>
<RESULT_CODE>-1</RESULT_CODE>
<RESULT>OK</RESULT>
<RESPONSE_TEXT>SUCCESS</RESPONSE_TEXT>
<CTROUTD>28</CTROUTD>
<TROUTD>157</TROUTD>
<CARD_TOKEN>7987654321098765</CARD_TOKEN>
<ACCT_NUM>454545******4545</ACCT_NUM>
<CARDHOLDER>JOHN DOE</CARDHOLDER>
<CARD_EXP_MONTH>04</CARD_EXP_MONTH>
<CARD_EXP_YEAR>17</CARD_EXP_YEAR>
<TRAN_LANG_CODE>en</TRAN_LANG_CODE>
</RESPONSE>
Rate this article:
