SAF QUERY
Last updated: 23-Jan-2025
This command queries SAF transactions in the database.
Device UI Required: No
Request Packet
| Field | Rule | Type | Minimum | Maximum | Value(s) | Description |
|---|---|---|---|---|---|---|
| FUNCTION_TYPE | Required | Static value | SAF | Type of function | ||
| COMMAND | Required | Static value | QUERY | Command name | ||
| SAF_STATUS | Optional | List |
|
If specified, SAF transactions returned will be filtered by this status. NOTE: PREAUTH is specific to UGP. | ||
| SAF_NUM_BEGIN | Optional | Numeric | 1 | 4 | Ex: 1235 | If the beginning number is not specified, then the application enquires all SAF transactions. Example: 1235 |
| SAF_NUM_END | Optional | Numeric | 1 | 4 | If the ending number is not specified, then it will be defaults to SAF_NUM_BEGIN. Example: 1236 | |
| 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. Used to authenticate the POS. Example: 100 | |
| MAC | Required | Base64 Encoded Data | Message Authentication Code. 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. Used to authenticate the POS. Example: REG1 |
Example
Following is an example of request packet
<TRANSACTION>
<FUNCTION_TYPE>SAF</FUNCTION_TYPE>
<COMMAND>QUERY</COMMAND>
<COUNTER>1</COUNTER>
<MAC> … </MAC>
<MAC_LABEL>REG2</MAC_LABEL>
<SAF_STATUS>ELIGIBLE</SAF_STATUS>
</TRANSACTION>
Response Packet
| Field | Type | Value(s) | Description |
|---|---|---|---|
| RESPONSE_TEXT | Character | Ex: n SAF RECORDS FOUND | Processor response text. n = Number of records |
| RESULT | Character | Ex: OK | This indicates the Result details. |
| RESULT_CODE | Numeric | Expected result code: -1, 59046, 59047, 59048, 59040 | This indicates the result code. |
| TERMINATION_STATUS | Character | Valid values: 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. |
| MERCHID | Numeric | Ex: 900000000123 | Merchant ID. This is a conditional field. |
| TERMID | Numeric | Ex: 001 | Terminal ID. This is a conditional field. |
| COUNTER | Numeric | Ex: 100 | Echoes COUNTER sent in the request. |
| RECORD_COUNT | Numeric | Ex: 55 | Number of SAF transactions. |
| TOTAL_AMOUNT | Floating point number | Ex: 5592.00 | Total amount of all SAF transactions. |
| RECORDS | See RECORD section for child elements |
RECORD Child Elements
| Field | Type | Value(s) | Description |
|---|---|---|---|
| ACCT_NUM | Number | Ex: 400555******0019 | Returns the masked account number. This is a conditional field. |
| TRANS_AMOUNT | Floating point number | Ex: 5.00 | Returns the transaction amount. This is a conditional field. |
| INVOICE | Character | Ex: 123456 | Merchant invoice number. This is a conditional field. |
| PAYMENT_TYPE | Character | Ex: CREDIT | Returns the type of payment used. This is a conditional field. |
| PAYMENT_MEDIA | Character | Ex: VISA | Mode of payment. This is a conditional field. |
| SAF_NUM | Numeric | Ex: 0045 | SAF number. This is a conditional field. |
| SAF_STATUS | Character | Valid values: ELIGIBLE, PROCESSED, IN_PROCESS, NOT_PROCESSED, DECLINED | SAF transaction status. This is a conditional field. |
| CTROUTD | Numeric | Ex: 45 | Returns Client-specific Transaction routing ID. This is a conditional field. |
| TROUTD | Numeric | Ex: 435674 | This is a conditional field. |
| CARD_TOKEN | Character | Ex: 7987654321098765 | Authorization code. This is a conditional field. |
| TOKEN_SOURCE | Character | Ex: PWC | Card Token. This is a conditional field. |
| AUTH_CODE | Character | Ex: TA01561 | Source of token. This is a conditional field. |
| BANK_USERDATA | Character | Ex: /CustData`JANE`K`DOE`````00` | Bank User Data, normally returned with CARD_TOKEN. Maximum 50 alphanumeric characters. This is a conditional field. |
| CVV2_CODE | Character | Ex: M | Result of CVV2 check. This is a conditional field. This is applicable to direct-to-processor (DHI) implementations only. |
| BUSINESSDATE | Numeric | Ex: 20161102 | This indicates the business date. The format would be YYYYMMDD. This is a conditional field, if sent in START SESSION. |
| MERCHID | Merchant ID. This is a conditional field. This is applicable to (DHI) implementations only. | ||
| TERMID | Term ID. This is a conditional field. This is applicable to (DHI) implementations only. | ||
| LANE | This field is used to identify the retail lane. This is a conditional field. This is not applicable to Point Classic. | ||
| COMMAND | List | Valid value: SALE | Returns the command name. |
| STORE_NUM | Store number. This is a conditional field. This is not applicable to Point Classic. | ||
| APPROVED_AMOUNT | Floating point number | The amount which is approved. This is a conditional field. |
EMV (Engage devices)
| Field | Type | Value(s) | Description |
|---|---|---|---|
| EMV_MODE | EMV mode. This is a conditional field. | ||
| EMV_CVM | EMV CVM. This is a conditional field. | ||
| EMV_CHIP_INDICATOR | Ex: CONTACT | EMV chip indicator to identify, contact or contactless. This is a conditional field. | |
| EMV_MODE | EMV mode. This is a conditional field. |
Dynamic Currency Conversion Response Fields (Conditional)
Note
If ALLOWDDCTOSAF parameter is set to 1.
| Field | Type | Value(s) | Description |
|---|---|---|---|
| DCC_IND | Numeric |
|
DCC Indicator. |
| DCC_EXCHANGE_RATE | Floating point number | Ex: 1.7461 | Exchange rate for converting local currency to foreign currency. |
| DCC_ALPHA_CURR_CODE | Character | Ex: SGD | Currency code of the foreign transaction. |
| DCC_DATETIME | Date | Indicates the date and time, when the DCC conversion took place. | |
| DCC_TIMEZONE | Character | Time zone for the DCC_DATETIME, that will be provided in the device by the application or Merchants. | |
| DCC_TRAN_AMOUNT | Floating point number | Ex: 24.45 | Converted amount |
Example 1
Following is an example when there are SAF records to be removed
<RESPONSE>
<RESPONSE_TEXT>2 SAF RECORDS FOUND<RESPONSE_TEXT>
<RESULT>OK</RESULT>
<RESULT_CODE>-1</RESULT_CODE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<COUNTER>1</COUNTER>
<RECORD_COUNT>2</RECORD_COUNT>
<TOTAL_AMOUNT>10.40</TOTAL_AMOUNT>
<RECORDS>
<RECORD>
<ACCT_NUM>523456******1594</ACCT_NUM>
<TRANS_AMOUNT>5.20</TRANS_AMOUNT>
<INVOICE>123456</INVOICE>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<PAYMENT_MEDIA>MASTERCARD</PAYMENT_MEDIA>
<SAF_NUM>1235</SAF_NUM>
<SAF_STATUS>ELIGIBLE</SAF_STATUS>
<CTROUTD>759</CTROUTD>
<AUTH_CODE>17760K</AUTH_CODE>
<CARD_TOKEN>8834134431340010|0AB5DD</CARD_TOKEN>
<CVV2_CODE>M</CVV2_CODE>
<BANK_USERDATA>/CustData`JANE`K`DOE`````00`</BANK_USERDATA>
</RECORD>
<RECORD>
<ACCT_NUM>4005555******0019</ACCT_NUM>
<TRANS_AMOUNT>5.20</TRANS_AMOUNT>
<INVOICE>123456</INVOICE>
<PAYMENT_TYPE>CREDIT</PAYMENT_TYPE>
<PAYMENT_MEDIA>VISA</PAYMENT_MEDIA>
<SAF_NUM>1236</SAF_NUM>
<SAF_STATUS>ELIGIBLE</SAF_STATUS>
<CTROUTD>760</CTROUTD>
<AUTH_CODE>17760K</AUTH_CODE>
<CARD_TOKEN>8834134431340010|0AB5DD</CARD_TOKEN>
<CVV2_CODE>M</CVV2_CODE>
<BANK_USERDATA>/CustData`JANE`K`DOE`````00`</BANK_USERDATA>
</RECORD>
</RECORDS>
</RESPONSE>
Example 2
Following is an example when there are SAF records are not present
<RESPONSE>
<RESPONSE_TEXT>0 SAF RECORDS FOUND<RESPONSE_TEXT>
<RESULT>OK</RESULT>
<RESULT_CODE>-1</RESULT_CODE>
<TERMINATION_STATUS>SUCCESS</TERMINATION_STATUS>
<COUNTER>1</COUNTER>
<RECORD_COUNT>0</RECORD_COUNT>
<TOTAL_AMOUNT>0.00</TOTAL_AMOUNT>
<RESPONSE>
Rate this article:
