Listen for events

Sample code

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

The code sample listens for the most important events dispatched by SPI and logs them to the browser console using spi._log.info(...). It also performs actions in response to some of these events.

Each event contains data within its detail field, but you can also find this data within the spi object.

‘StatusChanged’ event

This event occurs when the connection status of the EFTPOS terminal changes. The event’s detail is the new connection status:

• Unpaired — the terminal is not connected.
• PairedConnecting — the terminal is in the process of connecting.
• PairedConnected — the terminal is connected.

This data can also be found in spi._currentStatus

‘PairingFlowStateChanged’ event

This event occurs at several stages during the pairing of an EFTPOS terminal to give updates on its progress.

The event’s detail contains a message that you may include in your user interface, e.g. Message: "Negotiating Pairing..."

It also contains the confirmation code that you will display to the user to confirm before pairing, e.g. ConfirmationCode: "123456"

In the code sample, when pairing has successfully finished, the EFTPOS terminal is returned to the ‘Idle’ status.

This data can also be found in spi.CurrentPairingFlowState

‘SecretsChanged’ event

This event occurs when the pairing secrets are added, changed, or removed. Its detail contains the secrets object that must be stored in local storage so it can be used during pairing.

This data can also be found in spi._secrets

‘terminal_configuration’ event

This event occurs when the EFTPOS terminal is successfully paired and it contains information about the terminal. Its Data contains details that you can display in your user interface, such as the merchant_id, terminal_id, and terminal_model.

This data can also be found by calling spi.TerminalConfigurationResponse()

‘terminal_status’ event

This event occurs when the status of the EFTPOS terminal changes. Its Data contains a status that can be any of the following.

• IDLE — the terminal is ready to process a transaction.
• BUSY — the terminal is not ready to process a transaction.
• TRANSACTION — a transaction is in progress so the terminal is not ready to process another transaction until this one is complete.

The event also includes information about the terminal’s battery.

• The percentage of charge in the device’s battery — e.g. battery_level: 99
• Whether the device is currently charging (or ‘plugged in’ to a charger) — e.g. charging: true

This data can also be found by calling spi.TerminalStatusResponse()

‘TxFlowStateChanged’ event

This event occurs at important stages during a transaction such as when it starts, when it finishes, and when a signature is required. It contains detailed information and is used for handling the transaction.

Learn more about handling transactions and handling signatures.

‘txn_update_message’ event

This event occurs at several stages during a transaction to give updates on its progress. Its Data contains a display_message_text that you can use in your UI — e.g. "Waiting for customer to present card". It also contains the display_message_code which identifies the stage of the transaction.

This data can also be found by calling spi.TransactionUpdateMessage()

‘battery_level_changed’ event

This event occurs when the EFTPOS terminal's battery level changes. Its Data contains the new battery level; for instance, when the battery level changes from 100% to 99%, it will contain battery_level: 99

This data can also be found by calling spi.BatteryLevelChanged()

Custom logging

It’s possible to use a custom function to log SPI’s messages, for instance, if you want to log to a file or database. To do so, override the value of spi._log as in the following example, but replace customLog with your own logging function.

spi._log = {
    debug: message => customLog(message),
    error: message => customLog(message),
    info: message => customLog(message),
    warn: message => customLog(message)
}