Invoicing Configuration

You can manage the compensation of third-party entities through different invoicing processes, defined per your specific business requirements. For example, you could set up an invoicing process to be used in conjunction with the contracts recorded in Loan Management, or you could use a separate invoicing process for insurance policies. Through the Configuration menu item, Distribution Management allows you to specify which custom-made function to use to retrieve the invoice details for each scope and invoicing type.

To manage third-party invoicing configurations:

In FintechOS Portal, click the main menu icon and expand the Distribution Management menu.
Expand the Distribution Management Admin menu and click the Distribution Management Configuration menu item to open the Distribution Management Configurations List page.

On the Distribution Management Configurations List page, you can create a new invoicing configuration, search, edit, or delete an existing one. You can't delete configurations already used by other records.

Creating Invoicing Configurations

Follow these steps to create new invoicing configuration records:

In the FintechOS Portal, click the Insert button on the top right side of the Distribution Management Configurations List page. The TPM Configuration page is displayed.
Fill in the following fields from the Main Information section:
- Name - Enter the name of the configuration.
- Scope - Select the scope of the configuration. You can select one of the following options: Invoice or Payment.
- Invoicing Type - Choose the invoicing type to filter only the agreements of the selected type to be considered through the current configuration. The invoicing type must be set at each agreement's level.
- Library Name - Specify the name of the library containing the function(s) you want to use for this configuration scope.
- Function Name - Specify the function(s), custom-built for your business, from the library that will be executed for the current scope.
  
  IMPORTANT!
  Make sure that the function you define for the Invoice scope follows the input and output example below.
  For the Payment scope, the function is executed when you change the invoice's business status from NotPaid to Paid. For each setting found in the order of orderIndex attribute, the system imports the library and calls function. If an error is received, then the status is not changed.
  
  If error is received that the status cannot be changed
- Has Extended Attributes - Check this box to specify if an invoicing detail has references to other entities. If there are no references, leave it unchecked.
- Extended Attributes - If Has Extended Attributes = True, then list here the names of the attributes referenced in other entities. They must exist at the invoice detail level.
- Execute Insert - Check this box if the function you just entered also inserts the invoice detail (for invoice scope). If not, the function must have a specific output structure that will be used by Distribution Management to perform the insert. If the function also performs the insert, then the output structure is not relevant.
Click the Save and Reload button. The configuration record is saved.

IMPORTANT!
If you are using multiple functions for one scope, you should order the functions on the Distribution Management Configurations List page by dragging and dropping them in the correct order (displayed by the Order Index attribute) so the system knows which is the correct way of calling them.

Input/ Output Structures for the Function Defined for Invoice Scope

Function input example:

Copy

Input

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array",
  "description": "Array of objects containing agreement/invoice details details.",
  "items": [
    {
      "type": "object",
      "description": "Object containing agreement/invoice details details.",
      "properties": {
        "agreement": {
          "type": "object",
          "description": "Agreement object.",
          "properties": {
            "agreementId": {
              "type": "string",
              "description": "Id of the agreement."
            },
            "validFrom": {
              "type": "object",
              "description": "Agreement validFrom property.",
              "properties": {
                "invariantDate": {
                  "type": "string"
                }
              },
              "required": [
                "invariantDate"
              ]
            },
            "validTo": {
              "type": "object",
              "description": "Agreement validFrom property.",
              "properties": {
                "invariantDate": {
                  "type": "string"
                }
              },
              "required": [
                "invariantDate"
              ]
            }
          },
          "required": [
            "agreementId",
            "validFrom",
            "validTo"
          ]
        },
        "invoiceDetails": {
          "type": "array",
          "description": "Array containing invoice detail objects.",
          "items": [
            {
              "type": "object",
              "description": "Object representing an invoice detail.",
              "properties": {
                "invoiceId": {
                  "type": "null",
                  "description": "The invoice id, should be null."
                },
                "value": {
                  "type": "null",
                  "description": "The calculated value, should be null, it will be calculated by the next endpoint."
                },
                "currencyId": {
                  "type": "string",
                  "description": "The currency of the calculated value."
                },
                "exchangeRate": {
                  "type": "number",
                  "description": "The exchange rate between the commission currency and agreement currency."
                },
                "equivalentValue": {
                  "type": "null",
                  "description": "The calculated equivalentvalue, should be null, it will be calculated by the next endpoint."
                },
                "detailTypeId": {
                  "type": "string",
                  "description": "The detail type id, in case of a normal commission."
                },
                "clawbackDetailTypeId": {
                  "type": "string",
                  "description": "The detail type id, in case of a clawback commission."
                },
                "tpmCommissionId": {
                  "type": "string",
                  "description": "The commission id."
                },
                "tpmClawbackCommissionId": {
                  "type": "string",
                  "description": "The clawback commission id."
                },
                "agreementId": {
                  "type": "string",
                  "description": "The agreement id."
                },
                "agreementPricingId": {
                  "type": "string",
                  "description": "The agreement pricing id."
                },
                "calculateCommValueData": {
                  "type": "object",
                  "description": "Object containing calculation data for a normal commission",
                  "properties": {
                    "percentAppliedTo": {
                      "type": "string",
                      "description": "The id of the dimension to which the percent will be applied."
                    },
                    "valuePercent": {
                      "type": "number",
                      "description": "The percentage value that will be applied."
                    }
                  },
                  "required": [
                    "percentAppliedTo",
                    "valuePercent"
                  ]
                },
                "calculateClawbackCommValueData": {
                  "type": "object",
                  "description": "Object containing calculation data for a clawback commission",
                  "properties": {
                    "percentAppliedTo": {
                      "type": "string",
                      "description": "The id of the dimension to which the percent will be applied."
                    },
                    "valuePercent": {
                      "type": "number",
                      "description": "The percentage value that will be applied."
                    }
                  },
                  "required": [
                    "percentAppliedTo",
                    "valuePercent"
                  ]
                },
                "clawbackValue": {
                  "type": "number",
                  "description": "The clawback calculated value, should be null, it will be calculated by the next endpoint."
                },
                "tpmClawbackCommPeriodTypeId": {
                  "type": "string",
                  "description": "The period type id needed to calculate if clawback can still be performed."
                },
                "tpmClawbackCommPeriod": {
                  "type": "number",
                  "description": "The period value."
                },
                "tpmClawbackCommBlockAfterClawback": {
                  "type": "boolean",
                  "description": "Specifies if clawbacks will be prevented after the first clawback occured."
                },
                "clawbackEquivalentValue": {
                  "type": "number",
                  "description": "The calculated equivalentvalue for clawback, should be null, it will be calculated by the next endpoint."
                },
                "clawbackExchangeRate": {
                  "type": "number",
                  "description": "The exchange rate between the clawback commission currency and agreement currency."
                }
              },
              "required": [
                "invoiceId",
                "value",
                "currencyId",
                "exchangeRate",
                "equivalentValue",
                "detailTypeId",
                "clawbackDetailTypeId",
                "tpmCommissionId",
                "tpmClawbackCommissionId",
                "agreementId",
                "agreementPricingId",
                "calculateCommValueData",
                "clawbackValue",
                "tpmClawbackCommPeriodTypeId",
                "tpmClawbackCommPeriod",
                "tpmClawbackCommBlockAfterClawback",
                "clawbackEquivalentValue",
                "clawbackExchangeRate"
              ]
            }
          ]
        }
      },
      "required": [
        "agreement",
        "invoiceDetails"
      ]
    }
  ]
}

Function Output example:

Copy

