This chapter describes how to manage customer billing information, such as billing dates, credit limits, and payment methods.
For more information on Oracle Communications Billing and Revenue Management (BRM) billing, see "About Billing" in BRM Configuring and Running Billing.
In addition to the main account contact, you can use a separate name and address for the person who receives the invoice. For example, if a company has several customer accounts, but only one person handles the invoice, you can send all invoices to one person.
You can change the following invoice information:
The mailing address for the invoice. If the invoice recipient is the same as the account holder, this information should be the same as the customer contact information.
How to deliver the invoice (postal mail or email). If you choose email, you enter the email address.
If you want the account holder's information to reflect the new billing information, update the contact information for the account after you have updated the invoice information.
See "Customizing Customer Payment Information" for more information on changing a customer's invoice information.
When you change credit card information, BRM validates the credit card. If credit card tokenization is enabled, BRM requests Paymentech for tokens and stores the tokens instead of the actual credit card numbers in the BRM database. See "About BRM-Initiated Payment Processing" in BRM Configuring and Collecting Payments.
Important:
For security reasons, the Visa CVV2 numbers and American Express CID numbers are not stored in the BRM database; however, you can configure BRM to send them to the credit card processor when a credit card is added to an account or changed in an account if they are required for authorization. See "Requiring Additional Protection against Credit Card Fraud" in BRM Configuring and Collecting Payments.The billing information for accounts is typically listed as the primary account contact. If you want the account holder's information to reflect the new billing information, update the contact information for the account after you have updated the credit card information.
Use Customer Center to change credit card information. See the discussion on changing credit card information in the Customer Center Help.
The billing information for accounts is typically listed as the primary account contact. If you want the account holder's information to reflect the new billing information, update the contact information for the account after you have updated the debit card information.
Use Customer Center to change direct debit information. See the discussion on changing direct debit information in the Customer Center Help.
Each account's bill unit includes a payment method, such as credit card or invoice.
To make an account's bill unit a nonpaying bill unit, add the account to an account group hierarchy as a child account. You can change an account's bill unit to a nonpaying bill unit only if the account was billed for the previous cycle.
When changing to the credit card payment method, BRM validates the customer's credit card. However, BRM does not charge the customer for the current balance until the end of the current billing cycle.
Use Customer Center to change payment methods. See the discussion on reviewing and modifying payment method information in the Customer Center Help.
If you change a child account bill unit's payment method to nonpaying (subordinate) after creating the account, the billing information for the nonpaying bill unit changes to match the parent account. A nonpaying bill unit must use the same currency, billing date, billing frequency, and accounting type as its parent account. If the accounts use two currencies, the parent account and the nonpaying bill unit in the child account must use the same primary currency.
See the discussion on moving an account between hierarchical groups in the Customer Center Help.
You can change a closed child account bill unit's payment method to nonpaying (subordinate) if either of the following conditions is true:
The closed child account was billed for all the previous cycles.
The closed child account was not billed because you have disabled billing of closed accounts and the child account's total balance due for the bill unit is zero. See "Suspending Billing of Closed Accounts" in BRM Configuring and Running Billing for more information about disabling the billing of closed accounts.
See the discussion on moving an account between hierarchical groups in the Customer Center Help.
Each account includes one or more payment methods, such as credit card or invoice. The list of available payment methods displayed in Customer Center is stored in the /config/payment object. Creating a new payment method requires programming. See "Customizing Payment Methods".
Customer payment information is stored in /payinfo objects. Use the PCM_OP_CUST_SET_PAYINFO opcode to create or modify a /payinfo object.
PCM_OP_CUST_CREATE_PAYINFO is called by the PCM_OP_CUST_UPDATE_CUSTOMER opcode when a customer's payment information is modified. For more information, see "Modifying an Account".
PCM_OP_CUST_SET_PAYINFO is a wrapper opcode that calls the following opcodes:
PCM_OP_CUST_CREATE_PAYINFO, which creates the account /payinfo object.
PCM_OP_CUST_MODIFY_PAYINFO, which modifies a /payinfo object.
To customize how /payinfo objects are created, use the following opcodes:
PCM_OP_CUST_POL_PREP_PAYINFO. See "Customizing Payment Method Data Preparation" and "About the PREP and VALID Opcodes" in BRM Developer's Guide.
PCM_OP_CUST_POL_VALID_PAYINFO. See "Customizing Payment Method Validation" and "About the PREP and VALID Opcodes" in BRM Developer's Guide.
PCM_OP_CUST_FIND_PAYINFO. See "Finding Payment Info" in BRM Configuring and Collecting Payments.
PCM_OP_PYMT_POL_SPEC_VALIDATE. See "Customizing the Account Used for Credit Card Validation".
To delete a /payinfo object, use the PCM_OP_CUST_DELETE_PAYINFO opcode. This opcode is given the /payinfo object Portal object ID (POID) of the object to delete.
Note:
You cannot delete a /payinfo object that is currently associated with a /billinfo object; you must first delete the /billinfo object.If you have customized objects related to payment for an account, then, before you delete the /payinfo object for the account, you need to take steps to ensure that the deletion will not affect any customized information associated with that payment setup. To do so, use the PCM_OP_CUST_POL_PRE_DELETE_PAYINFO policy opcode.
The PCM_OP_CUST_POL_PRE_DELETE_PAYINFO policy opcode is called by the PCM_OP_CUST_DELETE_PAYINFO opcode before the latter opcode deletes the /payinfo object.
The PCM_OP_CUST_POL_PRE_DELETE_PAYINFO policy opcode requires the POID of the /payinfo object in the PIN_FLD_POID field of its input flist. It returns the POID of the /payinfo object in the PIN_FLD_POID field to the calling PCM_OP_CUST_DELETE_PAYINFO opcode.
For more information on the PCM_OP_CUST_POL_PRE_DELETE_PAYINFO policy opcode, see BRM Developer's Reference.
The PCM_OP_CUST_POL_PREP_PAYINFO policy opcode processes inherited fields and prepares a /payinfo object. This policy opcode checks the payment method and creates the correct object based on that information.
If the payment method is invoice, the /payinfo/invoice object is created.
If the payment method is cc (credit card), the /payinfo/cc object is created and the information is prepared for online registration.
If the payment method is dd (US and Canadian direct debit), the /payinfo/dd object is created and the information is prepared for online registration.
If the payment method is SEPA, the /payinfo/sepa object is created and the information is prepared for SEPA payments.
If the payment method is cc or dd, the PCM_OP_CUST_POL_PREP_PAYINFO policy opcode checks the /config/ach object to find the payment processor vendor to associate with the payment method. To use a vendor other than the default, you must customize this policy opcode.
The PCM_OP_CUST_POL_PREP_PAYINFO policy opcode selects the first payment processor vendor listed in the /config/ach object to process the BRM-initiated payment. If you configured multiple payment processor vendors, you can specify the vendor to use by passing the vendor's ID in the PIN_FLD_ACH field in the opcode input flist. The vendor's ID corresponds to the ID of the PIN_FLD_ACH_INFO array, in the /config/ach object, that contains the information for that vendor.
The PCM_OP_CUST_POL_VALID_PAYINFO policy opcode validates inherited fields for a /payinfo object, which may include a /payinfo/cc object for credit cards, or a /payinfo/dd object for direct debit, or a /payinfo/sepa object for SEPA Direct Debit or SEPA Credit Transfer transactions.
For credit cards, this policy opcode checks the credit card type, number, and expiration date during registration.
For SEPA Direct Debit and Credit Transfer, this policy opcode checks that the International Bank Account Number (IBAN) and the Business Identifier Code (BIC) formats comply with the standards in the SEPA Rulebook and also validates that the primary currency of the account is euro.
Note:
Visa and American Express require a CVV2 or CID number for credit card fraud prevention. For security reasons, these numbers are not stored in the BRM database. For more information on how BRM handles these numbers, see "CVV2/CID Fraud Prevention Functionality".If the information is valid, the standard checksum operation is performed.
This operation validates inherited fields for a /payinfo object according to the criteria contained in the /config/fld_validate object.
Mandatory fields for validation:
PIN_FLD_CITY
PIN_FLD_STATE
PIN_FLD_ZIP
PIN_FLD_COUNTRY
PIN_FLD_CARD_TYPE
Checks performed for credit card-specific billing information:
Is the debit number acceptable? (checksum)
Is the debit number an acceptable type?
Has the expiration date passed?
Checks performed for Paymentech direct debit transactions:
Is the bank number acceptable? (9 digits)
Is the debit number acceptable? (11 digits)
What is the account type? (checking, corporate checking, savings)
As a fraud prevention feature, Visa and American Express use additional three- and four-digit security codes attached to standard credit card numbers.
Visa uses a three-digit CVV2 number in the signature section on the back of the card.
American Express uses a four-digit CID number.
For security reasons, the PCM_OP_CUST_CREATE_PAYINFO and the PCM_OP_CUST_MODIFY_PAYINFO opcodes omit the PIN_FLD_SECURITY_ID field from the input flist of the PCM_OP_CREATE_OBJ opcode when the /payinfo object is created or changed. The result is that the CVV2/CID information is stored in the database with a NULL value. Likewise, the PCM_OP_PYMT_CHARGE opcode omits this value when a credit card is charged or validated; therefore, the /event/billing/charge/cc and /event/billing/validate/cc objects also store a NULL value for the PIN_FLD_SECURITY_ID value.
If the Connection Manager (CM) pin.conf file's cvv2_required flag is set to 1 (required), these opcodes send the PIN_FLD_SECURITY_ID value directly to the credit card processor when customers add or change credit cards in their accounts. If the CVV2 information is not provided in the input flist, the PIN_FLD_RESULT value is set to PIN_ERR_MISSING_ARG, with the description ”Missing argument”.
For more information on how to make these values required or optional, see "Requiring Additional Protection against Credit Card Fraud" in BRM Configuring and Collecting Payments.
By default, the PCM_OP_CUST_POL_VALID_PAYINFO policy opcode verifies that a credit card's CVV2 passed in the PIN_FLD_SECURITY_ID input flist field does not exceed three digits. You can modify the maximum allowed number of CVV2 digits by customizing the policy opcode to:
Validate that the number of digits passed in the PIN_FLD_SECURITY_ID input flist field of the PIN_FLD_CC_INFO array does not exceed a specified value.
If the validation succeeds, pass the PIN_FLD_SECURITY_ID field to the calling opcode.
If the validation fails, return the appropriate error in the PIN_FLD_RESULT output flist field.
To disable the credit card checksum:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf, where BRM_Home is the directory in which BRM is installed).
Change the flag in the cc_checksum entry from 1 (enable) to 0 (disable):
- fm_cust_pol cc_checksum 0
Save and close the file.
The new value becomes effective immediately and applies to the next account created. The CM does not need to be restarted.
The bank number (/bank_no) and debit number (/debit_num) fields can be customized to allow for bank and debit numbers that do not meet the US standard (5 digits) by using the Field Validation Editor in Configuration Center.
When validating a credit card at registration, BRM needs an account to validate the card with. By default, this is the root account. You cannot store this information with each account because the credit card validation is done before the account is created.
You can use the PCM_OP_PYMT_POL_SPEC_VALIDATE policy opcode to change the account used for credit card validation.
The default account is:
0.0.0.1 /account 1
You can change the 1 to some other account number as long as it has a bill type that is not affected by billing operations or events.
The PCM_OP_PYMT_POL_SPEC_VALIDATE policy opcode reads the following CM pin.conf file entries:
The cc_validate entry, which specifies whether to validate credit cards. See "Validating Credit Cards at Registration".
The cc_revalidate entry, which specifies the amount of time before revalidation is required. See "Revalidating Credit Cards".
In addition, the PCM_OP_PYMT_POL_SPEC_VALIDATE policy opcode reads the /config/ach object to find the merchant value.
The only types of action supported are prep customer and commit customer. If one of these is not passed in, PIN_ERR_BAD_VALUE is returned. If the action passed in is NULL, a blank flist is returned. If an error occurs, a null flist is returned.
If the PIN_FLD_PAY_TYPE value is NULL, only the POID from the pin.conf file is returned. If the PIN_FLD_PAY_TYPE value is not PIN_PAY_TYPE_CC or PIN_PAY_TYPE_DD, the result is set to PIN_BOOLEAN_FALSE because there is nothing to validate. If the value is PIN_PAY_TYPE_CC or PIN_PAY_TYPE_DD, the result is set to PIN_BOOLEAN_TRUE.
This section describes the information necessary to add custom payment methods to your BRM system.
The PIN_FLD_PAY_TYPE field in the /billinfo object defines the payment method for an account's bill. All defined payment methods are stored in the /config/payment object.
When you add a new payment method to your BRM system, you must update the PIN_FLD_PAY_TYPES array in the /config/payment object. The PIN_FLD_PAY_TYPES array index corresponds to an entry in the pin_pymt.h file, where payment methods are defined.
Note:
If you create accounts that have custom payment methods, you must modify the PCM_OP_CUST_POL_PREP_PAYINFO policy opcode to validate them. For example, add code for your custom payment method everywhere the opcode checks the various payment methods.Use the information in the following tables to edit the predefined payment methods and element IDs in the /config/payment object:
See pin_pymt.h in the BRM_Home/include directory for a complete list of supported payment methods.
Table 9-1 list the payment methods and element IDs.
Table 9-1 Payment Methods and Element IDs
| Payment Method | Element ID |
|---|---|
|
PIN_PAY_TYPE_UNDEFINED Used during account creation. |
0 |
|
PIN_PAY_TYPE_PREPAID Used to keep negative balances. |
10000 |
|
PIN_PAY_TYPE_INVOICE Used for monthly invoices. |
10001 |
|
PIN_PAY_TYPE_DEBIT Used for checking account debit. |
10002 |
|
PIN_PAY_TYPE_CC Used for credit cards. |
10003 |
|
PIN_PAY_TYPE_DD Used for US/Canadian direct debits. |
10005 |
|
PIN_PAY_TYPE_SMARTC Used for smartcards. |
10006 |
|
PIN_PAY_TYPE_SUBORD Used to roll up balances to the parent account. |
10007 |
|
PIN_PAY_TYPE_BETA For use by beta testers only. Billing utilities ignore this. |
10008 |
|
PIN_PAY_TYPE_INTERNAL Used for internal employees. Used the same way as guest accounts. |
10009 |
|
PIN_PAY_TYPE_GUEST Used for guest accounts. It is not charged, but credit limits apply. |
10010 |
|
PIN_PAY_TYPE_CASH Used for cash. |
10011 |
|
PIN_PAY_TYPE_CHECK Used for personal bank checks. |
10012 |
|
PIN_PAY_TYPE_WTRANSFER Used for wire transfers. |
10013 |
|
PIN_PAY_TYPE_PAYORDER Used for inter-bank payment orders. |
10014 |
|
PIN_PAY_TYPE_POSTALORDER Used for postal payment orders. |
10015 |
|
PIN_PAY_TYPE_VOUCHER Used for payment vouchers. |
10016 |
|
PIN_PAY_TYPE_FAILED Used for unconfirmed payments that failed. |
10017 |
|
PIN_PAY_TYPE_SEPA Used for SEPA payments. |
10018 |
Note:
To avoid conflicts with payment IDs reserved by BRM, custom payment methods should be defined with an element ID greater than 10099.Important:
If a customer makes a payment with a payment method that has not been saved with an account, you must add the new payment method, when first used, to the input flist of the following opcodes. For example, this is required if an invoice customer makes a one-time payment by using a new credit card. (This is not required if the payment method was defined when the account was created. If the new payment method is SEPA, you must add the payment method to the account before it can be used.)Table 9-2 lists the opcodes that use the PIN_FLD_PAY_TYPE field.
Table 9-2 Opcodes Using PIN_FLD_PAY_TYPE
| Opcode Name |
|---|
|
PCM_OP_PYMT_CHARGE |
|
PCM_OP_PYMT_CHARGE_CC |
|
PCM_OP_PYMT_COLLECT |
|
PCM_OP_BILL_GROUP_DELETE_MEMBER |
|
PCM_OP_BILL_MAKE_BILL |
|
PCM_OP_BILL_MAKE_BILL_NEW |
|
PCM_OP_BILL_MAKE_BILL_ON_DEMAND |
|
PCM_OP_BILL_MAKE_BILL_RCV_PAYMENT |
|
PCM_OP_PYMT_RECOVER |
|
PCM_OP_BILL_REVERSE |
|
PCM_OP_BILL_REVERSE_PAYMENT |
|
PCM_OP_PYMT_VALIDATE |
Table 9-3 lists the fields in PIN_FLD_PAY_TYPES array.
Table 9-3 Fields in PIN_FLD_PAY_TYPE
| Field Name | Description |
|---|---|
|
PIN_FLD_PAYINFO_TYPE |
A string that indicates the type of /payinfo object to create. |
|
PIN_FLD_PAYMENT_EVENT_TYPE |
A string that indicates the type of /event object to create when payment is received. |
|
PIN_FLD_REFUND_EVENT_TYPE |
A string that indicates the type of /event object to create when a refund is paid. |
|
PIN_FLD_OPCODES |
An array that contains the following information about an opcode to be associated with this pay type:
|
Table 9-4 lists the PIN_FLD_OPCODES array indexes-to-opcode mapping.
To add a custom payment method to your BRM system, edit the /config/payment object.
Using a text editor, edit the file to add an element to the PIN_FLD_PAY_TYPES array for each new payment method.
For a predefined payment method, use the appropriate value as the index for that element of the PIN_FLD_PAY_TYPES array. See "Payment Methods and Element IDs".
For a custom payment method, define a payment method in a header file and use that value as the index of the new element in the PIN_FLD_PAY_TYPES array.
Important:
To avoid conflicts with payment IDs used by BRM, define custom payment methods with an element ID of 10100 or higher.Save and close the file.
Use the testnap utility to load the /config/payment object into the database. See "Testing Your Applications and Custom Modules" in BRM Developer's Guide.
You can configure your own /config/payment object and load it into the database using the testnap utility. See "Creating Objects" in BRM Developer's Guide.
After you create the /config/payment object, update the config_payment entry in the CM pin.conf file with the POID of the new object:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
Edit the following entry:
- fm_pymt config_payment database_number /config/payment 200
where database_number is the database number of the BRM database. By default, this number is 0.0.0.1. Replace 200, the default POID of the /config/payment object, with the POID of the new object.
Save and close the file.
Stop and restart the CM.
To view payment information in Customer Center for custom payment methods, run the pin_collect utility for that payment method. The pin_bill_day utility calls pin_collect for credit card payment methods and pin_inv_accts for invoice payment methods. You can make a call to pin_collect in pin_bill_day for each new custom payment method.
For more information, see "Running Daily Billing" (in BRM Configuring and Running Billing) and "About Collecting BRM-Initiated Payments" (in BRM Configuring and Collecting Payments).
You can set a bill unit's payment method to Undefined to enable users to access services without being charged. When you set the payment method for a bill unit to Undefined, BRM generates rating events and applies credit limits in the same way it does for a normal payment method; however, a payment is not requested from the account.
You can set the payment method to Undefined by either:
Using Customer Center.
Calling the PCM_OP_CUST_SET_BILLINFO opcode in an application and setting the value of PIN_FLD_PAY_TYPE to PIN_BILL_TYPE_UNDEFINED (0).
Important:
By default, credit limits are set to 0. Because an account with a payment method of Undefined never pays a bill, you need to set the credit limit to Unlimited.Accounts that pay by credit card should always use balance forward accounting. Accounts that use other payment methods can use either balance forward accounting or open item accounting.
For more information, see "About Accounting Types" in BRM Configuring and Running Billing.
A change to a billing day of month (DOM) takes effect in the next billing cycle. This means that there will be a partial billing cycle to handle the difference in days between the end of the current billing cycle and the start of the new billing cycle. For more information, see "Specifying How to Handle Partial Accounting Cycles" in BRM Configuring and Running Billing.
The default start date for an accounting cycle is the account's creation date. To change that date, see "Setting the Default Accounting Day of Month (DOM)" in BRM Configuring and Running Billing.
Use Customer Center to change the billing day of month. See the Customer Center Help.
If you use bill cycle management, see "Changing a Bill Unit's Billing DOM" for more information on changing a customer's billing day of month. For an overview of bill cycle management, see "About Managing Billing Cycles".
Use Customer Center to change a customer's billing cycle length. See "About Accounting and Billing Cycles" in BRM Configuring and Running Billing and the discussion on reviewing or changing the billing frequency or billing date in the Customer Center Help.
Note:
Because billing cycles are whole multiples of accounting cycles, the only cycle fee proration that might occur is for multi-month cycle rates.
A child account with a subordinate bill unit must use the same currency, billing frequency, billing day of the month, and accounting type as its parent account.
Use the bill run management feature to change a customer's bill due date. See "About Managing Bill Due Dates" in BRM Configuring and Running Billing.
A credit limit is the maximum amount of a resource, such as currency or hours, that can accumulate in an account balance group before the customer is prevented from using the service. By default, a customer cannot be authorized for service usage if a credit limit has been reached.
Note:
For nonpaying bill units, BRM uses the credit limit of the parent (paying) accounts receivable (A/R) bill unit to determine whether the nonpaying bill unit's credit limit is reached.You define credit limits in plans. For example, a plan might include a credit limit of $200. You change an individual customer's credit limit by using Customer Center.
You can also define credit thresholds to alert customers when the credit limit is about to be reached. You use event notification to alert customers automatically. See "About Applying Credit Limits to Resources" in BRM Setting Up Pricing and Rating.
You can set credit limits for currency resources and noncurrency resources.
Note:
If the account uses a secondary currency, you need to set the credit limit in the primary currency. See "Managing Currencies in Customer Accounts".Use Pricing Center to set credit limits for plans. See the Pricing Center Help.
Use Customer Center to set or change credit limits. See the Customer Center Help.
There might be occasions when customers purchase plans with credit limits that conflict with the credit limit set on their account or another service. There are two ways to handle credit limit conflicts:
When you create your price plans, if two services have different credit limits, create new balance groups for the services. This allows credit limits for each service to be set and tracked independently. See "Tracking Resources by Service" in BRM Setting Up Pricing and Rating.
Specify which credit limit takes precedence when a new credit limit conflicts with an existing credit limit. You do this by setting the credit_limit_conflict entry in the CM configuration file.
To specify credit limit precedence:
Open the CM configuration file (BRM_Home/sys/cm/pin.conf).
Add the credit_limit_conflict entry:
-fm_bill credit_limit_conflict value
where value is one of the following:
replace, to use the new credit limit.
ignore, to ignore the new credit limit and keep the existing credit limit.
add, to add the new credit limit to the existing credit limit and create a new limit.
minimum, to use the credit limit that specifies the smaller amount.
maximum, to use the credit limit that specifies the greater amount.
If this entry is not present, the new credit limit is used by default.
Stop and restart the CM.
BRM automatically checks whether an account balance has exceeded a credit limit when processing authorization requests or rating events. When an account balance exceeds a credit limit, BRM:
Denies all authorization requests. This prevents an account from logging in or using services until the account balance falls below the credit limit.
Stops rating events associated with the account. BRM rates events up to the credit limit amount and then returns any remaining usage as unrated.
To prevent revenue leakage, you can configure BRM to rate all events as defined in the rate plan, regardless of whether the account balance exceeded the limit.
You configure whether BRM ignores credit limit settings during the rating process in three different ways as shown in Table 9-5.
Table 9-5 Ways to Override Credit Limit Settings
| Override | Event Type | Description |
|---|---|---|
|
Product-level override |
Actual event |
Specifies to ignore credit limit settings when rating the specified product. When a resource has exceeded a credit limit, BRM uses the credit limit override rate to rate the specified product. This product-level setting takes precedence over the system-wide default setting. See the discussion on defining rates in the Pricing Center Help. Note: This setting does not affect prepaid AAA events, which are always checked against the credit limit. |
|
System-wide default |
Actual event |
Specifies to ignore the credit limit setting during the rating process. See "Configuring the System-Wide Override Credit Limit". Note: This setting does not affect prepaid AAA events, which are always checked against the credit limit. |
|
Calc-only override |
Calc-only event |
Specifies to ignore credit limit settings during calc-only rating. You use this setting for calc-only events that do not require credit limit checks, such as for best pricing rating or prepaid top-ups. You override credit limit checks during calc-only rating by passing the PIN_RATE_FLG_OVERRIDE_CREDIT_LIMIT flag in the PIN_FLD_FLAGS input flist field of an opcode. |
Note:
Even when BRM is configured to enforce all credit limit settings, BRM may still ignore credit limits during real-time pipeline discount rating and charge sharing.By default, BRM stops rating any events for accounts that have exceeded their credit limit. To prevent revenue leakage, you can configure BRM to ignore credit limits during the rating process and rate all events, regardless of whether a credit limit was breached.
You specify whether BRM enforces or ignores credit limit settings during the rating process by using the OverrideCreditLimit entry in the /config/business_params object.
When this feature is enabled, the rating engine applies the full cycle-forward fee and full usage fee.
When this feature is disabled, the rating engine applies part of the cycle-forward fee or usage fee until the credit limit is reached.
Note:
Tax amounts are applied even if the credit limit has been exceeded and the OverrideCreditLimit entry is disabled.To set credit limit enforcement:
Go to the BRM_Home/sys/data/config directory and run the following command:
pin_bus_params -r BusParamsRating bus_params_rating.xml
This command creates an editable XML file named bus_params_rating.xml.out in your working directory. If you do not want this file in your working directory, specify the path as part of the file name.
Search the XML file for the following line:
<BusParamsRating>
<OverrideCreditLimit>disabled</OverrideCreditLimit>
</BusParamsRating>
Set the OverrideCreditLimit entry to the appropriate value:
enabled specifies to ignore all account credit limit settings during the rating process. BRM continues to enforce credit limits during the authorization process.
disabled specifies to enforce credit limit settings. This is the default setting.
Save and close the file.
Go to the BRM_Home/sys/data/config directory and run the following command:
pin_bus_params bus_params_rating.xml
This command loads your changes into the rating instance of the /config/business_params object.
Caution:
BRM uses the XML in this file to overwrite the existing rating instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM rating configuration.Read the object with the testnap utility or Object Browser to verify that all fields are correct.
Stop and restart the CM.
(Multischema systems only) Run the pin_multidb script:
pin_multidb -R CONFIG
For more information, see "pin_multidb" in BRM System Administrator's Guide.
A credit threshold is a resource balance value, such as 90 minutes or $150, that triggers an alert to the customer. This allows customers to know when their balances are approaching a credit limit and to adjust their spending habits accordingly.
BRM can perform credit threshold checks during both real-time rating and batch rating:
Real-time rating: Credit threshold checks are performed for both currency and non-currency resources. To configure real-time rating to perform credit threshold checks, see "Configuring Event Notification for Threshold Checking".
Batch rating: Credit threshold checks are performed for only non-currency resources, such as minutes. To configure batch rating to perform credit threshold checks, see "Configuring Event Notification for Threshold Checking" and "Setting Up the Batch Rating Process to Perform Threshold Checking".
Note:
Performing credit threshold checking during batch rating decreases pipeline processing performance. See "Enabling Threshold Checking in Pipeline Manager".Credit thresholds can be specified either as a percentage of the credit floor and credit limit range or as a fixed value.
For example, you can set a credit threshold to 90 minutes in two different ways:
By setting the credit floor to 0, the credit threshold to 90%, and the credit limit to 100 minutes.
By setting the credit threshold to 90 minutes.
In the above example, if credit floor is set to 10 and the credit threshold is 90%,
The threshold will be 100, for a credit limit of 110.
The threshold will be 91, for a credit limit of 100.
You set or modify credit threshold values in your plans by using Pricing Center. After a customer purchases a plan, you can change the customer's individual credit threshold values by using Customer Center.
Note:
Customer Center can modify only percentage threshold values. To modify fixed threshold values, you must customize your client application to call the PCM_OP_BILL_SET_LIMIT_AND_CR opcode. See "Customizing Client Applications to Modify Fixed Thresholds".BRM uses event notification to alert customers when their balances breach a credit threshold value. When a threshold is breached, BRM generates a notification event, which triggers a call to a specified opcode. The opcode can then send an alert to the client application, email the customer, or perform other custom actions. For more information, see "Using Event Notification" in BRM Developer's Guide.
To indicate that a resource balance breached a customer's credit threshold, BRM generates one of the following notification events:
/event/notification/threshold when the balance crosses above the credit threshold value due to a new balance impact.
/event/notification/threshold_below when the balance falls below the credit threshold value due to a customer payment or an adjustment.
These notification events trigger a call to the opcode specified in the /config/notify object. By default, the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode is called. This policy opcode processes the event data and passes information to Customer Center or your custom client application. You can customize the policy opcode to perform other actions, such as sending an email to the customer.
To alert customers when credit thresholds are breached, you must configure the event notification feature, the policy opcode, and your custom client application to process these events and alert customers. For more information, see "Configuring Event Notification for Threshold Checking".
BRM performs credit threshold checking at the following times:
When balance impacts are applied during real-time rating. For more information, see "About Credit Limit and Threshold Checking during Real-Time Rating".
When balance impacts are applied during batch rating. For more information, see "About Credit Limit and Threshold Checking during Batch Rating".
Note:
The utility that loads balance impacts into the BRM database is different from the utility that loads threshold breach notifications into BRM. Therefore, the customer's balance may not immediately reflect the balance on the threshold breach notification.When a credit profile is modified and balance monitoring is enabled. After a customer's credit threshold values are updated in the credit profile, BRM determines whether the customer's balance has breached any of the new threshold values.
During the real-time rating process, BRM checks for threshold breaches after calculating the charges generated by an event and applying the balances but before the customer's balances are updated in the database. BRM compares the customer's new balance against the customer's credit threshold values. If a balance crossed a credit threshold value, BRM generates a notification event.
If balance monitoring is enabled, BRM also checks for credit threshold breaches when a credit profile is modified. The PCM_OP_BILL_SET_LIMIT_AND_CR opcode compares the customer's current balance to the updated credit floor, credit limit, and credit threshold values that are stored in the customer's credit profile (/config/credit_profile object). If the balance has breached a credit threshold value, BRM generates a notification event.
To enable custom client applications to perform credit threshold checks during the real-time rating process, configure your client application to pass information in the input flist of the PCM_OP_BILL_SET_LIMIT_AND_CR opcode. For more information, see "How BRM Handles Consumption Rules and Credit Limits".
During batch rating, Pipeline Manager determines whether a customer's noncurrency balance has breached a credit threshold. Pipeline Manager modules compare a customer's balance against non-currency credit threshold values and then compile a list of events that crossed thresholds. A utility loads the list from Pipeline Manager into BRM.
Important:
Pipeline rating calculates balance impacts and credit threshold breaches immediately. However, the utility that loads the balance impacts into the BRM database is different from the utility that loads credit threshold breaches into BRM. This means that a notification for a credit threshold breach might be sent before the customer's balance is updated in the BRM database. Therefore, the customer balance shown on the threshold breach notification might temporarily differ from the balance in the customer's account.The following pipeline modules are responsible for checking credit thresholds during the batch rating process:
DAT_PortalConfig retrieves credit profile information from the BRM database and stores it in its internal memory.
DAT_BalanceBatch retrieves the customer's current credit profile from the DAT_PortalConfig module, compares the customer's updated balance to the credit profile, and notifies FCT_ApplyBalance if a credit threshold or credit limit has been breached.
FCT_ApplyBalance updates the customer's current balance in the DAT_BalanceBatch internal memory and, if a credit threshold has been breached, writes the event detail record (EDR) into an internal list.
To help you identify the exact event that caused the threshold breach, FCT_ApplyBalance adds the following event attributes to each threshold breach notification:
Event type (DETAIL.EVENTTYPE)
Call originator (DETAIL.A_NUMBER)
Call destination (DETAIL.B_NUMBER)
At the end of the transaction, FCT_ApplyBalance writes all of the EDRs from the internal list to an XML output file. See "About the Format of the XML Output File Name".
After the XML output file is generated, Batch Controller uses the load_notification_event utility to load the notification events into BRM. See "About Loading Notifications from Pipeline Manager to BRM".
Pipeline Manager generates output XML files using the following file name format:
OutputPrefix_PipelineName_StreamName_TransactionID_SequenceNumber
where:
OutputPrefix is the prefix name specified in the OutputPrefix registry entry.
PipelineName is the name of the individual pipeline, such as ALL_RATE.
StreamName is based on the unitsPerTransaction parameter maintained at the input level of the pipeline. A value of 1 means that one input file generates one output file. A value greater than 1 means that multiple input files are merged into one output file. StreamName is replaced with the name of the last file merged into the output file. For example, if unitsPerTransaction was 3 and the files merged into the output file were file01, file02, and file03, StreamName would be replaced with file03.
TransactionID is the system-generated transaction ID number.
SequenceNumber signifies the order in which FCT_ApplyBalance created the XML output file within a transaction. For example, the first XML output file has a sequence number of 1, the second output file has a sequence number of 2, and so on.
For example:
balancenotification_ALL_RATE_file01_776_1
Notifications from Pipeline Manager are loaded into the BRM database by the load_notification_event utility. This utility is launched automatically by Batch Controller whenever Pipeline Manager writes an output XML file to a specified directory.
When Pipeline Manager writes an output XML file to the specified directory, notifications are loaded as follows:
Batch Controller launches the SampleLoadHandler batch handler.
SampleLoadHandler moves the output XML file to a processing directory and runs the load_notification_event utility.
load_notification_event converts the notification events in the output XML file into flist format and loads them into BRM.
The BRM event notification system sends an alert to the customer. See "About Alerting Customers When Credit Thresholds Are Breached".
SampleLoadHandler determines whether the utility successfully loaded the notification events into BRM:
If the utility was successful, SampleLoadHandler moves the output XML file from the processing directory to the archive directory.
If the utility failed, SampleLoadHandler moves the output XML file from the processing directory to the reject directory.
You must configure Batch Controller, the batch handler, and the load_notification_event utility to process the output XML files. See "Configuring Batch Controller to Run load_notification_event".
To modify any fixed threshold values in a customer's credit profile, you must customize your client application to call the PCM_OP_BILL_SET_LIMIT_AND_CR opcode.
You pass the fixed threshold values in the input flist's PIN_FLD_THRESHOLDS array. Each fixed value has a separate PIN_FLD_THRESHOLD flist entry in the array.
When the opcode receives fixed threshold values in its input flist, PCM_OP_BILL_SET_LIMIT_AND_CR updates the amount, refreshes the cache of credit profiles, and generates a ModifyBalanceGroup business event for Pipeline Manager so DAT_BalanceBatch updates its cache as well.
When a balance breaches a credit threshold value, BRM generates either an /event/notification/threshold or an /event/notification/threshold_below notification event. By default, when these events occur, the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode is called. You can either:
Customize the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode to process threshold breaches. You can add custom code to this policy opcode so that it alerts the CRM client application or sends an email to the customer. For more information, see "Adding and Modifying Policy Facilities Modules" in BRM Developer's Guide.
Configure event notification to call a different opcode by editing the BRM_Home/sys/data/config/pin_notify file and running the load_pin_notify utility. See "load_pin_notify". For more information, see "Implementing Event Notification" in BRM Developer's Guide.
To set up your system to perform threshold checking during the batch rating process:
Enable threshold checking. See "Enabling Threshold Checking in Pipeline Manager".
Configure Batch Controller to run the load_notification_event utility. See "Configuring Batch Controller to Run load_notification_event".
Configure Pipeline Manager to check thresholds. See "Configuring Pipeline Manager to Perform Threshold Checking".
By default, threshold checking is disabled for batch rating because it decreases pipeline rating performance.
You can enable threshold checking in batch rating by modifying a field in the multi_bal instance of the /config/business_params object.
To enable credit threshold checking during batch rating:
Go to the BRM_Home/sys/data/config directory and run the following command:
pin_bus_params -r BusParamsMultiBal bus_params_multi_bal.xml
This command creates an editable XML file named bus_params_multi_bal.xml.out in your working directory. If you do not want this file in your working directory, specify the path as part of the file name.
Search the XML file for the following line:
<CreditThresholdChecking>disabled</CreditThresholdChecking>
Set the CreditThresholdChecking entry to the appropriate value:
enabledOffline specifies to check credit thresholds during the batch rating process.
disabled specifies to skip credit threshold checking during the batch rating process and thus increase pipeline processing performance. This is the default setting.
Go to the BRM_Home/sys/data/config directory and run the following command:
pin_bus_params bus_params_multi_bal.xml
This command loads your changes into the multi_bal instance of the /config/business_params object.
Caution:
BRM uses the XML in this file to overwrite the existing multi_bal instance of the /config/business_params object. If you delete or modify any other parameters in the file, these changes affect the associated aspects of the BRM multi_bal configuration.Read the object with the testnap utility or Object Browser to verify that all fields are correct.
Stop and restart the CM.
(Multischema systems only) Run the pin_multidb script:
pin_multidb -R CONFIG
For more information, see "pin_multidb" in BRM System Administrator's Guide.
Batch Controller is a cronjob application that monitors a processing directory and starts batch handlers. When configured for threshold checking, Batch Controller waits for output XML files to appear in the processing directory and then launches the SampleLoadHandler handler. The batch handler moves the output XML files to a separate directory and then calls the load_notification_event utility to load the notifications into the BRM database. For more information on Batch Controller, see "Controlling Batch Operations" in BRM System Administrator's Guide.
You configure Batch Controller by using the following configuration files:
The batch_controller.properties file connects the Batch Controller to the CM, specifies run-time parameters, identifies the batch handlers to run, and specifies when and how to run the batch handlers.
The load_notification_event pin.conf file connects the load_notification_event utility to the CM.
The SampleLoadHandler_config.values file specifies where the batch handler retrieves and deposits the XML files and which utility to run.
To configure Batch Controller for threshold checking:
Open the BRM_Home/apps/batch_controller/batch_controller.properties file in a text editor.
Connect Batch Controller to the CM, if you have not already done so. See "General Batch Controller Parameters" in BRM System Administrator's Guide.
Make sure the entries for the load_notification_event batch handler (BRM_Home/apps/load_notification_event/SampleLoadUtilityHandler.pl) are correct. For example:
SampleHandler.name = SampleHandler SampleHandler.max.at.lowload.time = 1 SampleHandler.start.string = $PIN_HOME/apps/load_notification_event/SampleLoadUtilityHandler.pl
For more information, see "Handler Identification" in BRM System Administrator's Guide.
Specify the handler's polling directory and the file pattern to look for. For example:
event1.name = eventlabel1 event1.handlers = SampleHandler event1.at = 115700 event1.file.location = $HOME/opt/ifw/data/out/notifybalancebreach/ event1.file.pattern = *.xml
For more information, see "Occurrence-Driven Execution" in BRM System Administrator's Guide.
Save and close the file.
Connect the load_notification_event utility to the BRM database by editing the BRM_Home/apps/load_notification_event/pin.conf file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.
Open the BRM_Home/apps/load_notification_event/SampleLoadHandler_config.values file in a text editor.
Specify the directory from which to retrieve the XML files in the $STAGING entry. For example:
$STAGING = "$HOME/opt/ifw/data/out/notifybalancebreach/"
Specify the directory in which the handler archives the output XML files that loaded successfully into BRM in the $ARCHIVE entry. For example:
$ARCHIVE = "$HANDLER_DIR/archive"
Specify the directory in which the handler stores the output XML files that failed to load into BRM in the $REJECT entry. For example:
$REJECT = "$HANDLER_DIR/reject"
Save and close the file.
Start Batch Controller.
To configure threshold checking, perform the following:
Configure the DAT_BalanceBatch module. See "DAT_BalanceBatch" in BRM System Administrator's Guide.
Configure the DAT_PortalConfig module. See "DAT_PortalConfig" in BRM System Administrator's Guide.
Configure the FCT_ApplyBalance module. See "FCT_ApplyBalance" in BRM System Administrator's Guide.
When you configure the FCT_ApplyBalance module, you specify the following:
The maximum number of notifications in the output file. See "Configuring the Maximum Number of Notifications".
The output file prefix and directory location. See "Configuring the Output XML File".
Configuring the Maximum Number of Notifications
You specify the maximum number of notification events that FCT_ApplyBalance writes into the XML output file by using the NumberOfNotificationLimit registry entry. When the file breaches the maximum number, FCT_ApplyBalance closes the file and begins writing notification events into a new XML output file.
Note:
You can identify the order in which XML output files were created by the sequence number used in the file name. See "About the Format of the XML Output File Name".Configuring the Output XML File
After FCT_ApplyBalance identifies that an EDR caused a balance to breach a credit threshold, it writes the EDR to an output XML file. You can specify the prefix for the output file name by using the OutputPrefix registry entry and the directory in which to save the file by using the OutputDirectory registry entry.
Resource consumption rules specify the order in which resource sub-balances are consumed. For example, when a customer is granted free minutes with different validity periods, you can specify which minutes to use first, based on the validity start time and end time.
A credit limit is the maximum amount of a resource, such as currency or hours, that can accumulate in an account balance group before the customer is prevented from using the service. By default, a customer cannot be authorized for service usage if a credit limit has been reached.
You use the following opcodes to set credit limits and consumption rules in an account:
To set both the credit limit and the resource consumption rules, use the PCM_OP_BILL_SET_LIMIT_AND_CR opcode. See "How BRM Handles Consumption Rules and Credit Limits".
To customize setting the credit limit, use the PCM_OP_CUST_POL_PREP_LIMIT policy opcode and the PCM_OP_CUST_POL_VALID_LIMIT policy opcode. See "About the PREP and VALID Opcodes" in BRM Developer's Guide.
For more information on how BRM uses consumption rules, see "Specifying the Order in Which Resource Sub-Balances Are Consumed" in BRM Setting Up Pricing and Rating.
Use PCM_OP_BILL_SET_LIMIT_AND_CR to set a credit limit and resource consumption rule in an account.
The opcode sets the consumption rule and credit limit in a balance group for both currency and non-currency resources. This opcode must be called separately for each resource to be set. PCM_OP_BILL_SET_LIMIT_AND_CR creates a new /event/billing/limit event each time a credit limit is changed and a new /event/billing/consumption_rule event each time a consumption rule is changed.
By default, PCM_OP_BILL_SET_LIMIT_AND_CR sets or changes the credit limit and consumption rule in the account-level /balance_group object. To set a credit limit and consumption rule for any of the other billing entities associated with the object, specify them with the optional PIN_FLD_BAL_GRP_OBJ input flist field.
The credit limit is passed in the PIN_FLD_LIMIT array of the PCM_OP_BILL_SET_LIMIT_AND_CR input flist, which contains the resource ID of the sub-balance to change or create. The credit limit is set in the PIN_FLD_BALANCES array of the /balance_group object of the various billing entities. The POID of this object is passed in the PIN_FLD_BAL_GRP_OBJ field of the input flist.
The consumption rule is passed in the PIN_FLD_RULES array of the PCM_OP_BILL_SET_LIMIT_AND_CR input flist, which contains the resource ID of the sub-balance to change or create. The consumption rule is set in the PIN_FLD_CONSUMPTION_RULE field of the /balance_group object of the various billing entities.
A non-currency resource without an explicitly set credit limit has a default credit limit of zero. If PCM_OP_BILL_SET_LIMIT_AND_CR is called for a nonexistent resource, the resource is created. In the specified balance group, the resource is created, the credit limit is set, and the current balance is set to zero.
PCM_OP_BILL_SET_LIMIT_AND_CR does not affect the current balances of the account.
To return all the fields in the event object, set the PCM_OPFLG_READ_RESULT flag. If this flag is not set, PCM_OP_BILL_SET_LIMIT_AND_CR returns only the POID.
To run PCM_OP_BILL_SET_LIMIT_AND_CR without changing data in the database, use the PCM_OPFLG_CALC_ONLY flag.
If the flag is set, no fields in the database are changed and the event object is not created. The fields that would have been used to create the event object are returned to the caller.
If the flag is not set, either the /event/billing/limit object or the /event/billing/consumption_rule object is created to record details of the operation.
A customer might be exempt from paying taxes levied by certain jurisdictions. For example, the customer might not be required to pay city or state taxes.
You record tax exemption information in the customer's account so BRM can send this information to the tax calculation software your company uses.
Use Customer Center to change tax exemption information. See the Customer Center Help.
You can customize the Customer Center properties file to change the exemption types offered. For example, you can override the exemptionType.format property to include a different tax exemption type. See "Adding a Tax Exemption Type" and "Configurator Properties Files" in BRM Developer's Guide.
You can record the customer's buyer value added tax (VAT) registration number in the customer's account. BRM sends this information to the tax calculation software your company uses.
Use Customer Center to change VAT registration numbers.
Customer billing information includes sensitive data such as banking details. BRM supports configurable masking of string type customer data fields in CM responses to clients and external systems and within logs. Use masking to ensure that sensitive customer billing information is protected.
See "About Securing Sensitive Customer Data with Masking" for information on configuring sensitive data masking.