The problem
Verification and consent flows look simple in a design file: a form, a button, a success screen. In production they have a dozen states that nobody drew. The check is pending. The provider times out. The document has expired. The user closes the tab halfway and comes back on another device. Each undrawn state becomes a guess in code.
The guesses add up. Users get stuck on a spinner with no way out. Support tickets ask why an account is locked. Personal data ends up in logs, analytics events or local storage because nobody said it shouldn’t. A review then finds the gaps, after launch.
Consent has the same shape. A choice is recorded but not enforced, or enforced on one page but not another, or not honoured when it is withdrawn. Fixing it later touches every feature that reads it.
What we put in the spec
We spec these flows as state machines, not screens. Every step lists its states, the transitions between them, what the user sees in each, and what data exists at that moment. The verification provider and the rules for each market come from you. We turn them into behaviour that can be tested.
Verification steps and states
For each step we define:
- States: not started, in progress, pending review, passed, failed, expired, and needs more information.
- Transitions: what moves the user between states, including timeouts and retries.
- Copy for every state: what happened, what the user can do next, and how long it usually takes, if you know.
- Resume behaviour: what happens when the user leaves and returns, on the same device or another one.
Feature: Verification pending
Scenario: The provider has not answered yet
Given a member who submitted verification documents
And the provider has not returned a result
When the member opens their account
Then they see the "pending review" state with the expected wait
And the actions that require verification are disabled with a reason
And no document image is kept in browser storage
Consent capture
Consent is specified per purpose, never as one blanket switch. The spec records what is asked, when it is asked, how the choice is stored, how it is enforced across the product, and how it is withdrawn in the same number of steps it took to give.
Data minimisation
Every field in every step is mapped to a purpose and a destination. Some data must reach the verification provider but never touch your frontend storage. Some is needed for one request and then discarded. The spec says which is which.
What not to store
| Data | Rule |
|---|---|
| Document images and selfies | Sent directly to the provider. Never in browser storage, logs or analytics |
| Full date of birth | Only where a rule requires it. Otherwise a pass or fail result |
| Provider error payloads | Mapped to user-facing states. Raw payloads never shown or logged in the client |
| Consent choices | Stored as purpose and timestamp. No profiling data attached |
How it is checked before release
Each state and transition in the spec becomes an automated test. Provider responses are mocked, so every state can be reached on demand, including the rare ones.
- State coverage: a test for every state and every transition, run on every pull request.
- Storage and network checks: tests confirm that sensitive fields never appear in storage, URLs, logs or third-party requests.
- Consent enforcement: each purpose is tested granted, refused and withdrawn, across every feature that reads it.
- Accessibility: each state is checked against WCAG 2.2 AA, including focus handling when a state changes and error messages tied to their fields.
A senior engineer reviews every change. The trace report shows each criterion with its test and result.
What changes for you
Your support team gets fewer “I’m stuck” tickets, because every state has copy and a next step. Your privacy and security reviews have evidence to read, not code to reverse-engineer. When a provider or a rule changes, the change is written as a spec delta, priced, and tested before it ships.
What you receive
| Deliverable | Format |
|---|---|
| State machine per flow | A diagram plus a table in the spec |
| Copy for every state | In the spec, ready for your review |
| Field-to-purpose and destination map | Per step, in the spec |
| Consent model per purpose | Criteria plus storage format |
| Test suite with mocked provider responses | In your CI |
| Accessibility results per state | In each trace report |
What we need from you
We need the provider’s documentation and sandbox access, the rules your compliance team has confirmed for each market, and one decision-maker for questions about copy and edge cases. We implement those rules precisely. We don’t decide them, and we don’t give legal advice.
Most teams start with a Spec Sprint to map the flows before anything is built.