Output example

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "description": "Object containing the details needed for calculation and insertion.",
  "properties": {
    "extendedAttributes": {
      "type": "object",
      "description": "Object containing extended attributes if there are any defined for your use-case.",
      "properties": {
        "extendedAttributeId": {
          "type": "string",
          "description": "The extended attribute id. It's name should be changed to adapt to your use-case and should be the same as the extended attributes defined in FTOS_TPM_Configuration for Invoice scope."
        }
      },
      "required": [
        "extendedAttributeId"
      ]
    },
    "invoiceDetails": {
      "type": "array",
      "description": "Array of invoice detail objects.",
      "items": [
        {
          "type": "object",
          "description": "Invoice detail object.",
          "properties": {
            "invoiceId": {
              "type": "null",
              "description": "Invoice id, should be null."
            },
            "value": {
              "type": "null",
              "description": "The calculated value, should be null, it will be calculated by the next endpoint."
            },
            "currencyId": {
              "type": "string",
              "description": "The currency of the calculated value."
            },
            "exchangeRate": {
              "type": "number",
              "description": "The exchange rate between the commission currency and agreement currency."
            },
            "equivalentValue": {
              "type": "null",
              "description": "The calculated equivalentvalue, should be null, it will be calculated by the next endpoint."
            },
            "detailTypeId": {
              "type": "string",
              "description": "The detail type id, in case of a normal commission."
            },
            "clawbackDetailTypeId": {
              "type": "string",
              "description": "The detail type id, in case of a clawback commission."
            },
            "tpmCommissionId": {
              "type": "string",
              "description": "The commission id."
            },
            "tpmClawbackCommissionId": {
              "type": "string",
              "description": "The clawback commission id."
            },
            "agreementId": {
              "type": "string",
              "description": "The agreement id."
            },
            "agreementPricingId": {
              "type": "string",
              "description": "The agreement pricing id."
            },
            "calculateCommValueData": {
              "type": "object",
              "properties": {
                "percentAppliedTo": {
                  "type": "string",
                  "description": "Object containing calculation data for a normal commission",
                },
                "valuePercent": {
                  "type": "number",
                  "description": "The percentage value that will be applied."
                }
              },
              "required": [
                "percentAppliedTo",
                "valuePercent"
              ]
            },
            "clawbackValue": {
              "type": "number"
            },
            "calculateClawbackCommValueData": {
              "type": "object",
              "description": "Object containing calculation data for a clawback commission",
              "properties": {
                "percentAppliedTo": {
                  "type": "string",
                  "description": "The id of the dimension to which the percent will be applied."
                },
                "valuePercent": {
                  "type": "number",
                  "description": "The percentage value that will be applied."
                }
              },
              "required": [
                "percentAppliedTo",
                "valuePercent"
              ]
            },
            "tpmClawbackCommPeriodTypeId": {
              "type": "string",
              "description": "The period type id needed to calculate if clawback can still be performed."
            },
            "tpmClawbackCommPeriod": {
              "type": "number",
              "description": "The period value."
            },
            "tpmClawbackCommBlockAfterClawback": {
              "type": "boolean",
              "description": "Specifies if clawbacks will be prevented after the first clawback occured."
            },
            "clawbackEquivalentValue": {
              "type": "number",
              "description": "The calculated equivalentvalue for clawback, should be null, it will be calculated by the next endpoint."
            },
            "clawbackExchangeRate": {
              "type": "number",
              "description": "The exchange rate between the clawback commission currency and agreement currency."
            },
            "name": {
              "type": "string",
              "description": "The name of the invoice detail entry."
            },
            "clawbackStartDate": {
              "type": "object",
              "description": "The date from which the clawback period will be calculated.",
              "properties": {
                "invariantDate": {
                  "type": "string"
                }
              },
              "required": [
                "invariantDate"
              ]
            },
            "extendedAttributeId": {
              "type": "string",
              "description": "The extended attribute. Name should match the extended attribute(s) defined in FTOS_TPM_Configuration for Invoice scope.",
            },
            "isClawback": {
              "type": "boolean",
              "description": "Specifies if the invoice detail generated is for a clawback or not."
            }
          },
          "required": [
            "invoiceId",
            "value",
            "currencyId",
            "exchangeRate",
            "equivalentValue",
            "detailTypeId",
            "clawbackDetailTypeId",
            "tpmCommissionId",
            "tpmClawbackCommissionId",
            "agreementId",
            "agreementPricingId",
            "calculateCommValueData",
            "clawbackValue",
            "tpmClawbackCommPeriodTypeId",
            "tpmClawbackCommPeriod",
            "tpmClawbackCommBlockAfterClawback",
            "clawbackEquivalentValue",
            "clawbackExchangeRate",
            "name",
            "clawbackStartDate",
            "isClawback"
          ]
        }
      ]
    }
  },
  "required": [
    "extendedAttributes",
    "invoiceDetails"
  ]
}