1 About Accounts Receivable

This chapter describes how Oracle Communications Billing and Revenue Management (BRM) stores, displays, and manipulates accounts receivable (A/R) data.

Caution:

Do not use or modify this product except as explicitly instructed in this documentation. Assumptions should not be made about functionality that is not documented or use of functionality in a manner that is not documented. Use or modification of this software product in any manner or for any purpose other than as expressly set forth in this documentation may result in voidance or forfeiture of your warranties and support services rights. See your software license agreement for more details. If you have any questions regarding an intended use or modification of this product, contact Oracle.

For information about the procedures for managing payments, see "About BRM-Initiated Payment Processing" and "Managing Externally Initiated Payments" in BRM Configuring and Collecting Payments.

For information about configuring adjustments, disputes, and settlements, see "Configuring Adjustments, Disputes, and Settlements".

For basic information about BRM and billing, see the discussion on BRM in BRM Concepts and "About Billing" in BRM Configuring and Running Billing.

How BRM Stores Accounts Receivable Information

When a customer generates a billable event, the BRM system rates the event to determine how much to charge the customer for it.

The BRM system stores the cost of the event, along with the cost of similar events generated by the customer, in an item in the BRM database. The cost of the events stored in the items affects the current balances of the customer's account.

During billing, the BRM system collects the items for an account in a bill, which is also stored in the database.

The BRM billing utilities request payment for the bill from the customer.

Until payment is received, the money a customer owes, along with the amounts due from other customers, represents your company's accounts receivable.

A/R actions impact the amount a customer owes your company. The effects of these A/R actions are stored in items. For more information, see "About Items".

About A/R Database Objects

To bill an account, BRM must track and store the following information for each billing cycle:

• The balance impact for a billable event. This information is stored in an /item object. Billable events are grouped by type. See "About Items".

• Total balance due from all billable events in a billing cycle. The total balance is stored in a /balance_group object. You can create multiple balance groups to track balance totals by service type. For example, one balance group could store the total balance of all GSM charges and another balance group could store the total balance of all GPRS charges. See "About Balance Groups".

• When and how to generate a bill. All administrative information for creating a bill, such as the payment method, billing cycle length, payment collection date, and account hierarchy information, is stored in the /billinfo object. See "About Bill Units".

• The bill itself. All information necessary to create a payment request is stored in a /bill object. See "About Bills".

When you are ready to request a payment from the customer, the billing utilities read the /bill object and generate one of the following:

• An invoice that can be mailed or emailed to the customer.

• A credit card transaction that is sent through a credit card processor.

• A direct debit transaction that is sent through a payment processing service.

Figure 1-1 shows a typical event to invoice billing cycle.

Figure 1-1 Billing Cycle

Description of ''Figure 1-1 Billing Cycle''

For example, a customer accumulates the following charges in one billing cycle: a $20 cycle forward fee, a $10 email usage fee, and a $40 SMS text messaging usage fee. BRM stores the A/R data in the following objects:

• One /item object stores the $20 cycle forward fee and another /item object stores the $50 in usage fees.

• A /balance_group object stores the total cost of all bill items ($70).

• A /billinfo object stores information about when and how to generate a bill. For example, it might specify the 5th as the billing day of month (DOM), the next billing date as January 5, and an invoice payment method.

• A /bill object is generated on January 5 that includes all billing information, such as a list of billable events that occurred during the cycle, any adjustments or credits made by customer service representatives (CSRs), any customer payments, and the total amount due.

When you are ready to request a payment, you run the appropriate BRM utility to generate a printed invoice and then mail the invoice to the customer.

About Items

Item objects in the BRM database store A/R data for an account.

Types of Items

To understand BRM accounts receivable, think of two types of items: bill items, which contribute to the total amount stored in a bill, and A/R items, which reflect actions on the A/R of an account or account bill, such as payments or adjustments. BRM manages A/R by transferring amounts between A/R items and bill items. See "How A/R Actions Affect Account Balances".

Bill Items

Bill items include cycle forward items, cycle arrears items, usage items, and custom items. See "About Bill Items" in BRM Configuring and Running Billing.

A/R Items

A/R items include adjustment items, dispute items, settlement items, payment items, refund items, payment reversal items, write-off items, and write-off reversal items. A/R items collect balance impacts from the type of event reflected in their name.

For information on the general ledger (G/L) impact of the events that contribute to bill items and A/R items, see See "About Collecting General Ledger Data" in BRM Collecting General Ledger Data.

Fields in an Item

All item objects in the BRM database include the same fields.

For a technical description of item objects, see /item in BRM Storable Class Reference.

The following item fields are of particular importance in understanding the flow of amounts through the BRM accounts receivable system:

You can think of the Due, Adjusted, Disputed, Transferred, and Received fields as buckets that contain coins. As the BRM system manipulates A/R, it moves coins among these buckets, but it never changes the number of coins in the Total bucket. The Total bucket contains the coins from all the events linked to the item.

Figure 1-2 shows an example account's total charges in a cycle. The customer has accumulated a hundred dollars ($100) in charges. Without any adjustments the customer has a balance due of $100.

Figure 1-2 Total Cycle Charges

Description of ''Figure 1-2 Total Cycle Charges''

Figure 1-3 shows the same account holder's total charges of $100. An adjustment of $20 has reduced the customer's balance due to $80. The total value of the balance due and the adjustment still equals the total amount of charges.

Figure 1-3 Balance Due Impacted by Adjustment

Description of ''Figure 1-3 Balance Due Impacted by Adjustment''

• Total: The sum of all balance impacts to a currency resource that occurred as a result of the events that contribute to the item. For example, the usage item stores the costs of the usage events a customer generated during the accounting cycle.

• Due: The amount owed by the customer for this item. Initially, Due is the same as Total, but after A/R is received from or transferred to another item, the amounts may be different. For example, the Total and Due of a bill item are the same when the item is created, but payments, adjustments, or disputes reduce the Due.

  Note:

  The amount due includes the balance impact of unresolved disputes.

• Adjusted: The total amount of adjustments made to the item, the net of both debit and credit adjustments. Because most adjustments are credits, the amount in the adjustment field usually reduces the Due of the item.

• Disputed: The total amount of unresolved disputes against the item. The disputed amount reduces the Due of the item.

• Received: The total amount transferred into this item from another item, which is usually a payment item.

• Write-off: A write-off is an A/R transaction that removes an uncollectable balance from a customer's account so it is not considered as an asset for accounting purposes.

• Transferred: The total amount transferred out of this item and into another item.

• Status: The state of the item, which can be Pending (unbilled), Open (billed), or Closed (zero amount due). Items generally move from Pending to Open to Closed status, but closed items can be reopened.

When thinking about item fields, remember that:

• Adjustment and dispute items are different from the Adjusted and Disputed fields in an item. Adjustment and dispute items have Adjusted and Disputed fields, although these fields are unlikely to store a value other than zero for these items.

• A transfer operation places values in the Transferred field of the source item and the Adjusted, Disputed, Received, or Write-off field of the target item, based on the A/R operation being performed.

• Credit values are stored as negative numbers.

• The Status field represents the condition of the item in the flow of A/R.

About Balance Groups

A balance group is an object in the BRM database that stores the balance total for a group of bill items. For example, /balance_group objects store the following information:

• Account associated with the balance group.

• Bill unit associated with the balance group.

• Current balance total.

• Balance that is currently reserved for an active prepaid session. See "Reserving Resources for Concurrent Network Sessions" in BRM Configuring and Collecting Payments.

• Consumed reservation amount.

• Details about any sub-balances, such as the sub-balance total and validity dates. See "About Tracking Resources in Account Sub-Balances" in BRM Setting Up Pricing and Rating.

• Resource consumption rule. See "Specifying the Order in Which Resource Sub-Balances Are Consumed" in BRM Setting Up Pricing and Rating.

All customer accounts in the database, including accounts that do not pay their own bills, have their own account-level /balance_group object. Customers can optionally add service-level balance groups to track the balances for specific services. See "Tracking Resources by Service" in BRM Setting Up Pricing and Rating.

Bill items for an account are stored for each account balance group. During billing, items for each balance group are collected in the bill.

Balance groups contain fields that store sub-balance data, such as the type of resource stored in the sub-balance, the amount in each sub-balance, and the dates when the resource is valid. The sub-balances are grouped by the type of resource they track.

For a technical definition of the balance group object, see /balance_group in BRM Storable Class Reference.

About the Default Balance Group of a Bill Unit

In general, BRM applies event balance impacts to the balance group of the service for which the event was generated. However, some events are not generated for any service. For example, bill-level adjustment and dispute, payment, payment incentive, and payment fee events are generated for a specific bill unit. In such instances, BRM applies the event balance impact to the default balance group of the bill unit and assigns the event to an item belonging to the default service of the default balance group. See "About the Default Service of the Default Balance Group".

Customer Center chooses a random balance group to be the default for new bill units during account creation and account maintenance. You cannot choose a different default balance group for a bill unit.

