8 Configuring Payment Incentives

This chapter provides an overview of how payment incentives are handled in your Oracle Communications Billing and Revenue Management (BRM) system. It includes:

  • A summary of the payment incentive functionality.

  • An overview of how BRM processes payment incentives.

  • Information on how to enable BRM for payment incentives, create payment incentive products, and manually reverse a payment incentive.

For information on customizing payment incentives, see "Customizing Payment Incentives".

For background information on payments, see "About Payments".

About Payment Incentives

A payment incentive is a special compensation for customers who pay their bills early and in full. Payment incentives can take the form of free gifts, certificates, free minutes, and so forth. In typical implementations, they reward customers by reducing the bill amount or adding resource bonuses to their accounts. Payment incentives can include currency resources such as monetary credit or non-currency resources such as free minutes. For example, you can award 20 free minutes or provide a 5% reduction in the monthly bill amount. In addition, you can define attributes that govern whether a payment incentive is granted. These attributes specify the types of customers that qualify, the payment methods that qualify, and so forth.

BRM determines an account's basic eligibility for a payment incentive at payment time but applies the payment incentive during billing, as shown in Figure 8-1:

Figure 8-1 Payment Incentive Time Line

Description of Figure 8-1 follows
Description of ''Figure 8-1 Payment Incentive Time Line''

Here, the payment incentive is applied to the current bill, but you can apply it to the next bill instead.

About Setting Up Payment Incentives

You create payment incentives in Pricing Center by defining a product and rate plan. You can create payment incentives for the following product types:

  • Subscription: Create a subscription product for payment incentives that you want to apply on a recurring basis (for example, a reduction in the monthly bill). Subscription products must be purchased by the customer.

  • System: Create a system product for payment incentives that you want apply to an entire class of accounts. For example, to reward all your customers who pay by credit card, you create the payment incentive as a system discount.

A single payment incentive can impact multiple resources (for example, both free minutes and the amount due for a cycle forward fee). Customers may be eligible for multiple payment incentives depending on which products they purchase and whether any payment incentive system products are valid for their account. For more information on creating products and rate plans, see Pricing Center Help.

BRM calculates payment incentives through real-time rating based on attributes you define in the Pricing Center rate plan selector. By default, BRM works with three attributes when determining the payment incentive: customer segment, payment channel, and payment method. To expand the attributes available through the rate plan selector, you customize the PCM_OP_PYMT_POL_GRANT_INCENTIVE policy opcode such that the flist includes extra field types or provides additional filtering logic. You also extend the /event/billing/incentive storable class to include the added fields. After you perform this customization, you can create payment incentive rate plans that enable BRM to consider the additional attributes.

In addition to creating payment incentives, you must enable payment incentives in BRM. To perform this task, you modify the /config/business_params storable object.

For more information on performing these tasks, see the following:

About Payment Incentive Processing

BRM determines whether to apply a payment incentive when it allocates the payment for the previous bill. BRM makes this decision by verifying:

  • Account eligibility for payment incentives.

  • Full payment before the bill due date.

If the account qualifies for a payment incentive by meeting both of these conditions, BRM adds a trigger to the /billinfo object. This is known as provisioning the payment incentive.

During the next billing run, BRM checks the /billinfo object for this trigger. If the trigger is present, indicating that the payment incentive is provisioned, BRM passes the payment incentive information to the rating opcodes to calculate the payment incentive. Depending on how the payment incentive is set up, BRM performs one of these actions:

  • If the payment incentive is a fee reduction, BRM subtracts the incentive amount from the total currency amount.

  • If the payment incentive is a resource grant such as free minutes, BRM reduces or increases the total resource amount by the incentive amount, depending on the conventions you use for non-currency resources.

In either case, the payment incentive is applied to the default balance group of the bill unit associated with the bill.

During real-time rating, BRM bases its calculations on either the current bill total or the last bill total, depending on how your pricing expert defined the product.


The current bill total indicates the current bill amount. This does not include the debits and credits from the previous bill.

