SCA Functional Specification

LOYALTY

Last updated: 07-Apr-2025
Download as PDF

This command directs the device to capture loyalty information from a customer.

Device UI Required: No

Request Packet
Field Rule Type Minimum Maximum Value(s) Description
FUNCTION_TYPE Required Static value N/A N/A DEVICE Type of function
COMMAND Required Static value N/A N/A LOYALTY Command name
TYPE Optional List N/A N/A NUMBER – Will initiate prompting for Enter Loyalty Number (5 - 20 digits) instead of telephone number. Loyalty type to be entered.
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 sed 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>DEVICE</FUNCTION_TYPE>
    <COMMAND>LOYALTY</COMMAND>
    <COUNTER>1</COUNTER>
    <MAC> … </MAC>
    <MAC_LABEL>REG2</MAC_LABEL>
    </TRANSACTION>
Response Packet
Field Type Value Description
RESPONSE_TEXT Character   Processor response text. Example: Loyalty Details Captured
RESULT Character   This indicates the Result details. Example: OK
RESULT_CODE Numeric Expected result code: -1, 59001, 59006, 59040 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.
LOYALTY_DATA Character   Returns the loyalty data as Phone Number or swiped consumer input or loyalty number. Swiped non-PCI BIN cards return unencrypted account number. Swiped PCI cards return masked account number. Example: 8585552580
FULL_VAS_RESPONSE Character   This field will return when Apple phone is tapped. Example: <FULL_VAS_RESPONSE>{"Source":"ApplePay "," ….. Status_Word":"6a83"}]}</FULL_VAS_RESPONSE>
POS_RECON Character   POS reconciliation field echoed back if sent in request. Example: RetailPOS1
COUNTER Numeric   Echoes counter sent in the request. Example: 100

Fields returned for Token details

Field Type Value Description
CARD_TOKEN Character   Proxy set of numbers representing a unique card. Example: 7987654321098765
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
TROUTD Numeric   Transaction routing ID. Example: 157
CTROUTD Numeric   Client-specific Transaction routing ID. Example: 28
ACCT_NUM Numeric   Masked account number. Example: 454545******4545
CARDHOLDER Character   Cardholder name. Example: JOHN DOE
CARD_EXP_MONTH Numeric   Card expiration month. Example: 06
CUSTOMER_ZIP Numeric   Returns when zip code is captured with MANUAL_PROMPT_OPTIONS in request. Example: 02134
BANK_USERDATA Character   Bank User Data, normally returned with CARD_TOKEN. Max 50 alphanumeric. Example: /CustData`JANE`K`DOE`````00`
CARD_ENTRY_MODE Character   Returns card entry mode values. Refer to Card Entry Mode for more details on possible 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.

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

Example Response (PCI Cards)

<RESULT_CODE>-1</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    <LOYALTY_DATA>2223603580350203</LOYALTY_DATA>
    <COMMAND>LOYALTY</COMMAND>
    <ACCT_NUM>222360******0203</ACCT_NUM>
    <BATCH_TRACE_ID>8d6266b7-5604-4d81-b5df-a230e9289330</BATCH_TRACE_ID>
    <BANK_USERDATA>MASTERCARD</BANK_USERDATA>
    <CARD_ENTRY_MODE>Contactless</CARD_ENTRY_MODE>
    <CARD_EXP_MONTH>12</CARD_EXP_MONTH>
    <CARD_EXP_YEAR>25</CARD_EXP_YEAR>
    <CARD_TOKEN>2223603580350203</CARD_TOKEN>
    <MERCHID>700000013301</MERCHID>
    <TERMID>104</TERMID>
    <PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
    <PAYMENT_MEDIA>MASTERCARD</PAYMENT_MEDIA>
    <CTROUTD>308816163451</CTROUTD>
    <TRANS_DATE>2023.03.29</TRANS_DATE>
    <TRAN_LANG_CODE>en</TRAN_LANG_CODE>
    <TRANS_TIME>16.34.51</TRANS_TIME>
    <TOKEN_SOURCE>CHASE</TOKEN_SOURCE>
    <TRAINING_MODE>OFF</TRAINING_MODE>
    <TRANS_AMOUNT>0.00</TRANS_AMOUNT>
    <COUNTER>33</COUNTER>
    </RESPONSE>

Example Response (Non PCI Range - Gift card)

<RESPONSE>
    <RESPONSE_TEXT>Loyalty Details Captured</RESPONSE_TEXT>
    <RESULT>OK</RESULT>
    <RESULT_CODE>-1</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    <LOYALTY_DATA>6010567191858854</LOYALTY_DATA>
    <COMMAND>LOYALTY</COMMAND>
    <CARD_EXP_MONTH>12</CARD_EXP_MONTH>
    <CARD_EXP_YEAR>25</CARD_EXP_YEAR>
    <CARDHOLDER>FIRSTDATA/TEST</CARDHOLDER>
    <TRAN_LANG_CODE>en</TRAN_LANG_CODE>
    <COUNTER>8</COUNTER>
    </RESPONSE>
Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Get in touch

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Contact sales Get Started
Verifone logo