Note:

During account maintenance through Customer Center, bill units that already have a default balance group are not changed.

If you use the PCM_OP_CUST_CREATE_CUSTOMER and PCM_OP_CUST_MODIFY_CUSTOMER opcodes to create and modify accounts, you must pass the default balance group array for each bill unit to the opcodes.

About the Default Service of the Default Balance Group

BRM uses the default service of the default balance group primarily to assign events that are not associated with any service to the items of the default service. See "About the Default Balance Group of a Bill Unit".

BRM selects a default service using the same algorithm for selecting the default balance group. It selects the service object in the default balance group with the smallest create time (PIN_FLD_CREATED_T). If more than one service object is selected, the service object with the smallest POID is selected as the default service of the default balance group.

You can override the algorithm BRM uses to select the default service. You do this by adding your custom algorithm to the PCM_OP_BAL_POL_GET_BAL_GRP_AND_SVC policy opcode.

About Bill Units

A bill unit is a /billinfo object in the BRM database that stores information on how, how often, and when to generate a /bill object. For example, a bill unit stores the following information:

• Billing state: open, closed, or done.

• Billing status: active, inactive, or accounting only.

• Billing DOM.

• Billing type: open-item accounting or balance-forward accounting.

• Starting date of the current billing cycle.

• Starting date of the next billing cycle.

• Billing frequency, in number of months.

• Primary currency.

• Hierarchical information, such as if the bill unit is a subordinate or a parent account.

• Payment method: credit card, invoice, direct debit, or paid by parent account.

• Payment collection date.

• Default balance group associated with the bill unit.

  Note:

  A bill unit must be associated with at least one balance group.

• Account associated with the bill unit.

• Bill associated with the bill unit.

BRM creates one /bill object for each /billinfo object in the BRM database. All customer accounts in the database, including accounts that do not pay their own bills, have their own /billinfo objects. Customers can optionally add additional /billinfo objects to their account to divide charges into separate bills. For example, a customer can have one /billinfo object that generates a bill for all services related to a home-based business and another /billinfo object that generates a bill for all personal telephony charges.

For a technical definition of the bill unit object, see /billinfo in BRM Storable Class Reference.

About Bills

A BRM bill is a /bill object in the BRM database that stores all billing information necessary to generate a request for payment. BRM creates one /bill object for each /billinfo object in the BRM database.

The /bill object only stores billing information and is not a request for payment itself. You request payments from customers by creating the following:

• Invoices, which are generated by the pin_inv_accts utility (see "pin_inv_accts" in BRM Designing and Generating Invoices)

• Credit card or debit card transactions, which are generated by the pin_collect utility (see "pin_collect" in BRM Configuring and Collecting Payments)

All customer accounts in the database, including accounts that do not pay their own bills, have their own /bill objects. The /bill object stores data such as the bill creation date, total charges accumulated in the bill, the amount due from the customer, and the bill due date.

For a technical definition of the bill object, see /bill in BRM Storable Class Reference.

About Generating Multiple Bills per Cycle for a Single Account

You can generate multiple bills per billing cycle for a single account. You might do this to:

• Permit a customer to pay for different services by using different payment methods, such as credit card for one service and invoice for another.

• Track usage and bill customers for individual subscriptions rather than their account. For more information, see "Managing Customers' Subscription-Level Services" in BRM Managing Customers.

When billing is run, a bill is generated for each bill unit (/billinfo object) owned by the account.

By default, accounts are created with one account-level /billinfo object. You can create, adjust, and modify the default account-level /billinfo object by using Customer Center.

Customizing How to Modify a Bill Object

To modify a bill object before it is committed in the database, use the PCM_OP_BILL_POL_BILL_PRE_COMMIT policy opcode.

This policy opcode is called by the PCM_OP_BILL_MAKE_BILL opcode when a /bill object is created.

About Bill States

The /billinfo object stores the state of a bill and can have one of the following values:

• 0 to indicate that the bill has been finalized.

• 1 to indicate that partial billing has been completed.

• 2 to indicate that all cycle charges have been applied at the end of the billing period and the bill needs to be finalized.

When an account with best pricing configuration is billed, the bill advances to the next state, except in certain cases such as triggered billing and billing for previously skipped months.

About A/R Management

A/R actions constitute the major A/R management activities. A/R actions include recording externally initiated payments and payment reversals, making adjustments, creating and settling disputes, issuing refunds, and writing off bad debt.

CSRs perform many A/R actions in the Balance tab of Customer Center. A CSR must have the proper permission to perform A/R actions and adjust account balances in Customer Center. See "Setting Up Permissions in BRM Applications" in BRM System Administrator's Guide.

To properly account for the effects of A/R actions on your company's revenue, be sure to assign G/L IDs to the associated events. See "Assigning G/L IDs to Nonrated Events" in BRM Collecting General Ledger Data.

About Viewing A/R Information

A CSR can see the balances of an account's currency and non-currency resources in Customer Center. The Customer Center Balance tab displays this information. See "Balance Tab" in Customer Center in BRM Managing Customers.

The Customer Center Balance tab displays the billed, unallocated, and unbilled amounts included in the current balances of each account and the nonpaying bill unit of its child accounts. If the current account is a child account with a nonpaying bill unit, you see information for its A/R parent account.

For accounts that use two currencies, you can display account balances in either the primary account currency or secondary account currency in Customer Center.

If your company has implemented a customer self-care Web site, customers can see the balance of their accounts on the Web. See "Ways to Implement a Web Interface" in BRM Managing Customers.

For information on viewing A/R information in Customer Center, see the Customer Center Help.

Determining the Amount Due

The Summary tab of Customer Center displays the sum of the due amounts for all bills of the account; the total due amount. The total due amount is reduced by unallocated payments and adjustments. To see the due amount for a bill, a service included in a bill, or a bill item, click the Balance tab.

Exporting A/R Data to Files

You can export the data in these Customer Center tables to an HTML file:

• Balance information.

• Payments, A/R actions, and item charges.

Displaying the History of an Item

An item's history shows details about the amounts the item received from and transferred to other items. This information is available for both automatic transfers performed by BRM and manual transfers performed by using Customer Center. See "Transferring Amounts between Items".

Note:

For information on how to display the history of an item in Customer Center, see Reviewing bill item charges and details.

Configuring BRM to Get Events based on Balance Impact Type

You can limit the event search criteria to just one type of balance impact by changing the value of the new PIN_FLD_MODE field directly or by setting the EventChargeDiscountMode parameter to one of the following values:

• 0: (Default and only pre-fix mode) Returns events whose gross, net, or total balance impact matches the search criteria.

• 1: Returns events whose gross balance impact (the sum of all charges) matches the search criteria. Discounts and tax are not considered.

• 2: Returns events whose net balance impacts (the sum of all charges and discounts) matches the search criteria. Tax is not considered.

• 3: Returns events whose total balance impact (the sum of all charges, discounts, and tax) matches the search criteria.

Improving Item Search Performance

If an A/R account has subordinate accounts, BRM performs a step search to find items. By default, BRM returns 1000 items with each step of the search.

To customize the number of items returned:

1. Open the Connection Manager (CM) pin.conf file in BRM_Home/sys/cm.

2. Change the value of the item_search_batch entry.

   For example, to set the number of returned items to 2000:

   - fm_bill     item_search_batch     2000
    
   

   You can also choose not to use step-search by setting the number of returned items to 0.

   Important:

   If your A/R account has a large hierarchy, bypassing step-search can cause the Data Manager (DM) to run out of memory.

Use larger batch search memory sizes to improve run-time performance. You do not need to restart the CM to enable this entry.

How A/R Actions Affect Account Balances

When the BRM system creates a bill item, the Total and Due fields of the item are equal. When an A/R action occurs, the balance impact of the action is stored in an A/R item. For most A/R actions, the balance impact is immediately transferred to a bill item, which changes the Due of the bill item. For example, a payment typically reduces the Due of a bill item.

You can review the details of the transfers between bill items and A/R items by using Customer Center. See "Displaying the History of an Item".

When the Due of a bill item is reduced, the current balance of the account's balance group is also reduced. When the Due of the bill item reaches zero, the item is closed and no further requests for payment are made for it unless further A/R actions occur on the item and reopen it.

However, if the item is under dispute (that is, the disputed field is nonzero) the bill item would remain open even if the Due becomes zero.

Backdating A/R Actions

You can backdate A/R actions so that, for accounting purposes, the action is considered to have occurred at an earlier point in time and the revenue for that time is reported accurately. The A/R actions you can backdate include adjustments, disputes, settlements, externally initiated payments, payment reversals, and write-offs.

Note:

BRM does not support future dating of A/R actions.

To backdate an A/R action, the CSR sets the transaction date (the date that the action is to take effect) to a date before the current date. When backdating, the CSR must select a date after the following:

• The last posted G/L transaction report. See "Posting G/L Reports" in BRM Collecting General Ledger Data.

• The account creation date.

