7 Configuring Payment Fees

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

• An overview of failed payments and payment fee processing.

• Information on how to configure BRM for payment fees, create payment fee products, and manually remove a payment fee from an account balance.

For information on customizing payment fees, see "Customizing Payment Fees".

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

About Failed Payments

If you use BRM-initiated payment processing, payments are loaded directly into BRM by the payment processor. If you use externally initiated payment processing, you use Payment Tool to load payments into BRM. Regardless of the way they are loaded, by default they are posted as successful or failed, and are identified by PIN_FLD_STATUS value.

Successful payments are automatically posted to the account to which they belong. The payment amount is removed from the current balance on the account, and any remaining amount is allocated according to your business policies.

Failed payments are those that do not comply with the financial practices of your company because, upon collection, they have been dishonored or rejected by the bank. For example, payments can fail due to expired credit and debit cards, incorrect account details, and insufficient funds. You can configure BRM to charge payment fees for payments that have a failed status.

Note:

If you have the Payment Suspense Manager feature enabled, failed payments are submitted to the payment suspense account, but can still receive payment fees. See ”Configuring Payment Suspense Manager” for more information on Payment Suspense Manager.

For information on payment status, see "About Payment Status".

For information on failed unconfirmed payments, see "Handling Failed Unconfirmed Payments".

About Payment Fees

Payment fees are one-time, non-recurring penalties that can be charged to an account for payments that fail due to financial errors. For example, if a customer check is denied due to insufficient funds, or a credit card is invalid because it has expired, you can charge the customer a payment fee.

By default, payment fees can be charged only for failures that occur due to financial reasons, and not for failures that occur due to communication errors between BRM and the payment transaction service. Communication errors are considered unresolved transactions. You run the "pin_clean" utility to find all unresolved credit card and direct debit payments recorded in the BRM database. For more information, see "Resolving Failed BRM-Initiated Payment Transactions".

When a failed payment is posted in BRM, it is recorded in BRM with a balance impact of 0, and is identified by a transaction ID, a failure status, and a reason ID for the failure. BRM uses the failure status and reason ID to determine whether to apply payment fees when the payment is posted. Payment fees can be applied only to payments that have a PIN_FLD_STATUS value of PIN_PYMT_FAILED.

Note:

If the transaction ID, status or reason ID is missing from the actual payment, it can be retrieved from the payment batch header. See Payment Tool Help for information on batch headers and footers.

If you defined payment fees, the failed payment triggers the creation of a payment fee event, and the rated amount is applied to the customer's current account balance. Failed payments can be posted to an account only when the account number is available in BRM. If a failed payment is not posted, the associated fee cannot be applied.

Note:

If you have Payment Suspense Manager enabled, and configured to handle failed payments, any failed payment will be posted to the payment suspense account and will receive a payment fee. When the payment is later fixed and posted to the correct account, the payment fee will be allocated along with the payment.

You create fees for failed payments by setting up pricing plans. The product in the plan contains a rate that is mapped to the payment fee event. When you create a payment fee product, any account that own the product will receive a payment fee if a payment fails; you cannot exempt accounts from receiving payment fees. To cancel out unwanted fees from an account's balance, you set up account-level discounts for the payment fee event. See "Defining Exemptions from Payment Fees".

BRM applies the balance impact of the payment fee event to the default balance group of the bill unit.

Configuring BRM for Payment Fees

Before you can define payment fees, you must configure BRM with the payment information. After your system is configured, you create the payment fees by using pricing plans.

Setting up payment fees involves the following processes:

• Defining Payment Attributes for Payment Fees

• Defining Reason Codes for Failed Payments

Defining Payment Attributes for Payment Fees

BRM calculates payment fees by using real-time rating. Payment fees are based on attributes you define in the Pricing Center rate plan selector. By default, the rate plan selector and rating opcodes work with three attributes when determining the payment fee: customer segment, payment channel, and payment method. The failed payment storable class contains these default fields upon which you can base your payment fees.

To charge payment fees based on any of these payment attributes, you must first define the attributes in the BRM database. For information on defining payment attributes, see the following information:

• Creating and Managing Customer Segments in BRM Managing Customers

• Configuring Payment Channels

• Customizing Payment Methods in BRM Managing Customers

To expand the attributes available in the rate plan selector, you can customize the PCM_OP_PYMT_POL_APPLY_FEE policy opcode such that the flist includes extra field types or provides additional filtering logic. You also extend the /event/billing/payment/failed storable class to include the added fields. After you perform this customization, you can create payment fee rate plans that enable BRM to consider the additional attributes.

For more information, see "Customizing Payment Fees".

Defining Reason Codes for Failed Payments

Reason codes explain why payments fail, and they enable you to charge a payment fee based on the reason for the failure.