In default implementations, payment incentives are granted after BRM processes all billing time events including the application of taxes. Therefore, payment incentives cannot be based on a pre-tax bill amount: only on the total after-tax amount. However, you can customize the PCM_OP_PYMT_POL_GRANT_INCENTIVE policy opcode to consider all the /bill items on a before tax basis.

Figure 8-2 shows how BRM processes payment incentives:

Figure 8-2 BRM Payment Incentives Processing

Description of Figure 8-2 follows
Description of ''Figure 8-2 BRM Payment Incentives Processing''

Payment incentives are granted only in the billing run for the account's normal billing cycle. BRM does not apply payment incentives for:

  • On-demand billing runs.

  • Bill-now billing runs.

If these types of billing runs occur during a billing cycle, BRM ignores any payment incentives. Later, BRM applies the payment incentive during the next normal billing run, provided there was an early payment within the normal billing cycle and the account is eligible.

How Payment Reversals Affect Payment Incentives

The provisioning of payment incentives can be reversed under certain circumstances, particularly ones that involve unconfirmed payments: those where a payment was allocated before the credit card processor or automated clearing house (ACH) verified funding. For example, a customer pays a bill early by personal bank check, and BRM allocates an unconfirmed payment, consequently applying the incentive. Then, the ACH notifies BRM that the bank account had insufficient funds, and the check failed. In this case, BRM must reverse both the payment and the payment incentive provision.

The payment reversal itself triggers the reversal of the payment incentive provision. If a payment is reversed, BRM reverses only those payment incentives that meet these conditions:

  • The payment incentive has been provisioned.

  • The payment incentive has not yet been applied to the account during a billing run.

If the payment incentive was already applied, you must perform the adjustment manually. For information on streamlining manual reversals, see "Manually Reversing a Payment Incentive".


Unconfirmed payment processing requires a custom payment Data Manager (DM) to post the payments immediately. The DM requires an input flist of payments from BRM, and must return the results to BRM in the output flist. For more information, see "About Unconfirmed Payment Processing".

Enabling BRM for Payment Incentives

By default, BRM does not process payment incentives. You can enable this feature by modifying a field in the ar instance /config/business_params object created during BRM installation. As part of payment allocation, payment reversal, and billing, BRM reads this object, checking the payment incentive array to determine whether the PIN_FLD_PARAM_VALUE field for this array is set to enable payment incentives.

You modify the /config/business_params object by using the pin_bus_params utility. For information on this utility, see pin_bus_params.

To enable payment incentives:

  1. Use the following command to create an editable XML file for the BusParamsAR parameter class:

    pin_bus_params -r BusParamsAR bus_params_AR.xml 

    This command creates the XML file named bus_params_AR.xml.out in your working directory. If you do not want this file in your working directory, specify the full path as part of the file name.

  2. Search the XML file for following line:

  3. Change disabled to enabled.


    BRM uses the XML in this file to overwrite the existing /config/business_params object for the ar instance. If you delete or modify any other parameters in the file, these changes affect the associated aspects of BRM's billing configuration.
  4. Use the following command to load the change into the /config/business_params object:

    pin_bus_params bus_params_AR.xml 

    You should execute this command from the BRM_Home/sys/data/config directory, which includes support files used by the utility. To execute it from a different directory, see pin_bus_params.

  5. Read the object with the testnap utility or the Object Browser to verify that all fields are correct.

    See "Using testnap" in BRM Developer's Guide for general instructions on using testnap. See "Reading Objects by Using Object Browser" in BRM Developer's Guide for information on how to use Object Browser.

  6. Stop and restart the Connection Manager (CM). For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  7. (Multischema systems only) Run the pin_multidb script with the -R CONFIG parameter. For more information, see "pin_multidb" in the BRM System Administrator's Guide.

Creating Payment Incentive Products

You create payment incentives by defining products and rate plans. The rate plans you set up for payment incentives are based on the fields defined in the /event/billing/incentive event. You use these fields to create attribute combinations in Pricing Center that BRM compares with the actual event to determine whether it should rate the payment incentive and, if so, which rate to use.


You should be familiar with real-time rating before you begin. For detailed information on creating rates and pricing plans, see Pricing Center Help and BRM Setting Up Pricing and Rating.

Defining a Payment Incentive