Whether backdated A/R actions appear on the current bill depends on the accounting method you use:

• If you use balance forward accounting, the total of A/R actions for all prior open bills appears on the current bill or invoice as part of the previous balance.

• If you use open item accounting, A/R actions do not appear on the current bill or invoice.

If customers request an invoice that includes information on specific A/R actions in a prior billing period, you can create the invoice by using the testnap utility to run the PCM_OP_INV_MAKE_INVOICE opcode. For information on testnap, see "Testing Your Applications and Custom Modules" in BRM Developer's Guide.

About Payments

In the simple case, payments are the easiest A/R action to understand. When a payment event occurs, the BRM system creates a payment item. The values in the Total and Due fields of the item are initially equal. If the payment is recorded against a bill item, the credit in the Due field of the payment item is immediately transferred to the bill item. The Due of the payment item is then zero and the payment item is closed.

After the transfer from the payment item, the Due field of the bill item is reduced by the amount of the payment. If the payment amount is the same as the amount of the bill item, the bill item is closed.

When a customer's payment is allocated to a bill item, the payment amount also reduces the current balance of the customer's account balance group. Unallocated payments also reduce the current balance of the customer's bill, but they do not reduce the Due of any bill item. The Due amounts of bill items continue to contribute to the Due of the bill and the customer continues to receive requests to pay the unallocated amount.

A payment clerk or CSR allocates payments for invoice accounts by using Payment Tool or Customer Center. For more information, see "About Allocating Payments" in BRM Configuring and Collecting Payments.

Payments made by credit card or direct debit are automatically allocated during the collection process. For information, see "About BRM-Initiated Payment Processing" and "Managing Externally Initiated Payments" in BRM Configuring and Collecting Payments.

For more information about payments and payment processing, see "About Payments" in BRM Configuring and Collecting Payments.

About Reversing Payments

When a payment has been recorded in the BRM database but has not yet been deposited, you can reverse it from the BRM system. This enables BRM to treat the payment as if it never happened. When a payment is reversed, any bills or items previously closed by the payment are reopened, and the payment is deactivated in the BRM system.

For more information, see "About Reversing Payments" in BRM Configuring and Collecting Payments.

About Suspending Payments

If you have the optional Payment Suspense Manager feature enabled, and payments fail validation when they are submitted to BRM, they can be suspended and saved to the payment suspense account. This enables you to continue with your payment processing without interruption and correct the suspended payments at a later time. After you correct suspended payments (for example, by providing the correct account number or bill number), you can submit them to one or more customer accounts.

For more information, see "Configuring Payment Suspense Manager" in BRM Configuring and Collecting Payments.

About Adjustments

A CSR usually performs an adjustment to satisfy an unhappy customer or correct a problem. For example, a CSR might give an adjustment when your company charged the entire monthly fee for a service that was unavailable for a few days. A/R adjustments usually credit the balance of currency resources in the customer's account and reduce the amount the customer owes. They do not return money directly to the customer as refunds. See "About Refunds".

A CSR can adjust the customer's account, subscription services, member services, bills, bill items, and selected events.

Depending on the type of adjustment (account, bill, and so forth), a CSR can adjust currency resources, non-currency resources, or both, as shown in Table 1-1:

Table 1-1 Adjustable Resources

Adjustment Type	Currency	Non-currency
Account-level adjustmentFoot 1	Yes	Yes
Subscription service-level adjustment Footref 1	Yes	Yes
Member service-level adjustment Footref 1	Yes	Yes
Bill-level adjustment	Yes	No
Item-level adjustment	Yes	No
Event-level adjustment	Yes	Yes

^Footnote 1 For these adjustments, there must be a non-currency balance group at the account level for the adjustment to affect a non-currency resource.

Credit adjustments for currency resources decrease the Due of a bill item or, for non-currency resources, increase the balance of the adjusted resource. If a CSR is crediting an event, the balance impact of that event is removed from the customer's account. Debit adjustments have the opposite effect.

BRM processes adjustments and records the adjustment's balance impact in slightly different ways for each type of adjustment. For detailed information on these differences, see "About Adjustments".

Making Adjustments through Customer Center

CSRs make adjustments in Customer Center. A CSR can make either a credit or debit adjustment. For example, if a customer questions an hourly charge, the CSR can credit the amount at issue.

CSRs can adjust accounts, subscription services, member services, bills, bill items, and events. For all levels except the bill and bill item level, the CSR can adjust both currency and non-currency resources. Bill and bill item adjustments are for currency only.

CSRs can make adjustments at each of these levels in Customer Center; they can also adjust events in the Event Browser. To make adjustments in Customer Center, the CSR uses the Balance tab.

Note:

For information on how to perform adjustments in Customer Center, see the Customer Center Help.

An account, subscription service, and member service adjustment to a currency resource sets aside an amount that must be allocated to a bill item. Use Customer Center to allocate the adjustment. Until you do this, account-level, subscription service-level, and member service-level credit adjustments reduce the current balance in the customer's account but they do not reduce the amount a customer is asked to pay.

For account, subscription service, or member service adjustments, perform a transfer to allocate an adjustment of balances paid by credit card or to allocate a debit adjustment. See "Transferring Amounts between Items".

About Opening and Resolving Disputes

A CSR creates a dispute when a customer disagrees with the amount he or she is asked to pay and the problem requires investigation before it can be resolved. A settlement is the resolution of a dispute; a settlement might favor the customer, favor the company, or divide the disputed amount between them. Disputes and settlements credit or debit the currency or non-currency resources of a customer's account but do not return money to the customer directly.

As with payments and adjustments, the BRM system creates a dispute item when the CSR enters a dispute. The disputed amount typically reduces the Due of a bill and the current balances of the customer's account. BRM does not request payment for the disputed amount.

To resolve a dispute, the CSR specifies how much of the disputed amount to grant to the customer. In settling a dispute, the CSR can grant the entire disputed amount to the customer, grant only part of the disputed amount, or deny the dispute and again request payment for the entire disputed amount. The BRM system creates a settlement item for the amount that is not granted and transfers amounts between the settlement item and the disputed bill item. After the dispute resolution, the Due and the current balance in the customer's account balance group reflect what the customer owes.

When the dispute item is created, its Total and Due are initially equal, but the BRM system immediately transfers the credit in the Due field of the dispute item to the disputed bill item, makes the Due of the dispute item zero, and closes the dispute item.

After a settlement, the amount of the dispute that is granted to the customer appears in the Adjusted field of the disputed bill item and in the histories of the disputed item and the settlement item.

A CSR can dispute and settle the customer's bill, bill items, and selected events. Depending on the type of dispute or settlement (bill, bill item, or event), a CSR can dispute or settle currency resources, non-currency resources, or both as shown in Table 1-2.

Table 1-2 Disputable Settlement Types

Dispute or Settlement Type	Currency	Non-currency
Bill-level dispute or settlement	Yes	No
Item-level dispute or settlement	Yes	No
Event-level dispute or settlement	Yes	Yes

Credit disputes for currency resources decrease the Due of a bill or bill item. If the customer is disputing the currency resources of an event for credit, the dispute removes the balance impact of the disputed event from the account. Debit disputes have the opposite effect.

Important:

Event disputes for non-currency resources are recorded but do not directly affect the resource balance until the dispute is settled. At that point, the balance of the disputed resource is increased by the amount of the settlement.

BRM processes disputes and settlements in slightly different ways for each type of dispute or settlement. For detailed information on these differences, see "About Disputes and Settlements".

For information on how to open and resolve disputes in Customer Center, see the Customer Center Help.

About Refunds

You can give customers a refund whenever your company owes them money. Unlike an adjustment, which credits the customer's account balances, a refund returns money that your company owes a customer directly to the customer. Refunds for BRM-initiated payments return money to the direct debit or credit card account the customer uses to make payments. For customers who pay invoices, your company makes a refund by check or other externally initiated payment method.

Note:

You cannot refund suspended payments. For information on how refunds relate to payment suspense processing, see "How Direct Reversals and Refunds Relate to Suspense" in BRM Configuring and Collecting Payments.

The following situations might require a refund:

• When a customer pays too much on a bill.

• When a customer has been given a credit adjustment.

• When a dispute has been settled and the customer is owed some money.

Instead of giving a refund, you can apply the money owed the customer to an open bill. You typically make refunds only if the customer must receive the money directly.

Refunding a customer is accomplished in two steps: creating a refund item, and making the refund payment. There are different ways to complete each step.

For information on how to refund accounts in Customer Center, see the Customer Center Help.

For information on how to define which items in your system are nonrefundable, see "Defining Nonrefundable Items" in BRM Configuring and Running Billing.

Creating Refund Items

The procedure for creating refund items varies depending on whether you want to refund a single account or perform a mass refund.

Creating refund items is not required; you can handle refunds by transferring A/R amounts and allocating payments between A/R items. (See "Making Adjustments through Customer Center".) Therefore, the pin_mass_refund utility is, by default, not included in any billing script.

