Installment Opcode Workflows

Opcodes Described in This Chapter

Table 14-1 describes the installment management opcodes.

Caution:

Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.
Do not use SQL commands to change data in the database. Always use the API.

Table 14-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_INSTALLMENT_APPLY_CHARGE	Applying Installment Charge
PCM_OP_INSTALLMENT_CANCEL_INSTALLMENT	Canceling Installments Validating Installments Customizing How to Bill Events That Occur between Billing Cycles Customizing Credit Limit and Consumption Rules
PCM_OP_INSTALLMENT_CREATE_INSTALLMENT	Creating Installments Validating Installments Installment Proposal Creating Installment Schedule Specifications Validating Installment Schedule Specifications Customizing How to Bill Events That Occur between Billing Cycles Running Bill Now Transferring Balances between Items
PCM_OP_INSTALLMENT_CREATE_SCHEDULE_SPEC	Creating Installment Schedule Specifications Validating Installment Schedule Specifications Preparing Installment Schedule Specifications
PCM_OP_INSTALLMENT_GET_INSTALLMENTS	Retrieving Installments Finding a Bill
PCM_OP_INSTALLMENT_GET_SCHEDULE_SPEC	Retrieving Installment Schedule Specifications Getting Installment Schedule Specifications Validating Installment Schedule Specifications Preparing Installment Schedule Specifications
PCM_OP_INSTALLMENT_MODIFY_SCHEDULE_SPEC	Modifying Installment Schedule Specifications Validating Installment Schedule Specifications Preparing Installment Schedule Specifications Creating Installment Schedule Specifications
PCM_OP_INSTALLMENT_POL_GET_SCHEDULE_SPEC	Getting Installment Schedule Specifications Retrieving Installment Schedule Specifications Creating Installment Schedule Specifications
PCM_OP_INSTALLMENT_POL_PREP_INSTALLMENT	Preparing Installments
PCM_OP_INSTALLMENT_POL_PREP_SCHEDULE_SPEC	Preparing Installment Schedule Specifications Validating Installment Schedule Specifications
PCM_OP_INSTALLMENT_POL_PROPOSAL	Installment Proposal
PCM_OP_INSTALLMENT_POL_VALID_INSTALLMENT	Validating Installments Creating Installments Validating Installment Schedule Specifications
PCM_OP_INSTALLMENT_POL_VALID_SCHEDULE_SPEC	Validating Installment Schedule Specifications Preparing Installment Schedule Specifications
PCM_OP_INSTALLMENT_PROPOSAL	Installment Proposal
PCM_OP_INSTALLMENT_UPDATE_INSTALLMENT_STATUS	Updating Installment Status Customizing How to Bill Events That Occur between Billing Cycles Customizing Credit Limit and Consumption Rules
PCM_OP_INSTALLMENT_UPDATE_INSTALLMENT	Updating Installment Status Validating Installments Preparing Installment Schedule Specifications

Creating Installment Schedule Specifications

Use PCM_OP_INSTALLMENT_CREATE_SCHEDULE_SPEC to create an installment schedule specification, which defines the terms for an installment plan your company offers your customers.

You set the installment schedule specification name, start date, end date, minimum installment amount, the maximum number of unequal installments, unequal installment frequency, installment type, and eligibility criteria by passing the information in the input flist.

You specify the eligibility criteria by including the following in the PIN_FLD_CRITERIA input flist array:

PIN_FLD_CLASS_NAME: The class name, such as /account or /service
PIN_FLD_FIELD_NAME: The field's name, such as PIN_FLD_POID or PIN_FLD_FLAGS
PIN_FLD_OPERATOR: The operator type: equal to (0), less than (1), greater than (2), less than or equal to (3), greater than or equal to (4), not equal to (5), in (6), like (7), null (8), or not null (9).
PIN_FLD_TYPE: The field's data type: integer (1), enum (3), string (5), POID (7), timestamp (8), or decimal (14)
PIN_FLD_VALUE: The field's value, such as PIN_FLDT_POID or 2

For example, to set the eligibility criteria to accounts that own services like /service/telco/gsm/telephony and /service/telco/gsm/sms, you would use the following:

0 PIN_FLD_CRITERIA          ARRAY [0]
1     PIN_FLD_CLASS_NAME      STR [0] "/service"
1     PIN_FLD_FIELD_NAME      STR [0] "PIN_FLD_POID"
1     PIN_FLD_OPERATOR       ENUM [0] 7    # "PIN_INSTL_OPERATOR_LIKE"
1     PIN_FLD_TYPE           ENUM [0] 7    # PIN_FLDT_POID
1     PIN_FLD_VALUE           STR [0] "/service/telco/gsm"

PCM_OP_INSTALLMENT_CREATE_SCHEDULE_SPEC does the following:

