Configuring Loans

About Loans

Prepaid customers can opt-in to receive the following types of loan:

Dynamic loans are granted when a customer's credit limit is crossed during rating. For example, if a customer's balance is $5, their credit limit is set to $0, and they try to purchase a subscription for $10, they can be granted a loan for the remaining $5. You enable dynamic loans when configuring subscription charge offers in PDC.
Offered loans are offered when a customer's balance falls below a threshold set in their credit profile and are granted after the customer confirms. Loans can be offered either when the threshold is crossed during subscription or usage charging.
Channel loans are granted when a customer uses an external purchase channel, such as an external app, an Unstructured Supplementary Service Data (USSD) gateway, or interactive voice response (IVR) system to use a loan to purchase a package. These channels send the purchase and loan request to BRM, and BRM checks eligibility and grants the loan without considering or consuming the customer's current balance.
You must configure a policy opcode to grant channel loans after rating is complete. See "Granting a Channel Loan" in BRM Opcode Guide for more information.

You recover loans from customers from the next top-up or balance transfer they make.

When configuring loans and customer loan profiles, you can:

Charge service fees, taxes, and late repayment fees.
Configure loan offer thresholds.
Set the number of days before repayment is considered late and specify what happens after; you can charge a late fee or pull the amount due from the customer's available balance.
Configure what happens if a top-up amount is less than the full amount due for the loan, including service fees, taxes, and late fees.
Set the maximum number of active loans for a customer.

Although loans are always for currency resources, you can optionally grant noncurrency resources along with the currency loan. You can also calculate the maximum amount to loan based on the previous month's consumption of a noncurrency resource.

Loan amounts are temporarily added to the customer's credit limit so that they do not count against them in credit checks.

About Loan Thresholds

You can set loan thresholds either as a percent of the balance, or a fixed amount. When the customer's balance falls below their loan threshold, the /event/notification/threshold_loan event is generated and a notification is sent to the customer to offer a loan. The notification is then resent each day until the balance is no longer below the threshold.

You configure loan thresholds for all customers when creating packages in PDC or plans in BRM using the XML Pricing Interface. When a customer purchases the package, the thresholds are stored in the /config/credit_profile associated with the customer's balance group. You can update the loan offer thresholds for individual customers when creating or modifying the customer's loan profile. See:

"Setting Loan Thresholds for Packages" in PDC Creating Product Offerings
"Setting Loan Thresholds for Plans" in BRM Configuring Pipeline Rating and Discounting
"Creating and Modifying a Customer's Loan Profile" in BRM Opcode Guide

You must configure your charging application to send the notification generated for the /event/notification/threshold_loan event, manage the customer's response by USSD, IVR, or other self-care application, and request the loan from BRM with the PCM_OP_LOAN_APPLY_LOAN opcode or BRM REST APIs if the customer accepts the loan.

About Recovering Loans

You automatically recover loans granted to your customers the next time they top up their balance, either by making a standard or sponsored top-up. You can also customize the events for recurring charges or adjustments to call the PCM_OP_LOAN_RECOVER_LOAN opcode in the pin_notify file.

Any top-up balance remaining after the loan and all associated service fees and taxes have been recovered is credited to the main account balance.

If the top-up amount is less than the amount due for the loan, you can:

Partially recover the loan using a percentage of the top-up balance, credit the remaining amount to the main account balance, and notify the customer of the remaining amount due.
Reject the top-up and notify the customer that they must pay the full amount.

If the payment associated with a top-up is reversed, the loan recovery is also reversed.

Configuring Loans

At a high level, configuring loans involves the following:

Configure loans in /config/loan configuration objects and load them to the BRM database by using the load_config utility. See "Loading Your Loan Information into the BRM Database."
To grant noncurrency resources with loans, create charge offers for the /event/billing/loan_grant event. See "Configuring Charge Offers" in PDC Creating Product Offerings.
To apply loan service fees, if you did not configure the amount in the /config/loan object, create charge offers for the /event/billing/loan_fee event. You can use the loan amount as a RUM for the charge. See "Configuring Charge Offers" in PDC Creating Product Offerings.
Configure what happens during loan recovery if the top-up amount is less than the loan amount due:
- To allocate a percentage of a top-up to loan repayment, set the loan_repayment_percent subscription business parameter. Set this parameter to a number between 0 (none of the top-up goes to repaying the loan) and 100 (all of the top-up goes to repaying the loan). The default is 100. See "Configuring BRM by Using the pin_bus_params Utility" and "business_params Reference" in BRM System Administrator's Guide for more information about configuring business parameters.
- To reject the top-up completely and notify the customer of the amount due, customize the PCM_OP_LOAN_POL_PRE_RECOVER_LOAN policy opcode. This is an empty policy hook that can be called during payment and balance transfer flows for top-ups.
When creating subscription charge offers in PDC, specify that a loan can be applied if the customer has insufficient credit. See "Allowing Customers to Exceed Their Credit Limit" in PDC Creating Product Offerings.
When using the XML Pricing Interface to create packages in PDC or plans in BRM, set balance thresholds for offering loans to customers. See "Setting Loan Thresholds for Packages" in PDC Creating Product Offerings or "Setting Loan Thresholds for Plans" in BRM Configuring Pipeline Rating and Discounting.
Configure whether customers want to receive loans, and how loans are implemented for the customer by creating loan profiles (/profile/loan objects). Loan profiles store the details for the current loan cycle. See "Creating a Customer's Loan Profile" in BRM Opcode Guide.
Set loan thresholds for customers in /config/credit_profile objects. See "Setting a Customer's Automatic Loan Threshold" in BRM Opcode Guide.

Loading Your Loan Information into the BRM Database

Your loan information includes parameters such as maximum and minimum amounts, minimum eligible account age, eligible locations, service fees, and tax codes. You load the loan information into /config/loan objects in the BRM database. You can create new /config/loan objects, or update existing ones.

To set up and load loan information:

Open the BRM_home/sys/data/config/config_loan.xml file in an XML or text editor, where BRM_home is the directory in which the BRM server software is installed.

Provide the values listed in Table 20-1:

Table 20-1 Fields in the Loan Configuration Object

Field	Description
DESCR	(Optional) The loan configuration object's description.
NAME	(Required) The name of the loan configuration object. If a /config/loan object with this name already exists, its fields are updated with the new values provided. If it doesn't exist, a new object is created.
CREDIT_AMOUNT	(Required) The default loan amount to grant. The account's primary currency is used. If there is no amount specified on a loan request, this value is used.
LOAN_FIXED_FEE	(Optional) The fixed amount to charge as service fee. If you specify this, you cannot specify LOAN_PERCENT_FEE.
LOAN_PERCENT_FEE	(Optional) The percent of the loan to charge as a service fee. For example, if the requested amount is 10, and you set PERCENT_FEE to 10, the service fee will be $1. If you specify this, you cannot specify LOAN_FIXED_FEE.
AGE	(Optional) The minimum number of days, months, or years the account must be active to be eligible for a loan.
UNIT	(Optional) The unit for the AGE field. Can be: 4 (days) 5 (months) 6 (years)
LOAN_MINIMUM	(Optional) The minimum amount for the loan. Used only for dynamic loans. If the specified amount on the loan request is less than the minimum, the loan is rejected.
FIXED_MAXIMUM	(Optional) The maximum fixed amount to grant for each loan cycle. This amount can represents a total amount from multiple loans. For example, if the amount specified in a loan request is 10, and FIXED_MAXIMUM is set to 30, that loan could be granted a maximum of three times in the cycle. You configure the loan cycle in the /profile/loan object. See "Creating a Customer's Loan Profile" in BRM Opcode Guide. If you specify this, you cannot specify SCALED_MAXIMUM.
SCALED_MAXIMUM	(Optional) The maximum scaled amount to grant. This is a percent of the resource specified in RESOURCE_ID, which represents consumption of a noncurrency resource in the previous calendar month. For example, if you set SCALED_MAXIMUM to 50% and use the resource ID for GB of data, the maximum loan amount is calculated by determining the cost of 50% of the GB used by the customer in the previous month. If a customer pays $20 monthly for 10GB of data, and used the full 10GB in the previous month, the maximum loan amount would be $10. If you specify this, you cannot specify FIXED_MAXIMUM.
RESOURCE_ID	(Optional) The ID of a noncurrency resource to use when calculating the loan when SCALED_MAXIMUM is specified. This resource ID is unrelated to noncurrency resources you can grant with loans by the /event/billing/loan_grant event. Those are specified in the loan request.
MAX_QUANTITY	(Optional) The maximum number of times the loan can be granted in each loan cycle.
TAX_CODE	(Optional) The tax code for the loan service fee.
LOAN_TAX_CODE	(Optional) The tax code for the loan.
REASON_ID	(Optional) The A/R reason code to map to the G/L ID.
REASON_DOMAIN_ID	(Optional) The A/R reason domain to map to the G/L ID.
LOCATION_MODE	(Optional) Whether the locations specified in the LOCATIONS array are eligible for the loan (0) or ineligible (1).
LOCATIONS	(Optional) An array of locations. If LOCATION_MODE is set to 0, only the locations specified in the array are eligible for the loan. If you don't specify any locations in the array, all locations are eligible. If LOCATION_MODE is set to 1, the array is required. The locations specified in the array are not eligible for the loan.
LOCATION	(Optional) A location, specified in an array under LOCATIONS. This can be a ZIP code, city, state, or ISO-3166 country code.