A CSR can initiate a refund to a customer whose account or bill has a credit balance.

Creating Refund Items for All Accounts with a Credit Balance

The pin_mass_refund utility creates a refund item for accounts that have a credit balance. See "pin_mass_refund".

To give refunds to customers, include the pin_mass_refund utility in any of the billing scripts, such as the pin_bill_day script. If you do, run the pin_mass_refund utility before you run the pin_refund utility. See "Running Billing Utilities" in BRM Configuring and Running Billing.

Making Refund Payments

The procedure for making refund payments to customers varies depending on whether they pay your company by using a BRM-initiated or externally initiated payment method.

Making BRM-Initiated Refund Payments

Run the pin_refund utility to give refunds to all accounts that use the specified payment method and which have refund items when the pin_refund utility is run. You do not specify start and end date parameters when you run this utility. See "pin_refund".

If you miss a billing day, the pin_refund utility processes on all existing refund items.

When to Run the pin_refund Utility

The pin_refund utility is included by default in the pin_bill_day, pin_bill_week, and pin_bill_month scripts. For information about the billing scripts, see "About the Billing Utilities" in BRM Configuring and Running Billing.

Important:

When you use multiple clearing house vendors, you run this utility for each clearing house. See "Using More Than One Payment Processor" in BRM Configuring and Collecting Payments.

For information about editing the billing scripts, see "Running Daily Billing" in BRM Configuring and Running Billing.

Setting the Minimum Amount to Refund

By default, pin_refund does not refund amounts less than two dollars. To change the minimum amount, see "Specifying the Minimum Amount to Refund" in BRM Configuring and Running Billing.

Making Externally Initiated Refund Payments

To make refund payments to customers whose payment method is not BRM-initiated, first create the payments outside the BRM system and then record them in the BRM database by using Payment Tool. For example, write checks to the customers who are due a refund and whose payment method is invoice, and then submit a refund batch. See "Processing a Batch of Payments by Using Payment Tool" in BRM Configuring and Collecting Payments.

Tip:

You can create a custom application that finds refund items and sends the amount and account identification to a check-writing program.

About Refund Items

Refunds create refund items that appear in Customer Center. In other respects, they are different from other A/R actions.

The BRM A/R system creates a refund item to contain the credit in a customer's account. For example, if a balance in a customer's account is $110 and the customer owes your company $100, the amount in the refund item is $10.

When creating a refund item, the BRM A/R system evaluates the open bill items and A/R action items for the account, transfers credit among the items to close as many as possible, creates a refund item to contain the remaining credit, and closes the remaining open items that had a credit in Due.

There are two ways to create refund items:

• Use Customer Center to create refund items for individual accounts. You can create refunds for accounts or bills.

• Use the pin_mass_refund utility to create refund items for all accounts that have a credit balance; that is, all accounts that your company owes money to. See "pin_mass_refund".

About Refunding Child Accounts in Account Hierarchies

When you refund a non-paying child account, the refund is applied to the parent account. BRM associates the refund item with the parent's balance group that has the greatest amount due. If the parent account has no amount due, the refund item is associated with the default balance group of the parent account's bill unit.

For more information about account hierarchies, see "About Account Groups".

Making Refunds

To make refunds for BRM-initiated payments, you first create refund items and then run the pin_refund utility to deposit the refunds and close the refund items. By default, the pin_bill_day script runs the pin_refund utility daily. See "About the Billing Utilities" in BRM Configuring and Running Billing.

To make refunds for externally initiated payments, you begin by creating the refund items and then make the refund payments by check or other externally initiated payment method. You then use Payment Tool to record the refund in the BRM database and close the refund items. See "Processing a Batch of Payments by Using Payment Tool" in BRM Configuring and Collecting Payments.

After the refund, the credits in account balances are reduced by the refund amount.

Canceling Refunds

If you refund a customer account by mistake, you cannot cancel or reverse the refund. Instead, use the PCM_OP_AR_ACCOUNT_ADJUSTMENT opcode to perform a debit adjustment for the refund amount.

See "Adjusting Accounts, Subscription Services, and Member Services".

About Transferring Services between Balance Groups

CSRs can transfer a customer's service from one balance group to another balance group when the customer purchases a new deal or wants to track a service's balance separately.

Important:

Only custom client applications can be used to transfer services between balance groups. To implement this functionality in your custom client application, see "Transferring Services between Balance Groups by Using Custom Client Applications".

When transferring services between balance groups of different accounts, be aware of the following limitations:

• The service's existing balance will be transferred to the new balance group.

• Only one service can be transferred at a time, except for line services. When transferring line services, the entire line will be transferred.

• Services cannot be transferred to an existing balance group.

When a service transfers to a new balance group within the same account, each balance group keeps its existing balance. Events and call detail records (CDRs) with a timestamp before the transfer continue to impact the old balance group, and events and CDRs with a timestamp after the transfer impact the new balance group.

For example, assume that an account owns two services, email and Internet access, that are each assigned to their own balance group. On June 1, balance group A has a balance of $30, and balance group B has a balance of $20. On June 15, the account transfers the email service to balance group A. Balance group A still has a balance of $30, and balance group B still has a balance of $20 as shown in Table 1-3.

Table 1-3 Multiple Balance Groups Example

Balance Group	June 1	June 15
A  Service	/service/ip	/service/ip /service/email
Balance	$30	$30
B   Service	/service/email	None
Balance	$20	$20

In this example, all email-related charges that occur on or after June 15 impact balance group A, and those that occurred before June 15 impact balance group B.

Table 1-4 shows how transferring services between balance groups impacts other BRM features:

Table 1-4 Impact of Transferring Services between Balance Groups

Affected Feature	Description
Resource sharing groups	The way transfers affect resource sharing groups depends on whether the service is transferring to a balance group within the same account or in a different account: Within the same account: If the service being transferred is the owner of a discount sharing group or a charge sharing group, the charges or discounts will be shared by the new balance group. To a different account: If the service being transferred is the owner of a discount sharing group or a charge sharing group, the resource sharing group is unlinked and you must create a new group. See "Managing Resource Sharing Groups".
Balance monitoring	The way transfers affect balance monitoring depends on whether the service is transferring to a balance group within the same account or in a different account: Within the same account: Transferring a service to a different balance group does not change the service's existing balance monitoring setup. To a different account: If the service is the owner of a balance monitor, the balance monitor is deleted and you must create a new balance monitor. See "About Balance Monitoring".
Delayed CDRs	The way transfers affect delayed CDRs depends on whether the event occurred before or after the service was transferred: Before: Balance impacts are applied to the old balance group. After: Balance impacts are applied to the new balance group.
Subscriptions	The way transfers affect subscriptions depends on whether you are transferring a subscription service or a member service: Subscription services: BRM transfers all member services that share the same balance group to the new balance group. Member services: BRM does not transfer the other member services in the subscription. Note: Subscription services and their member services must all point to the same balance group. See "Managing Customers' Subscription-Level Services" in BRM Managing Customers.
Bill items	When a service transfers to a new balance group, BRM creates bill items for the new balance group. Events and CDRs with a timestamp before the transfer continue to impact the old bill items, and events and CDRs with a timestamp after the transfer impact the new bill items. See "About Bill Items" in BRM Configuring and Running Billing.
Backdating	After a service transfers to a new balance group, the service can no longer be backdated. Also, the service transfer cannot be backdated or future dated.

About Transferring Amounts between Items

Transfers are made to correct payments that were allocated incorrectly, to allocate a debit adjustment for any account, and to allocate an account adjustment for an account that pays by credit card. In Customer Center, a CSR can transfer amounts between bill items. Transfers can also be made from payment items and account adjustment items to bill items.

A CSR can make a credit or debit transfer of a currency resource.

For more information, see "Applying Debits and Credits".

For information on how to transfer amounts in Customer Center, see the Customer Center Help.

About Writing Off Bad Debt

To perform a write-off when your company no longer expects to be paid, use Customer Center. A CSR can write off:

• Top-level A/R accounts.

• Bills.

• Bill items.

A write-off removes from your company's assets an A/R amount that your company has determined the customer will never pay. A write-off can also remove an A/R amount that your company has decided it will not refund to the customer; for example, if the amount is very small or if you sent the customer a check that was returned because the customer moved without leaving a new address.

To perform a write-off, use Customer Center. A CSR can write off:

• Top-level A/R accounts: Write-offs are not available for a top-level A/R account if its Due is zero.

• Bills: Write-offs are not available for a bill if it is pending or its Due is zero.

• Bill items: Item level write-offs are allowed for pending and open items.

To ensure proper write-off and write-off reversal functionality, the account should be inactivated before it is written off.

When a CSR performs a write-off, the BRM A/R system creates a write-off item for the amount to be written off. It transfers the Due from the write-off item to the bill items being written off and closes the bill items.

Writing off uncollectable debt or an unpayable credit lets you remove it from the books and more accurately control how it is treated in your accounting and G/L reporting system. Depending on how your company has set up its G/L system, the amount written off is transferred from A/R to a bad debt account or, for unpayable credit, to a miscellaneous revenue account.

