17 Loan Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) loan opcode workflows.

For information about the loan opcodes, see "Loan FM Standard Opcodes" and "Loan FM Policy Opcodes".

Topics in this document:

• Opcodes Described in This Chapter
• Granting a Loan
• Granting a Channel Loan
• Resetting a Loan Cycle and Other Loan Profile Fields
• Checking a Customer's Eligibility for a Loan
• Retrieving Loan Information
• Creating and Modifying a Customer's Loan Profile
• Customizing Loan Recovery

Opcodes Described in This Chapter

Table 17-1 lists the opcodes described in this chapter.

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 17-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_CUST_CREATE_PROFILE	Creating and Modifying a Customer's Loan Profile
PCM_OP_CUST_MODIFY_PROFILE	Creating and Modifying a Customer's Loan Profile
PCM_OP_LOAN_APPLY_LOAN	Granting a Loan
PCM_OP_LOAN_ELIGIBILITY	Checking a Customer's Eligibility for a Loan
PCM_OP_LOAN_GET_LOAN	Retrieving Loan Information
PCM_OP_LOAN_POL_ELIGIBILITY	Customizing Loan Eligibility Checks
PCM_OP_LOAN_POL_PRE_APPLY_LOAN	Customizing Loan Grants
PCM_OP_LOAN_POL_PRE_RECOVER_LOAN	Customizing Loan Recovery
PCM_OP_LOAN_POL_RESET_CYCLE	Resetting a Loan Cycle and Other Loan Profile Fields
PCM_OP_RATE_POL_POST_RATING	Granting a Channel Loan

Granting a Loan

To grant a loan to a customer, use PCM_OP_LOAN_APPLY_LOAN. This opcode is not called internally by BRM, you must configure API calls from external systems to call this opcode.

This opcode does the following:

1. Takes at minimum an account POID as input. You can optionally provide locale, amount, and service parameters. If the account POID alone is provided, rather than the full account object, the account object is retrieved using the service object or service type and MSISDN.
2. Calls the PCM_OP_CUST_FIND_PROFILE opcode to retrieve the customer's loan profile.
3. If PIN_FLD_UNIT and PIN_FLD_FREQUENCY are specified in the /profile/loan object and the current date is later than the timestamp in PIN_FLD_CYCLE_T, calls the PCM_OP_LOAN_POL_RESET_CYCLE opcode to reset the loan cycle.
4. Calls the PCM_OP_LOAN_ELIGIBILITY opcode to check if the customer is eligible for the requested loan.

   If the customer is ineligible, the loan is rejected and a response containing the rejection reason is returned to the calling service.

   If the customer is eligible, the workflow continues.

5. If there is a fee configured in the /config/loan object specified in the /profile/loan, calls PCM_OP_ACT_USAGE to create the /event/billing/loan_fee event and /item/loan_fee as a non-billable open item.
6. Calls PCM_OP_ACT_USAGE to create /event/billing/loan_credit and /event/billing/loan_debit events and /item/loan_credit and /item/loan_debit items.

   The credit represents the cash granted and the debit represents the loan asset in a form of double-entry bookkeeping. This allows the customer's account balance to remain at 0 while their credit limit is temporarily increased by the loan amount.

   The gl_id and gl_accts fields are updated in the reasons.en_US and pin_glid files for the events.

7. If the input flist contains a noncurrency resource specified in the PIN_FLD_RESOURCE_ID field, creates an /event/billing/loan_grant event to grant the noncurrency resource configured for the event in PDC or Pricing Center.
8. Calls the PCM_OP_BILL_SET_LIMIT_AND_CR opcode to set the amount owed for the loan in the balance group in the PIN_FLD_OUSTANDING_AMOUNT field to the sum of:
   • The loan amount
   • The loan service fee
   • The tax on the loan service fee
   • The tax on the loan amount
9. Calls PCM_OP_CUST_MODIFY_PROFILE to update the loan profile to reflect the total loan amount and the number of loans granted.
10. The output flist containing information about the loan granted, including amount, resource ID, and events, is returned to the calling service.

Customizing Loan Grants

To customize loan grants, use the PCM_OP_LOAN_POL_PRE_APPLY_LOAN policy opcode. By default, this policy opcode does nothing.

This policy opcode is called by PCM_OP_LOAN_APPLY_LOAN.

Granting a Channel Loan

To grant a channel loan for a package without considering or consuming a customer's available balance, customize the PCM_OP_RATE_POL_POST_RATING policy opcode to call PCM_OP_LOAN_APPLY_LOAN and grant a loan for the price of the package purchased by subscription request from your channel.

For example, you can indicate that the package should be purchased using a loan with the PIN_FLD_FLAGS field in the input flist for PCM_OP_RATE_POL_POST_RATING, then use PCM_OP_RATE_POL_POST_RATING to get the package's rated impact for the loan amount.

Resetting a Loan Cycle and Other Loan Profile Fields

You use loan cycles when limiting how many times a loan can be granted and total amounts that can be granted.

