SCA Functional Specification

BALANCE INQUIRY

Last updated: 06-Jan-2025
Download as PDF

This command checks the balance on a Gift card.

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 REACTIVATE Command name
PAYMENT_TYPE Optional List N/A N/A GIFT
MERCH_CREDIT		 Payment type field for Gift or Merchandise Credit. NOTE: PAYMENT_TYPE field is mandatory for card token based transactions.
PAYMENT_TYPES Optional Character 3     Pipe-delimited list of valid tender types (for capture/refund transactions) specified by POS. Only listed payment types will appear on consumer payment selection screen. NOTE: All included tender types must be configuration enabled. Example: CREDIT|DEBIT|GIFT|FSA
TRANS_AMOUNT Required Floating point number (decimal) 1(2) 6(2)   This indicate the transaction amount. This amount must be a non-zero amount. Example: 10.00
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.
MANUAL_PROMPT_OPTIONS Optional Character 1 50 NOEXP This field is applicable when MANUAL_ENTRY field is set to TRUE. The value is NOEXP, hence when this field is present, SCA will not prompt for expiration.
ENCRYPT Conditional Boolean 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 value will be TRUE as default 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.
COL_3, COL_4, COL_5, COL_6, COL_7, COL_8, COL_9, COL_10 Optional Character 1 225   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
BANK_USERDATA Conditional Character 1 50   Returned with CARD_TOKEN. Whatever comes back with BANK_USERDATA in the response for the token should also be sent in the request. Example: 01/00/02/Visa/
CDD_DATA Optional Character 1 30   Customer Defined Data. It is a pass through field and it is passed in the host request if this field is present in the POS request and also returned in POS response. Example: <CDD_DATA>INV200471</CDD_DATA>
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.
CAPTURECARD_EARLYRETURN Optional Boolean N/A N/A TRUE
FALSE		 If the sending value is TRUE, then the application returns card data to POS before processing. PCI BIN checking in place to return full PAN or masked PAN BIN range level. NOTE: SCA will cache data from the swipe, however, will only use in immediately subsequent CAPTURE request containing explicit tender type – else, it will discard.
EMV_TAGS_REQD Character Binary     Valid values: Y/N EMV tags detail required. This field is sent in request to return the EMV tags in the response, only in case of CAPTURECARD_EARLYRETURN is sent as TRUE.
SERVER_ID Optional Numeric 1 10   This indicates the Server ID, performing the transaction. Example: 560
SHIFT_ID Optional Character 1 1   This indicates the Shifts at the store. Example: 2
CASHIER_ID Optional Character 1 10   This indicates the Cashier ID performing the transaction ID. Example: 7987654321098765
TRAINING_MODE Optional List 1 3 OFF
ON		 This field is included to turn on Training Mode for the session. Transactions are routed to HIF Test for host simulation and results are mocked for approvals. NOTE: 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.
CARD_PRESENT Optional Binary    
  • TRUE - Card present (Default)
  • FALSE - Card not present
 Card Present Indicator
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
Keyed Account Information
Field Rule Type Minimum Maximum Value(s) Description
ACCT_NUM Optional Numeric 1 25 PAYMENT This field is used to enter the account number manually. For this MANUAL_ENTRY must be set to TRUE. Pre-swipe data will not be honored. Example: 67823456781313
CARD_EXP_MONTH Required Numeric 2 2   Card expiry month. NOTE: If the encryption is set to TRUE, then SCI will use 12 as default value if this field is not passed. Example: 12
CARD_EXP_YEAR Required Numeric 2 2   Card expiry year. NOTE: If encryption is set to TRUE, SCI will use 49 as default value if this field is not passed. Example: 49
BARCODE Optional Character 1 100   Barcode scanning option.
PIN_CODE Required Numeric 1 12   Gift PIN code. Example: 5.00
CVV2 Optional Numeric 1 10   Card Verification Value 2.
Example

Following is an example of request packet

<TRANSACTION>
    <FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
    <COMMAND>BALANCE</COMMAND>
    <COUNTER>1</COUNTER>
    <MAC> … </MAC>
    <MAC_LABEL>REG2</MAC_LABEL>
    <PAYMENT_TYPE>GIFT</PAYMENT_TYPE>
    <MANUAL_ENTRY>TRUE</MANUAL_ENTRY>
    <ENCRYPT>TRUE</ENCRYPT>
    </TRANSACTION>

Following is an example of request packet - First leg(Capture Card Early Return)

<TRANSACTION>
    <FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
    <COMMAND>BALANCE</COMMAND>
    <CAPTURECARD_EARLYRETURN>TRUE</CAPTURECARD_EARLYRETURN>
    <MANUAL_ENTRY>FALSE</MANUAL_ENTRY>
    <PAYMENT_TYPE>GIFT</PAYMENT_TYPE>
    <FORCE_FLAG>FALSE</FORCE_FLAG>
    <MAC_LABEL>P_EJIOKG</MAC_LABEL>
    <COUNTER>19</COUNTER>
    <MAC>Mv/UaPYHXPbcF0cHsq37CP4S0VOXqXq1ubE/TJ4myCI=</MAC>
    </TRANSACTION>