Save and close the file.
Run the following command, which loads the contents of the file into the /config/loan object:
```
BRM_home/apps/load_config/load_config -v config_loan.xml
```
The load_config utility validates the contents using the config_loan.xsd file before loading the data.

See "load_config" in BRM Developer's Guide for more information about the utility's syntax and parameters.
Read the object by using the robj command with the testnap utility or by using Object Browser in Developer Center to verify that the creditor configurations are loaded.
See "Using the testnap Utility to Test BRM" in BRM Developer's Guide for general instructions on using the testnap utility.
Stop and restart the Connection Manager (CM).

See "Loan Configuration Examples" for examples of how to use the loan configuration fields.

Loan Configuration Examples

The following examples show how to configure different kinds of loan.

Example: Configuring an offered loan

This example shows how to configure a loan for $10 and:

Charge a fixed fee of $0.50
Grant the loan only to accounts in the USA that have been active for at least 6 months
Grant a maximum worth 50% of the data used from the previous month
Restrict customers to one loan per cycle
Grant 1GB of data with the loan

It also shows how to set up the customer's loan profile to:

Resets the loan cycle every 30 days.
Offer a loan when the customer's balance reaches 5.
Require the customer to pay the loan back 14 days after it is granted. Repayment details:
Pull any outstanding balance after 14 days from the customer's available balance.
Have a maximum of 3 active loans at a time.

To do this:

Create a /config/config_loan object and import it using the load_config utility. The following shows the sample XML for the /config/config_loan object:

<ConfigObject>
    <DESCR>Loan for $10</DESCR>
    <NAME>10DollarLoan</NAME>
    <LOAN_INFO>
        <CREDIT_AMOUNT>10</CREDIT_AMOUNT>
        <LOAN_FIXED_FEE>.50</LOAN_FIXED_FEE>
        <AGE>6</AGE>
        <UNIT>5</UNIT>
        <RESOURCE_ID>1000100</RESOURCE_ID>
        <MAX_QUANTITY>1</MAX_QUANTITY>
        <SCALED_MAXIMUM>50</SCALED_MAXIMUM>
        <TAX_CODE>purchase</TAX_CODE>
        <LOAN_TAX_CODE>usage</LOAN_TAX_CODE>
        <REASON_ID>2</REASON_ID>
        <REASON_DOMAIN_ID>Reason Codes - Loan Reasons</REASON_DOMAIN_ID>
        <LOCATION_MODE>0</LOCATION_MODE>
        <LOCATIONS>
            <LOCATION>US</LOCATION>
        </LOCATIONS>
    </LOAN_INFO>
</ConfigObject>

When creating subscription charge offers in PDC, specify that a loan can be applied if the customer has insufficient credit. See "Allowing Customers to Exceed Their Credit Limit" in PDC Creating Product Offerings.
Create a charge offer with a charge for the /event/billing/loan_grant event that has a credit balance impact of 1GB of data.

Create the customer's loan profile to opt-in for loans, define loan thresholds, and other settings by using the following input flist for the PCM_OP_CUST_CREATE_PROFILE opcode:

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 235101 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] "5"

See BRM Opcode Guide for more information about using opcodes.