Validates the mandatory parameters in the input.
Calls PCM_OP_INSTALLMENT_POL_VALID_SCHEDULE_SPEC to validate the input parameters. See "Validating Installment Schedule Specifications".
Checks the results of PCM_OP_INSTALLMENT_POL_VALID_SCHEDULE_SPEC and sends appropriate error messages.
Calls and gets the output flist from PCM_OP_INSTALLMENT_POL_PREP_SCHEDULE_SPEC, which it passes as the input flist for any additional functions. See "Preparing Installment Schedule Specifications".

If the object is successfully created, the PCM_OP_INSTALLMENT_CREATE_SCHEDULE_SPEC output flist contains the POID of the /config/installment/schedule_spec object.

Validating Installment Schedule Specifications

PCM_OP_INSTALLMENT_POL_VALID_SCHEDULE_SPEC validates the information in the installment schedule specification (/config/installment/schedule_spec object).

PCM_OP_INSTALLMENT_POL_VALID_SCHEDULE_SPEC performs these validation checks:

Validates that the installment schedule specification contains the mandatory input parameters.
If PIN_FLD_TYPE is percentage (2), checks that PIN_FLD_MINIMUM is between 0 and 100.
If PIN_FLD_TYPE is absolute (1), checks that PIN_FLD_MINIMUM is 0 or greater.
Checks that the PIN_FLD_MAX_UNEQUAL_INTERVALS and PIN_FLD_MAX_UNEQUAL_INSTALLMENTS fields are 0 or greater.
Checks that all elements in the PIN_FLD_CRITERIA array are in the required format.
Checks that the PIN_FLD_CLASS_NAME field is /account, /service, or /profile.
If the error buffer is set, clears the error and sets the PIN_FLD_RESULT field to FAIL. If the buffer is not set, sets the PIN_FLD_RESULT field to PASS.

Preparing Installment Schedule Specifications

Use PCM_OP_INSTALLMENT_POL_PREP_SCHEDULE_SPEC to prepare installment schedule specification creation fields.

For more information about PREP opcodes, see "About the PREP and VALID Opcodes" in BRM Developer’s Guide.

Modifying Installment Schedule Specifications

Use PCM_OP_INSTALLMENT_MODIFY_SCHEDULE_SPEC to modify an existing installment schedule specification (/config/installment/schedule_spec object).

You can modify the installment schedule specification name, start date, end date, minimum installment amount, the maximum number of unequal installments, unequal installment frequency, installment type, and the eligibility criteria.

PCM_OP_INSTALLMENT_MODIFY_SCHEDULE_SPEC does the following:

Validates the mandatory input parameters using PCM_OP_INSTALLMENT_POL_VALID_SCHEDULE_SPEC. See "Validating Installment Schedule Specifications".
Calls PCM_OP_INSTALLMENT_POL_PREP_SCHEDULE_SPEC to prepare the input flist and include any customizations. See "Preparing Installment Schedule Specifications".
Updates the values in the /config/installment/schedule_spec object.

Retrieving Installment Schedule Specifications

PCM_OP_INSTALLMENT_GET_SCHEDULE_SPEC retrieves information about the installment schedule specification.

PCM_OP_INSTALLMENT_GET_SCHEDULE_SPEC does the following:

Validates the mandatory input parameters.
Gets the /config/installment/schedule_spec object from the database.
Gets the information while creating the installment schedule specifications and the installments.
During the installment schedule specification creation, gets the status of the installment schedule such as active, inactive, or draft.
During installment creation, gets only the specifications that match the criteria for the specified account POID.

Getting Installment Schedule Specifications

PCM_OP_INSTALLMENT_POL_GET_SCHEDULE_SPEC is a policy opcode to allow customizations for getting the installment schedule specifications.

Creating Installments

Use PCM_OP_INSTALLMENT_CREATE_INSTALLMENT to create installments for a specific customer.

This opcode retrieves the charge object for the customer and divides the total due amount into the specified number of installments.

Validating Installments

Use PCM_OP_INSTALLMENT_POL_VALID_INSTALLMENT to validate the input.

PCM_OP_INSTALLMENT_POL_VALID_INSTALLMENT does the following:

Validates the installment amount. If the amount or percentage is greater than the minimum installment amount or percentage that is defined in the /config/installment/schedule_spec object, sends an error.
Checks for unequal installments in the input PIN_FLD_INSTALLMENTS array and validates them with the value in the INSTALLMENT_SPEC object.
Validates the sum of all the installments amount with the total installment amount and if not equal, sends an error.
Checks if the Flags indicate 0 (for the regular bill) or 1 (for the bill now).
While creating the installments, it checks if the PIN_FLD_STATUS is in the open state for the overall installments and individual installments.
Ensures that the installments are created only for bills or items.
Validates if the PIN_FLD_START_T is less than PIN_FLD_END_T. If it is, sets the PIN_FLD_RESULT as Pass in the output flist. If not, sets the PIN_FLD_RESULT as Fail in the output flist.
Validates if the PIN_FLD_START_T is not less than PIN_VIRTUAL_TIME. If it is not, sets the PIN_FLD_RESULT as Pass in the output flist. If it is, sets the PIN_FLD_RESULT as Fail in the output flist.