Following is an example of request packet - Second leg(Capture Card Early Return)

<TRANSACTION>
<FUNCTION_TYPE>PAYMENT</FUNCTION_TYPE>
<COMMAND>BALANCE</COMMAND>
<MANUAL_ENTRY>FALSE</MANUAL_ENTRY>
<PAYMENT_TYPE>GIFT</PAYMENT_TYPE>
<FORCE_FLAG>FALSE</FORCE_FLAG>
<MAC_LABEL>P_EJIOKG</MAC_LABEL>
<COUNTER>20</COUNTER>
<MAC>0ZUWt0Q3V0RMgGrPPZChuirs16jEyrqLCIVdufvekEA=</MAC>
</TRANSACTION>
Response Packet
Field Type Value Description
RESPONSE_TEXT Character   Processor response text. Example: COMPLETED.
RESULT Character   This indicates the Result details. Commonly COMPLETED or APPROVED or DECLINED.
RESULT_CODE Numeric Expected result code: 4, 10 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
COMMAND Character   Echoes the command name, sent in the request.
AUTHNWID Character   This field will be returned if present in the SSI response from host. Example: 03
AUTHNWNAME Character   This field will be returned if present in the SSI response from host. Example: Amex
EMBOSSED_ACCT_NUM Numeric   Card number conditionally returned if present in the SSI response. Returned if payment type = GIFT and returnembossednumforgift is enabled. Example: 6499991111115789
HOST_RESPCODE Numeric   This field will be sent if present in the host response. Example: 000
RESPONSE_CODE Character A and E Response code data will be returned to POS, same as received from the Host if this is present in Host response. Example: <RESPONSE_CODE>E</RESPONSE_CODE>
POS_RECON Character   POS reconciliation field echoed back if sent in request. Example: RetailPOS1
CARD_ABBRV Character   Card abbreviation as present in SSI response. If not in SSI response, MSR: Value from CDT or EMV: Value from AIDList.xml. Example: MC
TRANS_SEQ_NUM Numeric   Processor/Batch transaction sequence number. Example: 5
INTRN_SEQ_NUM Numeric   PWC transaction ID. Example: 123456789
MERCHID Numeric   Merchant ID. Example: 900000000123
TERMID Numeric   Merchant ID. Example: 001
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. NOTE: For Private Label transaction (ADS), PT_CTROUTD field will be mapped to CTROUTD field back to SCA. Example: 45
LPTOKEN Numeric   LP Token is a non-sensitive unique number assigned to each unique card number processed with the UGP gateway. This value will automatically increment by one for each unique card number. This is a conditional field. NOTE: Refer to Responses from Point section in Message Format. Example: 12457
AUTH_CODE Character   Processor authorization number. Example: 123456
PAYMENT_MEDIA Character   Mode of payment. Commonly VISA/MC/DISC/AMEX/DEBIT. Example: : GIFT/MERCHANDISE
PAYMENT_TYPE Character   Payment type returned, like Gift. Example: GIFT/MERCH_CREDIT
ACCT_NUM Numeric   Returned the masked account number. NOTE: If UNMASKEDPANFORNONPCI=1 then the account number will be sent back to POS as unmasked for non PCI cards. Refer to GSC Parameters for more details on the parameter. Example: 600649******9147
CARDHOLDER Character   Returned for swiped transactions. Example: TEST PROCESSOR
CARD_EXP_MONTH Numeric   Card expiry month. Example: 12
CARD_EXP_YEAR Numeric   Card expiry year. Example: 20
CARD_ENTRY_MODE Character   Returns card entry mode values. NOTE: Refer to Card Entry Mode for details on possible values. Example: 123123
EMV_TAGS Character   This is returned for Early Card Capture payment flows for Non PCI BIN ranges, only when EMV_TAGS_REQD is sent as Y.
CARD_CLASS Numeric   This field is returned to identify the card type of the gift transaction. Example: 0
PIN_CODE Numeric   Gift PIN code. This is a conditional field. This field will return in POS response if GIFTPINTOPOS parameter is enabled. Refer to Application Parameters for more details on this parameter.
APPROVED_AMOUNT Floating point number   The amount which got approved. Example: 5.00.
AVAILABLE_BALANCE Floating point number   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. Example: 100.00
PREVIOUS_BALANCE Floating point number   Previous balance on card. Example: 200.00.
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
TRAINING_MODE Character ON
OFF		 This field is returned conditionally, when session is in Training Mode.
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.
TRANS_CURRENCY_CODE Numeric  
  • This is the currency code of the transaction. This field is sent from POS to identify if it is US or Canada transaction. Example:
    • For USA, POS response is: <TRANS_CURRENCY_CODE>0840</TRANS_CURRENCY_CODE>
    • For Canada, POS response: <TRANS_CURRENCY_CODE>0124</TRANS_CURRENCY_CODE>
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 Charactert   Column 3 to Column 10 fields value will be echoed in POS response. These fields are not sent to any payment processor.
Processor-Based Token (Conditional)
  