This example uses a rate plan selector to define payment incentives based on combinations of two attributes: the payment method and customer segment:

  • The payment incentive awards a 15% reduction on the total bill amount for all customers in the ”Platinum Subscriber” customer segment who pay by credit card.

  • It also awards a $10 reduction on the total bill amount plus 30 free minutes for customers in the ”Silver Subscriber” customer segment who pay by cash.

This example includes a restriction for customers in the ”Silver Subscriber” customer segment. These customers do not qualify for a payment incentive unless their total bill is over $100.


A rate plan selector can only contain fields defined in the payment incentive event. For example, you can apply a payment incentive based on a customer segment, payment channel, or payment method, or a combination of these attributes.
  1. Start Pricing Center and begin creating a System product.


    This defines payment fees for all customer accounts. To define fees only for certain accounts, create a Subscription product and purchase the product for the account.
  2. Apply the product at the account level and define the purchase and ownership information.

  3. In the General Product Info tab, type 1 in Priority.

  4. Under Event Map, click Add.

    1. In the Event column, select Payment Incentive Event.

    2. In the Measured By column, select Current Bill Total.

    3. In the Rate Plan Structure column, select Rate Plan Selector.

  5. Set up a rate plan for the 15% total bill reduction.

    1. Under Rate Plan Selector, type 15% Reduction as the name for the payment incentive.

    2. Click Edit Plans and click New.

    3. Define the Plan Details and Rate Plan Structure.

    4. Define the Quantity Discount Bracket for the new rate as Based on: Rate Dependent.

    5. In the Balance Impacts tab, select US Dollars [840] as the Resource ID and type –0.15 in Scaled Amount. Because the value for Scaled Amount is negative, this results in a 15% reduction. (A positive number would result in a fee.)

    6. Click OK.

  6. Set up a second rate plan for the $10 total bill reduction plus the 30 free minutes. This reduction is applied only if the total for the current bill is over $100.

    1. Under Rate Plan Selector, type $10 Reduction + 30 Minutes as the name for the payment incentive.

    2. Click Edit Plans and click New.

    3. Define the Plan Details and Rate Plan Structure.

    4. Define the Quantity Discount Bracket for the new rate as Based on: Rate Dependent.

    5. In the Balance Impacts tab, deselect Minimum and type 100 in the associated entry box.

    6. Select US Dollars [840] as the Resource ID and type –10 in Fixed Amount.

    7. Add a row to the balance impacts table that sets Free Domestic Minutes as the Resource ID and enter 30 in Fixed Amount.

    8. Click OK.

  7. Set up the rate plan selector.

    1. Click ...+ in the first column, select Event, choose PIN_FLD_INCENTIVE.PIN_FLD_PAY_TYPE from the attributes list, and click OK.

    2. Click ...+ in the next column, select Event, choose PIN_FLD_INCENTIVE.PIN_FLD_CUSTOMER_SEGMENT from the attributes list, and click OK.

    3. Click + in the row column to create a row for each of the two payment method/customer segment combinations. The system product does not provide incentives to any customers who do not meet one of these two criteria.

    4. For the first row, type 10003 to define credit card as the payment method and Platinum Subscriber to define the customer segment. Select the 15% Reduction rate plan.

    5. For the second row, type 10011 to define cash as the payment method and Silver Subscriber to define the customer segment. Select the $10 Reduction + 30 Minutes rate plan.

    6. Click OK and Apply.

Customizing Payment Incentives

You can configure BRM to grant payment incentives. See "Configuring Payment Incentives".

To customize payment incentives, read the following:

How Payment Incentives Work

Payment incentives are implemented by calling PCM_OP_PYMT_PROVISION_INCENTIVE and PCM_OP_PYMT_GRANT_INCENTIVE.

PCM_OP_PYMT_PROVISION_INCENTIVE evaluates a payment to determine whether a payment incentive should be provisioned and, if so, sets the payment incentive trigger. If a payment incentive is triggered, the PCM_OP_PYMT_GRANT_INCENTIVE performs the incentive.

For more information, see "How Payment Incentives Are Triggered" and "How Payment Incentives Are Granted".

How Payment Incentives Are Triggered