Preparing Installments

Use PCM_OP_INSTALLMENT_POL_PREP_INSTALLMENT to prepare installment fields.

For more information about PREP opcodes, see "About the PREP and VALID Opcodes" in BRM Developer’s Guide.

Applying Installment Charge

PCM_OP_INSTALLMENT_APPLY_CHARGE applies the installment charge or amount for the customer on the effective date.

The charge impact of individual installments gets applied to the customer using the Multithreaded Application (MTA) named pin_installments after the charge is converted into installments. This MTA gets the installments that must be charged and are due.

PCM_OP_INSTALLMENT_APPLY_CHARGE creates /event/billing/installment/debit event and /item/installment/debit object, for the installment amount charge applied.

Updating Installment Status

Once an installment is paid, the payment gets allocated, the /item/installment/debit object and the /event/billing/item/transfer are updated, and PCM_OP_INSTALLMENT_UPDATE_INSTALLMENT_STATUS is called.

PCM_OP_INSTALLMENT_UPDATE_INSTALLMENT_STATUS changes the installment status from Charged to Paid. Once the installment status is changed to Paid, the status of the installment arrangement will be changed to Finished.

PCM_OP_INSTALLMENT_UPDATE_INSTALLMENT_STATUS is also called by the PIN_INSTALLMENT_STATUS_CHANGE MTA to change the installment status to Broken if the installment is not paid on the due date.

Retrieving Installments

PCM_OP_INSTALLMENT_GET_INSTALLMENTS retrieves information about all the installments associated with an account and service. If service is not mentioned, retrieves all the installments associated with the account.

PCM_OP_INSTALLMENT_GET_INSTALLMENTS does the following:

Validates the mandatory parameters in the input flist.
Gets the /installment objects for the account POID.
Includes PIN_FLD_BILLINFO_OBJ as search criteria, in the search template, if PIN_FLD_BILLINFO_OBJ is present in the input flist.
Searches for installments in the database based on the input parameters and returns all the installments details.

Updating Installments

PCM_OP_INSTALLMENT_UPDATE_INSTALLMENT updates OPEN installments.

Note: Only open installments can be updated.

If the amount in the installments array is not the same as the sum of the remaining open amount, the opcode returns an error message.

For example, an account has a $300 X 6 months installments hence $1800 amount must be paid. The installment has been paid for two months that is $600 is paid and the remaining amount to be paid is $1200.

The update installment request must not have a different amount in the installments array and the remaining open amount. Both the amount, as in this example, must be $1200. If the amount is different, it sends an error.

PCM_OP_INSTALLMENT_UPDATE_INSTALLMENT does the following:

Validates the mandatory input parameters in the input flist.
Validates if the due amount meets the minimum installment due amount as per the installment schedule specification.
Gets the installment total amount due, adds up the remaining installments, and validates them to ensure the total due amount is equal to the sum of the installment amount.
Validates the number of remaining installments, the term, and installment elements.
Calls and gets results from PCM_OP_INSTALLMENT_POL_VALID_INSTALLMENT. Sends error message in case of any error.
Reads the /installment object using PCM_OP_READ_OBJ opcode.
Calls PCM_OP_INSTALLMENT_POL_PREP_SCHEDULE_SPEC.
Updates the /installment object with the input parameter values.

Canceling Installments

Use PCM_OP_INSTALLMENT_CANCEL_INSTALLMENT to sum any remaining amounts, charge the customer, and cancel the remaining installments.

PCM_OP_INSTALLMENT_CANCEL_INSTALLMENT does the following:

Validates the mandatory input parameters in the input flist.
Calls PCM_OP_BILL_SET_LIMIT_AND_CR to update the credit limit to increase the open installments amount and the same will be reverted after creating a one-off charge.
Gets the balance group for the given installment POID from the /installment object.
Calls PCM_OP_ACT_USAGE to create a one-off charge with the total installment due, for the installment charge with the /event/billing/installment/debit event and associates it with the installment charge item.
Calls PCM_OP_ACT_USAGE to create notification event for the canceled installment, with the /event/installment/cancel event.
Updates the /installment object with the input parameter values. Updates the status in the /installment object and the status in the installments_details array to canceled.

Installment Proposal

PCM_OP_INSTALLMENT_PROPOSAL is called by the API layer to prepare the installment proposal.

The opcode refers to the input parameters such as installment amount, installment term (the number of months), and start date and divides the installment amount into equal installments. If the installment amount cannot be divided into equal installments, the opcode rounds it off to the nearest amount and adjusts any remaining amount to the last installment.

PCM_OP_INSTALLMENT_PROPOSAL returns the proposed installment calculated details along with the installment amount and effective dates.

Use the PCM_OP_INSTALLMENT_POL_PROPOSAL policy opcode to modify and customize the return flist of PCM_OP_INSTALLMENT_PROPOSAL.