SCA Functional Specification

Reasons for SAF

SCA can be configured to perform SAF for various reasons

• Network Issues

  • LAN (Local Area Network)

    • Loose or damaged LAN cable
    • WiFi or LAN configuration issue (DNS, etc.)

  • WAN (Wide Area Network)

    • ISP (Internet Service Provider) issue
    • General internet issue

  • Gateway

    • Gateway down

  • Host

    • Host down

• Other reasons for SAF

  • A command from POS to trigger a SAF mode transaction
  • Gateway response (configured) to perform SAF
  • Certificate issues (cannot authenticate to gateway/host)
  • Host reachable but error responses indicate host internal/backend issues

Supported Transactions - SAF

Supported Card Types

Following are the card types supported

• Credit
• Gift
• Private Label

SAF Flow

Rules

• When the SAF configuration parameter is enabled and there is loss of connectivity to the server, the payment acceptance device can locally approve transactions below a set floor limit.
• SAF approvals are processed untill certain duration or till MAX limit is reached.
• The stored transactions are written to a queue within the payment device
• Transactions from the SAF queue are sent to the gateway periodically when the application can connect
• When the transaction amount is greater than or equal to the floor limit, then an approval code would be required by the bank to proceed with the transaction. Once approval code is acquired, the POS would send another CAPTURE command including the approval code acquired. This transaction gets added to the SAF queue.
• If an invalid AUTH number is sent in the request when the device is in SAF mode, then the transactions will not be posted to PWC as PWC will reject an invalid AUTH number and return the error code. As the device is in SAF mode, transactions with invalid AUTH number will not respond back to the POS outside of the SAF offline approval.

Configuration Parameters

Following are the configuration parameters which affect the operation

• ALLOWGIFTACTIVATETOSAF
• ALLOWREFUNDTOSAF
• ALLOWVOIDTOSAF

Messages Commands

Refer to the below Protocol sections for the command fields description and examples.

• SAF Query
• SAF Edit
• SAF Remove

SAF Result Codes

<RESPONSE>
<RESPONSE_TEXT>Offline Transaction Amount Exceeded, Please Call for Voice Approval</RESPONSE_TEXT>
<RESULT_CODE>59024</RESULT_CODE>

<RESPONSE>
<RESPONSE_TEXT>Offline Transaction Amount Exceeded, Please Call for Voice Approval</RESPONSE_TEXT>
<RESULT_CODE>59024</RESULT_CODE>

<RESPONSE>
<RESPONSE_TEXT>Offline Transaction Amount Exceeded, Please Call for Voice Approval</RESPONSE_TEXT>
<RESULT_CODE>59024</RESULT_CODE>

<RESPONSE>
<RESPONSE_TEXT>Offline Transaction Amount Exceeded, Please Call for Voice Approval</RESPONSE_TEXT>
<RESULT_CODE>59024</RESULT_CODE>

<RESPONSE>
<RESPONSE_TEXT>SAF NOT ALLOWED</RESPONSE_TEXT>
<RESULT_CODE>999998</RESULT_CODE>

<RESPONSE>
<RESPONSE_TEXT>SAF NOT ALLOWED MAX RECORDS REACHED</RESPONSE_TEXT>
<RESULT_CODE>999997</RESULT_CODE>

<RESPONSE>
<RESPONSE_TEXT>SAF NOT ALLOWED - SAF TOTAL LIMIT EXCEEDED</RESPONSE_TEXT>
<RESULT_CODE>999995</RESULT_CODE>

SAF Throttling

SAF Throttling feature is implemented and used to ensure that all the devices should not attempt to send all SAF transactions immediately upon renewal of connectivity to the host.

Devices will be in SAF mode when there is a connection outage with customer network. Once the connectivity is restored, all the devices will be online and start posting all the SAF transactions at the same time, and this could make the host overloaded.

Therefore, this feature is implemented in Engage devices, to ensure that the terminal will wait for a different duration of time before starting to post the transactions. The waiting time for each terminal will be calculated from the serial number of the terminal. So that all devices wait for a different amount of time, and then the host will not be loaded with huge number of connection request at the same time.

