A reality check,
not a spec.
After v0.1 mapped the ideal vendor payment lifecycle, engineering flagged a hard constraint: when a payment goes on hold, the reason lives in three disconnected backend systems that don’t share a format. A unified, machine-readable reason code — the thing that makes the perfect Hold state possible — is a ~3-month reconciliation project.
Rather than wait a quarter, v0.2 designs around the wall. It separates the expensive part (a precise reason with a one-click fix) from a cheap question hiding underneath: even without a clean reason, do we already know which of the three systems raised the hold? IIf yes, we can already answer some of the most important questions around the Hold state: who is handling it, whether action is required, and what happens next.
- Feasibility Review Design partner
- State Mapping Lifecycle
- Designing Around Limits Backend reality
- Phased Delivery Now → later
- Trust & Guardrails Payments
The happy path is unchanged.
The constraint only touches the Hold state. From approved work to paid, the lifecycle is unaffected — so the redesign leaves it exactly where it was.
Approved work → paid ↓
Why “show the reason” isn’t free.
Any of three systems can independently put a payment on hold — and they don’t share a reason format. Today all three collapse into one generic “On Hold”.
Three systems, three formats, no shared reason code ↓
The expensive part is a unified reason code with a specific fix (all three systems reconciled — the ~3-month project). But there’s a cheap question hiding underneath: even without a clean reason, do we already know which system raised the hold? If yes, we can ship a more informative Hold state without waiting for full reconciliation.
Design around the wall,
don’t wait for it.
Same component, two levels of detail. Phase 0 ships on a single flag; Phase 1 layers the precise reason on top once the backend work lands, using the same component structure to minimise redesign.
Depends only on knowing which system flagged the hold.
- ▸With: our Tax & Compliance team
- ▸“Action required: Yes
- ▸Next step: Check your compliance requirements
- ▸Next update: within 3 business days
Depends on the unified reason service reconciling A + B + C.
- ▸Reason: W-8BEN tax form expired on 12 Mar
- ▸Fix: Re-submit form → auto-releases on validation
- ▸Est. release: ~24h after re-submission
- ▸Status: live, no waiting for a human
So nobody’s blocked
waiting on the 3 months.
Ship Phase 0, measure its effect, and use the evidence to decide whether the reconciliation project earns the roadmap.
What’s cheap,
what’s a project.
The split that lets engineering make the call — Several useful vendor-facing signals sit in the lower-cost rows.
| Capability | Depends on | Cost | Ships |
|---|---|---|---|
| Which system holds it | A/B/C already expose some flag | cheap | Phase 0 |
| Action-needed? Y/N | One boolean per system | cheap | Phase 0 |
| “Next update by” date | SLA per hold type (a rule) | medium | Phase 0 |
| Specific reason code | Reconciling A + B + C | 3-mo | Phase 1 |
| One-click auto-release | Reason service + write-back | 3-mo | Phase 1 |
The one question that decides Phase 0: can each system already tell us that it’s holding a payment — even if not cleanly why? That flag is the key dependency that makes a smaller Phase 0 possible.