A write-off always includes taxes, but you can specify whether the net and tax amounts are written off in one or two events. If you write off in one event, the net and tax amounts are stored separately within the event and can be mapped to different sets of G/L accounts. If you write off in two events, one event stores the net amount of the write-off while another event stores the tax amount. The net and tax amounts stored in these two events can also be mapped to separate sets of G/L accounts. However, the way you specify mapping information for G/L accounts is different for the one-event and the two-event write-off. For more information on how you map the net and tax amounts of a write-off to separate sets of G/L accounts, see "Assigning G/L IDs to Nonrated Events."

If a write-off on an account must be reversed, you can perform a write-off reversal by calling the write-off reversal opcodes. This returns the written-off amount to the account balance.

For more information, see "About Initiating Write-Off Reversals".

Note:

If a payment is received for a write-off on an account, bill, or bill item, the written-off amount can be recovered and allocated to the correct account. For information on write-off reversals, see "Configuring Write-Offs and Write-Off Reversals".

About Account Groups

Accounts can be organized into groups for billing purposes or to represent the relationships between the accounts graphically in Customer Center. There are several kinds of account groups:

• A hierarchical group has a parent account and any number of child accounts and other hierarchical groups. Hierarchical account groups are created for two reasons:

  • To roll the charges of a child account up to the parent account during billing.

  • Solely to display relationships between accounts. In such cases, the parent account pays none of a child account's charges.

  A child account can belong to only one parent account.

  For more information, see "About Hierarchical Account Groups", "Creating Hierarchical Groups", and "Managing Hierarchical Groups".

  Note:

  Sponsor groups are supported for backward compatibility. If you have not set up sponsorship, use resource sharing groups instead.

• A resource sharing group consists of an owner account or service and one or more member accounts or services. Resource sharing groups are created so that discounts and charges can be shared between accounts.

  For more information, see "About Resource Sharing Groups".

• A sponsored top-up group consists of an owner account and one or more member accounts. The owner account can top up a specified balance in each member account. For more information, see "About Topping Up Accounts" in BRM Configuring and Collecting Payments.

• A sponsor group consists of an owner account and one or more member accounts. Sponsor groups are created so that bills and payments can be split between accounts.

  For more information, see "About Sponsor Groups".

In all types of account groups, the bills and payments belong to the account's bill units. For more information, see "About Bill Units and Account Groups".

About Bill Units and Account Groups

Accounts can have one or more bill units. Each bill unit stores billing information and tracks the charges for a particular bill. When accounts are set up with group relationships, the bill units in the accounts, not the accounts themselves, are the paying and nonpaying entities.

In hierarchy, sponsorship, and resource sharing groups, bill units have an additional internal group structure:

• A hierarchical group has a parent bill unit and any number of child bill units and other hierarchical bill unit groups. The charges of a child bill unit are rolled up to the parent bill unit during billing. The parent bill unit is a paying (nonsubordinate) bill unit and the child bill unit is a nonpaying (subordinate) bill unit.

  If the account hierarchy is set up solely to display relationships between accounts, the bill unit in the parent account pays none of the charges in a child account's bill unit. Both the parent and child account's bill units are paying (nonsubordinate) bill units.

  A child bill unit can belong to only one parent bill unit. The bill unit hierarchy must coincide with the account group hierarchy.

  For more information, see "About Hierarchical Bill Units", "Creating Hierarchical Groups", and "Managing Hierarchical Groups".

• A sponsor group consists of an owner (sponsor) bill unit and one or more member (sponsored) bill units. The owner bill unit receives sponsored charges from member bill units immediately after the events generating the sponsored charges occur. An owner bill unit can pay a portion of a member bill unit's charges. A member bill unit can be sponsored by multiple owner bill units in multiple accounts.

  For more information, see "About Sponsor Groups".

• A resource sharing group consists of a group owner and one or more members. The group owner's account has an owning balance group. The owning balance group bears the financial impact of the sharing group, and the bill unit for this balance group pays for the member bill unit's charges.

  Member accounts can have more than one bill unit. If a member account has multiple bill units, the bill unit that benefits from resource sharing is the one that has the balance group whose service has been chosen for resource sharing.

  For more information, see About Resource Sharing Groups.

For a detailed comparison of the hierarchy, sponsorship, and resource sharing features, see "Comparing Hierarchy, Resource Sharing, and Sponsorship".

To understand the financial implications of creating and managing account groups, see "Hierarchy Balance Impacts" and "Sponsorship Balance Impacts".

Comparing Hierarchy, Resource Sharing, and Sponsorship

Hierarchical, resource sharing, and sponsor groups enable customers to pay other customer's bills, but they do so in different ways. These are the main differences:

Relationships

• Hierarchy: Represents parent/child relationships between accounts and account bill units.

• Resource sharing: Represents owner/member relationships in which the owner assumes certain charges for the member or shares resources with the members. Discount sharing is based on discounts purchased by the owner as part of a product rate plans. Charge sharing is based on chargeshares in BRM.

• Sponsorship: Represents owner/member relationships in which the owner sponsors product rate plans for one or more member bill units.

Bill Units and Balance Groups

• Hierarchy: Parent and child accounts have either paying nonsubordinate bill units or nonpaying subordinate bill units.

• Resource sharing: Sharing group owner accounts have owning balance groups that are part of bill units. For charge sharing, charges for eligible member events impact the owning balance group and associated bill unit. For discount sharing, shared discounts impact the member's balance groups by either increasing non-currency resources or reducing the currency impact of an event.

• Sponsorship: Sponsor owner accounts have sponsor owner bill units. Member accounts have sponsored member bill units. The sponsor owner bill unit pays for some charges generated by a sponsored member bill unit.

  Sponsor owner accounts can themselves be part of a sponsorship and thus have member bill units that are sponsored by a different owner. Member accounts can be sponsor group owners and thus have owner bill units that sponsor charges for a different set of members. However, the sponsor group owner cannot be a member of a sponsor group owned by one of its members.

Product and Service Ownership

• Hierarchy: Nonpaying (subordinate) bill units of the same parent bill unit do not have to own the same products.

• Resource sharing: An owner account does not need to have the same products or services as the members.

  The owner bill units can provide resource sharing to group members even if, at group creation time, some members do not own the services for which sharing is provided. In this case, only members who currently own the shared services benefit from discount or charge sharing. Members who do not own the service when sharing is set up can participate in sharing if they purchase that service in the future.

• Sponsorship: For an owner (sponsor) bill unit to incur charges for its member (sponsored) bill units, all members of the owner's bill unit must own the products sponsored by that group. (Members can own different additional products.)

Product Guidelines

• Hierarchy: A parent bill unit can pay for any product.

• Resource sharing: An owner can pay for a member's charges in accordance with a ChargeShare selected when the sharing group is created. An owner can share any discount included in the plans they purchase.

• Sponsorship: To be paid for by a sponsor owner bill unit, a product must be set up in Pricing Center as sponsorable.

Number of Owners and Members

• Hierarchy: A child account and bill unit can belong to only one parent.

• Resource sharing: Multiple owners can provide discount or charge sharing for the same service, and a member account can participate in multiple sharing groups for a service. Thus, a member bill unit can share charges with multiple owner bill units or receive discounts from multiple owners.

• Sponsorship: A member account can be sponsored by multiple sponsor group owner accounts. Likewise, a member bill unit can be sponsored by multiple sponsor owner bill units.

  Each owner should sponsor a different product. See "One Sponsor per Product" in BRM Setting Up Pricing and Rating.

What the Parent or Owner Pays For

• Hierarchy: A parent bill unit pays all the charges for its nonpaying subordinate bill units. The parent cannot pay for only some of a subordinate's charges.

  Bill items are created for nonpaying (subordinate) bill units, but the amounts in them are rolled up at billing to the paying bill unit's bill.

  Exception: If a subordinate bill unit is also a member of a sponsor group, its sponsored charges are paid by the sponsor group's owner bill unit.

• Resource sharing: An owner bill unit pays only the member charges that are defined as shared when the charge sharing group is created.

  A charge sharing group can include some or all chargeshares in the database. The charges go directly to the bill items of the sharing group owner's bill unit.

• Sponsorship: A sponsor owner bill unit pays only its members' sponsored charges.

  You can sponsor some or all rate plans in a product. The sponsored charges go directly to the sponsor owner bill unit's bill items.

Multiple Groups and Multiple Bill Units

• Hierarchy: If a child account has multiple bill units, a parent account can pay the charges for one, several, or all of the child account's bill units.

• Resource sharing: If a member account has a service that participates in multiple sharing groups from different owner accounts, the member's charges are distributed among the groups' owners and the member benefits from each owner's shared discounts. BRM distributes the charges among the owner bill units and applies discounts based on priorities defined when the member joins the resource sharing groups. The member account pays any charges that are not eligible for sharing.

