Skip to main content

End-to-end payment lifecycle

Status: Proposed workflow. Timing, funds finality and retry rules require partner and merchant validation.

1. Bill submission​

A merchant sends a bill approximately 10 days before its due date, using a merchant-scoped external bill ID, amount in AUD cents, due date, customer reference and bill version. The API validates merchant identity, customer mapping, mandate scope, duplicate submissions and version changes. A repeated idempotency key must return the original outcome, not create another bill.

2. Consumer notification​

Sparelane notifies the consumer of the upcoming bill, the proposed payment date and selected primary method. The consumer can review the bill and authorised method choices. Notification delivery is recorded but is not evidence of payment consent on its own.

3. Collection​

The system schedules collection around 3 days before the due date, subject to provider cut-offs, business days, the merchant's rules and the consumer's mandate. A durable worker checks the bill version, mandate status, available methods, amount limits and existing in-flight attempts before submitting an idempotent provider request.

4. Backup and recovery​

If the first attempt fails, a retry decision evaluates whether the decline is eligible for another attempt, whether another method is expressly authorised, provider/network retry rules and the remaining time until due. Do not retry hard declines, revoked mandates or potentially successful/unknown attempts. The platform never guarantees recovery.

5. Settlement and payout​

Authorisation, capture, settlement and funds available for payout are different states. The regulated partner confirms the eligible amount; the ledger records the corresponding entries and reserves the funds for payout. Sparelane sends an aggregated merchant payout instruction with per-bill allocations, then reconciles partner statements and bank movements.

6. Failure and exceptions​

If all authorised attempts fail, notify the merchant and consumer with actionable status. Handle disputes, chargebacks, reversals, refunds, delayed settlement and merchant payout returns as independent workflows. Never silently mark an obligation paid merely because an API request was accepted.

Suggested bill states​

DRAFT, SCHEDULED, COLLECTION_PENDING, PARTIALLY_COLLECTED, COLLECTED, FAILED, CANCELLED, EXCEPTION. Financial attempt, settlement and payout statuses are tracked separately. A bill may be collected but not yet paid out.

Invariants​

  • Never charge above the authorised amount or outside mandate scope.
  • Prevent concurrent duplicate collection across workers.
  • Do not move a bill to collected based on an ambiguous provider outcome.
  • Preserve an immutable history of bill changes and attempts.
  • Every payout allocation must trace to eligible settled funds.