Excess Credits

Overview

Typically, funds flow in one direction only within an insured’s billing account: inward. Customers accrue charges based on provided coverage, and they send payments to cover those charges. Occasionally the funds can move in the other direction, where the carrier must send a disbursement back to the insured. This can happen in situations like:

  • Return premium from policy changes that reduce overall premium

  • Cancellations

  • Overpayments

  • Erroneously sent or applied payments

  • Reallocating payments such that greater amounts are allocated to credit balances

  • Ad-hoc credits

To avoid accrual of too much credit for any particular account, you can use rules about when and how credits beyond a desired threshold are to be returned or otherwise used.

Configuration

Automatic handling of excess credits requires creating one or more Excess Credit Plans, each of which describe the rules for handling excess credits. Each insured account in the system can be assigned an excess credit plan, and then the rules for that plan will be activated for that account.

An excess credit plan looks like this:

ExcessCreditPlanRef
required
advanceDisbursementTo Enum draft | validated | approved | executed | reversed | rejected | discarded
autoApplyExcessToInvoicesEnabled boolean
disburseExcess boolean
Set to true to enable excess funds handling for the plan.
disbursementType string
The type of the disbursement to be automatically created.
excludeDebits Enum none | pastDueInvoices | allInvoices | invoicesAndUnbilledInstallments
Which pending debits should be considered for determining how much of the credit to retain
disbursementThresholds map<string,number>

The disbursementType property should be set to one of the disbursement types configured in the system.

The advanceDisbursementTo property allows you to specify the state the system should advance automatic disbursements to, enabling a step for review or custom processes before the disbursement state is progressed further via API. This property should be set to draft, validated, approved, or executed, and defaults to executed if not provided.

Process

If an excess credit plan is assigned to an account and that plan has disburseExcess: true, then each time that account’s credit balance is increased, the system will do the following:

  • Start with the new credit balance amount.

  • Reduce it as indicated with the excludeDebits property.

  • Create a disbursement to the insured as given by the disbursementType property on the plan.

  • Advance the disbursement to the state indicated by the advanceDisbursementTo property. If not specified, the disbursement is executed and funds distributed.

  • The details about the disbursement, including its credit balance source, will be available on the newly-created disbursement entity.

For example, if excludeDebits is allInvoices, the sum of the unsettled amount for all outstanding invoices should be deducted from the credit balance amount. If the remainder is greater than zero, create a disbursement with amount equal to this remainder, and advance it to the state specified by advanceDisbursementTo.

For accounts with credit balances in multiple currencies, a separate disbursement will be created for each currency.

Note

It is possible in some cases for the excess amount (as it would be calculated above) to increase even if the credit balance itself does not increase, such as when payments are received while funds remain in a credit balance. Excess credits handling is not automatically triggered in those cases.

Automatic Disbursement Handling

Account credit balance amounts are only reserved when a disbursement transitions to an approved state. When advanceDisbursementTo is set to draft or validated, the system-generated disbursement waits for API approval. During this waiting period, the credit balance may change due to payments, reversals, new invoices settled, or other activity.

To accommodate these changes, the following processing rules apply:

  • The amount of a disbursement is updated to reflect the current credit balance of the account, with updates occurring at the same frequency as automatic disbursement creation.

  • When a disbursement is approved, the approved amount is treated as an upper limit. Upon advancement to executed, the amount is recalculated and the lesser of the recalculated and approved amounts is distributed.

  • If the recalculated amount for a disbursement becomes zero, the disbursement is discarded. A new disbursement will be created when additional funds become available for distribution.

  • A disbursement in an approved or executed state is never modified. A new disbursement will be created when additional funds become available for distribution.

  • A disbursement in a validated state is validated again each time it is updated.

Note

The advanceDisbursementTo property and its processing apply only to system-generated automatic disbursements and do not affect disbursements created via API.

See Also