Skip to main content

Terminal Firmware

Overview​

The Stitch terminal firmware APIs enable terminal app developers to manage firmware updates on payment terminals.

These APIs allow you to:

  • Check if firmware updates are available
  • Download required firmware files
  • Report successful installation back to Stitch

Firmware Update Process​

The diagram below illustrates the complete firmware update workflow:

Implementation Steps​

1. Check for Available Updates​

Start by calling the Terminal Status API. This returns a status object containing the firmwareUpdateRequired field:

  • true indicates new firmware is available.
  • false indicates all firmware is up to date.

2. Retrieve Firmware Update List​

If updates are available, call the List Firmware Files API to get details about each required update.

Each entry in the returned list contains:

  • Metadata about the firmware update.
  • A sha256Checksum value for file verification.
  • A downloadLink pointing to the firmware file location.

3. Download and Verify Firmware Files​

The downloadLink provides a URL to a cloud storage location (Azure or AWS, depending on your region). For each file:

  1. Download the file from the provided link.
  2. Calculate a SHA256 checksum on the downloaded file.
  3. Verify that the calculated checksum matches the sha256Checksum value provided in the API response.

4. Install and Confirm​

After successfully installing each firmware file:

  1. Call the Confirm Installation API.
  2. This notifies Stitch that the firmware has been successfully installed.
  3. Stitch updates its records to reflect the terminal's current firmware state.
note

You must repeat the 4 steps above for each firmware file in the list. The terminal application is responsible for determining the correct installation order for multiple firmware files.