To reset a loan cycle, use PCM_OP_LOAN_POL_RESET_CYCLE. This opcode is called by the PCM_OP_LOAN_APPLY_LOAN opcode.

This opcode does the following:

1. Takes at minimum an account POID as input. You can optionally provide a service object as well.
2. Calls the PCM_OP_CUST_FIND_PROFILE opcode to retrieve the customer's loan profile.
3. Uses the offset and unit from the PCM_OP_CUST_FIND_PROFILE output flist to calculate the next loan cycle date.
4. Validates that the current date is later than the timestamp in PIN_FLD_CYCLE_T in the /profile/loan object retrieved.
5. Calls the PCM_OP_CUST_MODIFY_PROFILE opcode to set the following fields in the /profile/loan object:
   • PIN_FLD_CREDIT_AMOUNT: Resets to 0
   • PIN_FLD_NUMBER_OF_LOANS: Resets to 0
   • PIN_FLD_CYCLE_T: Sets to newly calculated date

You can also customize this policy opcode to reset other fields in the /profile/loan object.

Checking a Customer's Eligibility for a Loan

To check whether a customer is eligible for a loan, use PCM_OP_LOAN_ELIGIBILITY. This opcode is called by PCM_OP_LOAN_APPLY_LOAN.

This opcode does the following:

1. Takes at minimum an account POID as input. You can optionally provide locale, amount, and service parameters.
2. Determines the account's location in one of the following ways:
   • Using the value provided in the LOCALE field
   • Looking the location up using the ZONEMAP_TARGET and ZONEMAP_NAME fields. If ZONEMAP_NAME isn't also specified, the name is taken from the DefaultZoneMapName Subscription business parameter.
   • If neither locale nor zonemap details are included in the input flist, the city, state, and zipcode specified in the customer's PIN_FLD_NAMEINFO array are used.
3. Determines if the account is eligible by confirming that all of the following are true:
   • The sum of PIN_FLD_CREDIT_AMOUNT in /profile/loan and the loan amount requested doesn't exceed the fixed or scaled maximum configured in /config/loan
   • The number in PIN_FLD_NUMBER_OF_LOANS in /profile/loan isn't already equal to PIN_FLD_QUANTITY in /config/loan.
   • The account's location is eligible, depending on the configuration in PIN_FLD_LOCATION_MODE and the LOCATIONS array in /config/loan.
   • The amount requested is greater than PIN_FLD_LOAN_MINIMUM in /config/loan.
   • The account's age is greater than the amount specified in PIN_FLD_AGE and PIN_FLD_UNIT in /config/loan.
   • The account's status is active.
4. Calls the PCM_OP_LOAN_POL_ELIGIBILITY policy opcode.
5. Returns a response that includes one of the reason codes in Table 17-2.

   Table 17-2 Reason Codes

   Code	Desription
   0	Success. The account is eligible for the loan.
   1	Failure. The maximum loan amount has been exceeded.
   2	Failure. A loan has already been granted the maximum number of times.
   3	Failure. The account's location is not eligible for the loan.
   4	Failure. An external entity (called by the policy opcode) rejected the loan request.
   5	Failure. The loan amount is less than the configured minimum.
   6	Failure. The account has not been active long enough.
   7	Failure. The account's status is inactive.
   8	Failure. Another error occurred, such as missing or invalid information.
   9	Failure. The customer has opted out of loans.
   10	Failure. The customer has met or exceeded the maximum number of active loans.

6. Generates one of the following events:
   • /event/notification/loan_reject
   • /event/notification/loan_success

Customizing Loan Eligibility Checks

To customize loan eligibility checks before they are finalized, use the PCM_OP_LOAN_POL_ELIGIBILITY policy opcode. By default, this policy opcode does nothing.

This policy opcode is called by PCM_OP_LOAN_ELIGIBILITY.

Retrieving Loan Information

To retrieve loan information, use PCM_OP_LOAN_GET_LOAN. This opcode is not called internally by BRM, you must configure API calls from external systems to call this opcode.

This opcode takes an account POID as input. You can optionally set the value of PIN_FLD_FLAGS to 0 to return only active loans or 1 to return all loans, active and past.

The output flist contains

• Event arrays for each loan that list:
  • The POIDs of the /event/billing/loan_debit event, /event/billing/loan/fee event, and associated service
  • The total outstanding amount that has yet to be paid for that loan
  • The amount originally loaned
  • The loan fee
  • The loan tax
  • The loan type
  • The loan channel
• The maximum loan amount configured in the /profile/loan object
• The amount available to be loaned, calculated based on the maximum configured in the /profile/loan object or the /config/loan object and the current total outstanding amount for all active loans. If the outstanding amount is greater than the maximum, the amount available is set to 0.

Creating and Modifying a Customer's Loan Profile

You create a loan profile for customers to connect the account or service to a loan configuration. When the customer is granted a loan, the information for that cycle, such as amount loaned and number of loans, is stored in the loan profile.

