Cash Management

Overview

Cash Management enables flexible payment management and invoice settlement, allowing you to do all of the following:

Use a “cash balance” associated with each policy to track accumulated over- or underpayment against settled invoices.
View cash balance summaries at policy and policyholder levels.
Record payments even without an invoice, policy, or policyholder.
Assign payments to invoices, even if amounts do not match.
View all tenant payments in one place, with filtering capabilities.
Issue and manage catch-up invoices and disbursements.
Configure document templates for catch-ups and disbursements.
Specify optional or required reasons for payment reversals.
Listen on all cash management events.
Query Data Mart for information related to Cash Management entities and actions.

Configuration

You can migrate to Cash Management without changing any of your existing workflows: all existing payment and invoice endpoints work as they did before, and you can continue to settle invoices with “on the fly” payments. Cash Management simply elevates payments to first-class entities in the system, and allows you greater flexibility through the use of cash balances and associated actions. See the Common Patterns section for examples of the flows that Cash Management enables.

Feature Flag

Cash Management can be activated with the property.cash.management.enabled flag.

Note

Cash Management activation cannot be reversed. Premium Reporting is not compatible with Cash Management, and attempts to deploy configurations with both Premium Reporting and Cash Management will fail.

cashmanagement.json

The new <root>/cashmanagement/cashmanagement.json file houses configuration for disbursements, cash transfers, and payment reversals. Here is an example configuration featuring all three components:

{
    "disbursement": {
        "fields": [
            {
                "name": "field_name",
                "title": "Field Title",
                "type": "string"
            }
        ]
    },
    "cashTransfers": [
        {
            "name": "misapplication",
            "displayName": "Misapplication Remediation",
            "requireDetails": true
        }
    ],
    "reversals": [
        {
            "name": "insufficient.funds",
            "displayName": "Insufficient Funds",
            "requireDetails": false
        }
    ]
}

cashmanagement.json must have a valid cashTransfers stanza to enable cash transfers. Disbursements and payment reversals are possible without explicit configuration in cashmanagement.json, which simply allows for the optional specification of custom fields for disbursements and “reasons” for payment reversals.

Components

Cash Balances

A policy receives an associated cash balance once it reaches the accepted state. This cash balance endures even if an accepted quote is invalidated or an issued policy is canceled.

A cash balance has a fixed association with exactly one policy. Its value is always the difference between the sum of the total due amount on paid invoices and the value of the payments associated with those invoices.

For example, given the following set of issued invoices and their associated payments, the cash balance will be $5.00, since the total due on invoices is $60.00 and the total value of their associated payments is $65.00.

Outstanding invoices have no impact on the value of the cash balance. If another $20.00 payment were to be issued in the example above, the cash balance value would not be recalculated until invoice settlement with another payment.

Cash management maintains the existing model in which an invoice can be associated with at most one payment. See the “Common Patterns” section of this guide for information on ways to accommodate more complex payment requirements.

Payments

A payment record can be created even if there is no known policy, policyholder, or invoice with which it will be associated. Payments can be moved along a fixed set of states:

Payment States
State	Description
draft	Initial state for all new payment records, allowing property edits.
ready	“Ready to post”: the payment is ready to be used for invoice settlement.
posted	The payment is bound to a settled invoice.
returned	The payment has been returned to the customer.
declined	The payment is invalid in some way.
discarded	The payment record is no longer needed.

In the initial draft state, a payment’s properties and custom fields can be modified. Once a payment leaves the draft state, its attributes cannot be changed unless the payment is reset to draft. The faded dashed lines indicate state reversion; note that discarded is a terminal state, and that a posted payment can only be moved back directly to ready. A payment is posted after it is used to settle an invoice, establishing a link to that invoice.

In order for a payment to be used to settle an invoice, it must be in the ready [to post] state. The move from draft to ready incurs validation checks to ensure that all required fields are present and that the payment has a target policy locator.

Payment Reversals

The existing payment reversal endpoint is still used to conduct payment reversals under Cash Management, with the same fundamental effect: a payment reversal severs the relationship between the payment and the invoice that it settles, putting the invoice back into an outstanding state. Under Cash Management, however, the payment reverts to the ready state and can be managed like any other payment object.

The cashmanagement.json configuration allows for the specification of “reasons” for payment reversal, in case you would like to define valid reversal conditions and persist associated information. Such specification is entirely optional. The following is an example of payment reversal configuration in cashmanagement.json:

{
    "reversals": [
        {
            "name": "user.error",
            "displayName": "User Error"
            "requireDetails": true
        },
        {
            "name": "insufficient.funds",
            "displayName": "Insufficient Funds"
            "requireDetails": false
        },
        {
            "name": "customer.not.authorized",
            "displayName": "Customer Advises Not Authorized",
            "requireDetails": true
        },
    ]
}

The requireDetails property adds a validation requirement, and is false by default. Details can be provided, and will be persisted, for any payment reversal; setting requireDetails: true blocks payment reversal for that particular reason unless details are included.

Disbursements

Disbursements allow for the return of cash to the customer, directly from the cash balance.

As with payments, disbursements begin in an editable draft state and can be advanced to other states. The model is simpler:

Both issued and discarded are terminal states. When a disbursement moves to issued, the disbursement amount is drawn directly from the cash balance; for example, a $50 cash balance will fall to $30 upon issuance of a $20 disbursement.

Disbursement Configuration

Custom fields for disbursements can be specified in the new <root>/cashmanagement/cashmanagement.json file. This specification is not required to create and manage disbursements, which do not require custom data fields.

