Bill pay lifecycle - Nectar Knowledge Base

This guide covers the bill pay lifecycle from a developer’s perspective — the statuses a bill can occupy, valid transitions between them, and how external events (deletion, revision, charge changes) affect in-flight cycles.

Cycle overview

Every bill that enters the bill pay pipeline gets a cycle — a stateful object that tracks the bill’s position in the payment lifecycle. The cycle progresses through a series of statuses driven by automated evaluation, manual actions, and external signals.

Status reference

Status	Category	Description	Terminal?
`UNVALIDATED`	Initial	Bill entered the cycle, checking for data quality issues	No
`VALIDATED`	Pre-routing	Bill passed validation, awaiting review	No
`PENDING_ROUTING`	Pre-routing	No routing rules matched; waiting for manual assignment	No
`DELIVERED`	Terminal	Bill forwarded to AP team or ERP system	Yes
`FUNDING_REQUESTED`	In-flight	Centralized path: waiting for customer funding	No
`FUNDING_RECEIVED`	In-flight	Funds received, vendor payment being initiated	No
`PAYMENT_PROCESSING`	In-flight	Payment in progress with provider	No
`PAID`	Terminal	Vendor paid successfully	Yes
`PAYMENT_FAILED`	Terminal	Payment attempt failed	Yes
`CANCELLED`	Terminal	Cycle cancelled (bill deleted, or manual action)	Yes
`NO_PAYMENT_REQUIRED`	Terminal	No payment needed for this bill	Yes
`IN_EXCEPTION`	Parked	Issue raised; cycle pauses, resumes on resolution	No
`IN_DISPUTE`	Parked	Dispute opened; cycle pauses, resumes on resolution	No

State transitions

Primary flow (delivered path)

UNVALIDATED → VALIDATED → [rule evaluation] → DELIVERED

If no rules match:

VALIDATED → PENDING_ROUTING → (manual assignment) → DELIVERED

Primary flow (centralized path)

UNVALIDATED → VALIDATED → FUNDING_REQUESTED → FUNDING_RECEIVED → PAYMENT_PROCESSING → PAID

Payment failure:

PAYMENT_PROCESSING → PAYMENT_FAILED

Exception and dispute parking

Any non-terminal status can transition to IN_EXCEPTION or IN_DISPUTE. When resolved, the cycle restores to its prior status and resumes from that point.

VALIDATED → IN_EXCEPTION → VALIDATED (restored)
FUNDING_REQUESTED → IN_DISPUTE → FUNDING_REQUESTED (restored)

Cancellation

Most non-terminal statuses can be cancelled:

UNVALIDATED / VALIDATED / PENDING_ROUTING / FUNDING_REQUESTED / FUNDING_RECEIVED → CANCELLED

Terminal statuses

Once a cycle reaches a terminal status, no further transitions occur:

PAID — vendor paid successfully
DELIVERED — bill forwarded to AP/ERP
CANCELLED — cycle terminated
PAYMENT_FAILED — payment attempt failed, flagged for attention
NO_PAYMENT_REQUIRED — bill doesn’t require payment
REFUNDED — payment was refunded
ARCHIVED — cycle archived administratively

In-flight statuses (special handling)

The statuses FUNDING_REQUESTED, FUNDING_RECEIVED, and PAYMENT_PROCESSING represent cycles where real money movement may have begun. If a bill is deleted or revised while in one of these states, the cycle is cancelled and flagged for manual reconciliation rather than being silently terminated.

Bill lifecycle events

Bill deletion

Cycle state	Behavior
Terminal (including `PAID`)	Event logged; no state change
In-flight	Cancelled + flagged for manual reconciliation
All other non-terminal	Cancelled

Bill revision

When a bill is revised (superseded by a corrected version), the old cycle is cancelled following the same rules as deletion. The new bill version creates a fresh cycle if bill pay is enabled.

Charge amount change

Cycle state	Behavior
Terminal	No action
In-flight	Amount change logged + flagged for attention
`VALIDATED`	Cycle cancelled with reason “amount changed”
All other	Amount change logged

Late-risk escalation

Bills with a due date are monitored for late-payment risk. Three escalation tiers are calculated from dueDate - bufferDays:

Tier	Trigger	Default timing
WARNING	`dueDate - bufferDays`	7 days before due
URGENT	`dueDate - (bufferDays / 2)`	~3-4 days before due
CRITICAL	`dueDate - 2 days`	2 days before due

The buffer is configurable per company. Each escalation tier sends notifications to users matched by notification rules. The timer is cancelled when the cycle reaches a terminal status.

Bill Pay overview — end-user introduction
Funding overview — customer-facing status tracking
Bill pay rules API — creating rules programmatically

​Cycle overview

​Status reference

​State transitions

​Primary flow (delivered path)

​Primary flow (centralized path)

​Exception and dispute parking

​Cancellation

​Terminal statuses

​In-flight statuses (special handling)

​Bill lifecycle events

​Bill deletion

​Bill revision

​Charge amount change

​Late-risk escalation

​Related pages