---
title: Payment and Trezor Verification Report
tags: [operations, testing, payments, trezor]
---

# Payment and Trezor Verification Report

Date: 2026-05-24

Scope:

- Task 3 provider-neutral payment migration.
- Request Network primary pay-in, webhook, and reconciliation support.
- Internal funds ledger and release/refund ledger gates.
- Optional Trezor safekeeping support.

## Optionality Verdict

Trezor safekeeping is optional by default.

```env
TREZOR_SAFEKEEPING_REQUIRED=false
```

Only the literal value `true` enforces Trezor proof during release/refund confirmation. When unset, `false`, or any other value, release/refund confirmation continues through the existing payment adapter path.

Enforcement is centralized in `backend/src/services/trezor/trezorService.ts` and called from `backend/src/services/payment/orchestration/releaseRefundService.ts`.

## Focused Verification Command

Run this command from the backend package:

```bash
npm test -- __tests__/payment-adapter-registry.test.ts __tests__/request-network-adapter.test.ts __tests__/request-network-payin.test.ts __tests__/request-network-webhook.test.ts __tests__/payment-ledger.model.test.ts __tests__/payment-ledger.service.test.ts __tests__/payment-migration.service.test.ts __tests__/payment-release-refund-orchestration.test.ts __tests__/payment-release-refund-routes.test.ts __tests__/payment-reconciliation.service.test.ts __tests__/payment-observability-redaction.test.ts __tests__/payment-observability-events.test.ts __tests__/trezor-safekeeping.service.test.ts --runInBand
```

Expected result:

```text
Test Suites: 13 passed, 13 total
Tests:       64 passed, 64 total
```

Also run:

```bash
npm run typecheck
git diff --check
```

Expected result: both pass for backend changes.

## Suite Coverage

| Suite | Test count | Verifies |
| --- | ---: | --- |
| `payment-adapter-registry.test.ts` | 8 | Provider adapter selection, rollback defaults, enabled provider flags, Request Network alias support |
| `request-network-adapter.test.ts` | 6 | Request Network payload creation, parse/map helpers, webhook signature verification, adapter HTTP wiring |
| `request-network-payin.test.ts` | 3 | Pay-in creation, pending-intent dedupe, provider-disabled rejection |
| `request-network-webhook.test.ts` | 6 | Signature validation, test webhook allowlist, duplicate delivery handling, coordinator-blocked duplicate path |
| `payment-ledger.model.test.ts` | 3 | Ledger model entry types, required fields, unique sparse idempotency index |
| `payment-ledger.service.test.ts` | 9 | Append/idempotency behavior, balance aggregation, release/refund availability, held/disputed invariant |
| `payment-migration.service.test.ts` | 3 | SHKeeper migration dry-run counts, bounded sampling, ledger backfill candidate filtering |
| `payment-release-refund-orchestration.test.ts` | 5 | Release/refund instruction flow, ledger append, partial release, rollback compatibility, Trezor proof forwarding |
| `payment-release-refund-routes.test.ts` | 2 | Release/refund route ordering and controller dispatch |
| `payment-reconciliation.service.test.ts` | 6 | Dry-run/apply reconciliation, no-op alignment, missing refs, fallback Request Network references |
| `payment-observability-redaction.test.ts` | 3 | Recursive secret redaction and immutability |
| `payment-observability-events.test.ts` | 5 | Incident control snapshots and event construction |
| `trezor-safekeeping.service.test.ts` | 5 | Deterministic xpub derivation, xpub validation, registration proof, address allocation reuse, operation signature verification |

## Known Gaps

- No live Request Network API test is included in this CI-safe suite.
- No physical Trezor/hardware-device validation is included; Trezor tests use deterministic xpub/address/signature fixtures.
- Migration tests are read/report-oriented and do not execute destructive production backfills.
- Frontend checkout still needs a separate browser/build verification once frontend dependencies are installed.
- The existing `npm run test:payment` script points at a missing `__tests__/payment-services.test.ts`; use the focused command above instead.

## Release Gate

Before enabling Request Network for a non-test cohort:

1. Run the focused verification command.
2. Run backend typecheck.
3. Test one Request Network sandbox pay-in with webhook callback.
4. Confirm reconciliation dry-run output is empty or expected.
5. Keep the Request Network rollback/support runbook current; SHKeeper is historical context, not the current primary rollback target.

Before enabling Trezor safekeeping enforcement:

1. Register an admin Trezor account through `/api/trezor/register`.
2. Confirm `/api/trezor/account` reports `registered: true`.
3. Generate and sign one `/api/trezor/operation-message`.
4. Confirm `/api/trezor/verify-operation` succeeds.
5. Set `TREZOR_SAFEKEEPING_REQUIRED=true`.
6. Confirm release/refund without Trezor proof is rejected and release/refund with proof succeeds.