The payment gateway and your third-party payment application must be configured to identify failed payments and send reason codes with the payment information. When a failed payment is received, the reason code is mapped to the reason code ID defined in the BRM database.

You define reason codes in the reasons.locale file and load them into the BRM database as a /strings object. The file contains instructions on how to add the new domain Reason Codes - Payment Failure Reasons. For example:

DOMAIN = "Reason codes-Payment Failure Reasons";
STR
     ID = 1001 ;
     VERSION = 13 ;
     STRING = "Invalid Credit Card";
END

Note:

If you add your own reason codes to the reasons.locale file, you should use IDs above 100,000.

To define reason codes for failed payments, you edit the reasons.en_US sample file in the BRM_Home/sys/msgs/reasoncodes directory. You then use the load_localized_strings utility to load the contents of the file into the /strings objects.

When you run the load_localized_strings utility, use this command:

load_localized_strings reasons.locale

Note:

• If you are loading a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see Locale names.

• If a failed payment is loaded into BRM with an invalid reason code, payment fees are not applied.

For information on loading the reasons.locale file, see ”Loading Localized or Customized Strings” in BRM Developer's Guide. For information on creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.

Creating Payment Fees

You create payment fees by defining rates and configuring real-time rating. The rates you define for payment fees are based on the fields defined in the /event/billing/fee/failed_payment event. These fields enable you to charge and suppress payment fees.

Note:

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

Defining a Payment Fee

This example defines payment fees based on the payment method, which is the means by which customers pay their bills. It charges a $5 fee for failed wire transfers, credit card, debit card, and direct debit payments; a $7 fee for failed check, postal order, and invoice payments; and no fee for failed cash payments. Failed cash payments are handled by BRM as non-payments or overdue payments.

See "About Payment Methods" for more information about payment methods.

1. Start Pricing Center and begin creating a System product.

   Note:

   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 Failed Payment Fee Event.

   2. In the Measured By column, select Occurrence.

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

5. Set up the rate plan for the $5 fee.

   1. Under Rate Plan Selector, type a name for the payment fee.

   2. Click Edit Plans and click New.

   3. Define the Plan Details and Rate Plan Structure.

   4. In the Balance Impacts tab, select US Dollars [840] as the Resource ID and type 5.00 in Fixed Amount.

   5. Click OK.

6. Set up the rate plan for the $7 fee. Repeat step 5, but in the Balance Impacts tab, type 7.00 in Fixed Amount.

7. Set up the rate plan selector.

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

   2. Click + in the row column to create a row for each payment method, except Cash payments. Omitting the cash payment method from the rate plan selector excludes it from being rated and no fees will be applied.

   3. In the first column of each row, type the element ID for each payment method.

   4. For the credit card, debit card, direct debit, and wire transfer payment methods, select the $5 payment fee rate plan.

   5. For the invoice, check, and postal order payment methods, select the $7 payment fee rate plan.

      The rate plan selector for this example looks like Figure 7-1 in Pricing Center:

      Figure 7-1 Rate Plan Selector

      
      Description of ''Figure 7-1 Rate Plan Selector''
      
      

8. Click OK and Apply.

   Note:

   • To configure the rate plan according to additional payment fee attributes, click ...+ in the next column and choose the field on which to base the fees. Then enter the field values in each row.

   • A rate plan selector can only contain fields defined in the payment fee event. For example, you can apply a payment fee based on a customer segment, payment channel, or payment method, or a combination of these attributes.

To exempt accounts from receiving fees, see "Defining Exemptions from Payment Fees".

To define a threshold at which to suppress payment fees, see "Defining Thresholds for Payment Fees".

Defining Thresholds for Payment Fees

You can define a threshold amount at which payment fees are applied for failed payments. If the amount of the failed payment is less than the threshold, the payment fee is not applied. For example, you can set payment fees to be applied only for failed payments of $20 or more.

To create a payment fee threshold, define a rate plan selector in which you base the fee on the PIN_FLD_AMOUNT_ORIGINAL_PAYMENT attribute for the failed payment fee event. Then define balance impacts to define the threshold quantity.

This example charges a $5 fee if the failed payment is over $99.

1. Start Pricing Center.

   • To set up thresholds for all customer accounts. create a System product.

   • To set up thresholds only for certain accounts, create a Subscription product and purchase the product for those accounts.

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 Event, select Failed Payment Fee Event.

   2. In Measured By, select Amount.

   3. In Rate Plan Structure, select Single Rate Plan.

