update docs

docs/bmlapi/12-tap-to-pay.md

@@ -77,6 +77,16 @@ Expected response: `{ "code": 0, "payload": [...] }`
 
 The OTP is a standard TOTP (RFC 6238, SHA-1, 30-second window, 6 digits) derived from the stored BML authenticator seed.
 
+### Failure Handling
+
+Each of the three POSTs validates the server's `code` field and throws on mismatch (`BmlTapToPayClient.kt:37, 42, 47`). The exception message is the server's `message` field:
+
+| Step | Expected code | Throws if |
+|---|---|---|
+| 1a | `0` (rare) or `99` | code is neither — `message` propagated |
+| 1b | `22` | code is not `22` — `message` propagated |
+| 1c | `0` | code is not `0` — `message` propagated |
+
 ### Token Response
 
 ```json
@@ -239,6 +249,33 @@ All APDU responses use BER-TLV encoding. Tags are 1 or 2 bytes (hex string). Len
 
 ---
 
+## Lifecycle
+
+The HCE service (`BmlHostCardEmulatorService`) keeps a single active `BmlWalletToken` in a volatile companion-object field. Tokens are single-use — exactly one tap consumes one token.
+
+### Companion API
+
+```kotlin
+BmlHostCardEmulatorService.setToken(token: BmlWalletToken)
+BmlHostCardEmulatorService.clearToken()
+BmlHostCardEmulatorService.onTransactionComplete: (success: Boolean) -> Unit
+```
+
+| Call | When |
+|---|---|
+| `setToken(token)` | After fetching a token, before prompting the user to tap |
+| `clearToken()` | After the tap completes, when the prompt is dismissed, or on error |
+| `onTransactionComplete(true)` | Fired immediately after the `READ RECORD` response (`BmlHostCardEmulatorService.kt:78`) |
+| `onTransactionComplete(false)` | Fired from `onDeactivated` if GPO was never seen (`BmlHostCardEmulatorService.kt:35-38`) — i.e. the reader walked away before completing the EMV exchange |
+
+### State Rules
+
+- A token MUST be installed via `setToken` before the user taps. With no active token, `SELECT PPSE` launches `BmlTapToPayActivity` (a redirector to `MainActivity`) and returns `6F00`.
+- The service tracks `gpoSent` to distinguish "user pulled the phone away" from a successful read. A successful `handleReadRecord` resets `gpoSent` to `false` via `onDeactivated` after the success callback has already fired.
+- `BmlTapToPayActivity` provides the "Tap your phone…" prompt UI. The activity is responsible for calling `setToken` before showing the prompt and `clearToken` when dismissed.
+
+---
+
 ## Prerequisites
 
 - Valid `access_token` from [OAuth Token Exchange](03-oauth-token.md)