End-to-end user stories
Status: Proposed acceptance baseline. IDs are stable references; acceptance criteria must be validated with product, partner and legal stakeholders.
US-001 — Merchant activates
As a merchant administrator, I want to complete onboarding and connect billing systems so that eligible bills can be collected.
Given an invited merchant, when it provides required legal entity, contacts, agreements, verified payout destination and partner approval, then it can receive production credentials only after integration certification and activation approval. Missing checks keep the merchant inactive. All approvals and changes are audited.
Trace: Merchant onboarding; merchant portal M07/M08; Merchant, MerchantVerification, MerchantAgreement, PayoutDestination; API credentials; KYB tests.
US-002 — Consumer links merchant and grants mandate
As a consumer, I want to link my existing account to a merchant and authorise specific methods so that Sparelane can collect future bills within my chosen scope.
Given a valid invitation, when identity linkage is verified and the consumer accepts a versioned merchant-specific mandate, then the relationship becomes active. Email matching alone is insufficient. A method available for Merchant A is not automatically authorised for Merchant B.
Trace: Consumer C01/C03/C05; ConsumerMerchantLink, PaymentMandate, ConsentEvidence, PaymentPreference; linking and consent tests.
US-003 — Merchant submits bill
As a merchant integrator, I want to submit a bill once and retrieve its status so that duplicate network requests cannot create duplicate charges.
Given an active merchant and eligible consumer relationship, when a valid bill is submitted with an idempotency key, then Sparelane stores one versioned bill and schedules eligible collection. Repeating the same key and payload returns the original result; a different payload with the same key returns conflict.
Trace: Merchant M03; POST /v1/bills; Bill, BillVersion, IdempotencyKey, OutboxEvent.
US-004 — Primary collection succeeds
As a consumer, I want an authorised primary method used at the communicated time so that the merchant can receive my bill payment.
Given an active mandate and scheduled bill, when the payment provider confirms settlement and funds eligibility, then Sparelane records a single collection and corresponding balanced ledger journal. Pending provider acceptance does not count as final settlement.
Trace: Consumer C02/C06; merchant M04; PaymentAttempt, Collection, SettlementRecord, LedgerTransaction.
US-005 — Primary fails and backup succeeds
As a consumer, I want an expressly authorised backup method attempted when eligible so that a recoverable decline does not unnecessarily leave the bill unpaid.
Given a retryable primary decline and active backup authorisation, when policy and network rules permit, then one backup attempt is created and its result tracked. Hard decline, revoked mandate, expired collection window or unknown primary outcome prevents unsafe fallback. Notify parties appropriately.
Trace: Payment lifecycle, state machines, consent; consumer C05/C06; merchant M04.
US-006 — All eligible attempts fail
As a merchant operator, I want a definitive failure notice so that I can manage the customer's outstanding obligation.
Given all authorised methods are exhausted, when no provider attempt remains unresolved, then collection is marked failed and consumer/merchant receive actionable notices. Sparelane does not guarantee payment or silently initiate another method.
US-007 — Settlement and full-value payout
As a merchant finance user, I want a reconciled payout containing full bill proceeds so that I can match deposits to invoices.
Given $120 settled and eligible, when payout allocation is reserved and partner completion confirmed, then the merchant receives $120 (subject to any separately disclosed and legally required exceptions). The Sparelane success fee is assessed and invoiced separately, not silently netted. Payout allocations cannot be double-used.
Trace: Merchant M05/M06; Collection, LedgerEntry, Payout, PayoutAllocation, FeeAssessment.
US-008 — Consumer revokes mandate
As a consumer, I want to revoke a merchant's collection authorisation so that no new payments are initiated under it.
Given an active mandate, when revocation is confirmed, then future initiation is blocked, evidence is preserved and already-submitted payments are shown as potentially in flight. The merchant is notified as permitted.
US-009 — Refund or dispute
As an operations user, I want to investigate and process refunds/disputes so that customer and merchant outcomes remain traceable.
Given a settled payment, when a permitted refund or dispute event occurs, then the case links to the original collection, partner references, approval and compensating ledger entries. Original posted journals remain immutable.
US-010 — Provider timeout and recovery
As an operator, I want an unknown provider outcome held for reconciliation so that a timeout cannot trigger a duplicate charge.
Given an initiated attempt, when the provider times out, then the attempt becomes UNKNOWN and a lookup/reconciliation job is scheduled. No new charge is submitted until the previous outcome is resolved or a provider-guaranteed idempotent replay is proven safe.
US-011 — Payout returned
As a finance operator, I want a returned payout investigated so that merchant payable and safeguarded funds remain correct.
Given a payout submitted to the provider, when it returns, then the system records the return, reconciles balances, places affected funds on hold if necessary and notifies the merchant without incorrectly reporting completion.
US-012 — Tenant isolation
As a merchant administrator, I want my business data isolated so that another merchant cannot access it.
Given valid credentials for Merchant A, when requests reference Merchant B bills, consumers, payouts or invoices, then access is denied without disclosing whether the target exists. Tests cover all routes, exports, webhooks and background jobs.
Definition of story completion
Each story needs approved UI copy, OpenAPI/contract changes, data migration where applicable, event design, permissions, observability, failure modes, automated acceptance tests and operational runbook updates. No story handling real funds is complete without ledger and reconciliation evidence.