Transaction recovery

Introduction

Firstly, what is transaction recovery? When SPI makes a transaction but doesn’t receive a response from the EFTPOS terminal, SPI does not know whether the transaction succeeded, failed, or is still being processed. Transaction recovery is where SPI finds the transaction and its result, hence preventing missed transactions and other issues.

There are three transaction recovery scenarios handled by SPI, and integrating these is simple.

See the code

Take a tour of the code below, and copy it into your project to get started.

Scenario 1. The POS quits unexpectedly

If the POS quits unexpectedly ('shuts down', 'times out', or 'crashes') during a transaction, after it restarts, SPI can recover the transaction from the EFTPOS terminal.

In this scenario, the POS makes a transaction but then quits unexpectedly before it receives the 'TxFlowStateChanged' event containing the response. After the POS restarts, it must retrieve the transaction response from the terminal.

Integrating

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

• After starting a transaction ...
  1. Store the transaction’s posRefId and TransactionType details in the POS.
• On POS startup ...
  1. If there are transaction details stored in the POS, recover the transaction by calling spi.InitiateRecovery(...) with the posRefId and TransactionType.
• After the transaction finishes ...
  1. Remove the transaction details stored in the POS.

Testing

1. Start a transaction, e.g. by calling spi.InitiatePurchaseTxV2(...)
2. Shut down the POS.
3. Complete the transaction using Gecko Bank.
4. Restart the POS.
5. Confirm that a successful ‘TxFlowStateChanged’ event occurs.

Scenario 2. A network outage occurs

If a network outage (‘internet disconnection’) occurs during a transaction, once the network is restored, SPI will automatically recover the transaction from the EFTPOS terminal.

In this scenario, SPI conveys the transaction to the EFTPOS terminal but then a network outage occurs preventing SPI from communicating with the terminal, and hence the 'TxFlowStateChanged' event does not occur. When the network is restored, SPI recovers the transaction from the terminal and sends the 'TxFlowStateChanged' event.

Integrating

For your integration to handle this scenario, no additional logic is needed; your integration must simply wait for the 'TxFlowStateChanged' event to occur. We recommend not to use a timeout on waiting for this event, as it can take any amount of time.

Testing

1. Start a transaction, e.g. by calling spi.InitiatePurchaseTxV2(...)
2. Disconnect the internet connection on the Gecko Bank device.
3. Wait any amount of time.
4. Reconnect the internet connection on the Gecko Bank device.
5. Confirm that a successful 'TxFlowStateChanged' event occurs.

Scenario 3. 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, SPI conveys the transaction to the EFTPOS terminal but then a network outage prevents the 'TxFlowStateChanged' event from occurring. The merchant manually checks the EFTPOS terminal for the transaction status, then confirms it in the POS's UI.

Integrating

To handle this scenario, you will need to do the following.

1. If no 'TxFlowStateChanged' event occurs and spi.CurrentTxFlowState.Success equals to SuccessState.Unknown ...
   1. Display a user interface for performing a manual override which allows the merchant to confirm whether the transaction was successful or failed.
   2. If it is confirmed as successful ...
      • Call spi.AckFlowEndedAndBackToIdle() to finish the transaction.
      • Display a 'transaction success' message in the UI.
   3. Else, if it is confirmed as failed ...
      • Call spi.AckFlowEndedAndBackToIdle() to finish the transaction.
      • Display a 'transaction failed' message in the UI.

📘

Note:

• You may want to use a timer (e.g. 3 seconds) before starting the manual recovery process.
• SuccessState.Unknown is a constant string that must be imported:
  import { SuccessState } from "@mx51/spi-client-js";

Testing

1. Start a transaction, e.g. by calling spi.InitiatePurchaseTxV2(...)
2. Disconnect the internet connection on the Gecko Bank device.
3. Cancel the transaction on POS UI.
4. Wait until the manual recovery UI appears.
5. Use the UI to manually recover the transaction.
6. Confirm that a successful 'TxFlowStateChanged' event occurs.