• Sponsorship: If a member account belongs to multiple sponsor groups that are owned by different accounts and that sponsor different products, the member's charges are split accordingly among the groups' owners. The member account pays all its own unsponsored charges.

Collecting Payment Information

• Hierarchy: During account creation, payment information is not collected for child accounts' nonpaying bill units. Their payment method is Paid by parent account.

• Resource sharing: During charge sharing group creation, the payment method of the owning balance group is set as the payment method for any shared charges. The members' payment method has no bearing on the resource sharing so members can use any payment method.

  Discounts do not generate bills, they only change the amount of a bill. Therefore, payment method is not a factor for discount sharing groups.

• Sponsorship: During account creation, payment information is collected for all member accounts' bill units that do not participate in the sponsorship (paying, subordinate bill units). Members can use any payment method.

Tracking Balance Impacts

• Hierarchy: Nonpaying (subordinate) bill units track and display their own balance impacts in real time. When you bill accounts in a hierarchical group, balance impacts of nonpaying bill units are rolled up to the parent bill unit, and the parent account is billed for them.

• Resource sharing: Member bill units do not track or display the balance impacts of shared charges. The owning balance group tracks the balance impacts of usage resulting from non-currency shared discounts; for example, free minutes.

• Sponsorship: Members of sponsored bill units do not track or display the balance impacts of sponsored charges.

Resources

• Hierarchy: Hierarchical groups deal only with billing, so only currency resources are affected.

• Resource sharing: Sharing groups handle all types of resources. For example, you can apply an owner's discount for free minutes to each member or apply a 15% discount on a member's monthly fee.

• Sponsorship: Sponsor groups handle all types of resources. For example, you can apply a non-currency credit to a sponsor owner bill unit from each sponsor member bill unit.

Hierarchy Balance Impacts

The parent-child relationship has no financial impact unless the child bill unit is a nonpaying bill unit. Nonpaying bill units in child accounts maintain all their charges until billing, when the charges are rolled up to the paying bill unit of the parent account, who is then responsible for the bill.

There is no financial impact when you move an independent account or bill unit into a hierarchy and make it a child. If you make the bill unit a nonpaying (subordinate) bill unit, then you choose whether to bill the subordinate bill unit for bill-in-progress charges or to transfer the charges to the new parent, nonsubordinate bill unit.

When you move a nonpaying bill unit from one paying parent to another, you can determine which parent bill unit will pay the bill-in-progress charges. By default, the bill-in-progress charges transfer to the new parent bill unit.

Before you can move a nonpaying bill unit out of a hierarchy, you must change it to a paying bill unit and indicate whether the bill unit or its former parent will pay any bill-in-progress charges.

Resource Sharing Group Balance Impacts

When a member account's service is added to a resource sharing group, a financial relationship is created between the sharing group owner account and the member account.

• Charge sharing: If the group owner account is active and the member service has events eligible for charge sharing, the shared charges impact the balance of the group owner account rather than the member account.

• Discount sharing: If the group owner account is active and the member account has services eligible for discount sharing, the shared discounts reduce the amount of money a member owes by applying the owner's discounts to the balance of the member account before finalizing the member's charges.

The member account stops benefiting from the resource sharing group in the following situations:

• The owner account is inactive or closed.

• The resource sharing group is deleted from the owner account.

• The member account's service is removed from the sharing group.

• Events generated by a member fall outside of the validity period for the shared discount or charge.

• The discounts or chargeshares that were included in the sharing group are deleted through Pricing Center.

• For discount sharing groups, the non-currency resources that were offered as part of the discount have been depleted in the owner account; for example, a monthly discount of free minutes that has already been consumed by the owner or other members. In this case, the member still benefits from currency-type shared discounts such as a 10% reduction on bills for email usage or a $15 discount on overseas calls.

Sponsorship Balance Impacts

When an account is added to a sponsor group and sponsored products are purchased for the account, a financial relationship is created between the sponsor owner bill unit and the member bill unit. If sponsorship is guaranteed and the sponsor owner bill unit remains active, sponsored charges affect the balance of the sponsor owner bill unit rather than the member bill unit.

The member bill unit, rather than the sponsor owner bill unit, receives sponsored charges in the following situations:

• Sponsorship is not guaranteed and the sponsor bill unit reaches its credit limit.

• The sponsor group owner account or bill unit is inactivated.

• The sponsor group owner account or bill unit is closed, the sponsor group is deleted rather than reassigned, and the sponsored products are not canceled.

• The member account or bill unit is removed from the group.

• The sponsor group is deleted from the sponsor group owner account or bill unit.

Managing Balance Groups with Your Custom Application

For information about how BRM uses balance groups, see "About Balance Groups".

To manage balance groups, use the following opcodes:

• PCM_OP_CUST_SET_BAL_GRP

  See "Creating Balance Groups".

• PCM_OP_CUST_MODIFY_CUSTOMER

  See "Moving a Balance Group from One Bill Unit to Another".

• PCM_OP_CUST_DELETE_BAL_GRP

  See "Deleting a Balance Group".

To modify a sub-balance, see "Modifying a Sub-balance".

Creating Balance Groups

PCM_OP_CUST_SET_BAL_GRP is a wrapper opcode that performs all necessary tasks to set up the /balance_group object and create a link to the customer account.

The PCM_OP_CUST_COMMIT_CUSTOMER opcode calls the PCM_OP_CUST_SET_BAL_GROUP opcode while creating a customer account and while modifying customer account information.

If the PIN_FLD_SERVICE_OBJ field in the input flist has a NULL value, the PCM_OP_CUST_SET_BAL_GRP opcode creates a balance group associated with the account. If the PIN_FLD_SERVICE_OBJ field specifies a service object POID, a balance group is created and associated with the service.

PCM_OP_CUST_SET_BAL_GROUP calls the following opcodes:

• PCM_OP_BILL_SET_LIMIT_AND_CR to set the credit limit in the balance group.

• PCM_OP_CUST_CREATE_BAL_GRP to create the /balance_group object.

• PCM_OP_CUST_MODIFY_BAL_GRP to modify an existing /balance_group object.

  Based on which field PCM_OP_CUST_MODIFY_BAL_GRP is modifying, the following fields are either mandatory or optional:

  • PIN_FLD_NAME

  • PIN_FLD_BILLINFO_OBJ

  While modifying the balance group, PCM_OP_CUST_SET_BAL_GROUP checks if there are any pending bill items. If there are pending bill items and if the billing information has changed, PCM_OP_CUST_SET_BAL_GROUP changes the billing information with the new billing information.

If successful, the PCM_OP_CUST_SET_BAL_GROUP output flist contains the POID of the /balance_group object that is created or modified.

Specifying the Default Balance Group of a Bill Unit

To specify your custom algorithm to select the default balance group of a bill unit, use the PCM_OP_BAL_POL_GET_BAL_GRP_AND_SVC policy opcode.

By default, this policy opcode is an empty hook provided for customization. You can add your own custom algorithm to override the BRM algorithm for selecting the default balance group of a bill unit. See "About the Default Balance Group of a Bill Unit".

Important:

By overriding the BRM algorithm, you will change the system behavior that could impact other functionality. For example, if you choose to use only the object creation time or the object POID as the selection criterion, multiple balance group objects might qualify. You should have a good understanding of the default implementation before you customize this policy opcode.

Specifying the Default Service of the Default Balance Group

To specify your custom algorithm to select the default service of the default balance group, use the PCM_OP_BAL_POL_GET_BAL_GRP_AND_SVC policy opcode.

By default, this policy opcode is an empty hook provided for customization. You can add your own custom algorithm to override the BRM algorithm for selecting the default service of the default balance group. See "About the Default Service of the Default Balance Group".

Important:

By overriding the BRM algorithm, you will change the system behavior that could impact other functionality. For example, if you choose to use only the object creation time or the object POID as the selection criterion, multiple service objects might qualify. You should have a good understanding of the default implementation before you customize this policy opcode.

Moving a Balance Group from One Bill Unit to Another

To move a balance group from one bill unit (/billinfo object) to another in the same account, use the PCM_OP_CUST_MODIFY_CUSTOMER opcode.

Important:

You cannot move account-level balance groups or default balance groups to a different /billinfo object.

Moving a balance group to a different /billinfo object means that any new charges for the services in the balance group will be applied to the new /billinfo object.

For example, an account has two /billinfo objects. One /billinfo object tracks charges for services that are invoiced. The other tracks charges for services paid by credit card. The customer decides to pay for all services by credit card. The balance group for invoiced services is moved to the /billinfo object with the credit card payment method. Any new charges for these services are applied to the new /billinfo object and are charged to the credit card. Existing charges for these services that occurred before the balance group was moved are associated with the old /billinfo object and are invoiced.

You cannot move a balance group to another /billinfo object if the balance group's /billinfo object has unallocated payments or adjustments, open refunds, or unresolved disputes. All disputes must be settled, refunds paid, and payments and adjustments allocated before the balance group can be moved.

