Cancel Policy and Produce Invoice

This operation provides the ability to cancel a policy and immediately produce an invoice for the canceled policy. The process from canceling a policy to the production of an invoice consists of separate steps. It is always convenient to have a way to execute several steps in one go rather than one by one. When a payer provides a portal to individuals or group accounts, it becomes necessary rather than just convenient because otherwise a lot of conversation back and forth would be obligatory.

The process from cancellation up to and including the production of an invoice consists of the following sub steps:

Cancel policy (includes premium calculation)
Select financial transactions into a set
Supersede financial transactions
Generate financial message (XML format)

The first sub step is described in detail in the Cancel Policy HTTP API operation while the subsequent sub steps are described in detail in the Financial implementation guide. Here, the focus will be on how the integration works and where the processing differs from the descriptions in the guides.

Resource Representation

Only policies in status Edit (first versions excluded), Pended (first versions excluded) or Approved (only last versions) can be canceled. If the policy is for a group account, then the group account’s group client must have the status Approved for the policy to be eligible for canceling. This can be derived by the presence or absence of the "cancelwithinvoice" link.

The resource representation of a policy that can be canceled, looks like this:

{
  ... policy properties ...
  "links": [
    {
      "href": "http://://generic/policies/",
      "rel": "self"
    },
    {
      "href": "http://://policies//cancelwithinvoice",
      "rel": "policy:cancelwithinvoice",
      "httpMethod": "POST"
    }
  ]
}

In the resource representation of a policy that cannot be canceled, the "cancelwithinvoice" link is not provided:

{
  ... policy properties ...
  "links": [
    {
    "href": "http://://generic/policies/",
    "rel": "self"
    }
  ]
}

Request Payload

The payload needs to provide the necessary information for all the sub steps to be executed. It looks like this:

{
  "finTransDynLogic": "",
  "comFinTransDynLogic": "",
  "disableRevGrouping": true/false,
  "createInvoiceDynLogic": "",
  "createInvoiceLineDynLogic": "",
  "createAccountingDetailDynLogic": "",
  "premiumEndPoint": "",
  "commissionEndPoint": ""
}

This payload maps to the different sub steps as follows:

Cancel policy (includes premium calculation)

The dynamic logic for financial transaction and commission financial transaction as well as the disable reversal grouping indicator are optional, just as they are when starting the premium calculation directly from within the application.

Select financial transactions into a set

A financial transaction set is used to group financial transactions together for financial processing. Here, the grouping is rather obvious. First, all financial transactions that were created during the cancellation process are put into a new set; this encompasses both premium and commission financial transactions. If unhandled financial transactions already exist for the same base financial object, they are moved into this set as well. This situation is not likely for the portal use case, but it is possible when a member makes a change in the portal while there were already unhandled financial transactions in the system. Because the financial transaction set is only used as a vehicle for financial processing, it is not stored in a persistent way.

Supersede financial transactions
Generate financial message (XML format)

The dynamic logic for the creation of invoice, invoice line and account detail is mandatory, just as it is when starting the generation of the financial message directly within the application. The endpoints for premium and commission are both optional: if an endpoint is not specified, it defaults to the endpoint for Generate Financial Message in the properties file. For premium and commission always separate financial messages will be created, even if they are delivered to the same endpoint.

Response Messages

This operation provides HTTP status codes as defined in Response Messages. If an error occurs, the appropriate HTTP status code is returned and a notification is sent containing the details of the error.

The following operation specific errors can occur:

Code	Severity	Message Text
POL-HTTP-008	Fatal	Policy is not in a cancellable state
POL-HTTP-006	Fatal	Could not resolve end point {0}
POL-HTTP-xxx	Fatal	The policy’s group client must be in status Approved

Code

Severity

Message Text

POL-HTTP-008

Fatal

Policy is not in a cancellable state

POL-HTTP-006

Fatal

Could not resolve end point {0}

POL-HTTP-xxx

Fatal

The policy’s group client must be in status Approved

Authorization

The above described operation is protected by access restriction "policies.cancel with invoice IP". A grant for this access restriction must be provided. If the access to a policy is restricted by a data access group restriction, then to perform this operation on that policy also a grant for that data access group restriction must be provided with the Update flag set.