When the customer's balance drops below $5, they are automatically sent a notification offering them the loan. If they accept and the charging system sends the request to BRM, the following happens:

If the current date is later than the reset date specified in the loan profile for the loan cycle, the number of loans and credit amount for the loan cycle in the loan profile is reset.
BRM checks whether the customer is eligible for the loan. In this scenario, it confirms that:
- The customer has opted in to receive loans
- The customer's maximum number of active loans hasn't been met
- The amount requested does not make the CREDIT_AMOUNT in the loan profile exceed the scaled maximum amount for this loan cycle. In this example, the amount must be less than the value of half of the customer's data for the previous month. If the customer currently pays $20 a month for 10GB of data, and they used all of their data in the previous month, the maximum amount of loans they can receive for this cycle is $10.
- The number of times the loan can be granted for this cycle is not exceeded.
- The customer's location is eligible.
- The customer's account has been active long enough.
- The customer's account status is active.
- There is no missing or incorrect information, such as an incorrect resource ID.
The loan is granted to the eligible customer. A $10 credit is added to their account balance. Their credit limit is temporarily raised to include the credit, the fee, and tax.
A non-billable open item is created for the $0.50 fee.
General ledger information is recorded.
Because the request input flist contained a noncurrency resource ID, an /event/billing/loan_grant event is generated, and the charge offer granting the 1GB of data is purchased.
The customer's credit profile is updated to reflect the loan amount and number of loans granted this cycle.

Example: Configuring a dynamic loan

This example shows how to configure a dynamic loan for a currency resource and:

Charge a fee of 10%
Grant the loan to accounts that have been active for at least 10 days in all locations other than Alaska
Restrict customers to two loans per cycle

To do this:

Create a /config/loan object and import it using the load_config utility. The following shows the sample XML for the /config/loan object:

<LOAN_INFO>
    <CREDIT_AMOUNT>10</CREDIT_AMOUNT>
    <LOAN_PERCENT_FEE>10</LOAN_PERCENT_FEE>
    <AGE>10</AGE>
    <UNIT>4</UNIT>
    <LOAN_MINIMUM>2</LOAN_MINIMUM>
    <LOAN_MAXIMUM>20</LOAN_MAXIMUM>
    <MAX_QUANTITY>2</MAX_QUANTITY>
    <TAX_CODE>PURCHASE</TAX_CODE>
    <LOAN_TAX_CODE>RECURRING</LOAN_TAX_CODE>
    <REASON_ID>2</REASON_ID>
    <REASON_DOMAIN_ID>Reason Codes - Loan Reasons</REASON_DOMAIN_ID>
    <LOCATION_MODE>1</LOCATION_MODE>
    <LOCATIONS>
        <LOCATION>ALASKA</LOCATION>
    </LOCATIONS>
</LOAN_INFO>

When creating subscription charge offers in PDC, specify that a loan can be applied if the customer has insufficient credit. See "Allowing Customers to Exceed Their Credit Limit" in PDC Creating Product Offerings.

When a customer is charged for a subscription that costs $20, but only has $12 in their account, the following happens:

If the current date is later than the reset date specified in the loan profile for the loan cycle, the number of loans and credit amount for the loan cycle in the loan profile is reset.
BRM checks whether the customer is eligible for the loan. In this scenario, it confirms that:
- The customer has opted in to receiving loans
- The customer's maximum number of active loans hasn't been met
- The amount requested does not make the CREDIT_AMOUNT in the loan profile exceed the fixed maximum amount for this loan cycle.
- The number of times the loan can be granted for this cycle is not exceeded.
- The customer's location is eligible.
- The loan requested is more than the minimum amount.
- The customer's account has been active long enough.
- The customer's account status is active.
- There is no missing or incorrect information.
The loan is granted to the eligible customer. An $8 credit is added to their account balance. Their credit limit is temporarily raised to include the credit, the fee, and tax.

Note:

Even though the CREDIT_AMOUNT configured for the loan was $10, the requested amount was only $8, so only $8 is granted. If the request did not contain an amount, the CREDIT_AMOUNT would have been used.
A non-billable open item is created for the $0.80 fee.
General ledger information is recorded.
The customer's credit profile is updated to reflect the loan amount and number of loans granted this cycle.