Voucher Virtual Phase 3

---

The Problem

Voucher Virtual Phase 2 shipped with tightly coupled transaction flows — each device model had its own bespoke UI logic, branching conditions, and edge case handling. What worked for one manufacturer's terminal didn't transfer to the next. When Phase 2 went live, the gaps became visible fast.

• Critical post-launch errors: Phase 2 logged 94 critical payment errors per 1M transactions in its first 60 days — primarily in timeout recovery and auth failure paths. Each error required manual recovery by the terminal operator, averaging 3–5 minutes per incident. At 2M daily transactions, even a 0.01% critical error rate represented 200 disrupted payments every day.
• Processing delays: End-to-end transaction time averaged 45 seconds — well above the 30-second target. The primary driver was decision latency in multi-branch flows: operators had to interpret ambiguous status screens and manually choose retry paths they hadn't been trained for.
• Integration bottleneck: Onboarding a new device model required 4–6 weeks of custom flow design, engineering, and QA. As the business signed contracts with new hardware manufacturers to expand into Peru and Colombia, this timeline became a strategic blocker — two signed contracts were waiting on Phase 3 to ship before terminal deployment could begin.
• Documentation debt: Phase 2 documented 18 of 47 identifiable edge cases. The remaining 29 were discovered in production through support escalations and merchant complaints.

Why now: Two regulatory deadlines converged in Q3 2022 — both Peru and Colombia were mandating contactless payment support by September 2022. Processing any new device model in those markets required a scalable architecture that didn't require weeks of custom work per manufacturer. The business case for investing in a parameterized system in Q1 was clear: ship it now or miss the market window.

---

What the research showed

We went in with four questions:

1. What are the most common failure modes in current transaction flows, and where do operator errors occur?
2. What information do terminal operators need at each decision point to recover from errors confidently?
3. Can a single, configurable flow logic replace device-specific custom flows without losing clarity or operator trust?
4. What device-specific differences are genuinely meaningful, requiring UI changes, versus purely technical and handled in configuration?

Four tracks answered them: on-site observation across eight retail locations, 60 days of production transaction logs, structured interviews with processors and device integrators, and a heuristic evaluation of the Phase 2 interface.

They converged on a conclusion that reframed the whole project. Phase 2 was not failing because every device needed its own flow. It was failing because we had built them as though they did. Underneath every terminal model the transaction followed the same four steps, and the differences that felt like flow differences turned out to live in configuration.

Method	Participants / data	Key finding
Contextual inquiryOn-site terminal observation	8 retail locations across 3 cities, full shifts of 6–8 hours per site, 14 operators observed	Operators at multi-device sites, using 2–3 different terminal models, showed higher error rates: they applied recovery behaviours learned on one terminal to another. Device inconsistency was multiplying cognitive load — not just hardware variation, but behavioural variation.
Transaction log analysis60 days, production	1,400 Phase 2 live terminals, 4.2M transactions analysed	Timeout recovery accounted for 61% of all critical errors: when the payment network did not respond within the terminal’s threshold, operators read the blank waiting state as a crash and force-restarted, risking a double charge. Auth failures (18%) and card read errors (14%) followed. 7% were unlogged edge cases with no defined recovery path.
Structured interviewsProcessors and integrators	6 payment processors, 3 device manufacturers, 2 compliance and regulatory liaisons	Each processor had independent requirements for receipt behaviour, retry limits, and contactless fallback — but all shared the same core state sequence: initiate, authorize, confirm, complete. The variation was in configuration, not in the fundamental transaction logic. This was the key structural insight.
Heuristic evaluationPhase 2 UI	3 evaluators (me plus 2 external UX reviewers) across 8 flows, using Nielsen’s 10 heuristics	Timeout and declined states used identical visual treatment: both a grey screen with a spinning indicator. Operators had no way to distinguish “still processing” from “this payment was declined.” That single ambiguity was responsible for the majority of duplicate-charge incidents.

The pattern underneath