5. Set up the rate plan that suppresses the payment fee.

   1. Under Rate Plan, click Open Rate Plan and set up the Plan Details.

   2. Under Rate Structure, select Tier 1 and set up the Tier Details.

   3. Under Rate Structure, select Rate 1 and set up the Rate Data.

   4. Under Quantity Discount Brackets, in Based on, select Rate Dependent.

   5. Under Rate Structure, select No Minimum - No Maximum to open the Balance Impacts tab.

   6. Under Valid Quantities, clear Maximum and type 100.

   7. In Resource ID, select US Dollars [840].

   8. Under Rate Structure, select Rate 1 and click Add to add another balance impact.

   9. Select No Minimum - No Maximum to open the Balance Impacts tab.

   10. Under Valid Quantities, clear Minimum and type 100.

   11. Under Balance Impacts, type 5.00 in Fixed.

   12. Click OK.

Defining Exemptions from Payment Fees

To exempt accounts from receiving payment fees, you create a real-time pipeline discount and associated it with the failed payment fee event.

For more information on discounting, see Pricing Center Help and "About Discounts" in BRM Configuring Pipeline Rating and Discounting.

1. Start Pricing Center and create a subscription discount that applies to the account.

2. Create a Discount Model that defines a discount of 100%.

   1. Using the Pipeline Toolbox, choose Discount/ChargeShare Trigger from the Discount list, select the DM10%OFF discount trigger, and change it to DM100%OFF.

   2. Create a discount rule and set the Rule Type to Threshold and the Drum Type to Charge.

   3. Enter the threshold amount and charge information.

   4. Change the DM10%OFF discount master to DM100%OFF and the DM10%OFF discount model to DM100%OFF.

3. Set up the event map.

   1. Under Map an Event to a Discount Model, click Add.

   2. In the Event column, select Failed Payment Fee Event.

   3. In the list of discount models, choose DM100%OFF and click Select.

4. Create a deal and add the discount to the deal.

5. Purchase the deal for the accounts that are exempt from the failed payment fee.

When the fee is rated, the following operations occur in BRM.

1. The balance impact of the /event/billing/fee/failed_payment is determined by BRM, and the balance impact is saved as a charge packet.

2. The real-time discounting pipeline calculates the charge packet discount and translates it into a second balance impact for the fee. This balance impact amount is the negative equivalent of the original fee amount.

3. The fee is saved with a balance impact amount of $0.

   For example, an account that is exempt from the payment fee receives a $5 balance impact for the fee when it is rated. When the 100% discount is applied, a second balance impact of -$5 is saved with the fee. The two amounts cancel each other, and the fee is $0.

For more information on thresholds, see Pricing Center Help.

Removing a Payment Fee from an Account Balance

To remove a payment fee from an account balance, you use Customer Center to credit the balance of the account for the amount of the fee.

1. Open the account in Customer Center.

2. Go to the Post Paid tab and click the Balance Adjustment link.

3. Select the balance to adjust.

4. If this is a dual currency account, select the currency to adjust.

5. Type the amount of the adjustment and select Credit.

6. Select a reason and type any notes about the adjustment.

7. Select a transaction date and an accounting date for the adjustment.

8. Click OK.

9. Click Yes in response to the confirmation message if the information is correct.

   When the adjustment is recorded in the BRM database, the amount of the adjustment is added to the amount in the Adjustments/Payments not applied field. The adjusted amount reduces the amount in the Due now field.

10. If the account uses open item accounting, you must allocate the adjusted amount to one or more bills.

    Until you perform the allocation, the credit reduces the amount due on the account, but it does not reduce the balance of any bills. When allocated, the credit reduces the due amount of the bill or bills.

For more information, see Customer Center Help.

Customizing Payment Fees

You can configure BRM to handle failed payments and to charge payment fees according to custom business policies.

• To apply payment fees, use PCM_OP_PYMT_APPLY_FEE. See "How Payment Fees Are Applied".

• To customize payment fees, use the PCM_OP_PYMT_POL_APPLY_FEE policy opcode. See "Customizing Payment Fees".

This section describes the following customization tasks:

• Customizing Payment Fees

• Storing Additional Information with Payment Fees

For background information on payment fees, see the following documents:

• Configuring Payment Fees

• Creating Payment Fees

• Defining Reason Codes for Failed Payments

How Payment Fees Are Applied

Payment fees are applied by PCM_OP_PYMT_APPLY_FEE. This opcode creates payment fees for payments that fail, for example, due to insufficient account funds or an expired credit card. It calls PCM_OP_ACT_USAGE to create the payment fee event to be rated.

PCM_OP_PYMT_APPLY_FEE is called by PCM_OP_PYMT_COLLECT.

The behavior of PCM_OP_PYMT_APPLY_FEE is determined by the PIN_FLD_STATUS field passed in on the input flist. Payments are eligible to receive payment fees if they have a PIN_FLD_STATUS value >= PIN_PYMT_FAILED and < PIN_PYMT_STATUS_MAX. The numeric range for financially failed payments is 30-44. For more information, see "About Payment Status".

