Payment Reversal Plugin

Overview

When payments for invoices are reversed, the resultant grace period must run its full course before it expires and the policy will lapse. This plugin allows control over the grace period to handle payment reversal cases, especially when the duration of the grace period should be reduced.

In the return object, you can set the gracePeriodEndTimestamp property which will be used to set any existing grace period’s end timestamp (at which time, if the invoice remains unpaid, the policy will lapse). This will also be the end timestamp used for any new grace period that commences as a result of the unpaid invoice.

Configuration

This plugin is configured similarly to other plugins. See the Plugins topic for details. Here is a portion of a product’s policy.json file enabling the plugin:

{
  "plugins": {
    "getPostPaymentReversal": {
      "path": "main/postPaymentReversal.js",
      "enabled": true
  }
}

Data

The data object sent to the plugin looks like this:

PaymentReversalPluginData¶

required
invoiceDueTimestamp timestamp
invoiceIssueTimestamp timestamp
invoiceAmount number
gracePeriodDays integer
invoiceLocator string
operationType string payment_reversal | payment_invalidation
paymentLocator string
policy PluginPolicyInfo
tenantTimeZone string

PluginPolicyInfo¶

required
locator string
policyholderLocator string
productName string
originalContractStartTimestamp timestamp
currency string

optional
quoteLocator string

Note

The operationType property will take the value payment_reversal for any manually reversed payment, or payment_invalidation for any payment reversed as a result of a transaction being invalidated, such as an invalidated endorsement that has its invoice already paid.

More context is available using the Plugin Data Fetch feature.

The plugin requires a return object in this form:

PaymentReversalPluginResponse¶

optional
gracePeriodEndTimestamp timestamp

Example

Normally the grace period would set its expiration date (the time the policy will lapse) using the current time as a start. For example, if the grace period duration is 7 days, the policy would lapse this time next week unless that is changed using this plugin.

The following example sets the expiration of the grace period to use the original invoice due date as the start time for the grace period. If that was more than 7 days ago, the policy would lapse as of midnight tonight.

Note

This Zip file contains the required library and associated support files for this example.

// In postPaymentReversal.js

const { DateCalc } = require('../lib/DateCalc.js');

function getPostPaymentReversal(data)
{
  const dateCalc = new DateCalc('America/Los_Angeles'); /* or other timezone */
  const midnightTonight = dateCalc.getEndOfDayTimestamp(new Date().getTime());
  const ret = {};
  if (data.operationType === 'payment_reversal' && data.invoiceAmount > 0)
  {
    const oneDayofMilliseconds = 24 * 60 * 60 * 1000;
    ret.gracePeriodEndTimestamp =
      Math.max(midnightTonight,
               parseInt(data.invoiceDueTimestamp) + data.gracePeriodDays * oneDayofMilliseconds);
  }
  return ret;
}
exports.getPostPaymentReversal = getPostPaymentReversal;