The transaction logic across all device models was structurally identical: every payment follows the same sequence — initiate, authorize, confirm, complete. Device differences mattered only at the configuration layer (timeout thresholds, receipt formatting, retry limits), not at the flow logic layer. Phase 2 failed not because the flows were different, but because we treated them as different when they weren’t. The fix wasn’t redesigning flows per device — it was building one robust state machine with configurable parameters.

What this meant for design. We could unify all transaction logic into a single, well-documented state machine. Device-specific behaviour — how long to wait before timeout, whether to print a receipt automatically, how many retries to allow — would live in a device configuration file rather than in the flow. Onboarding a new device became a matter of adding a configuration file, not rebuilding the flow.

Problem Definition

Primary user — Terminal Operator: Age 20–55, retail or hospitality context, processing 50–200+ transactions per shift. Not technically trained; not expected to understand payment network protocols. Needs to complete transactions quickly, recover from errors without calling support, and trust that the terminal screen is telling them exactly what is happening and what to do next.

Secondary user — Payment Processor/Integrator: Technical profile, responsible for connecting merchant hardware to payment networks. Needs to onboard new device models quickly, configure terminal behavior per merchant requirements, and guarantee consistent operator experience across their device portfolio.

Job-to-be-done (Terminal Operator):

"When a customer initiates a payment, I want the transaction to complete clearly and quickly — and if something goes wrong, I want the screen to tell me exactly what happened and what to do next, so I can recover without calling support or risking a double charge."

Job-to-be-done (Integrator):

"When I sign a contract with a new device manufacturer, I want to deploy their terminals on our network in 1–2 weeks, not 4–6, so I can meet merchant demand without becoming a bottleneck."

How we defined success (set before designing):

Metric	Baseline (Phase 2)	Target	Measurement Method
Critical payment errors (per 1M transactions)	94 errors/1M	< 5 errors/1M	Production monitoring, first 60 days post-launch
Transaction processing time (end-to-end, median)	45 seconds	≤ 36 seconds	Production timing logs, pre/post comparison
Operator error recovery success rate (first attempt, no escalation)	52%	≥ 80%	Usability testing with 10 operators across error scenarios
Device integration time (new model, design through QA)	4–6 weeks	≤ 2 weeks	Tracking actual integration timelines post-launch
Edge case documentation coverage	38% (18/47 identified)	100%	Internal documentation audit pre-launch

---

Design Process

Directions explored before converging:

1. Device-Specific Custom Flows (Phase 2 approach, evolved) Maintain separate flow definitions per device model, but standardize the visual language and documentation methodology across all of them.

• Why considered: Incremental improvement on existing investment; device teams retain full control; least engineering disruption
• Why we moved on: This was Phase 2's architecture, and it had already proven the fundamental problem: inconsistency at the flow level creates inconsistency in operator experience, and every new device model multiplies technical debt. Documentation standardization helps, but doesn't resolve the underlying coupling between logic and hardware.

2. Single Universal Flow with Conditional Branches One master flow diagram with branching conditions embedded for every device-specific variation (timeout values, receipt handling, retry logic).

• Why considered: Eliminates redundancy; one source of truth for all devices
• Why we moved on: When we modeled the 12 current device configurations into a single conditional flow, the diagram required 47 branch points and 218 distinct paths. It was theoretically correct but practically unmaintainable — a single configuration change for one device required reviewing the entire diagram for unintended side effects. Testing all combinations was computationally explosive.

3. Parameter-Driven State Machine — what we built A unified state machine defining all valid transaction states and transitions, controlled entirely by device configuration parameters (timeout duration, receipt auto-print flag, retry limit, contactless fallback rule). Adding a new device means adding a configuration file, not changing the state machine.

• Why this won: Structural analysis showed 100% of device differences were in configuration, not in transaction logic. A single state machine with configurable parameters gave us consistency (one flow for all operators regardless of hardware), scalability (new device = new config file), and testability (state machine had finite, enumerable paths that could be fully regression-tested).

