Transaction recovery

Introduction

Firstly, what is transaction recovery? When a POS makes a transaction request but the response is not returned, the POS will not know whether the transaction succeeded, failed, or is still being processed. Transaction recovery involves finding the transaction and returning the result to the POS, hence preventing missed transactions and other issues.

Spice makes transaction recovery possible — it stores the state of the current transaction and handles the recovery workflows. The recovered transaction responses are the same as what would have been returned normally.

There are four transaction recovery scenarios handled by Spice, and integrating these is simple.

Scenario 1. The POS quits unexpectedly

If the POS quits unexpectedly ('shuts down', 'times out', or 'crashes') during a transaction, Spice will continue processing the transaction and will allow its results to be recovered.

In this scenario, the POS requests a transaction but then quits unexpectedly before it receives the response. After the POS restarts, it must retrieve the transaction response from Spice.

Integrating

For your Spice integration to handle this scenario, it can use logic similar to the following.

• After making a transaction request ...
  1. Store the transaction’s posRefId and its status of 'in progress' in your POS.
• After receiving a transaction response ...
  1. Change the status of the transaction stored in your POS to ‘completed’.
• On startup ...
  1. If the stored transaction status is ‘in progress’ ...
     1. Get the transaction result from Spice, e.g. GET /v1/purchase
     2. Change the stored transaction status in your POS to ‘completed’.
  2. Else, do not retrieve a transaction from Spice.

Testing

To test this scenario, do the following.

1. Start a transaction, e.g. by calling POST /v1/purchase
2. Shut down the POS.
3. Restart the POS.

Scenario 2. Spice quits unexpectedly

If Spice quits unexpectedly during a transaction, once it restarts, it will recover the transaction from the EFTPOS terminal.

In this scenario, Spice conveys the transaction to the EFTPOS terminal but then quits unexpectedly before it receives the response. The POS must repeatedly call Spice to try to get a response until Spice recovers and the transaction response is finally returned.

Integrating

For your Spice integration to handle this scenario, it can use logic similar to the following.

1. If a transaction results in an ECONNRESET (‘connection closed’ or ‘socket hang up’) error ...
   1. This indicates that Spice has crashed before returning the response.
      You must call GET /v1/purchase on a loop until there is a successful response. (Don't use a timeout on this loop.)

Testing

To test this scenario, do the following.

1. Start a transaction, e.g. by calling POST /v1/purchase
2. Quit the Spice application.
3. Restart the Spice application.

Scenario 3. A network outage occurs

If a network outage ('internet disconnection') occurs during a transaction, once the network is restored, Spice will recover the transaction from the EFTPOS terminal.

In this scenario, Spice conveys the transaction to the EFTPOS terminal but then a network outage occurs preventing Spice from communicating with the terminal, and hence it does not receive a response. When the network is restored, Spice recovers the transaction from the terminal and returns the response to the POS.

Integrating

For your Spice integration to handle this scenario, no additional logic is needed; your integration must simply wait for the response. We recommend not to use a timeout on transaction requests, as the response can take any amount of time.

Testing

You do not need to test this scenario as the logic is handled by Spice.

Scenario 4. A manual override is performed

If a network outage occurs, the merchant may choose to manually recover the transaction instead of waiting for the network to be restored.

In this scenario, Spice conveys the transaction to the EFTPOS terminal but then a network outage prevents it from receiving the response. In Spice's transaction UI, the merchant clicks Cancel, then the UI asks them to manually check the EFTPOS terminal for the transaction status to confirm whether the transaction was successful.

After the merchant clicks Yes or No, the transaction response is returned to the POS. (The merchant may manually print the receipts from the EFTPOS terminal, if possible.)

Integrating

Handling this scenario is similar to the network outage scenario in that your Spice integration must simply wait for the response. However, the response from a manually overridden transaction has some differences, as follows.

• It contains user_override: true to indicate that it has been manually overridden.
• It does not contain the receipt fields customer_receipt and merchant_receipt.

Therefore, your integration can use logic similar to the following.

1. If the response contains user_override: true ...
   1. Do not attempt to print receipts from the POS.

Testing

When using Gecko Bank for testing, do the following.

1. Start a transaction, e.g. by calling POST /v1/purchase
2. Disconnect Gecko Bank by turning off the internet on the Android device.
3. On Spice's transaction pop-up, click Cancel, then the Unable to verify transaction result pop-up will appear.