The Store and Forward feature allows the client to run a transaction without sending it to the processor right away.
From the cardholder's perspective, the transaction is performed as usual, but triPOS stores the transaction in a local
database until it can be forwarded to the processor. triPOS provides automatic Store and Forward functionality and the ability to store and forward requests on a per-request basis,
which is configurable in the triPOS.config file. When the store functionality is set to perRequest, the client must include the
?action=store query parameter with the transaction for it to be stored.
When the store functionality is set to automatic, triPOS will automatically store transactions when it detects a loss of network connectivity.
Before continuing to read about automatic Store and Forward below, please read the Manual Store and Forward
documentation for Store and Forward basics.
For automatic Store and Forward, triPOS provides configuration values in the triPOS.config for setting the storeMode and forwardMode to either
perRequest or automatic separately. When
the storeMode is set to automatic, triPOS will automatically try to store qualified transactions when it detects a loss of network connectivity.
The only transactions that are qualified to be stored are Sale, Authorization and Refund, and each transaction must meet a set of 'storable' criteria.
For all other transactions, triPOS will behave just as it does now when network connectivity is lost, by attempting to perform a system reversal and returning a communication error in the response.
If the transaction is stored successfully without error, triPOS returns a response indicating that the transaction was accepted. It is very important to keep in mind that,
at this point, the transaction has only been "approved" locally. This means that triPOS accepted the transaction successfully but has NOT sent it to the processor for
approval. To clearly indicate that the transaction has not been processed online, triPOS returns an HTTP status code of 202 Accepted instead of the normal HTTP
status code of 200 OK. Additionally, triPOS returns a statusCode of ApprovedByMerchant instead of the normal statusCode
of Approved. With the addition of the automatic store feature, triPOS now returns a new response value isOffline that will be set to true if
triPOS is offline. Since the transaction has not been sent to the processor, some response fields will be empty if their values
come from the processor response. If the transaction is stored successfully, it can be identified by the request ID that
is returned in the header field tp-request-id of the store response.
The Store and Forward feature only supports credit transactions, and cannot support EMV transactions that require an online PIN. triPOS also cannot support cashback
while storing a transaction. In the case of manual Store and Forward, triPOS does not provide the options that are not supported, and will reject
the transaction if online PIN is required before even attempting to store it. However, in the case of automatic Store and Forward, it is possible that triPOS can lose network connectivity
in the middle of a transaction. If that transaction does not meet the 'storable' criteria (i.e. it includes cashback), triPOS will be forced to reject it instead of storing it when the loss
of connectivity is detected.
One of the biggest differences between the manual and automatic store functionality is that triPOS provides configurable limits around which transactions can be automatically stored.
Since storing a transaction means there is a chance the transaction will not be approved when forwarded, triPOS provides two kinds of limits in the triPOS.config to help reduce the
liability to a level that the client is comfortable with. The first configuration value is the transactionAmountLimit, which is configurable
per lane and allows the client to specify the greatest individual transaction amount that can be stored. The second is the unprocessedTotalAmountLimit, which is
configurable per triPOS instance and allows the client to specify the greatest total dollar amount that can be stored before triPOS begins rejecting offline transactions.
When triPOS is offline and the storeMode is set to automatic, if any transaction exceeds the transactionAmountLimit,
or would cause the total dollar amount stored to exceed the unprocessedTotalAmountLimit, triPOS will reject the transaction.
NOTE: The limits only apply to
storing transactions automatically. Even if the storeMode is set to automatic, the limits will not apply to a manually stored transaction.
When forwardMode is set to automatic, triPOS will begin to individually forward each stored transaction to the processor when triPOS detects that the network connectivity is back.
Since this process is done in the background, the client will not receive a response for each forwarded transaction. See the "Querying the Database" paragraph below for more
information on obtaining processed responses. When triPOS begins forwarding each request, it will set the state of the transaction to Processing.
If the request is successfully processed online, triPOS will set the state of the transaction to Processed. If an error occurs, triPOS will set the the state back to
Stored so it can be processed again at a later time. For each forwarded request, triPOS updates the database with information from the processor response.
If the stored transaction is never successfully forwarded to the processor, the transaction will not be processed and it will not make it into the merchant's batch.
When transactions are automatically forwarded, the stored response will contain HATEOAS links that do not have the server and port portion. This is because the automatic forwarding
occurs in the background and is not linked to a request sent in by the client.
When using the Store and Forward feature, errors can occur. It is important to understand how triPOS will behave in each error case to fully understand the scope of the
liability taken on by the client.
If triPOS attempts to forward a request, either manually or automatically, and cannot communicate with Express or Express cannot communicate with the processor, then triPOS sets the
state of the transaction back to Stored and considers itself offline. The forward can be retried when network connectivity is re-established.
If the data stored in the database becomes corrupt, preventing triPOS from constructing a valid Express message, triPOS will set the state of the transaction to Error.
At this point, triPOS will not be able to forward this transaction to the host. Depending on how the data is corrupted, the client may not even be able to execute a successful query
to obtain information about the transaction.
Lastly, if triPOS receives a successful response from Express, even in cases such as Decline or Duplicate, triPOS will consider the request successfully processed and
will set the state of the transaction to Processed.
When performing a manual forward, triPOS returns the response from the processor to the client as if it were performing a normal online request.
When triPOS performs the forwarding automatically in the background, the client does not receive a response from the processor. In order to allow the client to obtain
important information about each processed request, triPOS now supports a
GET /api/v1/storedTransactions endpoint. This endpoint returns all of the information about each stored transaction regardless of its state.
This endpoint allows the client to maintain an updated list of all stored transactions, the state of each transaction, and the information from the processor after
it has been forwarded.
The database mentioned above is a SQLite database that exists on the same machine as triPOS. The database does not need to be installed separately
because triPOS creates the database upon startup. In this phase of the Store and Forward feature, triPOS provides a way to delete records from the database
via the DELETE /api/v1/storedtransactions/{requestIDToDelete} method regardless of its state.
Once the transaction is forwarded to the processor, it is still possible for the processor to decline it. Storing the transaction with triPOS does not guarantee the transaction will be approved.
Store and Forward only supports credit capable cards, and does not allow EMV transactions that require an online PIN. If a refund transaction requires online PIN, it will be accepted and stored, but the cardholder will not be prompted for a PIN. If a credit EMV transaction allows cashback, cashback will not be supported when storing. Make sure that the tp-request-id provided in the header is unique, otherwise the attempt to store the transaction will fail.