Note

For use with host based processors supporting card based token implementations.

Field Type Value Description
CARD_TOKEN Character   Card Token field is returned in most of the GIFT administrative transactions. NOTE: Refer to Card Tokens section in Point Integration Best Practices. Example: 7987654321098765
TOKEN_SOURCE Character   Source of the token. Example: PWC
Example

Following is an example of response packet

<RESPONSE>
    <APPROVD_AMOUNT>5.00</APPROVED_AMOUNT>
    <AUTH_CODE>123654</AUTH_CODE>
    <AVAILABLE_BALANCE>10.00</AVAILABLE_BALANCE>
    <ACCT_NUM>600649******9147</ACCT_NUM>
    <CARDHOLDER>PROCESSOR GIFT</CARDHOLDER>
    <CTROUTD>141</CTROUTD>
    <INTRN_SEQ_NUM>569230</INTRN_SEQ_NUM>
    <PAYMENT_MEDIA>GIFT</PAYMENT_MEDIA>
    <PAYMENT_TYPE>GIFT</PAYMENT_TYPE>
    <RESPONSE_TEXT>TRANSACTION APPROVED</RESPONSE_TEXT>
    <RESULT>APPROVED</RESULT>
    <RESULT_CODE>5</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    <TRANS_SEQ_NUM>19</TRANS_SEQ_NUM>
    <TROUTD>569230</TROUTD>
    <TRAN_LANG_CODE>en</TRAN_LANG_CODE>
    </RESPONSE>

Following is an example of response packet - First leg(Capture Card Early Return)

<RESPONSE>
    <RESPONSE_TEXT>CAPTURE EARLY CARD NOTIFICATION</RESPONSE_TEXT>
    <RESULT>OK</RESULT>
    <RESULT_CODE>-1</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    <COUNTER>17</COUNTER>
    <CARD_TRACK1>B60105****************************************************************  ?.</CARD_TRACK1>
    <CARD_TRACK2>601056***************************4680</CARD_TRACK2>
    <ACCT_NUM>601056******6057</ACCT_NUM>
    <TRANS_AMOUNT>10.00</TRANS_AMOUNT>
    <CARD_EXP_MONTH>**</CARD_EXP_MONTH>
    <CARD_EXP_YEAR>**</CARD_EXP_YEAR>
    <CARDHOLDER>RAPI******************</CARDHOLDER>
    <PAYMENT_TYPE>GIFT</PAYMENT_TYPE>
    <PAYMENT_MEDIA>GIFT</PAYMENT_MEDIA>
    <CARD_ENTRY_MODE>Swiped</CARD_ENTRY_MODE>
    <INVOICE>123456</INVOICE>
    </RESPONSE>

Following is an example of response packet - Second leg(Capture Card Early Return)

<RESPONSE>
    <ACCT_NUM>601056******6057</ACCT_NUM>
    <COMMAND>ADD_VALUE</COMMAND>
    <BANK_USERDATA>GIFT</BANK_USERDATA>
    <BATCH_TRACE_ID>84cea432-6cdd-42a2-91b1-7153864f8529</BATCH_TRACE_ID>
    <CARD_ABBRV>GF</CARD_ABBRV>
    <CARD_ENTRY_MODE>Swiped</CARD_ENTRY_MODE>
    <CARD_EXP_MONTH>**</CARD_EXP_MONTH>
    <CARD_EXP_YEAR>**</CARD_EXP_YEAR>
    <CARDHOLDER>RAPI******************</CARDHOLDER>
    <CTROUTD>75066</CTROUTD>
    <INVOICE>123456</INVOICE>
    <EMBOSSED_ACCT_NUM>286831******4680</EMBOSSED_ACCT_NUM>
    <INTRN_SEQ_NUM>4016100329</INTRN_SEQ_NUM>
    <PAYMENT_MEDIA>GIFT</PAYMENT_MEDIA>
    <PAYMENT_TYPE>GIFT</PAYMENT_TYPE>
    <RESPONSE_TEXT>04: Inactive account.</RESPONSE_TEXT>
    <RESULT>DECLINED</RESULT>
    <RESULT_CODE>6</RESULT_CODE>
    <TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
    <TRANS_AMOUNT>10.00</TRANS_AMOUNT>
    <TRANS_DATE>2022.07.12</TRANS_DATE>
    <TRAN_LANG_CODE>en</TRAN_LANG_CODE>
    <TRANS_SEQ_NUM>20928</TRANS_SEQ_NUM>
    <TRANS_TIME>02:41:05</TRANS_TIME>
    <TROUTD>4016100329</TROUTD>
    <COUNTER>18</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