The normal flow of PCM_OP_PYMT_APPLY_FEE is as follows:

1. Checks the input flist for the status of the payment and the reason ID that describes why the payment failed.

2. Calls the PCM_OP_PYMT_POL_APPLY_FEE policy opcode to perform custom checks before the failed payment fee is applied. See "Customizing Payment Fees".

   When it returns the output flist, PCM_OP_PYMT_APPLY_FEE validates the information, and creates the failed payment fee events for all failed payments based on the information. The default value in the PIN_FLD_BOOLEAN field on the output flist is 0, which specifies that the fee will be created.

3. If a payment fails, records the /event/billing/payment/payment_type event.

   Note:

   If the payment is an unconfirmed payment, records the /event/billing/payment/failed event.

4. Creates the /event/billing/fee/failed_payment event.

PCM_OP_PYMT_APPLY_FEE provides feedback on its success or failure through the PIN_FLD_RESULTS array in the output flist. The value in the PIN_FLD_RESULTS field specifies whether the payment fee event was created. A value of 0 signifies that the payment fee event was created and the payment fee applied. A nonzero value signifies that the payment fee event was not created.

In the case of a write-off reversal, the output flist sends a results array of reversal events and tax events (if created) that were passed in by PCM_OP_AR_REVERSE_WRITEOFF.

Note:

Failed payments can only be applied to account numbers that already exist in the BRM database.

The PIN_FLD_EVENTS array of the output flist stores the POID of the failed payment fee event or write off event, if one is created. The PIN_FLD_EVENTS array is contained in the PIN_FLD_RESULTS array.

Flags are not used directly by PCM_OP_PYMT_APPLY_FEE. They are passed in from PCM_OP_PYMT_COLLECT for PCM_OP_PYMT_SELECT_ITEMS. For example, Payment Tool can set the PCM_BILLFLG_DEFER_ALLOCATION flag to indicate which payments should be left unallocated.

Customizing Payment Fees

You can define additional rules for payment fee processing by configuring the PCM_OP_PYMT_POL_APPLY_FEE policy opcode. This policy opcode is called by PCM_OP_PYMT_APPLY_FEE.

PCM_OP_PYMT_POL_APPLY_FEE enables you to customize payment fees by preprocessing, filtering, and extending the information available in failed payment fee events. For example:

• You can charge different fee amounts based on thresholds, or on the reason ID associated with a failed payment.

• You can use payment attributes such as the customer segment, payment method, payment channel, or a combination of these attributes to charge payment fees. You create the filters by passing the values in the PIN_FLD_EXTENDED_INFO substruct or the PIN_FLD_CHARGES array.

The default behavior of PCM_OP_PYMT_POL_APPLY_FEE is determined by the PIN_FLD_STATUS and PIN_FLD_REASON_ID fields passed in on the input flist. It enhances the input flist by adding fields to filter and extend the information available in the payment fee events.

Customization example: Charging a fee based on the customer segment

The following opcode customization is used to control which failed payment fee is assigned to an account based on the account's customer segment:

If (customer_segment = ”early bill payer”)
Then set PIN_FLD_BOOLEAN to False
END

The PIN_FLD_BOOLEAN value of False specifies that the fee event is not created. When payments are posted, BRM uses the customer segment ID to determine if a payment fee is charged.

You can also use the PIN_RESULT_PASS and PIN_RESULT_FAIL return values in PCM_OP_PYMT_POL_APPLY_FEE to configure whether payment fees are applied.

Storing Additional Information with Payment Fees

You can store additional information for payment fees by extending the /event/billing/fee/failed_payment storable class. Use the PIN_FLD_FAILED_PAYMENT_FEE field inside the PIN_FLD_EXTENDED_INFO substruct. This enables you to record any additional criteria you defined to create the payment fee.

You can then use the PIN_FLD_REASON_ID field in the input flist to configure fees based on this value of the PIN_FLD_FAILED_PAYMENT_FEE field. It contains the reason for failure that was sent by the payment processor for failed credit card and direct debit transactions.

You can then charge payment fees based on custom payment attributes such as currency type:

1. Extend the /event/billing/fee/failed_payment storable class with the new attributes by using Developer Center.

2. Customize the PCM_OP_PYMT_POL_APPLY_FEES policy opcode to pass the value in the PIN_FLD_CHARGES array or the PIN_FLD_FAILED_PAYMENT_FEE field in the PIN_FLD_EXTENDED_INFO substruct.

3. Use Pricing Center to create the rates for the new attribute values.

See "Configuring Payment Fees".