Collection lifecycle

Understand which parts of the billing lifecycle Root handles natively and which parts your collection module code controls.

For native collection methods, Root handles the core billing lifecycle: calculating the amount due on a policy, raising the premium, generating collections, submitting payments, and updating the policy balance from the collection result.

When you use Collection Modules, your module code controls the provider-specific collection behaviour. Use Root lifecycle events to react to policy, payment, and alteration events in your collection module.

For failed collections, Root automatically lapses policies, or marks them as "not taken up", according to the lapse rules configured on the product.

Collection lifecycle summary

The Root billing lifecycle is summarised below at a high level. These steps are generally completed at a daily interval.

• Raise premiums — Root determines which policies are due to be billed based on their billing day, and debits the policy ledger with the amount due. Root supports monthly billing, yearly billing, and once-off billing.
• Create payments — Root creates collections to be actioned. The type of collection created for a policy depends on the outstanding balance, the policy's collection history, and the collection method linked to the policy. Examples of collection types include:
  • Recurring collections - A policy's monthly or yearly premium that has most recently been raised.
  • Arrears collections - Outstanding payments that were missed prior to the current billing period.
  • Pro rata collections - Platform creates one-off pro rata collections when the policy's billing day does not match the policy start date.
  • Ad hoc collections - Dashboard users (agents) can create ad hoc collection requests for policies.
• Review collections — Before collections are submitted to the payment provider, Root performs automated checks to validate the collection.
• Submit payments — Collections are submitted to the collection provider linked to the policy.
  • Collection modules — Payments are submitted according to the payment integration logic defined in the collection module.
  • Native debit orders — Root submits payments to Nedbank, taking into account the required processing times for different debit order types.
• Process payment responses — Depending on the payment provider, Root receives responses through a callback endpoint or a flat file. Root updates the collection status and, for successful collections, adds a corresponding credit entry to the policy ledger.

Root automatically assumes that a payment was successful if it does not receive a payment failure notification within five days.

If a failed payment notification is received more than five days after the submission date, Root creates a corresponding payment reversal and debits the policy ledger with the outstanding amount.