To create a loan profile, use PCM_OP_CUST_CREATE_PROFILE. This opcode is called by PCM_OP_CUST_COMMIT_CUSTOMER. To modify the fields in a loan profile, use PCM_OP_CUST_MODIFY_PROFILE. See "Managing and Customizing Profiles" and "Creating Accounts" for more information about using these opcodes generally.

The input flist for creating a loan profile requires, at minimum, an account object, profile name (which corresponds to the name of the /config/loan object you are connecting the profile to), the maximum number of active loans, eligibility, and loan cycle frequency. You can optionally specify:

• Service details
• Thresholds for offering loans (these are stored in the credit profile of the associated balance group)
• Loan repayment details
• Maximum loan amounts (which overrides the fixed or scaled maximum amount specified in the /config/loan object)

For example, to create a profile:

0 PIN_FLD_POID                     POID      [0] 0.0.0.1 /profile/loan -1 0
0 PIN_FLD_ACCOUNT_OBJ                       POID      [0] 0.0.0.0 /account -1 0
0 PIN_FLD_SERVICE_OBJ                       POID      [0] 0.0.0.0 /service/telco/gsm -1 0
0 PIN_FLD_SERVICE_ID                        STR       [0] "0049100098"
0 PIN_FLD_PROFILES                          ARRAY     [0] allocated 20, used 7
1    PIN_FLD_PROFILE_OBJ                    POID      [0] 0.0.0.1 /profile/loan -1 0
1    PIN_FLD_INHERITED_INFO                 SUBSTRUCT [0] allocated 20, used 5
2        PIN_FLD_LOAN_INFO                  SUBSTRUCT [0] allocated 20,used 4
3            PIN_FLD_EXTERNAL_ELIGIBILITY   INT       [0] 1
3            PIN_FLD_PROFILE_NAME           STR       [0] "Loan Configuration 1"
3            PIN_FLD_FREQUENCY              INT       [0] 30
3            PIN_FLD_UNIT                   ENUM      [0] 4
3            PIN_FLD_OPT_LOAN               INT       [0] 1
3            PIN_FLD_MAX_ACTIVE_LOANS       INT       [0] 3
3            PIN_FLD_REPAYMENT_DAYS         INT       [0] 14
3            PIN_FLD_PULLBACK               INT       [0] 1
3            PIN_FLD_LOAN_THRESHOLDS_FIXED  STR       [0] "|15|20"
2        PIN_FLD_LIMIT                      ARRAY     [0] allocated 20,used 4
3            PIN_FLD_VALID_FROM             TSTAMP    [0] (1659423601) Tue Aug  2 00:00:01 2022
3            PIN_FLD_CREDIT_LIMIT           DECIMAL   [0] 100

This example specifies the following details:

• Loan cycle details: PIN_FLD_FREQUENCY and PIN_FLD_UNIT specify that the loan cycle resets every 30 days.
• Threshold details: PIN_FLD_LOAN_THRESHOLDS_FIXED field specifies to offer a loan when the customer's balance reaches 20, then 15. These fields can be set for packages at design time and updated for individual customers in their loan profiles.
• Repayment details:
  • PIN_FLD_REPAYMENT_DAYS specifies that the customer must pay the loan back in 14 days.
  • PIN_FLD_PULLBACK specifies that any outstanding balance that remains after 14 days will be pulled from the customer's available balance.
• Maximum loan details:
  • PIN_FLD_MAX_ACTIVE_LOANS specifies that the customer can have a maximum of 3 active loans at a time.
  • The PIN_FLD_LIMIT array specifies a maximum loan amount of 100, starting on August 2, 2022. This overrides any maximums specified in the /config/loan object for the associated loan.

To modify the same profile:

0 PIN_FLD_POID POID [0] 0.0.0.1  /profile/loan 239534 0
0 PIN_FLD_PROFILES ARRAY [0] allocated 20, used 7
1    PIN_FLD_PROFILE_OBJ POID [0] 0.0.0.1  /profile/loan 239534 0
1    PIN_FLD_INHERITED_INFO SUBSTRUCT [0] allocated 20, used 5
2        PIN_FLD_LOAN_INFO SUBSTRUCT [0] allocated 10, used 4
3            PIN_FLD_LOAN_THRESHOLDS INT [0] 80
2        PIN_FLD_LIMIT ARRAY [0] allocated 20,used 4
3            PIN_FLD_VALID_FROM TSTAMP [0] (1675324802)  Thu Feb  2 00:00:02 2023
3            PIN_FLD_CREDIT_LIMIT DECIMAL [0] 200

In this example:

• PIN_FLD_LOAN_THRESHOLDS specifies to offer a loan when 80% of the customer's balance is consumed.
• The PIN_FLD_LIMIT array adds a new maximum loan amount of 200, starting February 2, 2023.

Customizing Loan Recovery

To customize the loan recovery process, use the PCM_OP_LOAN_POL_PRE_RECOVER_LOAN policy opcode. By default, this policy opcode does nothing.

This policy opcode is called by internal loan recovery opcodes, before transferring balances from payment or balance transfer events to loan items.