A /billinfo object must have at least one balance group. When a /billinfo object has only one balance group and that balance group is moved to another /billinfo object, PCM_OP_CUST_MODIFY_CUSTOMER automatically creates a new balance group not associated with any service for the /billinfo object from which the balance group was moved.

Important:

You should never move a balance group to a /billinfo object in a different account. To have a different account be responsible for the charges in a balance group, you must create an account and /billinfo hierarchy.

Deleting a Balance Group

To delete a balance group, use the PCM_OP_CUST_DELETE_BAL_GRP opcode.

Modifying a Sub-balance

You can use Customer Center to change validity dates and apply debits and credits to any sub-balance in an account-level balance group. For more information, see the Customer Center Help.

Use the following opcodes to modify sub-balances associated with additional /billinfo objects. Specify the /balance_group object that contains the sub-balance to modify on the input flist:

• PCM_OP_BAL_CHANGE_VALIDITY changes a sub-balance validity period.

  For more information, see "Modifying the Sub-balance Validity Period".

• PCM_OP_BILL_DEBIT debits or credits a non-currency sub-balance.

• PCM_OP_AR_ACCOUNT_ADJUSTMENT debits or credits a currency sub-balance. Use this opcode to adjust the balance for a prepaid currency resource.

• PCM_OP_BILL_TRANSFER_BALANCE transfers a positive balance from one /balance_group object to another when the balance groups are specified on the input flist. The source and destination balance groups can be in different accounts.

• PCM_OP_BILL_SET_LIMIT_AND_CR sets the credit limit for currency and non-currency resources in a sub-balance.

Modifying the Sub-balance Validity Period

Resource validity periods define when a granted resource is available for consumption.

Customer Center calls the PCM_OP_BAL_CHANGE_VALIDITY opcode to update the valid dates for sub-balances in /balance_group objects. In turn, PCM_OP_BAL_CHANGE_VALIDITY calls the PCM_OP_ACT_USAGE opcode to generate /event/billing/sub_bal_validity events.

To change the validity period of resource balances, specify the following fields in the PIN_FLD_SUB_BALANCES array on the input flist:

• If you are changing the validity period of more than one resource:

  • Specify the resource ID in PIN_FLD_RESOURCE_ID.

  • Specify the sub-balance array index in PIN_FLD_ELEMENT_ID.

• If you are setting absolute dates:

  • Specify the new start time in PIN_FLD_VALID_FROM.

  • Specify the new end time in PIN_FLD_VALID_TO.

Transferring Amounts between Items

Transfers are usually made to correct payments that were allocated incorrectly. Transfers are also used to allocate an account-level debit adjustment for any account and to allocate an account adjustment for an account that pays by credit card. In Customer Center, a CSR can transfer amounts between bill items. Transfers can also be made from payment items and account adjustment items to bill items.

How Resources Are Transferred

During A/R operations, such as settlements and refunds, resources are transferred between items and between balance groups.

Use the following opcodes for transfers:

• PCM_OP_BILL_ITEM_TRANSFER

  See "Transferring Resources between Items".

• PCM_OP_BILL_TRANSFER_BALANCE

  See "Transferring Resources between Balance Groups".

• PCM_OP_BILL_POL_VALID_TRANSFER

  See "Customizing Payment Transfer Validation".

Transferring Resources between Items

To transfer resources between items, use the PCM_OP_BILL_ITEM_TRANSFER opcode.

Note:

This opcode can accept items from multiple A/R bills and creates one transfer event for each A/R bill.

PCM_OP_BILL_ITEM_TRANSFER is called by these opcodes:

• PCM_OP_BILL_RCV_PAYMENT

• PCM_OP_BILL_REVERSE_PAYMENT

• PCM_OP_AR_EVENT_ADJUSTMENT

• PCM_OP_AR_EVENT_DISPUTE

• PCM_OP_AR_EVENT_SETTLEMENT

• PCM_OP_AR_ITEM_ADJUSTMENT

• PCM_OP_AR_ITEM_DISPUTE

• PCM_OP_AR_ITEM_SETTLEMENT

• PCM_OP_AR_ITEM_WRITEOFF

• PCM_OP_AR_REVERSE_WRITEOFF

• PCM_OP_BILL_ITEM_REFUND

The POID of the source item is specified in the PIN_FLD_ITEM_OBJ field in the input flist. Each target item is specified in its own PIN_FLD_ITEMS array in the input flist. This array also includes the POID of the item's bill object and A/R bill object.

The POID of the corresponding A/R event is specified in the PIN_FLD_SESSION_OBJ field in the input flist and is stored in the PIN_FLD_SESSION_OBJ field of the transfer event. This associates the adjustment, dispute, or settlement event with the event that was used to transfer the A/R amount from an A/R item to the appropriate bill item.

Note:

If the transfer is not made as a result of an A/R operation, the value is the session in which the event took place; payment batch event, refund batch event, or reversal batch event.

Each call to PCM_OP_BILL_ITEM_TRANSFER makes a single transfer to an A/R bill. Each bill can include multiple target items. Amounts are allocated to items in the bill starting with the lowest-level items.

PCM_OP_BILL_ITEM_TRANSFER:

• Reads the target item.

• Changes the target item's fields. The fields changed depend on the source item. For example, if the source item is an adjustment, the PIN_FLD_ADJUSTED field of the target item is changed.

• Changes the source item fields as follows:

  PIN_FLD_DUE -= PIN_FLD_AMOUNT

  PIN_FLD_TRANSFERED += PIN_FLD_AMOUNT

• If PCM_OP_BILL_ITEM_TRANSFER was called as part of settling a dispute, checks the PIN_FLD_DISPUTED field in the flist to determine the dispute amount.

  The PIN_FLD_DISPUTED field is only populated in the flist if PCM_OP_BILL_ITEM_TRANSFER is called by an item-level and event-level settlement, and it is used to prevent misdirection of settlement resources. It ensures proper application of the settlement in cases where a single item may be disputed by both an item-level dispute and an event-level dispute.

  For item-level settlements, the amount in this field is the dispute amount that originated solely from the item-level dispute. This amount does not include any contribution from an event-level dispute. For event-level settlements, the PIN_FLD_DISPUTED field provides the dispute amount that originated solely from the event-level dispute being settled.

  Using this information, PCM_OP_BILL_ITEM_TRANSFER populates the settled amount in the original item's PIN_FLD_ADJUSTED field to record the balance impact of the settlement. If any of the disputed amount was denied in the settlement, the opcode also increases the PIN_FLD_DUE field in the original item by the denied amount. These activities are summarized as follows:

  PIN_FLD_DISPUTED -= PIN_FLD_DISPUTED

  PIN_FLD_ADJUSTED += PIN_FLD_AMOUNT

  PIN_FLD_DUE += (PIN_FLD_DISPUTED - PIN_FLD_AMOUNT)

