Overview

Billing settings on the root-config.json file allow you to configure basic billing rules for policies issued under your product module. This includes basic features such as the billing currency and how frequently policies are billed. It also allows you to enable different payment method types that policyholders can use to pay premiums (such as debit orders, card payments, etc.), and to configure the settings associated with each payment method type.

Understanding these settings requires a basic knowledge of the standard Root billing rails. You can read more about how billing works on Root under the "Billing & payments" category (work in progress).

These are some of the key concepts used in this guide:

• Billing lifecycle - The process by which the platform determines the amount due for collection on a policy, raises the premium on the policy ledger, generates payments, and updates the policy ledger depending on the payment result.
• Payment - A payment represents a collection from the policyholder for the policy premium. Payments are actioned by a payment provider, such as a bank. A payment can represent a collection that will be actioned in future, or a collection that has been actioned in the past. Typically, the Root platform will create payments as part of the policy billing cycle, or a dashboard user will create one as an ad hoc collection request.
• Recurring payment - Payment of the policy premium due for the most recent billing period (month or year).
• Arrears payment - A payment to settle a negative balance on the policy ledger dating from before the most recent billing period. For example, past premiums that were not collected successfully.

In addition to these concepts, it also useful to understand the different dates associated with a given payment:

• Billing day - This an integer representing the day of the month that a policy's premium is due, e.g. 1, 15 or 31. This value is stored on the policy. Policies that are billed annually will also have a billing month to indicate which month of the year the policy should be billed.
• Billing date - This is the actual date that the premium becomes due. It correspond's to the policy's billing day. For example, if today is 1 July 2025, and a policy's billing day is 15, the next billing date will be 15 July 2025.
• Payment date - This is the target date for the payment to be collected from the policyholder. Typically, the payment date will be the same as the billing date. The only exception is for debit order collections, if the billing date falls on a Sunday or a public holiday (non-process days). In these cases the payment date will be the first process day before or after the billing date.

🚧

Billing settings have dependencies with the broader Root billing config

The billing settings exposed in Workbench do not include all product-specific billing configurations. There are interdependencies between these settings and the broader billing config for your product module.

When setting or changing your product module's billing settings using Workbench, we recommend that you consult with a Root advisor about how this may affect the full suite of available billing configurations. You can get in touch with us at [email protected].

Allow policy start date change

📘

Using alteration hooks to change the start date

By default, a policy's start date can only be changed if the original start date has not yet been reached. In addition, the start date cannot be moved to a date in the past. Start date changes that meet these criteria can be performed using alteration hooks.

If this setting is enabled, users will be able to change the policy start via a specific flow on the Root management dashboard. This includes changing the start date for policies that have already started, and moving the start date to a date in the past.

Such changes typically require an adjustment on the policy ledger, to account for the period of cover being reduced or increased relative to past premiums collected. Platform will automatically perform this calculation and the user will be able to confirm the resulting ledger debit or credit.

You can use the beforePolicyStartDateChanged and afterPolicyStartDateChanged lifecycle hooks to modify the behaviour of this action. For example, you can prevent a start date change if certain conditions are not met, or update the policy data after the start date change.

{
  "billing": {
    "allowStartDateChange": true,
    ...
  }
}

Billing frequency

This setting determines the default billing frequency for policies issued under your product module. You can override this setting for individual policies by configuring the billing frequency as part of the quote hook.

The majority of policies on Root are billed monthly. For policies with yearly billing, the full year's monthly premiums will be aggregated and billed in a single amount once per year. Note: The billing frequency only affects how the policy is billed. For policies that are billed yearly or once_off, the premium is still stored on the policy object under the monthly_premium parameter. Note that this will render on the Dashboard with the correct label and the billing jobs will raise the premium inline with the billing frequency utilising the value stored under monthly_premium. For yearly billing, the monthly_premium value will be multipled by 12 once raised.

{
  "billing": {
    "billingFrequency": "monthly",
    ...
  }
}

Consecutive failed payments allowed

This setting allows the user to set the number of failed payments allowed before a policy holder's payment method is blocked.

Note: If this setting is not explicitly defined, Root will use a default of 4 consecutive failed payments to block a payment method.

