---
title: TMS Updates
slug: MGAJ-tms-updates
docTags: 
createdAt: 2026-06-19T11:55:43.782Z
---

The Terminal Management System (TMS) is the source of truth for a reader's encryption keys and configuration. There are two points at which the SDK applies pending TMS updates:

1. **During device setup**, as part of [ensureDeviceReady()](docId\:UymEfwQPsSfdqgfPvLAxg). This is the primary mechanism and handles everything: key injection, ECC certificate signing and configuration updates.
2. **On transaction start**: an **opt-in**, lighter-weight check that applies pending configuration updates immediately before a transaction.

## Updates during device setup

The recommended approach is to call [ensureDeviceReady()](docId\:UymEfwQPsSfdqgfPvLAxg) when pairing a reader and again on every app launch. It checks the TMS for pending updates and applies any that are found (keys, ECC certificate and configuration alike), skipping anything already up to date. On a healthy device with nothing pending, the only cost is a single `StatusReport` to the TMS.

See [Device Setup & Readiness](docId\:UymEfwQPsSfdqgfPvLAxg) for the full flow, progress states and ECC handling.

## Updates on transaction start (opt-in)

For integrators who want configuration to stay current without relying solely on app-launch setup, the SDK can check for and apply pending updates at the start of each transaction. This is **off by default**.

Enable it via `ToroConfig`:

```kotlin
val config = ToroConfig(
    // ...other config...
    checkForUpdatesOnTransactionStart = true
)
```

When enabled, `startTransaction()` checks the TMS for pending updates before proceeding and applies any applicable update. When disabled (the default), `startTransaction()` behaves exactly as before and runs no update checks.

:::hint{type="warning"}
The transaction-start path handles `CONFIGURATION_UPDATE`** (application parameters) only**. Key injection and ECC signing are **not** applied here; those are prerequisites that must be resolved during initial device setup via [ensureDeviceReady()](docId\:UymEfwQPsSfdqgfPvLAxg).
:::

### Transaction states for this flow

When `checkForUpdatesOnTransactionStart` is enabled, two additional `TransactionState` values may be emitted to your `TransactionStateListener` immediately after `CONNECTING_TO_DEVICE` (i.e. once the device is connected and its info has been read) and before the usual `AWAITING_GRATUITY` / `AWAITING_CARD` states:

| State                  | What's happening                                                                                                                         |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `CHECKING_FOR_UPDATES` | Checking the gateway for pending device updates before the transaction starts.                                                           |
| `APPLYING_UPDATES`     | Installing a pending configuration update on the device before the transaction starts. Only emitted when an applicable update was found. |

:::hint{type="info"}
If no update is pending, only `CHECKING_FOR_UPDATES` is emitted (briefly) and the transaction proceeds normally; the only cost is the status check itself.
:::

### Reconnection after an update

Applying a configuration update can reboot the reader. As with device setup, the SDK reconnects automatically via connection polling and then continues the transaction without integrator intervention.

## Choosing an approach

|                       | App-launch setup        | Transaction-start check                      |
| --------------------- | ----------------------- | -------------------------------------------- |
| Entry point           | `ensureDeviceReady()`   | `startTransaction()` (with config flag)      |
| Opt-in?               | No, call it yourself    | Yes, via `checkForUpdatesOnTransactionStart` |
| Handles keys / ECC    | Yes                     | No (configuration only)                      |
| Handles configuration | Yes                     | Yes                                          |
| Added latency         | On app launch / pairing | Before every transaction                     |

The two are complementary. At minimum, call `ensureDeviceReady()` regularly. Enable the transaction-start check additionally if you need configuration to converge as quickly as possible between setup runs.