SAF throttling feature can be enabled by setting SAFTHROTTLINGENABLE parameter. This parameter is used to enable or disable SAF throttling feature (throttling mechanism) in SCA. The default value is 0.
SAFTHROTTLINGINTERVAL parameter is also added to calculate the actual throttling interval by finding the modulus of device serial number. The parameter value is used as denominator. The default value is 300.

Refer to Store and Forward Parameters parameter table for more details on SAFTHROTTLINGENABLE and SAFTHROTTLINGINTERVAL configuration parameters.
Actual SAF throttling interval (in seconds) = (Device Serial Number) % SAFTHROTTLINGINTERVAL.

Example -

Serial number of the device is 169-000-278 and SAFTHROTTLINGINTERVAL=300, then throttling interval would be 169000278%300 = 26.
This device will post the SAF record at 26th second, after it detects the host connectivity is renewed and the application will check the file every SAFPOSTINTERVAL after that.

Handling SAF Repeating Transactions

In SCA solution, specific host response codes cause transactions to be routed to Store and Forward (SAF). Under certain conditions, these SAF transactions can enter a persistent retry loop, repeatedly attempting processing without successful completion. This behaviour can block subsequent transactions, degrade system performance, and introduce potential compliance risks.

To address this issue, SCA application is enhanced to detect and manage looping SAF transactions by changing them to a DEFERRED status and placing them in a separate processing queue. The application ensures that the same transaction is not continuously retried during a single processing cycle. When repeated host response codes indicate that a transaction would be SAF’d again, the transaction is deferred, and the application proceeds with the next eligible transaction.

Deferred transactions due to repeated SAF response codes are retried once per day for a maximum period of 10 days. If a transaction is not approved within this retry window, it is marked as NOT_PROCESSED, indicating that the transaction will no longer be eligible for automatic retries.

Key Points:

• A transaction is considered to be in a looping state if it receives the same host response code five consecutive times, at which point the looping condition is terminated.
• Transactions identified as looping are transitioned to a DEFERRED status.
• Deferred transactions are retried once per day for up to 10 consecutive days.
• If a transaction is not approved within this retry period, its status is updated to NOT_PROCESSED.
• During SAF dequeue processing, the application skips deferred transactions that are in a looping state.
• The application continues processing the next eligible transaction in the queue, ensuring that retry handling does not impact normal transaction flow.

SAF Forced Mode and Dequeue Functionality

In the SCA solution, certain host response codes can trigger transactions to be stored using SAF (Store and Forward). Specifically, upon receiving a 30024 result code, SCA stores the transaction and enters Forced SAF mode for a configured period, defaulting to 15 minutes. During this period, all eligible transactions are automatically SAF’d.
To support SAF dequeue functionality, the HOSTFORCESAFSUPP parameter has been introduced. When enabled, the application includes the SAF_FORCE_SUPPORT field in SAF eligible payment requests to the host, indicating support for SAF dequeue requests.

Once the terminal is ready to dequeue SAF transactions, typically after the host connection is restored, it establishes communication with PWC to notify the number of pending transactions and initiate the dequeue process using the SAF_DEQUE_REQUEST field in the host request. The dequeue request specifies the total number of SAF transactions and the total transaction amount to be processed.
During this communication, PWC can provide configuration fields that override the terminal’s local defaults. These fields include:

• SAF_DEQUE_PAUSE - Defines the pause between SAF transactions. Default duration can be 10 seconds.
• SAF_QUE_START_SECONDS - Specifies the start delay before initiating SAF dequeue.
• SAF_RETRY_COUNT - Maximum retry attempts for deferred transactions. This value corresponds to the SAFDEFERREDTRANRETRIES parameter, with a default of 5 retries, after which a looping SAF transaction is moved to the deferred state.
• SAF_RETRY_MINUTES - Interval between retries when resending a failed SAF transaction.
• SAF_DEQUE_STATUS - Indicates the current status of SAF dequeue. A value of 0 allows dequeuing if scheduled through SAF_DEQUE_REQUEST or if the count is greater than or equals to 3.

These configuration fields ensure that SAF dequeue processing on the terminal follows host-defined rules while respecting local configuration defaults.