Note: Please note that this setting may be subject to regulation. Be sure that this setting aligns with the regulatory guidelines of your product.

📘

Retry payments count towards failed payments

Retry payments are treated the same by the Root platform as the original payment attempt. If you have enabled the retry failed payments setting, and any retries fail, this will will result in the payment method being blocked sooner.

{
  "billing": {
    "consecutiveFailedPaymentsAllowed": 5,
    ...
  }
}

Currency

This setting determines in what currency policies issued under this product module will be billed.

{
  "billing": {
    "currency": "ZAR",
    ...
  }
}

Enable billing on Sandbox

This setting enables the running of some billing operations in the sandbox environment for this module. With this setting enabled, clients may simulate what would happen in the daily billing cycle in a safe test environment without impacting the production environment.

Currently the following billing operations are supported when the flag is set to true:

• Debiting premiums on active policies
• Creating external payments
• Creating debit order payments
• Batching pending payments

{
  "billing": {
    "enableBillingOnSandbox": true,
    ...
  }
}

Retry failed payments

This setting applies to all payment method types. After payments are submitted, Root receives a notification from the payment provider if any payments have failed. In these instances, the payment can automatically be resubmitted by the platform. This setting enables or disables such resubmissions, and configures the retry behaviour.

🚧

Retry payments count towards failed payments

If any of the automatic payment resubmissions fail, this will add to the count of failed payments on the payment method and the policy. Therefore changing this setting will affect the behaviour of the consecutive failed payments allowed setting and the lapse rules settings.

If this setting is enabled, you can configure the total number of retries the platform will attempt, and how many days the platform will wait before submitting each retry. The number of days is counted from the original payment date to the retry payment date (accounting, where applicable, for the submission lead time for debit order collections).

Note: Root does not currently impose any limits on the number of retries or the days between retries. You need to ensure that this setting compliant with any applicable regulations. As a guideline, we recommend no more than two automatic retries with five days between retry attempts.

{
  "billing": {
    "retryFailedPayments": {
      "enabled": true,
      "daysBetweenRetries": 5,
      "numberOfRetries": 2
    },
    ...
  }
}

Properties

Pro rata billing

Pro rata billing is relevant if a policy's first billing day falls after the policy start date. The pro rata amount is calculated as (next_billing_date - start_date) / (next_billing_date - previous_billing_date) * premium.

Let's consider an example policy with a start date of 1 July and a billing day of the 16th. Let's assume this policy is billed monthly with a premium of $100. The pro rata amount for this policy will be (16 July - 1 July) / (16 July - 16 June) * 100. This equals (15 days) / (30 days) * $100 = $50.

If this setting is disabled, the pro rata amount will not be billed to the policyholder at all. If this setting is enabled, the pro rata amount will be billed to the policyholder in one of two ways, depending on the proRataBillingOnIssue property. If set to true, the policyholder will be billed the pro rata amount on the policy start date (or as soon as the payment method is verified after the start date). If set to false, the pro rata amount will be billed together with the first premium on the policy's first billing date.

Note: Irrespective of this setting, a pro rata payment will always be created if the billing day is changed on an active policy that has already started.

{
  "billing": {
      "proRataBilling": {
        "enabled": false,
        "proRataBillingOnIssue": false,
        "minimumAmount": 0
      },
   ...
  }
}

Payment method types

This setting is used to determine which payment method types can be selected and linked to policies issued under your product.

{
  "billing": {
    "paymentMethodTypes": {
      "debitOrders": {
        "enabled": true,
        "naedoPoliciesInArrears": true,
        "strategy": "best_effort"
      },
      "card": {
        "enabled": false
      },
      "eft": {
        "enabled": false
      },
      "external": {
        "enabled": false,
        "createPayments": false
      }
    },
    ...
  }
}

Root debit orders

If this setting is enabled, policyholders will be able to use out-of-the-box native Root debit orders to pay their premiums.

These are some important concepts to understand in relation to debit orders:

• Submission day - Days when Root submits debit order payment batches to the bank. Any day that is not a Saturday, Sunday or public holiday is a submission day.
• Process day - Days when banks process debit order collections. Any day that is not a Sunday or a public holiday is a process day.
• Action date - The date that the debit order collection is actioned by the bank and strikes the policyholder's bank account. This date is the same as the payment date, except in the case of NAEDO or DebiCheck debit orders, in which case the collection will start tracking on the on the policyholder's bank account before the payment date. In these cases, the action date will (by default) be two process days before the payment date.

If debit orders are enabled on your product, you will need to choose the debit order collection strategy. The chosen collection strategy has cost implications, as each strategy attracts different transaction fees from the bank.

Debit order collections can be divided into two types:

• EFT collections: Normal collections actioned by the bank as an EFT. No special mandates are required, and the bank does not track collections on the policyholders bank account. Includes two-day payments, where payments are submitted to the bank at least two days before the action date, and same-day payments, where payments can be submitted to the bank on the action date.
• DebiCheck collections: The customer has electronically mandated (confirmed) the debit order via the DebiCheck process. The customer's bank account is first struck two process days before the payment date. The bank then tracks the collection on the customer's bank account for five process days, meaning that if the collection failed on the first attempt, the customer's bank account will be struck again the next process day, up to a maximum of five collection attempts.

You can select one of the following collections strategies for debit orders:

Card

If this setting is enabled, policyholders will be able to use credit and debit cards to pay their premiums. The following credit and debit cards are accepted (among others):

• VISA
• MasterCard
• Maestro
• AmericanExpress

EFT

If this setting is enabled, policyholders will be able to make ad hoc EFT (electronic funds transfer) payments. This is useful, for example, if an automated collection fails and the customer wants to settle their account by making an ad hoc bank transfer.

External

If this setting is enabled, you will be able to add payment methods with an external account number. This is useful, for example, if you will be using an external payments provider to process payments, or if you are using your own customer account system to process payments.

If enabled, you need to select whether the Root platform will generate payments as part of the billing lifecycle, which will then be processed by the external payments provider. Alternatively, the external payment system could generate the payments itself and simply send the updated policy balances to Root.

Client statement reference

Note: This setting applies only to Root debit orders. For card payments, the reference on the policyholder's statement is specified when you set up your profile with Peach Payments.

This setting is used to customise the string that will be prepended to the payment reference on the customer's bank statement for premium collections. This serves two purposes:

1. Provides the account holder with detail on the source of the payment that has been deducted from their account.
2. Ties the payment response back to the original payment object to allow the Root platform to update the payment status.

The statement reference string must match the CPS short name configured on your Nedbank profile. The maximum number of characters is 10.

The final reference on the accountholder's bank statement will consist of the following strings appended together:

• The CPS short name which you need to specify (10 characters).
• The policy number. In the event of an arrears payment, ARR will be prepended to the policy number (14 characters).
• The date in the format YYMMDD (6 characters).

Examples:

• Recurring payment on 1 October 2021: DINOSURE     437C711E53211001
• Arrears payment on 1 October 2021: DINOSURE ARR 437C711E53211001

{
  "billing": {
    "clientStatementReference": "DINOSURE",
		...
  }
}

Bill before weekend enabled

Note: This setting is only relevant for Root debit order collections.

This setting determines billing behaviour if the policy billing date falls on a Sunday or public holiday. These are not process days and banks cannot action debit order collections on these days. By default, the payment date will fall on the first process day after the billing day. For example, if the billing date falls on a Sunday, the collection will be actioned on the Monday (assuming that the Monday is not a public holiday).

If this setting is enabled, the default behaviour is reversed, and the payment date will be the last process day before the Sunday or public holiday. For example, if the billing date falls on a public holiday on Wednesday, the payment will be submitted to be actioned on Tuesday. Note: Saturdays are process days so if the default billing date falls on a Sunday, the payment date will be on the Saturday.

{
  "billing": {
    "billBeforeWeekendEnabled": false,
    ...
  }
}

Payment submission lead time

Note: This setting applies to Root debit orders and external payment methods.

This setting causes a payment to be submitted the specified number of days prior to its default submission date. For example, by default a two-day debit order payment will be submitted two days before the action date. If the payment submission lead time is set to one day, the payment would instead be submitted three days before the action date.

{
  "billing": {
    "paymentSubmissionLeadTime": 0,
    ...
  }
}