PCM_OP_PYMT_PROVISION_INCENTIVE is called by PCM_OP_BILL_ITEM_TRANSFER immediately after payment allocation, provided BRM is configured for payment incentives.

PCM_OP_PYMT_PROVISION_INCENTIVE determines whether the payment resulted in an early, in-full settlement of the last bill. If so, the current bill may be eligible for a payment incentive and PCM_OP_PYMT_POL_PROVISION_INCENTIVE creates a trigger for payment incentive processing to apply an incentive.

PCM_OP_PYMT_PROVISION_INCENTIVE performs the following functions:

  1. It calls the PCM_OP_PYMT_POL_PROVISION_INCENTIVE policy opcode to determine if the PIN_EFFECTIVE_T field or any other customizable field contains a payment timestamp. See "Customizing How to Trigger Payment Incentives".

  2. It retrieves all of the bills and determines whether each of the bills is from the last billing cycle or a prior cycle. PCM_OP_PYMT_PROVISION_INCENTIVE is only concerned with the bills from the last billing cycles; none of the other bills qualify for early incentives.

  3. It reads the Due and Due Time in each /bill object. PCM_OP_PYMT_PROVISION_INCENTIVE uses this information along with the timestamp in the PIN_FLD_END_T field from the /event/billing/payment object or a timestamp from the policy opcode to determine whether the payment for a given bill was allocated in full and early. PCM_OP_PYMT_PROVISION_INCENTIVE must find the following conditions:

    • PIN_FLD_DUE must be 0, indicating that there are no more payments due for the bill, and it was paid in full.

    • The timestamp in PIN_FLD_END_T or the timestamp provided by the policy opcode must be earlier than or the same as the one in PIN_FLD_DUE_T, indicating that the payment was allocated before or at the same time as the due time. BRM considers both of these conditions to be indications of an early payment.

    BRM always attempts to use whatever timestamp the policy opcode provides. PCM_OP_PYMT_PROVISION_INCENTIVE only uses PIN_FLD_END_T if the policy opcode does not return a timestamp or returns PIN_FLD_END_T instead of some other timestamp.

  4. If the payment meets these conditions, PCM_OP_PYMT_PROVISION_INCENTIVE modifies the /billinfo object by setting the PIN_FLD_PAYMENT_EVENT_OBJ to the POID of the payment event that resulted in early, in-full payment. This acts as a trigger for granting the payment incentive during the billing run.

  5. It returns a list of /billinfo objects to which it added the payment incentive.

Customizing How to Trigger Payment Incentives

You can configure the PCM_OP_PYMT_POL_PROVISION_INCENTIVE policy opcode to determine the payment date that should be considered when provisioning incentives.

This policy opcode is called by PCM_OP_PYMT_PROVISION_INCENTIVE to provide the payment date that will be used when determining whether the bill was paid on time. It receives the POID of the /event/billing/payment object in the input flist and reads this object to determine the payment date. If it finds a payment date it's configured to provide, it returns the date to PCM_OP_PYMT_PROVISION_INCENTIVE, which performs the following tasks:

  • Retrieves the bill for which the payment allocation was made.

  • Determines if the bill was the last bill.

  • Compares the timestamp provided by the policy opcode to the due date for the payment.

By default, PCM_OP_PYMT_POL_PROVISION_INCENTIVE reads the PIN_FLD_END_T field to obtain the timestamp.

You can customize PCM_OP_PYMT_POL_PROVISION_INCENTIVE to provide the timestamp from a field other than PIN_FLD_END_T (for example, PIN_FLD_EFFECTIVE_T) or to apply business logic that determines the payment date.

For example, you can customize this opcode to use the payment receipt date as the payment timestamp for all credit card payments, and 3 days after the payment receipt date for all check payments.

You can also create custom payment objects that use fields other than PIN_FLD_EFFECTIVE_T or its equivalent. In this case, you would customize this policy opcode to read these fields and provide them as output for PCM_OP_PYMT_PROVISION_INCENTIVE.

How Payment Incentives Are Granted

