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:
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. |
|
write-off |
The amount stated on the catch-up invoice goes directly to the cash balance. |
|
invalidate |
No impact. |
|
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 |
|
Pay ahead of invoice issuance |
|
Suspense (holding cash) |
|
Transfer payment from one policy to another |
For an unassigned payment, no remediation is needed. For an assigned (“posted”) payment, there are two options:
|
Split a payment across policies |
Options:
|
Lump sum payment |
|
Spread negative endorsement balance to future transactions |
|
Partial invoice writeoff |
|