Create or update payments

When your system has processed payment instructions or created new payments, it’s important to update Root with the payment results. This allows side-effects such as payment lifecycle hooks and webhooks to trigger correctly, and for data records to be accurate for accounting purposes.

The reasons you need to keep payments accurately synced to Root includes:

• Side-effects such as payment lifecycle hooks and webhooks are triggered correctly, ensuring the product module behaves as expected (e.g. policies are appropriately lapsed when a consecutive payments fail)
• Various teams downstream rely on accurate payments data in order to analyze and report on performance of the insurance business.
• Payments information on Root is used for regulatory reporting.
• Accurate payment information and statuses on a policy allow for better customer service and debugging of customer issues.

Updating payments

When Root has created payments that your systems received to process, you need to keep Root updated with status changes on those payments.

Root processes payment updates asynchronously, so the platform will queue your updates upon receipt. You can therefore expect a slight delay between updating a payment and the changes reflecting on Root.

The preferred way to update payments on Root is with the update payments async endpoint.

You can update a payment status to one of the following: pending, submitted, processing, failed, successful, or cancelled.

Example payments update request looks as follows:

[
  {
    "payment_id": "128ba0c0-3f6a-4f8b-9b40-e2066b02b59e",
    "status": "successful"
  },
  {
    "payment_id": "bd0c2ab2-4bf9-4786-9d90-0588fdff2600",
    "status": "processing"
  },
  {
    "payment_id": "0463e674-ff1b-475d-901b-c37b01ab1ef6",
    "status": "failed",
    "failure_reason": "Not provided for",
    "failure_action": "block_retry"
  },
  {
    "payment_id": "96e06845-6d37-4dca-8859-9d8ed27dcf58",
    "status": "failed",
    "failure_reason": "Account closed",
    "failure_action": "block_payment_method"
  }
]

Create payments

Creating payments directly onto Root can be done through either API or CSV uploads. This would typically be used if billing logic runs off-platform, such as when createPayments is set to false, and Root depends on your system to determine when to create payments for policies.

Create payments through API

You can create payments on Root synchronously using the create payment endpoint.

Create payments with CSV uploads

Often it’s easiest to simply upload payment files created by your system without writing code. This typically happens when legacy systems that are difficult to update or change are at play, or when you need to get live fast.

To upload payments, use the Data Imports tool.

You can go live with using CSV uploads and then seamlessly switch over to an API integration at any point in time.