• Writes the /event/billing/item/transfer event, which includes the following fields in addition to those it inherits:

  • PIN_FLD_BUFFER: List of all items or bills affected.

  • PIN_FLD_AMOUNT: Amount of the transfer.

  • PIN_FLD_AR_BILL_OBJECT: A/R bill object of the items in the transfer.

  • PIN_FLD_SESSION_OBJ: The associated A/R event or batch event in which the A/R action took place (payment batch event, refund batch event, or reversal batch event.

• If (PIN_FLD_DUE == PIN_FLD_DISPUTED == 0) marks the status PIN_ITEM_STATUS_CLOSED.

• Writes the modified source and target items.

Transferring Resources between Balance Groups

To transfer resources between balance groups, use the PCM_OP_BILL_TRANSFER_BALANCE opcode.

For example, use this opcode to transfer funds from one prepaid calling card (account) to another.

By default, PCM_OP_BILL_TRANSFER_BALANCE transfers a resource from a credit balance to another balance by debiting the source balance and crediting the target balance with the PIN_FLD_AMOUNT specified in the opcode's input flist. For example:

• Balance group A has a credit balance of $100 (represented for accounting purposes as -100).

• Balance group B has a credit balance of $2 (-2).

• If PIN_FLD_AMOUNT is 30, PCM_OP_BILL_TRANSFER_BALANCE transfers $10 from balance group A to balance group B with these results:

  • Balance group A now has a credit balance of $70 (-70).

  • Balance group B now has a credit balance of $32 (-32).

If the PIN_FLD_VERIFY_BALANCE setting in the PCM_OP_BILL_TRANSFER_BALANCE input flist is set to PIN_BOOLEAN_FALSE, this opcode can also transfer a resource from a debit balance. For example:

• Balance group A has a debit balance of $10 (represented as +10).

• Balance group B has a credit balance of $2 (-2).

• If PIN_FLD_AMOUNT is 30 and PIN_FLD_VERIFY_BALANCE is PIN_BOOLEAN_FALSE, PCM_OP_BILL_TRANSFER_BALANCE transfers $30 from balance group A to balance group B with these results:

  • Balance group A now has a debit balance of $40 (+40).

  • Balance group B now has a credit balance of $32 (-32).

If the PIN_FLD_VERIFY_BALANCE field is not set (default) or is set to PIN_BOOLEAN_TRUE, PCM_OP_BILL_TRANSFER_BALANCE cannot transfer resources from post-paid balances.

For more information, see "About Transferring Sponsored Top-Ups from Debit Balances" in BRM Configuring and Collecting Payments.

If the PIN_FLD_AMOUNT field is greater than or equal to 0, the transfer succeeds. If the PIN_FLD_AMOUNT field is less than 0, the PIN_FLD_RESULT value in the output flist is set to 2.

Table 1-5 lists the valid entries for the PIN_FLD_RESULT field:

Table 1-5 PIN_FLD_RESULT Values

Value	Meaning
0	Balance transfer was successful.
1	Insufficient funds in the source account.
2	Transfer amount was less than 0.

These values are passed to PCM_OP_AR_ACCOUNT_ADJUSTMENT, which debits and credits the source and target accounts respectively.

Important:

When you use PCM_OP_BILL_TRANSFER_BALANCE, billing items are left unallocated as a result of the PCM_OP_AR_ACCOUNT_ADJUSTMENT calls.

Customizing Payment Transfer Validation

To customize how to validate amounts being transferred, use the PCM_OP_BILL_POL_VALID_TRANSFER policy opcode.

Changing a result from PIN_BOOLEAN_FALSE to PIN_BOOLEAN_TRUE enables the specified field value to pass. Changing a result from PIN_BOOLEAN_TRUE to PIN_BOOLEAN_FALSE causes the specified field value to fail.

Transferring Services between Balance Groups by Using Custom Client Applications

CSRs can use a custom client application to transfer a service from one balance group to another within the same account or in a different account. When this occurs, the custom client application calls the PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER opcode, which automatically performs all tasks necessary to transfer the service.

The opcode stores data about a service's old and new balance group and the timestamp of when the transfer occurred in the /service object's PIN_FLD_TRANSFER_LIST array. When BRM applies balance impacts or retrieves balance group information, it automatically checks the /service object's PIN_FLD_TRANSFER_LIST array to determine which balance group it should use based on the event timestamp. If the array does not list a balance group, the opcode automatically uses the service's default balance group.

For more information, see "About Transferring Services between Balance Groups".

To set up your system to transfer services between balance groups, perform these tasks:

• Customize your client application to call PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER.

  See "Transferring Services in Custom Client Applications".

• Configure BRM to synchronize the balance group transfer data with Pipeline Manager.

  See "Synchronizing Balance Group Transfer Data with Pipeline Manager".

Transferring Services in Custom Client Applications

To transfer a service from one balance group to another, use the PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER opcode.

PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER is a wrapper opcode that calls other standard opcodes to perform the following:

• Transfer a service between balance groups in the same account or transfer services when an account purchases a deal.

• Transfer services from the balance group of one account to the balance group of a different account.

• Reassign a balance group of one bill unit to another bill unit within the same account.

  Note:

  Use the PCM_OP_CUST_MODIFY_CUSTOMER opcode to reassign balance groups to a different bill unit because it performs additional validations during the reassignment process. See "Moving a Balance Group from One Bill Unit to Another".

PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER performs the following tasks:

1. Closes the service's accounting cycle and locks the balance group that the service is transferring from.

2. Generates the event/notification/service_balgrp_transfer/start notification event.

   Note:

   By default, this notification event does not trigger an action. However, you can use event notification to perform custom actions before the transfer occurs.

3. Determines whether the service is transferring to a new balance group by checking the PIN_FLD_TO_BAL_GRP_OBJ input flist field:

   • If the field contains a type-only POID, the service is transferring to a new balance group. The opcode skips to step 7.

   • If the field contains a complete POID, continues to the next step.

4. Determines whether a balance group is being reassigned to a different bill unit in the same account by comparing the PIN_FLD_TO_BAL_GRP_OBJ and PIN_FLD_FROM_BAL_GRP_OBJ fields.

   • If the fields are different, continues to the next step.

   • If the fields are the same and neither the PIN_FLD_BILLINFO_OBJ field nor the PIN_FLD_BILLINFO array are passed in, continues to the next step.

   • If the fields are the same and the PIN_FLD_BILLINFO_OBJ field is passed in, the balance group is being reassigned to an existing bill unit. The opcode skips to step 8.

   • If the fields are the same and the PIN_FLD_BILLINFO array is passed in, the balance group is being reassigned to a new bill unit. The opcode creates the bill unit by:

     1. Calling PCM_OP_CUST_SET_PAYINFO to add the bill unit's payment information.

     2. Calling PCM_OP_CUST_SET_BILLINFO to update the bill unit's billing information.

     3. Skips to step 7.

5. Determines whether the service to be transferred is a subscription service.

   If it is, all member services must be transferred and reassigned. The opcode performs the following validations:

   • If the transfer is across accounts, that the member services were not passed in the input flist, that the subscription service and member services are assigned to the same balance group, and that the services passed in the input flist all point to PIN_FLD_FROM_BALANCE_GROUP.

   • If the transfer is within the same account, that the services passed in the input flist all point to PIN_FLD_FROM_BALANCE_GROUP.

6. Determines whether a new deal was purchased by checking if the PIN_FLD_DEALS array was passed in the input flist for the /service object.

   If the array was passed in, a new deal was purchased and all of the service's existing deals must be canceled. The opcode performs the following:

   1. Calls the PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS opcode to retrieve the account's hierarchical relationships of deals, products, discounts, and services.

   2. Calls the PCM_OP_SUBSCRIPTION_CANCEL_DEAL opcode to cancel all of the service's existing deals and, if it is a subscription service, to cancel all of the member service deals.

7. Calls the PCM_OP_CUST_SET_BAL_GRP opcode.

   The PCM_OP_CUST_SET_BAL_GRP opcode performs one of the following:

   • If the PIN_FLD_TO_BAL_GRP_OBJ input flist field contains a type-only POID, creates a new balance group and then associates the service with the new balance group.

   • If the PIN_FLD_TO_BAL_GRP_OBJ input flist field contains a complete POID, associates the service with the specified balance group.

   • If the PIN_FLD_TO_BAL_GRP_OBJ input flist field contains a complete POID and the PIN_FLD_BILLINFO_OBJ field or PIN_FLD_BILLINFO array is passed in, associates the balance group with the specified bill unit.

     Note:

     If it is a subscription service, PCM_OP_CUST_SET_BAL_GRP is called for each member service as well.

8. Locks the balance group that the service is transferring to.

9. Determines whether the service that is being transferred is the owner of a sharing group or balance monitor.

   If it is, the opcode updates the /group/sharing object's PIN_FLD_BAL_GRP_OBJ field with the new balance group.

10. Determines whether the transfer is to a different account by checking the PIN_FLD_TO_BAL_GRP_OBJ and PIN_FLD_FROM_BAL_GRP_OBJ fields.

    If the fields are different, the opcode calls PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION to transfer the service and any member services from one account to another.

11. Determines whether a new deal was purchased by checking if the PIN_FLD_DEALS array was passed in the input flist for the /service object.

    If the array was passed in, the opcode calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL to purchase the new deal.

12. Creates the /event/audit/service_balgrp_transfer audit event.

13. Generates the /event/notification/service_balgrp_transfer/data notification event.

    By default, this triggers a call to the PCM_OP_IFW_SYNC_PUBLISH_EVENT opcode.

14. Generates the /event/notification/service_balgrp_transfer/end notification event.

    Note:

    By default, this notification event does not trigger an action. However, you can use event notification to perform custom actions after the transfer occurs.

Synchronizing Balance Group Transfer Data with Pipeline Manager

If your system uses both real-time rating and batch rating, you must configure BRM to notify Pipeline Manager when:

• A service transfers to a different balance group.

• A balance group transfers to a different bill unit.

BRM notifies Pipeline Manager through the ServiceBalanceGroupTransfer business event.

To configure BRM to notify Pipeline Manager when a service transfers to a different balance group, install the Account Synchronization DM and configure it to publish the ServiceBalanceGroupTransfer business event to the account synchronization queue. For detailed installation and configuration instructions, see "Installing and Configuring the Account Synchronization DM" in BRM Installation Guide.

When configuring the Account Synchronization DM:

• Make sure the ServiceBalanceGroupTransfer business event is listed in your payload configuration file under the <PublisherDefs> section. This business event appears in the default Account Synchronization payload configuration file (BRM_Home/sys/eai_js/payloadconfig_ifw_sync.xml).

• Make sure the event notification list maps the /event/notification/service_balgrp_transfer/data notification event to opcode number 3626. This mapping appears in the default Account Synchronization event notification file (BRM_Home/sys/data/config/pin_notify_ifw_sync).

• Add the ServiceBalanceGroupTransfer business event to your BRM_Home/sys/dm_aq/aq_queuenames file, if the file is configured to send specific business events.