PCM_OP_PYMT_GRANT_INCENTIVE is called by PCM_OP_BILL_MAKE_BILL as part of the billing run. PCM_OP_PYMT_GRANT_INCENTIVE grants payment incentives based on:

  • Whether the account has purchased a payment incentive subscription product or the account is eligible for a system product that includes a payment incentive.

  • Whether the payment incentive trigger is set in the /billinfo object.

  • Conditions specified in the rate plan.

  • Any additional conditions specified in the PCM_OP_PYMT_POL_GRANT_INCENTIVE policy opcode.

PCM_OP_PYMT_GRANT_INCENTIVE performs the following functions:

  1. If the bill qualifies for a payment incentive, the opcode uses information from the /account and /event/billing/payment objects to enrich the input flist with the payment method, payment channel, and customer segment list. It also includes:

    • The total for the current bill calculated during the current billing run.

    • The total for the last bill, as determined from the /bill object for that bill.

    By default, both these totals are after-tax amounts.

  2. It calls the PCM_OP_PYMT_POL_GRANT_INCENTIVE policy opcode to determine whether it must enrich the input flist with any extra fields, and validates the fields returned by the policy opcode. See "Customizing Payment Incentives".

  3. It creates an /item/incentive object and an /event/billing/incentive object for the bill. In addition to the payment method, payment channel, and so forth, the /event/billing/incentive object contains any fields specified in the PCM_OP_PYMT_POL_GRANT_INCENTIVE policy opcode, provided the object has been suitably extended.

  4. It sends the event to the rating opcodes to calculate the payment incentive for each bill. BRM applies the balance impact of the payment incentive event to the default balance group of the bill unit.

  5. It clears the payment incentive trigger in the PIN_FLD_PAYMENT_EVENT_OBJ field for the /billinfo objects of each affected bill, returning this field to a null value.

Two other standard opcodes are used for payment incentives:

Customizing How to Grant Payment Incentives

By default, you can set up a rate plan so that BRM considers three attributes when determining whether to apply a payment incentive:

  • Customer segment

  • Payment channel

  • Payment method.

You can broaden this scope by customizing the PCM_OP_PYMT_POL_GRANT_INCENTIVE policy opcode. When you customize this opcode, you must also extend the /event/billing/incentive storable class.

You implement additional attributes that BRM can work with by customizing the PCM_OP_PYMT_POL_GRANT_INCENTIVE policy opcode to include a broader set of account and service attributes (for example, service type, currency type, and so on). PCM_OP_PYMT_POL_GRANT_INCENTIVE augments the input flist by adding fields that PCM_OP_PYMT_GRANT_INCENTIVE includes when creating the /event/billing/incentive object.

If you include additional attributes in PCM_OP_PYMT_POL_GRANT_INCENTIVE, you must also extend the /event/billing/incentive object by adding these fields so that the object records all the criteria considered for the payment incentive. The additional fields are then included in the choices you can make when creating columns in the Pricing Center rate plan selector. Therefore, you can use these additional fields as criteria when defining attribute combinations that result in payment incentives.

The contents of the /event/billing/invoice object determine:

  • The list of attributes that can be considered when setting up a rate plan. The pricing expert associates combinations of these attributes with specific rate plans when creating the payment incentive product.

  • The information BRM compares with the attribute combinations defined for the payment incentive product. If BRM finds a match, it rates the payment incentive event according to the rate plan for the matching combination.

For example, to award a payment incentive to premium customers who pay in a certain currency, you perform two tasks:

  • Customize PCM_OP_PYMT_POL_GRANT_INCENTIVE by adding the PIN_FLD_SERVICE_OBJ and PIN_FLD_CURRENCY fields to the input flist. The opcode then includes the service type for the account and the currency type in the information sent to the real-time rating opcodes. As a result, the rating opcodes are able to consider the service type and currency along with the usual criteria when determining whether to apply the incentive and when calculating the payment incentive.

  • Extend the /event/billing/incentive class by adding the PIN_FLD_SERVICE_OBJ and PIN_FLD_CURRENCY fields. BRM then includes the service type and currency in the event object each time it's created. When you create columns in the rate plan selector, you can select these two fields along with the default fields.