{
    "disbursement": {
        "fields": [
            {
                "name": "field_name",
                "title": "Field Title",
                "type": "string"
            }
        ]
    }
}

Like payments, disbursements do not support group fields.

Disbursement Documents

To generate a document on disbursement, create a <productRoot>/policy/disbursement.template.liquid Liquid template file. Disbursement document templates have access to all the common template data, along with a data.disbursement_details object with the following properties:

amount
amount_currency
issued_timestamp
field_values

The disbursement document template is an optional configuration element. If it is omitted from configuration, no documents will be generated for issued disbursements.

Catch-Ups

Catch-ups allow you to remind the customer of a cash balance shortfall, collecting against the catch-up invoice. They allow for the specification of an amount and a due timestamp, but differ from conventional invoices in a few important ways:

Catch-ups have no notion of a “start” or “end” coverage period.
Grace and lapse does not apply: catch-up due dates must be enforced manually.
Financial transactions are always of type “cash”.

A catch-up can be issued manually, and can then be settled with a payment, written off, or invalidated.

Catch-Up Documents

To generate a document on catch-up issuance, create a <productRoot>/policy/catchUp.template.liquid Liquid template file. Catch-up document templates have access to all the common template data, along with a data.catch_up_details object with the following properties:

total_due
total_due_currency
due_timestamp

The catch-up document template is an optional configuration element. If it is omitted from configuration, no documents will be generated for issued catch-ups.

Catch-Ups and Cash Balance Calculation

Settlement, write-off, and invalidation of catch-ups affect the cash balance in the following ways:

Action	Cash Balance Effect	Example
settle	The amount stated on the settlement payment goes directly to the cash balance.	($50) cash balance Catch-up issued for $50 Catch-up settled with $50 payment Cash balance is now $0
write-off	The amount stated on the catch-up invoice goes directly to the cash balance.	($50) cash balance Catch-up issued for $50 Catch-up written off Cash balance is now $0
invalidate	No impact.	($50) cash balance Catch-up issued for $50 Catch-up invalidated Cash balance remains at ($50)

Cash Transfers

Cash transfers allow for the movement of funds between any two cash balances in a tenant. To enable them, a cashTransfers stanza must be present in the cashmanagement.json configuration file. A sample cash transfer configuration follows:

{
    "cashTransfers": [
        {
            "name": "misapplication",
            "displayName": "Misapplication Remediation",
            "requireDetails": true
        },
        {
            "name": "multi.policy.payment",
            "displayName": "Multi Policy Payment",
            "requireDetails": false
        }
    ]
}

As with payment reversal configuration, the requireDetails property adds a validation requirement, and is false by default. Setting requireDetails: true blocks cash transfers of that type unless details are included.

Cash Balance Log

The Cash Balance Log provides a convenient way to understand all the transactions that led to a cash balance’s current state. All transactions that could have a direct impact on cash balances, such as cash transfers and invoice settlement, are recorded in the cash balance log. This endpoint works in a fashion analogous to the event stream and provides several filtering capabilities, along with additional data in the returned objects, reducing the need for additional data fetches.

See the Cash Management API for details.

Enhancements

Event Stream

Cash Management introduces new event stream events for payments, disbursements, catch-ups, and cash transfers. See the event stream API for a complete listing of events and their properties.

Data Mart

Data Mart exposes several new tables related to Cash Management:

cash_balance
disbursement
cash_balance_log
catchup_invoices
disbursement_fields

See the Data Mart Guide for details.

Roles and Permissions

Roles and Permissions have been augmented to provide granular control over Cash Management activities. See the Permissions Reference for a complete listing of endpoints and associated permissions.

Core UI Highlights

See the Cash Management UI Overview.

Common Patterns

Note

Cash Management introduces the notion of a “nominal” payment, which is a 0-value payment used to draw funds from the cash balance on invoice settlement. Given the fundamentals of Cash Management, when you settle a $40 invoice with a $0 (nominal) payment, the net difference between the invoice amount and the payment (all $40) is drawn from the cash balance.

Core UI makes use of nominal payments when allowing an invoice to be paid with the cash balance: behind the scenes, a $0 payment is created and assigned to settle the invoice, inducing a draw of the entire invoice amount from the cash balance.

Use Case	Procedure
Accept more or less money then invoiced premium	Create a payment and realize it. Pay an invoice with the payment. Net difference goes to the cash balance.
Pay ahead of invoice issuance	Create a payment and advance it to “ready”. Apply the payment when the invoice is issued.
Suspense (holding cash)	Create a payment and leave as draft, or advance it to “ready”. Apply the payment when an appropriate invoice is issued.
Transfer payment from one policy to another	For an unassigned payment, no remediation is needed. For an assigned (“posted”) payment, there are two options: Reverse the payment. Reapply the payment to an issued invoice on the appropriate policy.
Split a payment across policies	Options: Create distinct payment objects with metadata to understand the grouping relationship. Apply the payment to one policy’s invoice and then conduct cash transfers to other policy balances, paying their invoices with nominal ($0) payments.
Lump sum payment	Apply the payment to an issued invoice. Change the payment schedule to up-front. Pay the outstanding up-front invoice with a nominal payment.
Spread negative endorsement balance to future transactions	Pay the refund invoice with a nominal payment. Use the cash balance in subsequent invoice payments.
Partial invoice writeoff	Apply (under)payment to the issued invoice. Issue a catch-up invoice for the value to be written off (i.e., the net difference between the settlement payment and the invoice’s “total due”). Write off the catch-up invoice.