docs: sync from backend 3e9a2f2 — BSC Testnet tUSDT rail

04 - Flows/Payment Flow - Scanner.md

@@ -6,7 +6,7 @@ created: 2026-05-30
 
 # Payment Flow — AMN Pay Scanner (In-House)
 
-> **Last updated:** 2026-06-06 — documented backend/frontend `2.8.115` and scanner `0.1.10` BSC Testnet rail alignment.
+> **Last updated:** 2026-06-06 — documented backend/frontend `2.8.116` and scanner BSC Testnet tUSDT rail correction.
 
 End-to-end payment flow using the in-house AMN Pay Scanner, replacing the Request Network integration. The scanner is a separate microservice; the backend talks to it over an internal HTTP API.
 
@@ -76,12 +76,14 @@ For dev end-to-end testing, backend and scanner must keep the chain 97 registry
 | Chain id | `97` |
 | Network aliases | `bsc-testnet`, `bnb-testnet`, `bsctest`, `bsc_testnet`, `binance-testnet`, `bnbt`, numeric string `97` |
 | RPC fallback | `https://bsc-testnet-rpc.publicnode.com` |
-| USDT test token | `0x337610d27c682E347C9cD60BD4b3b107C9d34dDd` |
+| USDT test token | `0x109F54Dab34426D5477986b0460aE5dFBA65f022` |
 | USDC test token | `0x64544969ed7EBf5f083679233325356EbE738930` |
 | Token decimals | `18` for USDT and USDC |
 | Default confirmation floor | `5` |
 
-Backend `2.8.115+` uses this same token address in both the Request Network/scanner intent registry and the legacy `BSCTransactionVerifier` path. This matters because `/api/payment/request-network/intents` resolves the buyer's selected chain/token before asking scanner to watch, while older wallet-direct verification endpoints call `BSCTransactionVerifier.verifyTransfer()` directly. A mismatch between these two registries will either create scanner intents for a token that the buyer does not pay, or verify the wrong ERC-20 contract after payment.
+Backend `2.8.116+` uses this same token address in both the Request Network/scanner intent registry and the legacy `BSCTransactionVerifier` path. This matters because `/api/payment/request-network/intents` resolves the buyer's selected chain/token before asking scanner to watch, while older wallet-direct verification endpoints call `BSCTransactionVerifier.verifyTransfer()` directly. A mismatch between these two registries will either create scanner intents for a token that the buyer does not pay, or verify the wrong ERC-20 contract after payment.
+
+Backend `2.8.116+` also passes an explicit `scannerContext` (`paymentId`, `chainId`, `tokenSymbol`, `tokenAddress`, `destination`) into AMN scanner intent registration. This prevents PG-only or partially hydrated payment reads from falling back to the global merchant reference and creating mainnet/default-style scanner intents such as `undefined-c56-USDC`.
 
 If a live dev stack still waits for `200` confirmations on chain 97, check the admin runtime setting `confirmation_threshold:97`. Built-in default is now `5`, but a previously persisted admin value above the floor still wins until updated.
 

08 - Operations/Scanner Operations.md

@@ -151,6 +151,14 @@ Edit `tokens.json`. Each entry:
 
 Token registry is used only for populating `tokenSymbol` and `decimals` in the `checkoutBlock` response. Omitting a token does not break scanning — it just leaves those fields empty.
 
+For dev BSC Testnet, chain `97` symbol `USDT` must point at the deployed tUSDT contract:
+
+```json
+{ "chainId": 97, "address": "0x109F54Dab34426D5477986b0460aE5dFBA65f022", "symbol": "USDT", "decimals": 18, "name": "Test USDT (BSC Testnet)" }
+```
+
+After a registry change, restart/redeploy the scanner and verify through `POST /balances/check` by symbol, not only by explicit `tokenAddress`.
+
 ---
 
 ## 7. Manual webhook retry

09 - Audits/Activity Log.md

@@ -11,6 +11,16 @@ entries on top. Maintained by agents per the rule in `../AGENTS.md`.
 
 ---
 
+### 2026-06-06 — backend@3e9a2f2, frontend@e4fa4de, scanner@1911c3a — BSC Testnet tUSDT contract corrected
+
+**Commits:** `3e9a2f2` `e4fa4de` `e235286` `1911c3a`
+**Touched:** backend `src/services/payment/requestNetwork/tokens.json`, `src/services/payment/requestNetwork/supportedChains.json`, `src/services/payment/decentralizedPaymentService.ts`, `src/services/payment/adapters/amnPayAdapter.ts`, `src/services/payment/amnScanner/amnScannerPayInService.ts`, `scripts/smoke/bsc-testnet-payment-registry.sh`, BSC Testnet payment tests, version files; frontend `package.json`; scanner `tokens.json`, `supported-chains.json`, `contracts/testnet/USDT.sol`.
+**Why:** The funded dev wallet held Test USDT at `0x109F54Dab34426D5477986b0460aE5dFBA65f022`, while backend/scanner still resolved chain 97 `USDT` to `0x337610...`. Scanner `/balances/check` returned zero for symbol `USDT` until the registry was pointed at the actual tUSDT contract. The backend adapter now also passes explicit `scannerContext` into scanner intent creation so BSC Testnet pay-ins do not fall back to mainnet/global merchant-reference defaults (`undefined-c56-USDC`).
+**Verification:** backend `npm test -- --runTestsByPath __tests__/rn-in-house-checkout.test.ts __tests__/decentralized-payment-verifier.test.ts __tests__/amn-pay-adapter-intent.test.ts --runInBand`, `BASE_URL=https://dev.amn.gg bash scripts/smoke/bsc-testnet-payment-registry.sh`, `git diff --check`; scanner `go test ./...`, `git diff --check`; frontend package version sanity check. Post-deploy scanner balance check pending.
+**Linked docs updated:** [[04 - Flows/Payment Flow - Scanner]], [[08 - Operations/Scanner Operations]]
+
+---
+
 ### 2026-06-06 — backend@810098f, frontend@5ccc15c, scanner@6897195 — BSC Testnet scanner rail aligned
 
 **Commits:** `810098f` `5ccc15c` `6897195`