Payment Plan Plugin

Overview

The payment plan plugin provides a way for configurers to write custom rules for generating payment plans. This gives fine control for situations like:

  • Non-standard payment plans, such as “monthly for the first 9 months out of a year-long policy term”

  • Consolidating small value invoices into one

  • Scheduling invoices on certain dates or days of the week

  • Special logic for endorsement or reinstatement invoicing

It also has a facility for changing the payment plan for an existing policy.

Enabling the Payment Play Plugin

Enabling the plugin requires (1) enabling the feature with a feature flag, (2) implementing a payment plan script, and (3) ensuring the the product or products that are to use the script are referencing it in their scriptsBranch setting.

Feature Flag

Enable the plugin with by enabling the feature flag in the configuration config.json file, for example:

{
  "timezone": "America/Los_Angeles",
  "currency": "USD",
  "features": {
    "property.installments.plugin.enabled": true
  }
}

Script

The script is defined in a file called installments.js with exported function createInstallments. This file should be under the scripts branch you wish to use, for example /scripts/master/installments.js.

A simple sample script is below, and another more detailed example is here.

Both of these samples will work with all the policy transaction types that are subject to installments:

Product Configuration

For the products that you want to enable the payments plan plugin, update the scriptsBranch property. For example, if the branch is named master (i.e. if the script is at /scripts/master/installments.js, make sure that policy.json has this property:

{
  "scriptsBranch": "master"
}

Writeoffs

To write off certain charges or portions of charges, put them on a separate set of installments and set the writeOff flag for those installments to true. This can be useful, for example, in putting extra cents onto a separate written-off invoice so that the totals for other invoices remain constant.

Written off invoices will have settlementStatus of settled and settlementType of writtenOff.

The Plugin data Object

The data object passed to the plugin looks like this:

PaymentPlanPluginData

{
  // Required
  charges : [PaymentPlanPluginCharge]
  coverageEndTimestamp : timestamp
  coverageStartTimestamp : timestamp
  defaultPaymentTerms : PaymentTermsResponse
  paymentScheduleName : string
  plannedInvoices : [FutureInvoiceResponse]
  policy : Policy2Response
  productName : string
  tenantTimeZone : string
  transactionType : string newBusiness | endorsement | renewal | reinstatement | manual
}
  • The coverageStartTimestamp and coverageEndTimestamp properties describe the period covered by the transaction. For example, for an endorsement, it is the period from the endorsement effective date to the policy end.

PaymentPlanPluginCharge

{
  // Required
  amount : number
  amountCurrency : string
  chargeId : string
  coverageEndTimestamp : timestamp
  coverageStartTimestamp : timestamp
  isNew : boolean
  type : string premium | tax | fee | holdback

  // Optional
  feeLocator : string
  feeName : string
  originalAmount : number
  perilCharacteristicsLocator : string
  perilLocator : string
  perilName : string
  policyModificationLocator : string
  previouslyInvoicedAmount : number
  taxLocator : string
  taxName : string
}
  • The isNew property is set to false for charges that have been scheduled before. These charges will also have originalAmount and previouslyInvoicedAmount properties. The amount for these charges is net of amounts on other invoices that remain in force.

  • The coverageStartTimestamp and coverageEndTimestamp properties for the individual charge describe the period covered by the charge. This can be different from the overall transaction coverage period.

The plugin is required to return a response in this form:

PaymentPlanPluginResponse

{
  // Required
}

PaymentPlanPluginInstallmentResponse

{
  // Required
  dueTimestamp : timestamp
  endTimestamp : timestamp
  issueTimestamp : timestamp
  startTimestamp : timestamp
  writeOff : boolean
}

PaymentPlanPluginInvoiceItemResponse

{
  // Required
  amount : number
  chargeId : string
}

Simple Example

This is the simplest possible implementation, which is a full-pay plan. It puts all the charges for each transaction on a single invoice:

function createInstallments(data)
{
  let invoiceItems = data.charges.map(ch => ({
    amount: parseFloat(ch.amount),
    chargeId: ch.chargeId
  }));

  return { installments: [{
    dueTimestamp: data.coverageStartTimestamp,
    issueTimestamp: data.coverageStartTimestamp,
    startTimestamp: data.coverageStartTimestamp,
    endTimestamp: data.coverageEndTimestamp,
    invoiceItems: invoiceItems,
    writeOff: false
  }]};
}

exports.createInstallments = createInstallments;

Note

A more detailed example with multiple supported plans is here.

Note

This plugin only affects future invoices. Changing already-generated invoices is not yet supported, but we are planning an upcoming feature to refactor existing invoices.