Custom payments integration

🚧

Deprecated feature

Please note that this functionality is approaching end-of-life and will be replaced by collection modules. To build a custom payment integration, refer to the collection module guides instead.

Collecting premiums for policies issued on the Root platform can be achieved in a variety of ways, leveraging any payment provider service or system. This ranges from using providers such as Stripe, with its broad range of payment method types in multiple countries, to doing billing on an internal on-prem credit system.

This section guides you to set up a payments integration to an external system that you control. Typically this would be an integration into a credit system, a central payments service built and managed by your team, or a 3rd party payments provider that’s not yet integrated to Root.

📘

Managed payment providers

Root supports select payment providers out of the box, pre-integrated. These integrations are managed by Root and ensure that clients can get up and running with lower friction. See the documentation for using Stripe (global), Debit orders (South Africa), or Credit cards (South Africa).

Setting up a payments integration with Root requires three components:

• Configuration & rules of how the engine should behave.
• Payment instructions telling your system what premiums should be billed.
• Create or update payments from your system on Root to ensure proper record is kept and required side-effects are triggered.

Payment process

The payment process is important to understand when doing a custom integration for premium collection. The process follows the following flow:

1. On a daily basis, the Root platform reviews policies’ balances together with the configured payment lead-time to determine if a payment needs to be created for each respective policy in your organization.
2. Payments are batched up into batches of 500 payments. Payments are split into batches that contain the same action_date, collection_type and payment_method_type respectively. (Note: the batch size can be increased in the future, please ensure your system is capable of handling a change in size)
3. Payment batches are sent through to your system daily between Monday-Friday (not including public holidays). See Payment instructions for more details on the different methods that Root can use to deliver payment instructions to your system.
4. Your system processes the received payment instructions. It’s recommended to first queue the instructions before processing them.
5. Payment results (statuses) are sent back to Root to update the original payments and fire off the relevant payment lifecycle hooks and webhooks.

Below is a diagram visualizing how your system can be integrated to Root’s payment rails.