The key design decision — separating status from action:

In Phase 2, the most dangerous screen was the payment-in-progress state: it looked identical whether the terminal was waiting for authorization, experiencing a timeout, or had already declined the transaction. Operators couldn't tell which situation they were in, so they guessed — and wrong guesses caused duplicate charges.

We introduced a strict visual distinction between three fundamentally different states:

• Processing (authorization pending): Animated progress ring, no action buttons, explicit time estimate ("Connecting — this usually takes 5–8 seconds")
• Timeout (network didn't respond in time): Static amber alert, clear label ("Connection timed out"), two explicit options: "Retry" or "Cancel and start over." The retry confirmation screen warns: "The previous transaction was cancelled. You are starting a new one."
• Declined (authorization received, payment rejected): Static red alert, clear label ("Payment not approved"), one option: "Try another payment method." No retry on declined transactions — retrying a declined card doesn't change the outcome and frustrates the cardholder.

This three-way distinction eliminated the ambiguity that caused 61% of Phase 2's critical errors.

Key tradeoffs:

What we prioritized	What we sacrificed	Why this was the right call
Operator experience consistency across all devices	Device-specific UI customization for individual manufacturers	Contextual inquiry showed operators at multi-device sites had 2.4x higher error rates. Consistency was worth more than device-specific optimization at the UI layer. Manufacturers could still customize via configuration; the flow itself stays constant.
Complete edge case documentation (all 47 cases before launch)	Faster initial shipping timeline	Phase 2's 29 undocumented edge cases were discovered in production through merchant complaints. Documentation took 2 extra weeks; it prevented 3–5 months of post-launch firefighting. The tradeoff was straightforwardly worth it.
Explicit disambiguation of timeout vs. declined vs. processing	Visual simplicity (fewer screen variants)	Three distinct states required three distinct screen designs. We accepted the added visual complexity because operator safety (no duplicate charges) outweighed aesthetic economy.
Parameterized architecture enabling 1-2 week device onboarding	Simplicity for existing device teams familiar with custom flows	Two device teams pushed back on the configuration model ("we know our device best"). We ran a pilot with one manufacturer's team: they configured their device in 4 days using the new parameter file structure, vs. their 4-week estimate under the old model. Skepticism resolved.

Iteration based on testing:

After building the first prototype of the state machine UI, we ran moderated usability tests with 10 terminal operators (mixed experience levels, multiple store types).

• Finding 1: Four of 10 operators tapped "Retry" on declined transactions even though the screen said "Payment not approved" — they associated the button with any error state. We added a conditional explanation: "This card was declined by your bank. Retrying won't change the result — please try a different payment method." The behavior stopped entirely in follow-up testing.
• Finding 2: The timeout recovery screen's two-option prompt ("Retry" / "Cancel and start over") confused 3 operators who weren't sure if "Cancel" would reverse the original authorization. We renamed "Cancel and start over" to "Start a new transaction (no charge was made)" — adding the parenthetical confirmation that no charge was pending. Confidence in the recovery path improved from 5/10 to 9/10.
• Finding 3: Paper jam / printer error states initially had no fallback. Operators at stores without backup printers had no path forward. We added a "Skip receipt — send via SMS/email" option with a manual phone number entry field. This was not in the original scope but was added after observing two operators during contextual inquiry who had to call support for this exact scenario.

---

The Solution

A parameterized transaction state machine supporting credit, debit, EMV chip, and contactless payments across 12+ device models, with complete documentation of all 47 identified edge cases.

Architecture: The state machine defines all valid transaction states (idle, card present, authorizing, timeout, auth-failed, declined, confirmed, printing, complete, error) and all valid transitions between them. Device-specific behavior is defined entirely in a JSON configuration file per device model. New device models require only a new configuration file — the state machine and UI remain unchanged.

Key flows:

• Happy path: Card detected → Amount confirmed → Authorization sent → Authorization received (approved) → Receipt options → Confirmation screen → Idle
• Timeout recovery: Authorization pending state times out per device config threshold → Amber screen "Connection timed out" → Operator chooses "Retry" (confirmation: "Starting new attempt — previous attempt was cancelled") or "Start new transaction" (confirmation: "No charge was made")
• Declined transaction: Authorization received, rejected → Red screen "Payment not approved — try another method" → No retry option (prevents futile retries on declined cards)
• Auth failure: Network connectivity issue before authorization completes → Amber screen distinguishes from timeout ("Unable to reach payment network") with support escalation option
• Card read error: Chip/swipe failure → Plain language guidance "Remove and reinsert card slowly" → Fallback to manual entry after 3 attempts
• Contactless fallback: NFC payment rejected (card not contactless-capable) → Immediate prompt to tap/insert instead, with visual guide
• Paper jam/printer error: Receipt printing failed → Operator offered: try again, skip receipt, or send digital receipt via SMS/email
• Network drop mid-transaction: Partial authorization state → Explicit hold state with clear operator guidance ("Transaction is pending — do not restart") and support contact number

Documentation deliverables: Complete BPMN 2.0 diagrams for all 47 edge cases with annotated recovery paths; Figma component library for all terminal UI states (27 distinct screens, 4 animation states); device configuration parameter reference guide with validation rules; engineering handoff specification with state transition tables and error code mapping.

Accessibility considerations:

• WCAG AA compliance: 4.5:1 minimum contrast for all status screens and action buttons
• Status differentiation uses color (amber/red/green) + icon + text label — never color alone, for color-blind operators
• Error messages written at a 6th-grade reading level, tested with non-native language speakers
• Large touch targets (60px minimum) for all action buttons; secondary options clearly smaller to prevent misclicks
• Auditory confirmation (configurable beep/vibration) for successful authorizations — critical in noisy retail environments

---

Results & Impact

Measurement approach: Staged rollout. Phase 3 launched to 30% of live terminals (4,500 devices) running in parallel with Phase 2 on the remaining 10,500. Pre/post comparison over 60 days, with Phase 2 serving as the live control group. Production monitoring tracked error rates, processing times, and support ticket volumes across both cohorts.

Measurement period: 60 days post-launch (July–August 2022).

Scale: 4,500 terminals, 1,400+ merchants, 1.8M daily transactions across the Phase 3 cohort during the measurement window.

Metric	Phase 2 (Before)	Phase 3 (After)	Change
Critical payment errors per 1M transactions	94	4	-96%
Transaction processing time (end-to-end, median)	45 seconds	36 seconds	-20%
Operator error recovery success rate (first attempt)	52%	84%	+61%
Device integration time (new model, design through QA)	4–6 weeks	9 days (first new model post-launch)	-75%
Edge case documentation coverage	38% (18/47)	100% (47/47)	Complete
Timeout-related duplicate charge incidents	1.8 per day (Phase 2 avg)	0.1 per day (Phase 3)	-94%
Support tickets for transaction-related issues	~840/month	~310/month	-63%

Business impact:

At scale across all 15,000+ terminals, the 20% processing time reduction and 96% error reduction have direct throughput and cost implications. At 2M daily transactions, Phase 2's 94 critical errors per million equated to approximately 188 disrupted payments daily — each requiring 3–5 minutes of operator recovery time. Phase 3 reduced this to fewer than 10 per day. For merchants processing in high-volume retail environments, this eliminated the primary source of checkout friction and manual recovery.

The 75% reduction in device integration time enabled two signed hardware partnerships — previously blocked waiting for Phase 3 — to go live in under 30 days from contract signing. Both the Peru and Colombia contactless mandates were met before the September 2022 regulatory deadline. The business retained both markets without penalty.

Support ticket reduction from ~840/month to ~310/month across the Phase 3 cohort, applied to the full 15,000-terminal network post-full-rollout, represented an estimated $180K/year reduction in support labor costs at Tier 1 resolution rates.

Qualitative signal:

Post-launch survey of 200 terminal operators (6 weeks after Phase 3 rollout):

• 91% agreed: "The new interface makes it clearer what I should do when something goes wrong"
• 88% said: "I feel more confident using the terminal than I did with the previous version"
• 76% said: "I've called support less often since the update"

Representative feedback from a store manager at a high-volume grocery chain: "Before, when the terminal froze, we'd have to call IT and the line would back up. Now the screen tells us exactly what happened. My team hasn't needed to call support for a terminal issue in 3 weeks."

Payment processor integration feedback (first new device partner onboarded post-Phase 3): "We configured the parameter file in four days. We were expecting to spend three weeks on this. Whatever you did architecturally, please don't change it."

---

Learnings

What worked:

1. Separating configuration from logic was the core architectural insight. Once we recognized that all 12 device models shared the same transaction state sequence — and that their differences were purely configurational — the design problem became much cleaner. The challenge shifted from "how do we design 12 different flows" to "how do we make one flow configurable enough to handle 12 devices." This reframing is now the first question I ask on any multi-platform design problem: what's universal vs. what's configuration?

2. Naming states precisely prevents misinterpretation at scale. The timeout vs. declined vs. processing distinction seems obvious in retrospect, but Phase 2 treated all three as "error states" with identical visual treatment. Investing 3 design reviews specifically on state naming conventions — before any visual work — paid off more than any later iteration. When operators can read a screen and know immediately whether they've lost network connectivity vs. received a decline, they make correct decisions. State labels are not copy — they are the product.

3. Complete edge case documentation before launch is non-negotiable on payment flows. Phase 2's 29 undocumented edge cases became 29 production incidents. Documenting all 47 edge cases before Phase 3 shipped took 2 additional weeks during design; it saved 3–4 months of post-launch incident response. For high-stakes transaction UX, launch-day completeness is a design deliverable, not an afterthought.

What I'd do differently:

1. Involve terminal operators in flow design earlier, not just validation. Our contextual inquiry happened in Week 2 of the project, which was early enough to influence architecture. But ideally it would have happened before the project kicked off — as a prerequisite for even writing the design brief. The insight that device inconsistency was hurting operators at multi-device sites would have changed our framing from "optimize per device" to "standardize across devices" from day one.

2. Prototype configuration parameter design with integrators concurrently. We designed the state machine and the UI first, then handed the configuration file structure to engineers. Two of the parameters we defined had ambiguous edge cases that engineers caught during implementation — requiring a mid-project architecture review. Involving a payment processor integrator in the parameter design phase (not just the testing phase) would have caught these earlier.

3. Define the error taxonomy before designing any screens. We iterated on error screen copy and labeling throughout the design phase because we hadn't established a shared terminology for error states upfront. I should have run a naming workshop with engineering, QA, and a terminal operator in Week 1 to agree on what "timeout," "declined," "auth failure," and "network error" meant to each stakeholder — before designing anything.

What this opened up:

• Dynamic parameter optimization: The configuration file architecture created a new capability the business hadn't anticipated: A/B testing configuration parameters across merchant segments. A high-volume grocery chain can test a 10-second vs. 15-second timeout threshold to optimize for their transaction velocity; a boutique retailer might prefer a longer threshold with more explicit status messaging. Personalized configuration is now on the 2023 roadmap.
• Accelerated market expansion: Two additional hardware partnerships (contracted pre-Phase 3 but unshippable under Phase 2's integration timeline) shipped in under 2 weeks each after Phase 3 launched. The parameterized architecture is now the company's standard for all new terminal integrations, and onboarding time has stayed below 2 weeks for all 4 new device models added since launch.
• Predictive error monitoring: Production monitoring of state machine transitions now surfaces anomalous transition patterns before they become critical errors. The data pipeline built for Phase 3 production tracking is being extended into a real-time alert system for device fleet managers — flagging unusual timeout rates that predict network issues before merchants notice.