In addition to performing this type of customization, you can also customize the PCM_OP_PYMT_POL_GRANT_INCENTIVE policy opcode to do the following:

  • Provide special types of incentives such as free gifts. In this case, you modify the opcode so that it calls the opcodes that process and control product purchases, for example, PCM_OP_SUBSCRIPTION_PURCHASE_DEAL. Then, you create a deal that includes an item product that awards the free gift.

  • Develop an aggregation application to count the number of subscription services for an account and customize PCM_OP_PYMT_POL_GRANT_INCENTIVE to include this information in the enriched flist.

  • Customize which customer segment to use. You can also customize this opcode to select a different customer segment from PIN_FLD_CUSTOMER_SEGMENT_LIST. By default, PCM_OP_PYMT_POL_GRANT_INCENTIVE selects the first customer segment from the PIN_FLD_CUSTOMER_SEGMENT_LIST it gets from PCM_OP_PYMT_GRANT_INCENTIVE. The customer segment returned by PCM_OP_PYMT_POL_GRANT_INCENTIVE is the one that BRM uses as a filtering attribute during payment incentive calculation.

How Payment Incentives Are Reversed

PCM_OP_PYMT_REVERSE_INCENTIVE reverses a payment incentive if it has not yet been granted.

PCM_OP_PYMT_REVERSE_INCENTIVE is called by PCM_OP_BILL_REVERSE_PAYMENT as part of payment reversal, provided BRM is configured for payment incentives. It determines whether payment is being reversed for a bill that had a payment incentive either provisioned or granted. If so, it either deactivates the payment incentive trigger or, for payment incentives that have already been granted, issues warnings and flags the reversal event so that you can initiate manual processing.

PCM_OP_PYMT_REVERSE_INCENTIVE performs the following functions:

  1. It retrieves all bills affected by the reversal and searches for the associated /billinfo objects.

  2. For each /billinfo object, it checks the PIN_FLD_PAYMENT_EVENT_OBJ field to determine whether a payment incentive has been provisioned but not yet granted. If so, it resets this field, removing the POID of the payment event, which automatically reverses the payment incentive.

  3. If the PIN_FLD_PAYMENT_EVENT_OBJ field does not indicate that a payment incentive has been provisioned, the opcode searches all /event/billing/incentive objects for the account to determine whether any of them are associated with the bill for which payment is being reversed.

    The existence of this object for a given bill means that BRM already granted a payment incentive for the bill. In this case, the opcode generates a warning in the cm.pinlog file to indicate that manual adjustment is required.

Manually Reversing a Payment Incentive

When a payment is reversed, BRM reverses any payment incentive provisioning triggers created at payment time, provided the payment was for the last bill. If payment was reversed for an earlier bill, BRM has already applied the incentive and does not reverse it. In this case, you must perform a manual account adjustment through your CRM client application. This type of adjustment debits account resources rather than crediting them.

BRM identifies payment incentives that need manual reversal in the cm.pinlog file, which lists any cases where a payment incentive reversal failed. Searching the cm.pinlog for this information can be time consuming. Therefore, you should consider customizing this process in one of the following ways:

  • Write your own reporting application that creates a list of all bills that meet the following two conditions:

    • The bill had a payment incentive that was not only provisioned, but also granted.

    • The payment reversal was for the bill before the one that had the payment incentive granted.

    Operations personnel can use this report to identify the adjustments they must perform.

  • Create your own custom opcode or customize the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode so that it checks the reporting conditions discussed above and alerts the CRM client application whenever both conditions are true. Then, enable event notification and add the following information to your system's event notification list so that BRM calls PCM_OP_ACT_POL_EVENT_NOTIFY (opcode number 301) each time an /event/billing/reversal/* event is generated during payment reversal:

    # comment, if any
    301    0    /event/billing/reversal/cc
    301    0    /event/billing/reversal/check
    301    0    /event/billing/reversal/dd
    301    0    /event/billing/reversal/payorder 
    301    0    /event/billing/reversal/postalorder
    301    0    /event/billing/reversal/transfer

    For more information, see "Using Event Notification" in BRM Developer's Guide.

    In addition, you must customize your middleware and CRM applications to process the notification correctly and issue appropriate messages to operations personnel.