4 Accounts Receivable Opcode Workflows

Learn about the Oracle Communications Billing and Revenue Management (BRM) accounts receivable (A/R) opcode workflows.

Topics in this document:

• Opcodes Described in This Chapter

• Getting a List of A/R Items

• Reversing Refunds

• Transferring Amounts between Items

• Managing Currency and Non-Currency Balance Transfers between Accounts or Services

• Transferring Services between Balance Groups

• Performing Adjustments

• Performing Disputes and Settlements

• Writing Off Debts and Reversing Write-Offs

• Retrieving A/R Information

• Performing Rollover Transfers

Opcodes Described in This Chapter

Table 4-1 lists the opcodes described in this chapter.

Caution:

• Always use the BRM API to manipulate data. Changing data in the database without using the API can corrupt the data.
• Do not use SQL commands to change data in the database. Always use the API.

Table 4-1 Opcodes Described in This Chapter

Opcode	Topic
PCM_OP_ACT_POL_SPEC_GLID	Assigning G/L IDs for an Adjustment Assigning G/L IDs for a Dispute or Settlement Performing Write Offs
PCM_OP_ACT_USAGE	Tax Processing for Account Adjustments
PCM_OP_AR_ACCOUNT_ADJUSTMENT	Transferring Balances between Balance Groups Adjusting Accounts, Subscription Services, and Member Services
PCM_OP_AR_ACCOUNT_WRITEOFF	About Account Write-Offs About Initiating Write-Offs Performing Write Offs About Bill Unit Write-Offs
PCM_OP_AR_BILL_ADJUSTMENT	Adjusting Bills Adjusting Items Tax Processing for Bill and Item Level Adjustments
PCM_OP_AR_BILL_CREDIT_TRANSFER	Transferring From a Negative to a Positive Balance
PCM_OP_AR_BILL_DISPUTE	Disputing Bills Disputing Items
PCM_OP_AR_BILL_SETTLEMENT	Settling Disputed Bills
PCM_OP_AR_BILL_WRITEOFF	About Bill Write-Offs About Initiating Write-Offs Performing Write Offs Flags You Should Use for Write-Offs
PCM_OP_AR_BILLINFO_WRITEOFF	About Bill Unit Write-Offs About Initiating Write-Offs Performing Write Offs About Account Write-Offs
PCM_OP_AR_EVENT_ADJUSTMENT	Adjusting Events Transferring Balances between Items Tax Processing for Account Adjustments Tax Processing for Bill and Item Level Adjustments Tax Processing for Event Adjustments Including Reason Codes in the Adjustment
PCM_OP_AR_EVENT_DISPUTE	Disputing Events Transferring Balances between Items
PCM_OP_AR_EVENT_SETTLEMENT	Settling Disputed Events Transferring Balances between Items
PCM_OP_AR_GET_ACCT_ACTION_ITEMS	Getting a List of A/R Items Retrieving A/R Items That Apply to a Bill Unit Returning a Limited Set of Dispute Data
PCM_OP_AR_GET_ACCT_BAL_SUMMARY	Retrieving a Balance Summary
PCM_OP_AR_GET_ACCT_BILLS	Getting a List of Bills Retrieving a List of Bills for a Bill Unit
PCM_OP_AR_GET_ACTION_ITEMS	Retrieving A/R Items That Apply to a Bill Unit
PCM_OP_AR_GET_BAL_SUMMARY	Retrieving a Balance Summary
PCM_OP_AR_GET_BILL_ITEMS	Getting Bill Items Retrieving a List of Bill Items for a Bill Unit
PCM_OP_AR_GET_BILLS	Getting a List of Bills Getting Bills Retrieving a List of Bills for a Bill Unit
PCM_OP_AR_GET_DISPUTE_DETAILS	Retrieving Dispute Details for a Bill Unit Retrieving Details on Available Balances
PCM_OP_AR_GET_DISPUTES	Retrieving Dispute Details for a Bill Unit
PCM_OP_AR_GET_ITEM_DETAIL	Retrieving Details about a Specific A/R Item or Bill Item Returning a Limited Set of Dispute Data
PCM_OP_AR_GET_ITEMS	Retrieving Details about a Specific A/R Item or Bill Item Retrieving Details on Available Balances
PCM_OP_AR_ITEM_ADJUSTMENT	Adjusting Items Transferring Balances between Items Adjusting Bills Tax Processing for Bill and Item Level Adjustments
PCM_OP_AR_ITEM_DISPUTE	Disputing Items Settling Disputed Bills Disputing Bills
PCM_OP_AR_ITEM_SETTLEMENT	Settling Disputed Items Settling Disputed Bills Transferring Balances between Items
PCM_OP_AR_ITEM_WRITEOFF	About Initiating Write-Offs Performing Write Offs About Bill Unit Write-Offs About Bill Write-Offs About Taxes for Write-Offs Customizing Write-Off Validation Transferring Balances between Items
PCM_OP_AR_POL_REVERSE_WRITEOFF	Reversing Write-Offs Customizing the Rules for Performing Write-Off Reversals
PCM_OP_AR_RESOURCE_AGGREGATION	Retrieving Details on Available Balances Retrieving Details about a Specific A/R Item or Bill Item Retrieving a Full Set of Dispute Data
PCM_OP_AR_REVERSE_REFUND	Reversing Refunds
PCM_OP_AR_REVERSE_WRITEOFF	Reversing Write-Offs About Initiating Write-Off Reversals Customizing the Rules for Performing Write-Off Reversals Transferring Balances between Items
PCM_OP_BAL_CHANGE_VALIDITY	Modifying the Sub-balance Validity Period
PCM_OP_BAL_GET_ACCT_BILLINFO	Finding a Bill Unit
PCM_OP_BAL_POL_SET_SUB_BALANCES	Customizing Balance Transfers
PCM_OP_BAL_TRANSFER_BALANCE	Transferring Balances between Accounts or Services
PCM_OP_BILL_DEBIT	Adjusting Accounts, Subscription Services, and Member Services Applying Debits and Credits
PCM_OP_BILL_FIND	Finding a Bill
PCM_OP_BILL_GET_ITEM_EVENT_CHARGE_DISCOUNT	Finding Discounts in Bill Items
PCM_OP_BILL_ITEM_EVENT_SEARCH	Finding Events Associated with Bill Items
PCM_OP_BILL_ITEM_REFUND	Transferring Balances between Items
PCM_OP_BILL_ITEM_TRANSFER	Reversing Refunds Transferring Balances between Items Disputing Events Settling Disputed Events
PCM_OP_BILL_POL_EVENT_SEARCH	Finding Events Associated with an Account
PCM_OP_BILL_POL_ITEM_VALID_SETTLEMENT	Settling Disputed Items
PCM_OP_BILL_POL_ITEM_VALID_WRITEOFF	Performing Write Offs
PCM_OP_BILL_POL_REVERSE_PAYMENT	Customizing Reversal of Payments Allocated to Written-Off Accounts About Initiating Write-Off Reversals Reversing a Write-Off Reversal
PCM_OP_BILL_POL_VALID_ADJUSTMENT	Adjusting Items Customizing Item Adjustments
PCM_OP_BILL_POL_VALID_DISPUTE	Disputing Items Customizing Item Disputes Customizing Item Settlements
PCM_OP_BILL_POL_VALID_SETTLEMENT	Disputing Items Customizing Item Settlements
PCM_OP_BILL_POL_VALID_TRANSFER	Customizing Item Transfer Validation
PCM_OP_BILL_POL_VALID_WRITEOFF	Customizing Write-Off Validation
PCM_OP_BILL_RCV_PAYMENT	Transferring Balances between Items
PCM_OP_BILL_REVERSE_PAYMENT	Reversing a Write-Off Reversal Customizing Reversal of Payments Allocated to Written-Off Accounts Transferring Balances between Items
PCM_OP_BILL_SET_LIMIT_AND_CR	Creating Balance Groups Modifying Sub-balances
PCM_OP_BILL_TAX_EVENT	Tax Processing for Bill and Item Level Adjustments Tax Processing for Disputes Tax Processing for Settlements
PCM_OP_BILL_TRANSFER	Adjusting Items Disputing Items Settling Disputed Items Performing Write Offs Customizing Reversal of Payments Allocated to Written-Off Accounts
PCM_OP_BILL_TRANSFER_BALANCE	Transferring Balances between Balance Groups
PCM_OP_GROUP_UPDATE_INHERITED	Updating Inheritance Fields in Groups
PCM_OP_IFW_SYNC_PUBLISH_EVENT	Transferring Services between Balance Groups
PCM_OP_PYMT_COLLECT	About Initiating Write-Off Reversals Reversing Write-Offs
PCM_OP_PYMT_ITEM_SEARCH	Finding Items
PCM_OP_SUBSCRIPTION_CANCEL_DEAL	Transferring Services between Balance Groups
PCM_OP_SUBSCRIPTION_PURCHASE_DEAL	Transferring Services between Balance Groups
PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS	Transferring Services between Balance Groups
PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER	Transferring Services between Balance Groups
PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER	Performing Rollover Transfers
PCM_OP_SUBSCRIPTION_TRANSFER_SUBSCRIPTION	Transferring Services between Balance Groups

Getting a List of A/R Items

PCM_OP_AR_GET_ACCT_ACTION_ITEMS retrieves the list of A/R items applied to all bill units (/billinfo objects) in an account or to a single bill unit.

You can restrict the search by various means, such as date, status, and bill unit POID.

You can find items for the specific bill unit or for it and its nonpaying child bill units.

PCM_OP_AR_GET_ACCT_ACTION_ITEMS uses the PIN_FLD_FLAGS both as an input and output field.

PCM_OP_AR_GET_ACCT_ACTION_ITEMS uses the input PIN_FLD_FLAGS value to select and/or mark the required items:

• When PIN_FLD_FLAGS contains PIN_AR_BILLED_ITEM, it selects the billed items that are allocated to the specified bill and marks each item as "billed."

• When PIN_FLD_FLAGS contains PIN_AR_UNBILLED_ITEM, it selects the unbilled items that are allocated to the specified bill and marks each item as "unbilled."

• If PIN_FLD_FLAGS is not present or is present but does not have either value, this opcode selects both billed and unbilled items allocated to the bill, but does not mark the A/R items.

If the PIN_FLD_FLAGS field is present, PCM_OP_AR_GET_ACCT_ACTION_ITEMS expects a value for the PIN_FLD_BILL_OBJ input field, or it returns an error.

PCM_OP_AR_GET_ACCT_ACTION_ITEMS determines that a special item is a “billed" item if it is allocated to a bill before the bill is finalized or before the corrective bill is created.

The PIN_FLD_RESULTS output array contains the PIN_FLD_FLAGS which indicates whether the allocated item is billed (PIN_AR_BILLED_ITEM) or unbilled (PIN_AR_UNBILLED_ITEM). This output array contains the PIN_FLD_FLAGS entry if the input flist contained PIN_FLD_FLAGS field and if a special item is allocated to the bill.

The special items that PCM_OP_AR_GET_ACCT_ACTION_ITEMS considers include all of the following:

• PIN_OBJ_TYPE_ITEM_PAYMENT

• PIN_OBJ_TYPE_ITEM_REVERSAL

• PIN_OBJ_TYPE_ITEM_REFUND

• PIN_OBJ_TYPE_ITEM_ADJUSTMENT

• PIN_OBJ_TYPE_ITEM_DISPUTE

• PIN_OBJ_TYPE_ITEM_SETTLEMENT

• PIN_OBJ_TYPE_ITEM_WRITEOFF

• PIN_OBJ_TYPE_ITEM_WRITEOFF_REVERSAL

Reversing Refunds

If a refund fails, you can reverse the refund. Refunds can fail because of returned checks and invalid credit cards.

• You can reverse only failed refunds.

• A refund can be reversed only once. You cannot reverse a refund that has been reversed before.

To reverse a refund, use PCM_OP_AR_REVERSE_REFUND.

PCM_OP_AR_REVERSE_REFUND does the following:

1. Takes as input one or more /item/refund POIDs in the input flist.

2. For each PIN_FLD_REVERSALS array, PCM_OP_AR_REVERSE_REFUND does the following:

   • Checks if the refund is already reversed

     Refunds that are already reversed cannot be reversed again.

   • Checks if the refund is a failed refund

3. Fetches the /event/billing/transfer/item event for each /item/refund in the input flist.

   The PIN_FLD_ACTION_INFO field of the /event/billing/transfer/item event contains the details of the /item/refund item from which the amount is transferred and the details of the /item/refund item to which the amount is transferred.

4. Creates the /event/billing/refund/reversal event that points to the /item/refund item in the input flist.

   The input does not contain the BALANCE_IMPACTS array. The PIN_FLD_REFUND substruct contains the amount that is being reversed.

   The SESSION_OBJ field of /event/billing/refund/reversal points to the corresponding /event/billing/refund/cc that failed.

5. Debits the refund amount from the /item/refund item and calls PCM_OP_BILL_ITEM_TRANSFER to transfer the refund amount back to the original items (for example, a credit amount to the /item/payment item).

6. Sets /item/refund to 0 and closes /item/refund.

   The PIN_FLD_SESSION_OBJ field of the transfer events point to /event/billing/refund/reversal.

7. Creates an /event/billing/refund/reversal event.

   The /event/billing/refund/reversal event does not contain the BALANCE_IMPACTS array.

Transferring Amounts between Items

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

BRM uses the following opcodes for transfers:

• PCM_OP_BILL_ITEM_TRANSFER

  See "Transferring Balances between Items".

• PCM_OP_BILL_TRANSFER_BALANCE

  See "Transferring Balances between Balance Groups".

• PCM_OP_BILL_POL_VALID_TRANSFER

  See "Customizing Item Transfer Validation".

Transferring Balances between Items

To transfer balances between items, BRM uses PCM_OP_BILL_ITEM_TRANSFER. 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 the following 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 and event settlement, and it is used to prevent misdirection of settlement balances. It ensures proper application of the settlement in cases where a single item may be disputed by both an item dispute and an event dispute.

  For item settlements, the amount in this field is the dispute amount that originated solely from the item dispute. This amount does not include any contribution from an event dispute. For event settlements, the PIN_FLD_DISPUTED field provides the dispute amount that originated solely from the event 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, this 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.
• Sets the bill's PIN_FLD_STATE field to one of the following:
  • PARTIALLYPAID: If the value of PIN_FLD_DUE for the bill is greater than 0 and less than the value of PIN_FLD_CURRENT_TOTAL.
  • SETTLED: If the value of PIN_FLD_DUE for the bill is equal to 0 and the value of PIN_FLD_CURRENT_TOTAL is greater than 0.

Transferring From a Negative to a Positive Balance

PCM_OP_AR_BILL_CREDIT_TRANSFER transfers the amount from a bill that has a negative balance to one or more bills that have a positive balance.

This opcode allocates credit amounts to bills that have a positive balance. This opcode takes as input the /bill object and corresponding /billinfo object of both the source bill and destination bill or bills.

Transferring Balances between Balance Groups

To transfer balances between balance groups, BRM uses PCM_OP_BILL_TRANSFER_BALANCE.

For example, BRM uses this opcode to transfer funds from one account to another.

PCM_OP_BILL_TRANSFER_BALANCE transfers an asset 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 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, PCM_OP_BILL_TRANSFER_BALANCE can also transfer an asset 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 assets from post-paid balances.

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 4-2 lists the entries for the PIN_FLD_RESULT field:

Table 4-2 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.

Note:

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 Item Transfer Validation

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

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.

PCM_OP_BILL_POL_VALID_TRANSFER is called by PCM_OP_BILL_ITEM_TRANSFER.

Managing Currency and Non-Currency Balance Transfers between Accounts or Services

Use the following opcodes to transfer currency or non-currency balances from one account or service to another account or service:

• PCM_OP_BAL_TRANSFER_BALANCE

  See "Transferring Balances between Accounts or Services".

• PCM_OP_BAL_POL_SET_SUB_BALANCES

  See "Customizing Balance Transfers".

Transferring Balances between Accounts or Services

To transfer currency or non-currency balances from one account or service to another, use PCM_OP_BAL_TRANSFER_BALANCE. This opcode transfers balances regardless of the source's and target's balance type: postpaid, prepaid, or hybrid. For example, this opcode could transfer 200 free minutes from a prepaid balance to a postpaid balance.

This opcode is called by Billing Care, Customer Center, and the Billing Care REST API.

When the opcode is called, pass the following information in the opcode's input flist:

• The POID of the source account, service, or balance group you are transferring from. If you specify the POID of an account or service, its default balance group is used.

• The POID of the destination account, service, or balance group you are transferring to. If you specify the POID on an account or service, its default balance group is used.

• The transfer amount and resource ID.

• By default, the transfer balance keeps the source's validity period. To modify the validity period of the transfer balance's validity period, pass in the PIN_FLD_SUB_BALANCES array with the following input flist fields:

  • PIN_FLD_VALID_FROM: Set this to the timestamp of the validity's start date and time.

  • PIN_FLD_VALID_TO: Set this to the timestamp of the validity's end date and time.

  • PIN_FLD_ELEMENT_ID: Set this to the balance element ID.

• Whether to charge a transaction fee to the source, destination, both, or none. To do so, set the PIN_FLD_FEE_FLAG input flist field to 0 (do not apply a fee), 1 (apply a fee to the source), 2 (apply a fee to the destination), or 3 (apply a fee to both the source and destination). If charging a transaction fee, also include the flat amount or percentage of the balance transfer to apply:

  To apply a flat fee, set these input flist fields:

  • PIN_FLD_CHARGE_AMT: The amount of the transaction fee.

  • PIN_FLD_CHARGE_RESOURCE_ID: The currency or non-currency resource ID of the transaction fee, such as 840 for USD or 111055 for free minutes.

  To apply a percentage of the balance transfer amount, set the PIN_FLD_PERCENT field to the percentage, such as 3 for 3%.

After it receives the input flist, PCM_OP_BAL_TRANSFER_BALANCE performs the following tasks:

1. Opens a global transaction.

2. If an /account or /service POID is passed in, calls PCM_OP_BAL_GET_BALANCES to retrieve its default /balance_group POID and its current currency or non-currency balance.

3. Generates an audit event (/event/audit/transfer_balance object).

4. Calls PCM_OP_BAL_POL_SET_SUB_BALANCES to perform any customizations to the transfer balance being debited from the source.

5. Calls PCM_OP_BILL_DEBIT to debit the transfer amount from the source account, service, or balance group.

6. Calls PCM_OP_BAL_POL_SET_SUB_BALANCES to perform any customizations to the transfer balance being credited to the destination.

7. Calls PCM_OP_BILL_DEBIT to credit the transfer amount to the destination account, service, or balance group.

8. If there is a transfer fee, calls the PCM_OP_ACT_USAGE to generate a balance transfer event (/event/billing/fee/balance_transfer object).

9. Closes the global transaction.

Customizing Balance Transfers

To customize balances before they are debited from the source account, service, or balance group, or after they are credited to the destination account, service, or balance group, use the PCM_OP_BAL_POL_SET_SUB_BALANCES policy opcode. By default, this policy opcode does nothing.

This policy opcode is called by PCM_OP_BAL_TRANSFER_BALANCE.

Transferring Services between Balance Groups

Use PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER to transfer a service from one balance group to another in the same account or in a different account. You must create a custom application to implement this functionality.

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

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

• Only one service can be transferred at a time, except for line services. For line service transfers, the entire line is transferred.

• Services cannot be transferred to an existing balance group.

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

For example, assume that an account owns two services: email and broadband access. Each is assigned its 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 4-3.

Table 4-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 4-4 shows how transferring services between balance groups impacts other BRM features:

Table 4-4 Impact of Transferring Services between Balance Groups

Affected Feature	Description
Charge and discount sharing groups	The way transfers affect charge and discount sharing groups depends on whether the service is transferring to a balance group in the same account or in a different account: In the same account: If the service being transferred is the owner of a charge or discount sharing group, the charges or discounts are shared by the new balance group. To a different account: If the service being transferred is the owner of a charge or discount sharing group, the group is unlinked and you must create a new group. See "Managing Sharing Groups".
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 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 time stamp before the transfer continue to impact the old bill items, and events and CDRs with a time stamp 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.

PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER stores data about a service's old and new balance groups and the time stamp 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, PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER automatically checks the /service object's PIN_FLD_TRANSFER_LIST array to determine which balance group it should use based on the event time stamp. If the array does not list a balance group, this opcode automatically uses the service's default balance group.

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

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

• 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 in the same account.

  Note:

  Use PCM_OP_CUST_MODIFY_CUSTOMER 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 calls PCM_OP_CUST_SET_BAL_GRP (see 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, determines whether the service to be transferred is a subscription service (see step 5).

   • If the fields are the same and neither the PIN_FLD_BILLINFO_OBJ field nor the PIN_FLD_BILLINFO array are passed in, determines whether the service to be transferred is a subscription service (see step 5).

   • 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. PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER locks the balance group that the service is transferring to (see 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. PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER 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. Calling PCM_OP_CUST_SET_BAL_GRP (see 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, it validates 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 in the same account, it validates that the services passed in the input flist all point to PIN_FLD_FROM_BALANCE_GROUP.

6. Determines whether a new bundle 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 bundle was purchased and all of the service's existing bundles must be canceled. PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER performs the following:

   1. Calls PCM_OP_SUBSCRIPTION_READ_ACCT_PRODUCTS to retrieve the account's hierarchical relationships of bundles, charge offers, discount offers, and services.

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

7. Calls PCM_OP_CUST_SET_BAL_GRP.

   PCM_OP_CUST_SET_BAL_GRP 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. PCM_OP_SUBSCRIPTION_SERVICE_BALGRP_TRANSFER then does the following:

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

   If it is, this 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, this 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 bundle 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, this opcode calls PCM_OP_SUBSCRIPTION_PURCHASE_DEAL to purchase the new bundle.

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

13. Generates the /event/notification/service_balgrp_transfer/data notification event. This triggers a call to PCM_OP_IFW_SYNC_PUBLISH_EVENT.

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.

Performing Adjustments

You use Billing Care or Customer Center to make adjustments. You can create a custom application to handle specialized adjustment scenarios, such as low-level adjustments against specific events or high-level adjustments distributed across an A/R account and its child accounts. For example, you might implement different adjustment levels to enable the CSR to help a customer who was charged too many minutes for a call and a customer whose prepaid service experienced a 3-day outage.

Use the following opcodes to perform and customize adjustments:

• PCM_OP_AR_ACCOUNT_ADJUSTMENT

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

• PCM_OP_AR_BILL_ADJUSTMENT

  See "Adjusting Bills".

• PCM_OP_AR_ITEM_ADJUSTMENT

  See "Adjusting Items".

• PCM_OP_BILL_POL_VALID_ADJUSTMENT

  See "Customizing Item Adjustments".

• PCM_OP_AR_EVENT_ADJUSTMENT

  See "Adjusting Events".

• PCM_OP_ACT_POL_SPEC_GLID

  See "Assigning G/L IDs for an Adjustment".

Adjusting Accounts, Subscription Services, and Member Services

To adjust accounts, subscription services, or member services, BRM uses PCM_OP_AR_ACCOUNT_ADJUSTMENT. This opcode debits or credits the currency balance for the specified account. This opcode is called by BRM client applications to adjust the balance impacts of an event.

If the input flist specifies a balance group, BRM debits or credits that /balance_group object. If the input flist specifies a bill unit, the adjustment is applied to the default balance group of the bill unit. If the input flist specifies account only, it debits or credits the account default balance group.

You can open an account adjustment with or without tax. For information on how PCM_OP_AR_ACCOUNT_ADJUSTMENT performs adjustments taxation, see "Including Taxes in the Adjustment".

The /event/billing/adjustment/account object records the balance impact. The item_total and due fields of the adjustment item show the amount of adjustment. The adjustment item is billed immediately after the transaction occurs. The status of the item is set to PIN_ITEM_STATUS_OPEN.

If a balance group is not specified in the input flist, PCM_OP_AR_ACCOUNT_ADJUSTMENT adjusts the account default balance group. If the input flist identifies a balance group, PCM_OP_AR_ACCOUNT_ADJUSTMENT updates the matching sub-balance or creates a new sub-balance if it cannot find a match. The sub-balance that must be updated is also specified in the input flist.

If your client application enables you to specify a subscription service and a member service in the input flist, you can perform subscription service adjustments and member service adjustments. These adjustment levels use PCM_OP_AR_ACCOUNT_ADJUSTMENT to perform adjustments against all the services that belong to the balance group, which the /service object supplies.

If an account, subscription service, or member service adjustment is for noncurrency balances, use PCM_OP_BILL_DEBIT to adjust the noncurrency balance. For more information on how PCM_OP_BILL_DEBIT works with balances, see "Applying Debits and Credits".

BRM creates a G/L ID for every account adjustment. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment".

Fields You Should Include in the Flist for Account, Subscription Service, and Member Service Adjustments

When performing account, subscription service, and member service adjustments, set these fields in the PCM_OP_AR_ACCOUNT_ADJUSTMENT input flist:

• PIN_FLD_POID for the account to which the adjustment applies. You obtain this value from the /account object that the CSR selects. Account, subscription service, and member service adjustments require this field.

• PIN_FLD_BILLINFO_OBJ for the bill unit to which the adjustment applies. The adjustment balance impact is applied to the default balance group of the bill unit.

• PIN_FLD_BAL_GRP_OBJ for the balance group to which the adjustment applies. You obtain this value from the /account or /service object that the CSR selects.

  This field is used for account, subscription service, and member service adjustments. If you omit this field from the input flist for an account adjustment, the adjustment uses the default balance group of the bill unit specified. Otherwise, it uses the account default balance group. Subscription service and member service adjustments require PIN_FLD_BAL_GRP_OBJ in the input flist.

• PIN_FLD_AMOUNT for the adjustment amount. The value supplied for this field should be negative when crediting and positive when debiting.

• PIN_FLD_CURRENCY for the balance to adjust.

• PIN_FLD_FLAGS for the tax treatment:

  • PIN_AR_WITHOUT_TAX: The account adjustment is nontaxable.

  • If the PIN_AR_WITH_TAX: The account adjustment is taxable.

    Note:

    If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The adjustment is nontaxable if the pin.conf entry is absent.

PCM_OP_AR_ACCOUNT_ADJUSTMENT accepts a variety of other fields used to define tax treatment, adjustment time, adjustment description, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Adjustment".

• For information on reason codes, see "Including Reason Codes in the Adjustment".

Flags for Account, Subscription Service, and Member Service Adjustments

Use these flags with PCM_OP_AR_ACCOUNT_ADJUSTMENT:

• If the PCM_OPFLG_READ_RESULT flag is set, all the fields in the event object are returned in addition to the POID.

• If the PCM_OPFLG_CALC_ONLY 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 and adjustment item are returned to the caller.

• If the PCM_OPFLG_CALC_ONLY flag is not set, the /event/billing/adjustment/account object is created to record details of the operation.

Adjusting Bills

To make adjustments at the bill level, BRM uses PCM_OP_AR_BILL_ADJUSTMENT. This opcode is called by BRM client applications to adjust the balance impacts of items associated with the specified bill.

PCM_OP_AR_BILL_ADJUSTMENT debits or credits a currency balance for the specified /bill object. You can open a bill adjustment with or without tax. For information on how PCM_OP_AR_BILL_ADJUSTMENT performs adjustment taxation, see "Including Taxes in the Adjustment".

Note:

PCM_OP_AR_BILL_ADJUSTMENT does not check to determine whether the item you are adjusting is billed yet. However, using this opcode to adjust pending items is not recommended. If you try to adjust pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.

Note:

You cannot move a balance group to a new bill unit if there are any adjustments against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.

PCM_OP_AR_BILL_ADJUSTMENT does not make adjustments when:

• The specified bill is not an A/R bill (for example, a bill from a nonpaying bill unit).

• The amount of the adjustment exceeds the total amount of the bill. For example, if the bill due is $5, you cannot perform a credit adjustment for $6. Similarly, if the bill due -$5, you cannot perform a debit adjustment for $6.

Bill adjustments can be performed against the entire bill or just specific bill items. When it receives an input flist, PCM_OP_AR_BILL_ADJUSTMENT creates a single, umbrella adjustment item for all bill items that require adjustment, as follows:

• If the input flist specifies individual bill items, the adjustment item is associated with each of these bill items. You must specify the adjustment amount for each bill item in the flist.

• If the flist does not specify any bill items, all bill items are eligible for adjustment. PCM_OP_AR_BILL_ADJUSTMENT opens adjustments for as many bill items as it can before it consumes the adjustment amount or percentage. In this case, the adjustment item covers only those bill items that PCM_OP_AR_BILL_ADJUSTMENT was able to fully or partially adjust before using up the adjustment amount or, if the adjustment is defined as a percentage of the bill, the specified percentage.

In either case, PCM_OP_AR_BILL_ADJUSTMENT passes the POID of the adjustment item and the appropriate adjustment amount to PCM_OP_AR_ITEM_ADJUSTMENT, which performs the adjustment for each of the associated bill items. An /event/billing/adjustment/item object is created for each adjusted item in the bill, recording the balance impact. The due fields of the adjustment items become 0 after the adjustment and the status of the item is set to PIN_ITEM_STATUS_CLOSED. For details on how PCM_OP_AR_ITEM_ADJUSTMENT works, see "Adjusting Items".

Before passing the adjustment item and amount to PCM_OP_AR_ITEM_ADJUSTMENT, PCM_OP_AR_BILL_ADJUSTMENT determines whether the adjustment has tax implications. If so, it checks the original /item object to determine the taxable portion of the item:

• If the item object stores only an amount generated by a tax event, the opcode omits it from tax calculation.

• If the item object stores only an amount generated by a usage event, the opcode calculates taxes for the amount.

• If the item object stores an amount generated by a tax event and an amount generated by a usage event, the opcode calculates the adjustment tax reversal only for the usage amount and not the tax amount.

For each item that can be adjusted, the opcode checks the events that make up the item to determine whether any of the events are tax exempt. If so, it omits these events from the amount it uses when calculating the adjustment tax reversal. As a result of eliminating any nontaxable components of the original item, the adjustment tax is calculated proportionally to the actual taxable amount of the item.

If the adjustment fails, PCM_OP_AR_BILL_ADJUSTMENT returns the reason in the PIN_FLD_DESCR field of the PIN_FLD_RESULTS array on the output flist.

BRM creates a G/L ID for every bill adjustment. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment".

Fields You Should Include in the Flist for Bill Adjustments

When performing bill adjustments, set the following fields in the PCM_OP_AR_BILL_ADJUSTMENT input flist:

• PIN_FLD_POID for the bill to which the adjustment applies. You obtain this from the /bill object that the CSR identifies. The adjusted amount is applied to the default balance group of the bill unit associated with the bill.

• PIN_FLD_POID for the items to be adjusted under the PIN_FLD_ITEMS array. This array is required only to adjust a particular set of bill items in the bill.

  Note:

  This field must be at level 1 of the input flist for the item adjustment to work.

• PIN_FLD_AMOUNT for the adjustment amount. The value supplied for this field should be negative when crediting and positive when debiting.

  You can specify the adjustment amount through either PIN_FLD_AMOUNT or PIN_FLD_PERCENT. The PIN_FLD_AMOUNT field is mandatory and the PIN_FLD_PERCENT field is optional. If the input flist includes both fields, BRM uses the value in PIN_FLD_PERCENT and ignores the value in PIN_FLD_AMOUNT.

  You can provide the PIN_FLD_AMOUNT field for the bill itself or, if the adjustment is against an array of bill items, for the individual bill items. If you are performing an adjustment that credits the bill, the absolute value of PIN_FLD_AMOUNT must be greater than 0 and less than the total bill amount and its sign should be negative.

• PIN_FLD_FLAGS for the tax treatment:

  • PIN_AR_WITHOUT_TAX: The bill adjustment is nontaxable.

  • If the PIN_AR_WITH_TAX: The bill adjustment is taxable.

    Note:

    If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The adjustment is nontaxable if the pin.conf entry is absent.

PCM_OP_AR_BILL_ADJUSTMENT accepts a variety of other fields used to define tax treatment, adjustment time, adjustment description, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Adjustment".

• For information on reason codes, see "Including Reason Codes in the Adjustment".

BRM creates a G/L ID for every bill adjustment. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment".

Flags for Bill Adjustments

Use these flags with PCM_OP_AR_BILL_ADJUSTMENT:

• If the PCM_OPFLG_READ_RESULT flag is set, all the fields in the event object are returned in addition to the POID.

• If the PCM_OPFLG_CALC_ONLY 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 and adjustment item are returned to the caller.

  If the PCM_OPFLG_CALC_ONLY flag is not set, the /event/billing/adjustment/item object is created to record details of the operation.

Adjusting Items

To adjust items, BRM uses PCM_OP_AR_ITEM_ADJUSTMENT. This opcode debits or credits a currency balance for the bill item specified in the input flist. The item adjustment balance impact is applied to the default balance group of the bill unit that is associated with the bill item. This opcode is also called by PCM_OP_AR_BILL_ADJUSTMENT to adjust items in a bill.

Note:

PCM_OP_AR_ITEM_ADJUSTMENT does not check to determine whether the item you are adjusting is billed yet. However, using this opcode to adjust pending items is not recommended. If you try to adjust pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.

Note:

You cannot move a balance group to a new bill unit if there are any adjustments against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.

PCM_OP_AR_ITEM_ADJUSTMENT does the following:

1. Reads the original /item object and prepares the changes to reflect the balance impact of the adjustment.

   For credit adjustments, these changes reduce the Due amount (PIN_FLD_DUE) for the item. For debit adjustments, the opposite occurs.

2. Calls PCM_OP_BILL_POL_VALID_ADJUSTMENT to validate the changes.

   You can customize the validation criteria for PCM_OP_BILL_POL_VALID_ADJUSTMENT. For information on customizing the opcode, see "Customizing Item Adjustments".

3. Checks to see if the PIN_FLD_ITEM_OBJ field is present in the input flist.

   If so, PCM_OP_AR_ITEM_ADJUSTMENT checks the contents of the field to determine:

   • Whether the field contains a POID, indicating that the opcode is being called by PCM_OP_AR_BILL_ADJUSTMENT to complete a bill adjustment.

     This POID identifies the /item/adjustment object that PCM_OP_AR_BILL_ADJUSTMENT created to store information on the bill adjustment. This is the /item/adjustment object that PCM_OP_AR_ITEM_ADJUSTMENT associates with each of the adjustment events it creates for the bill adjustment.

   • Whether the field is NULL, indicating that the opcode is being called directly from the client application to perform an item adjustment. In this case, PCM_OP_AR_ITEM_ADJUSTMENT creates its own /item/adjustment object. This object is exclusive to the individual item being adjusted.

4. If the adjustment has tax implications and PCM_OP_AR_ITEM_ADJUSTMENT is not being called as part of a bill adjustment, PCM_OP_AR_ITEM_ADJUSTMENT checks the original /item object to determine the taxable portion of the item:

   • If the item object stores only an amount generated by a tax event, the opcode omits it from tax calculation.

   • If the item object stores only an amount generated by a usage event, the opcode calculates taxes for the amount.

   • If the item object stores an amount generated by a tax event and an amount generated by a usage event, the opcode calculates the adjustment tax reversal only for the usage amount and not the tax amount.

   For each item that it can adjust, PCM_OP_AR_ITEM_ADJUSTMENT checks the events that make up the item to determine whether any of the events are tax exempt. If so, it omits these events from the amount it uses when calculating the adjustment tax reversal.

   As a result of eliminating any nontaxable components of the original item, the adjustment tax is calculated proportionally to the actual taxable amount of the item.

   Note:

   If the item adjustment is being performed as part of a bill adjustment, PCM_OP_AR_BILL_ADJUSTMENT performs this step before calling PCM_OP_AR_ITEM_ADJUSTMENT.

5. Creates an /event/billing/adjustment/item object.

   If the item adjustment is part of a bill adjustment, the event object for each adjusted item is associated with a single, umbrella /item/adjustment object.

6. Examines the flags in the input flist to determine whether the adjustment has any tax implications.

   For information on how PCM_OP_AR_ITEM_ADJUSTMENT performs adjustment taxation, see "Including Taxes in the Adjustment".

7. Calls PCM_OP_BILL_TRANSFER to transfer funds to the A/R bill.

8. If the Due amount after adjustment is 0 and there are no open disputes, PCM_OP_AR_ITEM_ADJUSTMENT sets the PIN_ITEM_STATUS field to CLOSED.

   If an over-adjustment is made on an item, the following occurs:

   • For deferred taxation, the adjustment amount is left unallocated in the adjustment item. If the tax to be adjusted is greater than the cycle tax amount, then the cycle tax item is adjusted for its due amount.

   • For tax now taxation, the excess adjustment amount is left unallocated in the adjustment item.

9. Writes the modified version of the original /item object.

10. Provides feedback on whether the adjustment was successfully created.

    If the adjustment creation failed, it indicates the reason for the failure.

BRM creates a G/L ID for item adjustments. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment".

Fields You Should Include in the Input Flist for Item Adjustments

When performing item adjustments, set these fields in the input flist:

• PIN_FLD_POID for the item to be adjusted. The adjusted amount is applied to the default balance group of the bill unit associated with the item.

• PIN_FLD_AMOUNT for the adjustment amount. The value should be negative when crediting and positive when debiting.

• PIN_FLD_CURRENCY for the balance to adjust.

PCM_OP_AR_ITEM_ADJUSTMENT accepts a variety of other fields used to define tax treatment, adjustment time, adjustment description, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Adjustment".

• For information on reason codes, see "Including Reason Codes in the Adjustment".

Flags for Item Adjustments

Use these flags with PCM_OP_AR_ITEM_ADJUSTMENT:

• If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_ITEM_ADJUSTMENT returns not only the POID, but all the fields in the /event/billing/adjustment/item object as well.

• If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_ITEM_ADJUSTMENT does not change any fields in the database and does not create an /event/billing/adjustment/item object. However, it does provide an adjustment calculation to the caller by returning the fields that would have been used to create the event object and adjustment item.

  Note:

  If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_ITEM_ADJUSTMENT behaves in a standard manner, creating an /event/billing/adjustment/item object to record details of the operation.

• PIN_FLD_FLAGS for the tax treatment:

  • PIN_AR_WITHOUT_TAX flag: The item adjustment is nontaxable.

  • PIN_AR_WITH_TAX flag: The item adjustment is taxable. Tax is reversed on an item-by-item basis.

    Note:

    If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The adjustment is nontaxable if the pin.conf entry is absent.

Customizing Item Adjustments

PCM_OP_BILL_POL_VALID_ADJUSTMENT validates information to make adjustments against an item.

This opcode is called by PCM_OP_AR_ITEM_ADJUSTMENT and PCM_OP_AR_ACCOUNT_ADJUSTMENT.

When you initiate a bill or item adjustment, PCM_OP_AR_ITEM_ADJUSTMENT calls PCM_OP_BILL_POL_VALID_ADJUSTMENT to validate all proposed changes to the fields in the original /item object. This opcode checks the validity of field values before processing. Field values either pass or fail. If one field fails, the entire operation fails.

To customize the adjustment validation criteria, use PCM_OP_BILL_POL_VALID_ADJUSTMENT. 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.

Adjusting Events

To adjust events, BRM uses PCM_OP_AR_EVENT_ADJUSTMENT. This opcode debits or credits a balance for a specified event.

PCM_OP_AR_EVENT_ADJUSTMENT receives a list of events to be adjusted as a batch on the input flist, and returns the adjusted /event/billing/adjustment/event data on the output flist. Events that can be adjusted are stored in the /config/adjustment/event object. There can be multiple events in a given batch, and the events to be adjusted do not need to belong to the same account specified in the PIN_FLD_POID for PCM_OP_AR_EVENT_ADJUSTMENT. Events that can be adjusted are defined in the init_objects.source file and stored in the /config/adjustment/event object.

If you are adjusting pending items, you can ensure proper recording of the adjustment in the General Ledger by using PCM_OP_AR_EVENT_ADJUSTMENT to create a shadow adjustment rather than the standard event adjustment you would normally want to create for a billed item. For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment" and "Categorizing Unbilled Event Adjustments in G/L Reports".

By default, the adjustable events are:

• /event/billing/debit

• /event/billing/product/fee/cycle/cycle_arrear

• /event/session/dialup

• /event/billing/product/fee/purchase

• /event/billing/product/fee/cancel

• /event/billing/product/fee/cycle/cycle_forward_monthly

• /event/billing/product/fee/cycle/cycle_forward_bimonthly

• /event/billing/product/fee/cycle/cycle_forward_quarterly

• /event/billing/product/fee/cycle/cycle_forward_semiannual

• /event/billing/product/fee/cycle/cycle_forward_annual

• /event/billing/product/fee/cycle/cycle_forward_arrear

If you create custom events that you must adjust or if you must adjust additional events, use PCM_OP_WRITE_FLDS to add additional event types to the /config/adjustment/event object.

When PCM_OP_AR_EVENT_ADJUSTMENT receives a batch of events, it:

1. Identifies all events in the batch to be adjusted, and runs the validation checks against those events.

2. If the event has any tax implications, the tax implications must be adjusted.

   For information on how PCM_OP_AR_EVENT_ADJUSTMENT performs adjustment taxation, see "Including Taxes in the Adjustment".

3. Creates a single /item/adjustment object for all the events in the batch for the account.

4. For each event to be adjusted for an account, a new /event/billing/adjustment/event object containing the amount to be adjusted is created.

   The /event/billing/adjustment/event object has the PIN_FLD_ITEM_OBJ pointing to the adjustment item created in step 3.

5. After the adjustment item and the /event/billing/adjustment/event object are created, the amount is transferred from the adjustment item to the original item where the adjusted event belongs.

   The original item may or may not be open. If the transfer happens to a closed item, the closed item is reopened automatically.

   Note:

   After the entire Due amount from the adjustment item is transferred to other items, the adjustment item is closed.

BRM creates a G/L ID for event adjustments.

For information on adjustments and G/L IDs, see "Assigning G/L IDs for an Adjustment" and "Categorizing Unbilled Event Adjustments in G/L Reports".

Fields You Should Include in the Input Flist for Event Adjustments

When performing adjustment, set these fields in the PCM_OP_AR_EVENT_ADJUSTMENT input flist:

• PIN_FLD_POID for each of the events to be adjusted. The adjusted amount is applied to the default balance group of the bill unit associated with the /item object that the event belongs to.

• PIN_FLD_AMOUNT or PIN_FLD_PERCENT for the adjustment amount. The value supplied for this field should be positive for adjustments that credit the event and negative for adjustments that debit the event. If you omit both of these fields, BRM adjusts the entire amount for each event.

• PIN_FLD_RESOURCE_ID for the balance to adjust.

PCM_OP_AR_EVENT_ADJUSTMENT accepts a variety of other fields used to define tax treatment, adjustment time, adjustment description, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Adjustment".

• For information on reason codes, see "Including Reason Codes in the Adjustment".

Flags for Event Adjustments

Use these flags with PCM_OP_AR_EVENT_ADJUSTMENT:

• If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_EVENT_ADJUSTMENT returns not only the POID, but all the fields in the /event/billing/adjustment/event object as well.

• If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_EVENT_ADJUSTMENT does not change any fields in the database and does not create an /event/billing/adjustment/event object. However, it does provide an adjustment calculation to the caller by returning the fields that would have been used to create the event object and adjustment item.

  Note:

  If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_EVENT_ADJUSTMENT behaves in a standard manner, creating an /event/billing/adjustment/event object to record details of the operation.

• If the PIN_ADJ_NO_TAX flag is set, the event adjustment is nontaxable. If this flag is not set, the adjustment is taxable.

• If the PIN_ADJ_TAX_ONLY flag is set, only the tax on the original event is adjusted; not the event itself.

  Note:

  Do not set this flag for adjustments against unbilled events that use deferred taxation.

• If the PIN_EVENT_ADJ_BATCH is set, the adjustment amount is distributed among the events in the batch on a first-come-first-serve basis until the adjustment amount is consumed.

• If the PIN_EVENT_ADJ_EVENT is set, the adjustment amount is applied individually to each of the events in the batch.

• If the PIN_EVENT_ADJ_FOR_RERATE flag is set, the adjustment is the result of rerating the original event.

• If the PIN_AR_RECORD_SHADOW_ADJUSTMENT_EVENT is set, BRM creates a shadow adjustment instead of an /event/billing/adjustment/event object. This flag should be set when the event being adjusted is pending and results in the adjustment being recorded as unbilled in the General Ledger.

Categorizing Unbilled Event Adjustments in G/L Reports

To report adjustments as unbilled in the G/L, BRM uses PCM_OP_AR_EVENT_ADJUSTMENT to create shadow event objects instead of adjustment event objects. A shadow event object is a new version of the original event object. It is identical to the original event object except for a new creation timestamp and a new balance impact resulting from the event adjustment.

To create shadow adjustments, set the value of the PIN_FLD_FLAGS field at the top level to 1 (PIN_AR_RECORD_SHADOW_ADJUSTMENT_EVENT) on the PCM_OP_AR_EVENT_ADJUSTMENT input flist. The shadow object is created only if the original event to be adjusted has not been billed or posted to a G/L report.

Note:

When the PIN_FLD_FLAGS field is not present in the input flist, BRM creates an /event/billing/adjustment/event object.

Unlike standard event adjustments, when creating shadow events, only one event should be present on the input flist.

As with standard event adjustments, you can adjust both currency and noncurrency balances. Regardless of whether PCM_OP_AR_EVENT_ADJUSTMENT is performing a standard or shadow adjustment, it adjusts only the balances specified in the input flist; it does not automatically adjust all balances for an event.

For information on the shadow adjustment flags, see "Flags for Event Adjustments".

Including Taxes in the Adjustment

You can configure tax calculation on adjustments, as described in "Calculating Taxes for Accounts Receivable Actions" in BRM Calculating Taxes. You can specify an optional tax treatment for adjustments by using flags in the PCM_OP_AR_EVENT_ADJUSTMENT input flist. See the following topics:

• Flags for Account, Subscription Service, and Member Service Adjustments

• Flags for Bill Adjustments

• Flags for Item Adjustments

• Flags for Event Adjustments

Tax Processing for Account Adjustments

If the PCM_OP_AR_EVENT_ADJUSTMENT input flist flags the adjustment as taxable or the pin.conf file specifies that BRM tax all adjustments, PCM_OP_AR_EVENT_ADJUSTMENT obtains tax information from a configuration file read into BRM when Connection Manager starts.

PCM_OP_AR_ACCOUNT_ADJUSTMENT uses this information as follows:

• If adjustment tax method is tax now, it uses this information to calculate the tax and apply it immediately.

• If adjustment tax method is tax deferred, it enriches the input flist with this information, and then passes it to PCM_OP_ACT_USAGE for deferred tax calculation.

Tax Processing for Bill and Item Level Adjustments

If the PCM_OP_AR_EVENT_ADJUSTMENT input flist flags the adjustment as taxable or the pin.conf file specifies that BRM tax all adjustments, PCM_OP_AR_EVENT_ADJUSTMENT obtains tax information from a configuration file read into BRM when Connection Manager starts.

PCM_OP_AR_ITEM_ADJUSTMENT and PCM_OP_AR_BILL_ADJUSTMENT perform one of two steps:

• If adjustment tax method is tax now, it uses information from the event associated with the original bill item to calculate taxes and apply the amount immediately with the adjustment amount.

• If adjustment tax method is tax deferred, The taxes are contained in the tax item. In such cases, PCM_OP_AR_ITEM_ADJUSTMENT does the following to handle the taxes:

  • Calls PCM_OP_BILL_TAX_EVENT to calculate the tax amount.

  • Compares the calculated tax with the due amount of the tax item to determine the amount to reverse.

  • Creates the /event/billing/adjustment/tax_event event to contain the tax amount.

  • Transfers the calculated tax amount to the original tax item.

The due amount is reduced by the adjustment amount.

Validations are made to ensure that an item's net amount and cycle tax amount are not over-adjusted during an adjustment. If the adjustment amount is greater than the item's due amount, the excess amount is left unallocated in the adjustment item and must be allocated either manually or when the next payment is applied on the account. The tax amount is always adjusted to the maximum amount due in the tax item.

Note:

The adjustment tax method (tax now or tax deferred) is determined based on whether the events associated with the item are taxed at event time or at bill time.

Tax Processing for Event Adjustments

If the PCM_OP_AR_EVENT_ADJUSTMENT input flist flags the adjustment as taxable, PCM_OP_AR_EVENT_ADJUSTMENT performs one of two steps:

• If adjustment tax method is tax now, the opcode uses information from the adjusted event to calculate the tax and apply it immediately.

• If adjustment tax method is tax deferred, the opcode uses information from the /event/billing/cycle/tax object to calculate the adjustment tax. When it has calculated the tax, it creates the /event/billing/adjustment/tax_event event.

  Note:

  If the adjustment is created in the same billing cycle as the adjusted item, the original item will not have been taxed yet. In this case, there is no need to create the /event/billing/adjustment/tax_event event because the adjustment precedes initial tax calculation for the original item.

Including Reason Codes in the Adjustment

Reason codes explain why an adjustment is being granted. In typical implementations, the BRM client application provides a selectable set of reasons appropriate to the event type. You choose a reason that matches the situation or, in some cases, compose a new reason. The client application populates the input flist for the opcode with this information, and BRM records the reason in the adjustment event object (for example, /event/billing/adjustment/item or /event/billing/adjustment/event). The flist fields that provide reason code information are PIN_FLD_REASON_ID and PIN_FLD_REASON_DOMAIN_ID. These fields are optional.

For event adjustments, you can filter a batch of adjustments based on the reason code supplied in the input flist. If the PCM_OP_AR_EVENT_ADJUSTMENT input flist includes a reason code and domain, PCM_OP_AR_EVENT_ADJUSTMENT performs a validation check of the reason code. It does so by comparing the reason code in its input flist against a stored global flist created by reading reason code configuration information from the /config/reason_code_scope object at Connection Manager (CM) start time. The global flist serves as a filter that indicates all the reason codes that are valid for a given event and service type.

Reason code validation produces these results:

• For all instances where the reason code is valid for the event and associated service, the opcode proceeds with the adjustment.

• For each instance where the reason code is not valid, the opcode indicates the failure in the PIN_FLD_RESULTS field for the output flist and describes the problem in the PIN_FLD_DESCR field.

For general information about reason codes, see "String Manipulation Functions" in BRM Developer's Reference.

Assigning G/L IDs for an Adjustment

The G/L ID for an adjustment event is assigned like other pre-rated events in the BRM system. PCM_OP_ACT_POL_SPEC_GLID assigns the G/L ID for the adjustment. Based on the event type, this opcode retrieves a G/L ID from the /config/map_glid object. The PIN_FLD_GL_ID field in the /event/billing/adjustment/event object points to the same G/L ID as the original event, ensuring that both the original event and the adjustment are correctly recorded in the general ledger.

Applying Debits and Credits

To apply debits and credits to noncurrency balances, BRM uses PCM_OP_BILL_DEBIT.

PCM_OP_BILL_DEBIT debits sub-balances for a specific /balance_group object associated with an account.

There are three ways to use PCM_OP_BILL_DEBIT:

• Pass in the POID of an account to impact that account's default /balance_group object.

• Pass in the POID of a specific balance group to impact that /balance_group object.

• For either the account or a balance group, pass in a specific sub-balance to impact that sub-balance.

The PIN_FLD_DEBIT array on the input object contains the amount of the balance to debit. The amount is a signed value, so the result can be a debit (positive value) or a credit (negative value) to the balance.

The PIN_FLD_SUB_BALANCES array contains a specific element ID, or uses PIN_ELEMID_ASSIGN to identify or create the specific sub-balance to receive the debit.

You specify validity information using the VALID_FROM and VALID_TO fields on the PIN_FLD_SUB_BALANCES array to credit or debit a sub-balance for specific dates. These are usually used with the PIN_ELEMID_ASSIGN field to specify a sub-balance to credit or debit.

Note:

If you are performing a noncurrency account or service adjustment, PCM_OP_BILL_DEBIT determines whether the sub-balance being adjusted is still open. Open sub-balances are those whose VALID_TO date has not yet been reached. If the sub-balance is no longer open, the opcode creates a new sub-balance for the adjustment. This sub-balance has the same validity period as the sub-balance you were trying to adjust.

If validity information is not specified, PCM_OP_BILL_DEBIT updates the "most valid" sub-balance first, and then continues through the rest of the sub-balances until the debit amount is used up. If no other sub-balances are left, or if there were no valid sub-balances to begin with, PCM_OP_BILL_DEBIT it creates a new sub-balance to hold the debit amount.

Note:

• You can change the order in which PCM_OP_BILL_DEBIT updates sub-balances.

• PCM_OP_BILL_DEBIT opens a local transaction.

Flags for Applying Debits and Credits

• If the PCM_OPFLG_READ_RESULT flag is set, all the fields in the event object are returned and not just the POID.

• If the PCM_OPFLG_CALC_ONLY flag is set, no fields in the database are changed and the event object is not actually created. The fields that would have been used to create the event object are returned to the caller.

• If the PCM_OPFLG_CALC_ONLY flag is not set, the /event/billing/debit object is created to record the details of the operation.

Performing Disputes and Settlements

You use Billing Care or Customer Center to manage disputes and settlements. BRM uses the following opcodes to perform and customize disputes and settlements:

• PCM_OP_AR_BILL_DISPUTE

  See "Disputing Bills".

• PCM_OP_AR_BILL_SETTLEMENT

  See "Settling Disputed Bills".

• PCM_OP_AR_ITEM_DISPUTE

  See "Disputing Items".

• PCM_OP_AR_ITEM_SETTLEMENT

  See "Settling Disputed Items".

• PCM_OP_BILL_POL_VALID_DISPUTE

  See "Customizing Item Disputes".

• PCM_OP_AR_EVENT_DISPUTE

  See "Disputing Events".

• PCM_OP_AR_EVENT_SETTLEMENT

  See "Settling Disputed Events".

• PCM_OP_ACT_POL_SPEC_GLID

  See "Assigning G/L IDs for a Dispute or Settlement".

Disputing Bills

To open a dispute at the bill level, BRM uses PCM_OP_AR_BILL_DISPUTE. This opcode debits or credits a currency balance for the specified /bill object. You can open a bill dispute with or without tax. This opcode is called by BRM client applications to dispute the items associated with the specified bill. For information on how PCM_OP_AR_BILL_DISPUTE performs dispute taxation, see "Including Taxes in the Dispute or Settlement".

Note:

PCM_OP_AR_BILL_DISPUTE does not check to determine whether the item you are disputing is billed yet. However, using PCM_OP_AR_BILL_DISPUTE to dispute pending items is not recommended. If you try to dispute pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.

Note:

You cannot move a balance group to a new bill unit if there are any disputes against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.

PCM_OP_AR_BILL_DISPUTE does not create disputes when:

• The specified bill is not an A/R bill (for example, a bill from a nonpaying bill unit).

• The amount of the dispute exceeds the total amount of the bill against which the dispute applies. For example, if the bill due is $5, you cannot open a credit dispute for $6. Similarly, if the bill due -$5, you cannot open a debit dispute for $6.

Bill disputes can apply to the entire bill or to specific bill items. When PCM_OP_AR_BILL_DISPUTE receives an input flist, it creates a single, umbrella dispute item for all bill items covered by the dispute, as follows:

• If the input flist specifies individual bill items, the dispute item is associated with each of these bill items. Further, the dispute amount for each bill item is equivalent to the entire due for that item unless otherwise specified in the input flist.

• If the flist does not specify any bill items, all bill items are eligible for dispute. PCM_OP_AR_BILL_DISPUTE opens disputes for as many bill items as it can before it consumes the dispute amount. In this case, the dispute item will cover only those bill items that the opcode was able to fully or partially dispute before using up the dispute amount. If the input flist does not supply a dispute amount, BRM uses amounts equivalent to the entire due for each dispute item.

In either case, PCM_OP_AR_BILL_DISPUTE passes the POID of the dispute item and the appropriate dispute amount to PCM_OP_AR_ITEM_DISPUTE, which opens the dispute for each of the associated bill items and creates the dispute events. An /event/billing/dispute/item object is created for each disputed item in the bill, recording the balance impact. The bill dispute event balance impact is applied to the default balance group of the bill unit associated with the bill. For details on how PCM_OP_AR_ITEM_DISPUTE works, see "Disputing Items".

Before passing the dispute item and amount to PCM_OP_AR_ITEM_DISPUTE, PCM_OP_AR_BILL_DISPUTE determines whether the dispute has tax implications. If so, it checks the original /item object to determine the taxable portion of the item:

• If the item object stores only an amount generated by a tax event, the opcode omits it from tax calculation.

• If the item object stores only an amount generated by a usage event, the opcode calculates taxes for the amount.

• If the item object stores an amount generated by a tax event and an amount generated by a usage event, the opcode calculates the dispute tax reversal only for the usage amount and not the tax amount.

For each item that can be disputed, PCM_OP_AR_BILL_DISPUTE checks the events that make up the item to determine whether any of the events are tax exempt. If so, it omits these events from the amount it uses when calculating the dispute tax reversal. As a result of eliminating any nontaxable components of the original item, the dispute tax is calculated proportionally to the actual taxable amount of the item.

If the dispute fails, PCM_OP_AR_BILL_DISPUTE returns the reason in the PIN_FLD_DESCR field of the PIN_FLD_RESULTS array on the output flist.

BRM creates a G/L ID for every bill dispute. For information on disputes and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".

Fields You Should Include in the Input Flist for Bill Disputes

Set these fields in the PCM_OP_AR_BILL_DISPUTE input flist when creating bill disputes:

• PIN_FLD_POID for the bill under dispute. You obtain this from the /bill object that the CSR identifies through the client application. The disputed amount is applied to the default balance group of the bill unit associated with the bill.

• PIN_FLD_POID for the item under dispute. This field is only required to dispute a particular set of bill items in the bill.

• PIN_FLD_AMOUNT for the dispute amount. The value supplied for this field should be negative when crediting and positive when debiting. This field is optional.

  You can provide the PIN_FLD_AMOUNT field for the bill itself or, if the dispute is against an array of bill items, for the individual bill items. If PIN_FLD_AMOUNT is NULL for a dispute, BRM assumes that the dispute is for the entire amount of the bill or the individual bill items, as appropriate. If you are performing a dispute that credits the bill, the absolute value of PIN_FLD_AMOUNT must be greater than 0 and less than the total bill amount and its sign should be negative.

• PIN_FLD_CURRENCY for the balance to dispute.

PCM_OP_AR_BILL_DISPUTE accepts a variety of other fields used to define tax treatment, dispute time, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Dispute or Settlement".

• For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".

Flags for Bill Disputes

Use the following flags with PCM_OP_AR_BILL_DISPUTE:

• If the PIN_AR_WITHOUT_TAX flag is set, the dispute is nontaxable.

• If the PIN_AR_WITH_TAX flag is set, the dispute is taxable. Tax is reversed on an item-by-item basis.

  Note:

  If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The dispute is nontaxable if the pin.conf entry is absent.

For information on flags that indirectly affect PCM_OP_AR_BILL_DISPUTE, see "Flags for Item Disputes".

Settling Disputed Bills

To settle a dispute at the bill level, BRM uses PCM_OP_AR_BILL_SETTLEMENT. This opcode debits or credits a currency balance for the specified /bill object. You can create a bill settlement with or without tax. This opcode is called by BRM client applications to settle the disputed items associated with the specified bill.

For information on how PCM_OP_AR_BILL_SETTLEMENT performs settlement taxation, see "Including Taxes in the Dispute or Settlement".

Note:

PCM_OP_AR_BILL_SETTLEMENT does not check to determine whether the item you are settling is billed yet. However, using this opcode to settle pending items is not recommended. If you try to settle pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.

Note:

You cannot move a balance group to a new bill unit if there are any disputes settled against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.

PCM_OP_AR_BILL_SETTLEMENT does not create settlements in these cases:

• The specified bill is not an A/R bill (for example, a bill from a nonpaying bill unit).

• The amount of the settlement exceeds the amount of the associated dispute.

Bill settlements can apply to the entire bill or to specific bill items. When PCM_OP_AR_BILL_SETTLEMENT receives an input flist, it creates a single, umbrella settlement item for all bill items covered by the settlement, as follows:

• If the input flist specifies individual bill items, the settlement item is associated with each of these bill items. The settlement amount for each bill item must be specified in the input flist.

• If the flist does not specify any bill items, all disputed items in the bill are eligible for settlement. PCM_OP_AR_BILL_SETTLEMENT opens settlements for as many disputed items as it can before it consumes the settlement amount. After it uses up the settlement amount, it continues to open settlements for the remaining disputed items, but with a settlement amount of 0.

For each bill item it must settle, PCM_OP_AR_BILL_SETTLEMENT passes the POID of the settlement item and the appropriate settlement amount to PCM_OP_AR_ITEM_SETTLEMENT, which creates a settlement event for each bill item it receives. An /event/billing/settlement/item object is created for each settled item in the bill, recording the balance impact. For details on how PCM_OP_AR_ITEM_SETTLEMENT works, see "Settling Disputed Items".

If the settlement fails, PCM_OP_AR_BILL_SETTLEMENT returns the reason in the PIN_FLD_DESCR field of the PIN_FLD_RESULTS array on the output flist.

BRM creates a G/L ID for every bill settlement. For information on settlements and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".

Fields You Should Include in the Input Flist

Set these fields in the PCM_OP_AR_BILL_SETTLEMENT input flist when creating bill settlements:

• PIN_FLD_POID for the bill under dispute or settlement. You obtain this from the /bill object that the CSR identifies through the BRM client application. The settled amount is applied to the default balance group of the bill unit associated with the bill.

• PIN_FLD_POID for the item to be settled. This field is only required to settle a particular set of bill items in the bill.

• PIN_FLD_AMOUNT for the settlement amount. The value supplied for this field should be negative when crediting and positive when debiting.

  You can provide the PIN_FLD_AMOUNT field for the bill itself or, if the settlement is against an array of bill items, for the individual bill items. If you supply a value for PIN_FLD_AMOUNT, it must be less than the dispute amount.

PCM_OP_AR_BILL_SETTLEMENT accepts a variety of other fields used to define tax treatment, settlement time, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Dispute or Settlement".

• For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".

Flags for Bill Settlements

Use this flags with PCM_OP_AR_BILL_SETTLEMENT:

• If the PIN_AR_WITHOUT_TAX flag is set, the settlement is nontaxable. This is the default.

• If the PIN_AR_WITH_TAX flag is set, the settlement is taxable. Tax is reversed on an item-by-item basis.

  Note:

  If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The settlement is nontaxable if the pin.conf entry is absent.

For information on flags that indirectly affect PCM_OP_AR_BILL_SETTLEMENT, see "Flags for Item Settlements".

Disputing Items

To open an item dispute, BRM uses PCM_OP_AR_ITEM_DISPUTE. This opcode debits or credits a currency balance for a particular bill item. This opcode is also called by PCM_OP_AR_BILL_DISPUTE to dispute items in a bill.

Note:

PCM_OP_AR_ITEM_DISPUTE does not check to determine whether the item you are disputing is billed yet. However, using this opcode to dispute pending items is not recommended. If you try to dispute pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.

Note:

You cannot move a balance group to a new bill unit if there are any disputes against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.

PCM_OP_AR_ITEM_DISPUTE does the following:

1. Reads the original /item object and prepares the changes to reflect the balance impact of the dispute.

   For credit disputes, these changes reduce the Due amount (PIN_FLD_DUE) for the item. For debit disputes, the opposite occurs.

2. Calls PCM_OP_BILL_POL_VALID_DISPUTE to validate the changes.

   You can customize the validation criteria for PCM_OP_BILL_POL_VALID_SETTLEMENT. For information on customizing the opcode, see "Customizing Item Disputes".

3. Checks to see if the PIN_FLD_ITEM_OBJ field is present in the input flist.

   If so, PCM_OP_AR_ITEM_DISPUTE checks the contents of the field to determine:

   • Whether the field contains a POID, indicating that the opcode is being called by PCM_OP_AR_BILL_DISPUTE to complete a bill dispute.

     This POID identifies the /item/dispute object that PCM_OP_AR_BILL_DISPUTE created to store information on the bill dispute. This is the /item/dispute object that PCM_OP_AR_ITEM_DISPUTE will associate with each of the dispute events it creates for the bill adjustment.

   • Whether the field is NULL, indicating that PCM_OP_AR_ITEM_DISPUTE is being called directly from the client application to perform an item dispute. In this case, PCM_OP_AR_ITEM_DISPUTE will create its own /item/dispute object. This object is exclusive to the individual item being disputed.

4. If the dispute has tax implications and the opcode is not being called as part of a bill dispute, checks the original /item object to determine the taxable portion of the item:

   • If the item object stores only an amount generated by a tax event, the opcode omits it from tax calculation.

   • If the item object stores only an amount generated by a usage event, the opcode calculates taxes for the amount.

   • If the item object stores an amount generated by a tax event and an amount generated by a usage event, the opcode calculates the dispute tax reversal only for the usage amount and not the tax amount.

   For each item that it can dispute, PCM_OP_AR_ITEM_DISPUTE checks the events that make up the item to determine whether any of the events are tax exempt. If so, it omits these events from the amount it uses when calculating the dispute tax reversal.

   As a result of eliminating any nontaxable components of the original item, the dispute tax is calculated proportionally to the actual taxable amount of the item.

   Note:

   If the item dispute is being performed as part of a bill dispute, PCM_OP_AR_BILL_DISPUTE performs this step before calling PCM_OP_AR_ITEM_DISPUTE.

5. Creates an /event/billing/dispute/item object.

   The item dispute event balance impact is applied to the default balance group of the bill unit associated with the item. If the item dispute is part of a bill dispute, the event object for each disputed item is associated with a single, umbrella /item/dispute object.

6. Examines the flags in the input flist to determine whether the dispute has any tax implications.

   For information on how the opcode performs dispute taxation, see "Including Taxes in the Dispute or Settlement".

7. Calls PCM_OP_BILL_TRANSFER to transfer funds to the A/R bill.

8. Writes the modified version of the original /item object.

9. Provides feedback on whether the dispute was successfully created.

   If the dispute creation failed, it indicates the reason for the failure.

BRM creates a G/L ID for item disputes. For information on disputes and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".

Fields You Should Include in the Input Flist

Set these fields in the PCM_OP_AR_ITEM_DISPUTE input flist when creating item disputes:

• PIN_FLD_POID for the item under dispute. The disputed amount is applied to the default balance group of the bill unit associated with the item.

• PIN_FLD_AMOUNT for the dispute amount. The value for this field should be negative when crediting and positive when debiting.

• PIN_FLD_CURRENCY for the balance to dispute.

PCM_OP_AR_ITEM_DISPUTE accepts a variety of other fields used to define tax treatment, dispute time, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Dispute or Settlement".

• For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".

Flags for Item Disputes

Use the following flags with PCM_OP_AR_ITEM_DISPUTE:

• If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_ITEM_DISPUTE returns not only the POID, but all the fields in the /event/billing/dispute/item object as well.

• If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_ITEM_DISPUTE does not change any fields in the database and does not create an /event/billing/dispute/item object. However, it does provide a dispute calculation to the caller by returning the fields that would have been used to create the event object and dispute item.

  Note:

  If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_ITEM_DISPUTE behaves in a standard manner, creating an /event/billing/dispute/item object to record details of the operation.

• If the PIN_AR_WITHOUT_TAX flag is set, the item dispute is nontaxable.

• If the PIN_AR_WITH_TAX flag is set, the item dispute is taxable. Tax is reversed on an item-by-item basis.

  Note:

  If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The dispute is nontaxable if the pin.conf entry is absent.

Customizing Item Disputes

When you initiate a bill or item dispute, PCM_OP_AR_ITEM_DISPUTE calls PCM_OP_BILL_POL_VALID_DISPUTE to validate all proposed changes to the fields in the original /item object. PCM_OP_BILL_POL_VALID_DISPUTE checks the validity of field values before processing. Field values either pass or fail. If one field fails, the entire operation fails.

You can customize the validation criteria for PCM_OP_BILL_POL_VALID_SETTLEMENT by modifying the policy source file. 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. PCM_OP_BILL_POL_VALID_SETTLEMENT is called by PCM_OP_AR_ITEM_SETTLEMENT.

Settling Disputed Items

To settle a dispute at the item level, BRM uses PCM_OP_AR_ITEM_SETTLEMENT. This opcode debits or credits the currency balance of a particular item to settle a dispute against that item. PCM_OP_AR_ITEM_SETTLEMENT is also called by PCM_OP_AR_BILL_SETTLEMENT to settle the dispute items associated with a bill.

Note:

PCM_OP_AR_ITEM_SETTLEMENT does not check to determine whether the item you are settling is billed yet. However, using this opcode to settle pending items is not recommended. If you try to settle pending items, you may introduce problems if you move the balance group to a new bill unit and there may be issues with G/L reporting.

Note:

You cannot move a balance group to a new bill unit if there are any disputes settled against pending bill items. Otherwise, there may be issues with G/L reporting. You can move the balance group when the items are billed.

PCM_OP_AR_ITEM_SETTLEMENT does the following:

1. Reads the original /item object and prepares the changes to reflect the balance impact based on the settlement amount.

   Settlement amounts have components:

   • Granted amount: The portion of the disputed amount granted by the settlement. This is the amount in the PIN_FLD_DISPUTED field of the PCM_OP_AR_ITEM_SETTLEMENT input flist.

   • Denied amount: The portion of the disputed amount that was denied by the settlement. This is the original dispute amount minus the granted amount. Settlements always work with the denied amount.

   For credit settlements, PCM_OP_AR_ITEM_SETTLEMENT makes the following changes to the balance impact:

   • Increases the Due amount (PIN_FLD_DUE) for the item by adding the amount denied during the settlement, if any.

   • For item disputes, it impacts the Adjusted amount (PIN_FLD_ADJUSTED) of the bill item by adding the settled amount and zeroing out the disputed amount (PIN_FLD_DISPUTED). Any dispute amount due to event disputes is not touched.

   For debit settlements, the opposite occurs.

2. Calls PCM_OP_BILL_POL_ITEM_VALID_SETTLEMENT to validate the changes.

   You can customize the validation criteria for PCM_OP_BILL_POL_ITEM_VALID_SETTLEMENT.

   For information on customizing the opcode, see "Customizing Item Settlements".

3. Checks to see if the PIN_FLD_ITEM_OBJ field is present in the input flist.

   If so, PCM_OP_AR_ITEM_SETTLEMENT checks the contents of the field to determine:

   • Whether the field contains a POID, indicating that PCM_OP_AR_ITEM_SETTLEMENT is being called by PCM_OP_AR_BILL_SETTLEMENT to complete a bill settlement.

     This POID identifies the /item/settlement object that PCM_OP_AR_BILL_SETTLEMENT created to store information on the bill settlement. This is the /item/settlement object that PCM_OP_AR_ITEM_SETTLEMENT associates with each of the settlement events it creates for the bill settlement.

   • Whether the field is NULL, indicating that PCM_OP_AR_ITEM_SETTLEMENT is being called directly from the client application to perform an item settlement. In this case, PCM_OP_AR_ITEM_SETTLEMENT creates its own /item/settlement object. This object is exclusive to the individual item being settled.

4. Creates an /event/billing/settlement/item object.

   If the item settlement is part of a bill settlement, the event object for each settled item is associated with a single, umbrella /item/settlement object.

5. Examines the flags in the input flist to determine whether the dispute has any tax implications.

   For information on how PCM_OP_AR_ITEM_SETTLEMENT performs settlement taxation, see "Including Taxes in the Dispute or Settlement".

6. Calls PCM_OP_BILL_TRANSFER to transfer funds to the A/R bill.

   Before transferring the funds, PCM_OP_AR_ITEM_SETTLEMENT filters disputed events that were created by event disputes and subtracts the amount associated with these events from the PIN_FLD_DISPUTED of the disputed item. What remains is the amount associated solely with the item dispute, with no contribution from event disputes.

7. If the Due amount after settlement is 0 and there are no other open disputes, PCM_OP_AR_ITEM_SETTLEMENT sets the PIN_ITEM_STATUS field to CLOSED.

8. Writes the modified version of the original /item object.

9. Provides feedback on whether the settlement was successfully created.

   If the settlement creation failed, the opcode indicates the reason for the failure.

BRM creates a G/L ID for item settlements. For information on settlements and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".

Fields You Should Include in the Input Flist for Item Settlements

Set these fields in the PCM_OP_AR_ITEM_SETTLEMENT input flist when creating item settlements:

• PIN_FLD_POID for the item to be settled. The settled amount is applied to the default balance group of the bill unit associated with the item.

• PIN_FLD_AMOUNT for the settlement amount. The value for this field should be negative when crediting and positive when debiting.

• PIN_FLD_CURRENCY for the balance to settle.

PCM_OP_AR_ITEM_SETTLEMENT accepts a variety of other fields used to define tax treatment, settlement time, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Dispute or Settlement".

• For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".

Flags for Item Settlements

Use these flags with PCM_OP_AR_ITEM_SETTLEMENT:

• If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_ITEM_SETTLEMENT returns not only the POID, but all the fields in the /event/billing/settlement/item object as well.

• If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_ITEM_SETTLEMENT does not change any fields in the database and does not create an /event/billing/settlement/item object. However, it does provide a settlement calculation to the caller by returning the fields that would have been used to create the event object and settlement item.

  Note:

  If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_ITEM_SETTLEMENT behaves in a standard manner, creating an /event/billing/settlement/item object to record details of the operation.

• If the PIN_AR_WITHOUT_TAX flag is set, the item settlement is nontaxable.

• If the PIN_AR_WITH_TAX flag is set, the item settlement is taxable. Tax is reversed on an item-by-item basis.

  Note:

  If the tax flag is not set, BRM refers to the pin.conf entry, fm_ar tax_reversal_with_tax, to determine the default tax reversal behavior. The settlement is nontaxable if the pin.conf entry is absent.

Customizing Item Settlements

When you initiate a bill or item settlement, PCM_OP_AR_ITEM_SETTLEMENT calls PCM_OP_BILL_POL_VALID_DISPUTE to validate all proposed changes to the fields in the original /item object. This opcode checks the validity of field values before processing. Field values either pass or fail. If one field fails, the entire operation fails.

You can customize the validation criteria for PCM_OP_BILL_POL_VALID_SETTLEMENT by modifying the policy source file. 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.

Disputing Events

To open a dispute at the event level, BRM uses PCM_OP_AR_EVENT_DISPUTE.

This opcode receives a batch of events on the input flist, and returns the disputed /event/billing/dispute/event data on the output flist. There can be multiple events in a given batch, and the events to be disputed do not need to belong to the account specified in the PIN_FLD_POID for PCM_OP_AR_EVENT_DISPUTE. The input flist can optionally include a reason code domain and descriptive string that indicates why the dispute is being made.

Caution:

PCM_OP_AR_EVENT_DISPUTE does not verify whether there are other disputes against the events it processes. Multiple disputes for the same event can cause conflicts in BRM, so make sure your client application prevents the CSR from logging more than one dispute for an event.

When it receives a batch of events, PCM_OP_AR_EVENT_DISPUTE performs these tasks:

1. It reads the batch, identifying all events to be disputed

2. It examines the flags in the input flist to determine whether the dispute has any tax implications.

   For information on how the opcode performs dispute taxation, see "Including Taxes in the Dispute or Settlement".

3. It creates a single dispute item, /item/dispute, for all the disputed events in the batch.

4. For each event to be disputed, it creates a new /event/billing/dispute/event object containing the dispute amount.

   The PIN_FLD_ITEM_OBJ field of /event/billing/dispute/event points to the dispute item created in step 3.

5. After the /item/dispute and /event/billing/dispute/event objects are created, it calls PCM_OP_BILL_ITEM_TRANSFER to transfer the dispute amount from the dispute item to the original item that owns the disputed event.

   Note:

   If the opcode transfer targets a closed item, that item is reopened automatically.

6. It creates a notification event (/event/billing/dispute/notify).

   If event notification is enabled in your system, this triggers the reservation of the disputed balances until the dispute is settled.

7. When it finishes, it provides feedback on whether the dispute was successfully created or, if dispute creation failed, the reason for the failure.

BRM creates a G/L ID for event disputes. For information on disputes and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".

Fields You Should Include in the Input Flist for Event Disputes

Set these fields in the PCM_OP_AR_EVENT_DISPUTE input flist when creating event disputes:

• PIN_FLD_POID for each of the events to be disputed. These fields form a PIN_FLD_EVENTS array. The disputed amount is applied to the default balance group of the bill unit associated with the /item object that the event belongs to.

• PIN_FLD_AMOUNT for the dispute amount. The value supplied for this field should be positive for adjustments that credit the event and negative for adjustments that debit the event.

  You can specify the dispute amount through either PIN_FLD_AMOUNT or PIN_FLD_PERCENT. If you omit both of these fields, BRM disputes the entire amount for each event.

• PIN_FLD_RESOURCE_ID for the disputed balance.

PCM_OP_AR_EVENT_DISPUTE accepts a variety of other fields used to define tax treatment, dispute time, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Dispute or Settlement".

• For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".

Flags for Event Disputes

Use the following flags with PCM_OP_AR_EVENT_DISPUTE:

• If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_EVENT_DISPUTE returns not only the POID, but all the fields in the /event/billing/dispute/event object as well.

• If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_EVENT_DISPUTE does not change any fields in the database and does not create an /event/billing/dispute/event object. However, it does provide a dispute calculation to the caller by returning the fields that would have been used to create the event object and dispute item.

  Note:

  If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_EVENT_DISPUTE behaves in a standard manner, creating an /event/billing/dispute/event object to record details of the operation.

• If the PIN_ADJ_NO_TAX flag is set, the event dispute is nontaxable. If this flag is not set, the dispute is taxable.

• If the PIN_ADJ_TAX_ONLY flag is set, only the tax on the original event is disputed; not the event itself.

  Note:

  Do not set this flag for disputes against unbilled events that use deferred taxation.

• If the PIN_EVENT_ADJUST_BATCH is set, the dispute amount is distributed among the events in the batch on a first-come-first-serve basis until the dispute amount is consumed.

• If the PIN_EVENT_ADJUST_EVENT is set, the dispute amount is applied individually to each of the events in the batch.

Settling Disputed Events

To settle a dispute at the event level, BRM uses PCM_OP_AR_EVENT_SETTLEMENT. This opcode debits or credits the balances of an event to settle a dispute against that event.

Note:

You cannot settle an event more than once. If PCM_OP_AR_EVENT_SETTLEMENT settles an event that has more than one open dispute, it settles all the disputes for that event.

PCM_OP_AR_EVENT_SETTLEMENT receives dispute item POID in the input flists and retrieves the associated dispute events. It returns the settled /event/billing/settlement/event data on the output flist. The input flist can optionally include a reason code domain and descriptive string that indicates why the settlement is being made.

When it receives a batch of events, PCM_OP_AR_EVENT_SETTLEMENT performs these tasks:

1. It verifies that, for backdated settlements, the settlement date falls after the dispute date.

2. It examines the flags in the input flist to determine whether the settlement has any tax implications.

   For information on how the opcode performs dispute taxation, see "Including Taxes in the Dispute or Settlement".

3. It searches for all dispute events whose PIN_FLD_ITEM_OBJ field points to the dispute item and creates a single settlement item, /item/settlement, for all these events.

4. For each dispute event to be settled, it creates a new /event/billing/settlement/event object containing the denied amount.

   The PIN_FLD_SESSION_OBJ field of /event/billing/settlement/event points to the corresponding dispute event.

5. After the /item/settlement and /event/billing/settlement/event objects are created, it calls PCM_OP_BILL_ITEM_TRANSFER to transfer the denied amount from the settlement item to the original item against which the settlement was filed and recalculate the Due of the original item accordingly.

   Note:

   If PCM_OP_AR_EVENT_SETTLEMENT transfer targets a closed item, that item is reopened automatically.

   To prevent misallocation of balances during settlement, PCM_OP_AR_EVENT_SETTLEMENT calculates the combined dispute amount for the all of the dispute events with respect to the original disputed item. This amount is associated solely with the event dispute being settled. It has no contribution from any item disputes or any event disputes other than the one being settled. It is this amount that PCM_OP_BILL_ITEM_TRANSFER works with when transferring the item.

6. It creates a notification event (/event/billing/settlement/notify).

   If event notification is enabled in your system, this triggers the release of disputed balances.

7. When it finishes, PCM_OP_AR_EVENT_SETTLEMENT provides feedback on whether the settlement was successfully created or, if settlement creation failed, the reason for the failure.

BRM creates a G/L ID for event settlements. For information on settlements and G/L IDs, see "Assigning G/L IDs for a Dispute or Settlement".

Fields You Should Include in the Input Flist for Event Settlements

Set these fields in the PCM_OP_AR_EVENT_SETTLEMENT input flist when creating event settlements:

• PIN_FLD_ITEM_OBJ for the dispute item.

• PIN_FLD_AMOUNT for the settlement amount. The value supplied for this field should be positive for settlements that credit the event and negative for settlements that debit the event.

  You can specify the settlement amount through the PIN_FLD_AMOUNT field or omit the field altogether. If you omit this field, BRM settles the entire amount for each event.

• PIN_FLD_RESOURCE_ID for the balance to settle.

PCM_OP_AR_EVENT_SETTLEMENT accepts a variety of other fields used to define tax treatment, settlement time, reason code, and so on.

• For information on tax treatment, see "Including Taxes in the Dispute or Settlement".

• For information on reason codes, see "Including Reason Codes in the Dispute or Settlement".

Flags for Event Settlements

Use the following flags with PCM_OP_AR_EVENT_SETTLEMENT:

• If the PCM_OPFLG_READ_RESULT flag is set, PCM_OP_AR_EVENT_SETTLEMENT returns not only the POID, but all the fields in the /event/billing/settlement/event object as well.

• If the PCM_OPFLG_CALC_ONLY flag is set, PCM_OP_AR_EVENT_SETTLEMENT does not change any fields in the database and does not create an /event/billing/settlement/event object. However, it does provide a settlement calculation to the caller by returning the fields that would have been used to create the event object and settlement item.

  Note:

  If the PCM_OPFLG_CALC_ONLY flag is not set, PCM_OP_AR_EVENT_SETTLEMENT behaves in a standard manner, creating an /event/billing/settlement/event object to record details of the operation.

• If the PIN_ADJ_NO_TAX flag is set, the event settlement is nontaxable. If this flag is not set, the settlement is taxable.

• If the PIN_ADJ_TAX_ONLY flag is set, only the tax on the original event is settled; not the event itself.

  Note:

  Do not set this flag for settlements against unbilled events that use deferred taxation.

• If the PIN_EVENT_ADJUST_BATCH is set, the settlement amount is distributed among the events in the batch on a first-come-first-serve basis until the settlement amount is consumed.

• If the PIN_EVENT_ADJUST_EVENT is set, the settlement amount is applied individually to each of the events in the batch.

Configuring the Tax Treatment for Adjustments, Disputes, and Settlements

To ensure that you can control whether BRM applies adjustment, dispute, and settlement tax reversals, your custom CRM implementation should set the following flags in the input flists for all account, bill, and item level adjustment, dispute, and settlement opcodes:

• PIN_AR_WITH_TAX: Set this flag for all adjustments, disputes, and settlements that involve a tax reversal.

• PIN_AR_WITHOUT_TAX: Set this flag for adjustments, disputes, and settlements that do not require a tax reversal.

If you do not pass in one of the flags, BRM uses the fm_ar tax_reversal_with_tax entry in the CM configuration file to determine the default behavior. This entry takes one of the tax flags (PIN_AR_WITH_TAX or PIN_AR_WITHOUT_TAX). If you do not pass in one of the flags and this entry is not present, BRM does not perform a tax reversal.

Note:

Event adjustments, disputes, and settlements use different flags for tax reversal. For more information on tax flags for event opcodes, see Flags for Event Adjustments, "Flags for Event Disputes", and "Flags for Event Settlements".

Including Taxes in the Dispute or Settlement

You specify an optional tax treatment for disputes and settlements through flags in the dispute and settlement opcode input flists. For information, see:

• Flags for Bill Disputes

• Flags for Bill Settlements

• Flags for Item Disputes

• Flags for Item Settlements

• Flags for Event Disputes

• Flags for Event Settlements

Tax Processing for Disputes

The dispute opcodes calculate taxes when the dispute is created. Before calculating taxes, they validate that the item due is not zero. If it is zero, the dispute is not allowed.

If the input flist flags the dispute or settlement as taxable, the dispute opcode either includes or excludes the tax:

• If it is tax now, the opcode uses information from the disputed event to calculate the tax and apply it immediately.

• If it is tax deferred, taxes are contained in the tax item. In such cases, the opcode does the following to handle the taxes:

  • Calls PCM_OP_BILL_TAX_EVENT to calculate the tax amount.

  • Compares the calculated tax with due amount of the tax item to determine the amount to reverse.

  • Creates the /event/billing/dispute/tax_event event to contain the tax amount.

  • Transfers the calculated tax amount to the original tax item.

    Note:

    If the dispute is created in the same billing cycle as the disputed item, the original item will not have been taxed yet. In this case, there is no need to create the /event/billing/dispute/tax_event or /event/billing/settlement/tax_event event because the dispute or settlement precedes initial tax calculation for the original item.

Tax Processing for Settlements

The settlement opcodes calculates taxes when the settlement is created. Before calculating taxes, they validate that the settlement amount is less than or equal to the disputed amount. If the settlement amount is greater, the settlement is not allowed.

If the original bill item uses taxation, the tax is considered tax inclusive or tax exclusive, depending on the amount of the dispute:

• If the disputed amount is partially granted, the settlement amount is considered to be tax-exclusive. The amount due on the bill item is increased by the net denied amount and the amount due on the cycle tax item is increased by the denied tax amount.

• If the disputed amount is completely granted (there is no denied amount), the settlement amount is considered to be tax-inclusive. The amount due on the bill item does change for taxes.

  Note:

  If the disputed amount is completely denied, the amount due on the bill item is increased by the net amount and the amount due on the tax item is increased by the tax amount.

If the input flist flags the settlement as taxable, the settlement opcode determines whether the tax method is tax now or tax deferred.

• If the tax method is tax now, the settlement opcodes use information from the event associated with the original bill item to calculate taxes and apply the amount immediately with the settlement amount.

• If the tax method is tax deferred, taxes are contained in the tax item associated with the dispute. In such cases, the opcode does the following to handle the taxes:

  • Calls PCM_OP_BILL_TAX_EVENT to calculate the net and tax amount from the total settlement amount. If a denied amount exists, it then calculates the net and tax amount from the total denied amount.

  • Creates the /event/billing/settlement/tax_event event to contain the denied tax amount.

  • Transfers the denied net amount to the original item and the denied tax amount to the tax item.

Including Reason Codes in the Dispute or Settlement

Reason codes explain why a dispute is being opened or settled. In typical implementations, the BRM client application provides a selectable set of reasons appropriate to the event type. You choose a reason that matches the situation or, in some cases, compose a new reason. The client application populates the input flist for the opcode with this information, and BRM records the reason in the dispute or settlement event object (for example, /event/billing/dispute/item or /event/billing/settlement/event). The dispute and settlement opcode flist fields that provide reason code information are PIN_FLD_REASON_ID and PIN_FLD_REASON_DOMAIN_ID. These fields are optional.

For general information about reason codes, see "String Manipulation Functions" in BRM Developer's Reference.

Assigning G/L IDs for a Dispute or Settlement

The G/L ID for an dispute or settlement event is assigned like other pre-rated events in the BRM system. PCM_OP_ACT_POL_SPEC_GLID assigns the G/L ID for the adjustment.

Writing Off Debts and Reversing Write-Offs

Write-offs remove A/R amounts that your company determines will never be paid. Write-off reversals allocate payments to accounts, bills, bill units, and items that have been previously written off. Write-offs are a standard feature of your BRM system.

About Initiating Write-Offs

BRM uses the following opcodes to perform write-offs:

• PCM_OP_AR_ACCOUNT_WRITEOFF. Writes off all A/R bill units for an account and each bill unit's nonpaying children. This opcode performs a write-off when there are open items with due amounts and your company has determined that these items will never be paid by the customer. To have your client application initiate an A/R account write-off, it should call this opcode and the input flist should specify the account POID.

• PCM_OP_AR_BILLINFO_WRITEOFF. Writes off an A/R bill units for an account. To have your client application perform an A/R bill unit write-off, it should call this opcode with the bill unit specified in the input flist.

• PCM_OP_AR_BILL_WRITEOFF. Writes off a bill. To have your client application perform a bill write-off, it should call this opcode with the bill specified in the input flist.

• PCM_OP_AR_ITEM_WRITEOFF. Writes off a bill item. To have your client application perform an item write-off, it should call this opcode with one or more items specified in the input flist.

  Note:

  • Before you write off an account or bill unit, ensure that all items have been billed and that there are no pending items for the account or bill unit.

  • To ensure that you can reverse a write-off on an account, the account status must be inactive before you write off the account.

Performing Write Offs

Though you can initiate a write-off by using opcodes for the account, bill unit, bill, or item, most write-offs are performed by using PCM_OP_AR_ITEM_WRITEOFF. This opcode is called in one of the following ways:

• By using PCM_OP_AR_BILLINFO_WRITEOFF and PCM_OP_AR_BILL_WRITEOFF when you perform an account, bill unit, or bill write-off

  Note:

  PCM_OP_AR_ACCOUNT_WRITEOFF, PCM_OP_AR_BILLINFO_WRITEOFF, and PCM_OP_AR_BILL_WRITEOFF perform several initial steps before calling PCM_OP_AR_ITEM_WRITEOFF. For more information, see "About Account Write-Offs", "About Bill Unit Write-Offs", and "About Bill Write-Offs".

• Independently when you perform an item write-off

  Note:

  PCM_OP_AR_ITEM_WRITEOFF performs write-offs on pending items with nonzero balances only.

PCM_OP_AR_ITEM_WRITEOFF does the following:

1. Prepares the charges for the /item object (for example, /item/misc).

2. Calls PCM_OP_BILL_POL_ITEM_VALID_WRITEOFF to validate the changes.

   For information on how to customize write-off validation, see "Customizing Write-Off Validation".

3. Creates the new write-off item (/item/writeoff).

   For an account or bill write-off, the item total is the sum of all item charges in the account or bill.

4. Creates the /event/billing/writeoff/item object.

   The balance impact of the write-off event is the sum of all amounts due for all open items in the bill unit.

   • If an account is written off, an /event/billing/writeoff/account object is created for the account and an /event/billing/writeoff/billinfo object is created for each bill unit.

   • If a bill is written off, an /event/billing/writeoff/bill object is created.

5. If you have specified to store the tax amount of the write-off in a separate event, PCM_OP_AR_ITEM_WRITEOFF creates one of the following event objects:

   • /event/billing/writeoff/tax_billinfo

   • /event/billing/writeoff/tax_bill

   • /event/billing/writeoff/tax_item

   For information on tax treatments for write-offs, see "About Taxes for Write-Offs".

6. Calls PCM_OP_BILL_TRANSFER to transfer funds to the A/R bill.

   Multiple transfer events (/event/billing/item/transfer) are created to move the credit from the write-off item to all the open items for the bill unit.

7. If the item has no due or disputed amount, PCM_OP_AR_ITEM_WRITEOFF closes the item.

8. Writes the modified /item object.

When this process is complete, all the open items, including the write-off item, are closed. The G/L ID for the account write-off is assigned by calling PCM_OP_ACT_POL_SPEC_GLID, which assigns the G/L ID for the write-off event (/event/billing/item/writeoff).

If write-off reversal is enabled, PCM_OP_AR_ITEM_WRITEOFF stores the write-off item in the write-off profile object of the account.

Note:

• Before you write off an account or bill unit, ensure that all items have been billed and that no pending or unbilled items for the account or bill unit remain.

• To ensure that you can reverse a write-off on an account, the account status must be inactive before you write off the account.

About Account Write-Offs

To write off an account, PCM_OP_AR_ACCOUNT_WRITEOFF writes off all the bill units associated with the account.

This opcode performs the following error checks before performing the item write-offs for the account:

• Ensures the due amount is not zero. Bill units with zero due are fully paid and do not need to be written off.

• Ensures that there are no partially allocated items (for example, a refund must be allocated before the write-off is performed).

PCM_OP_AR_ACCOUNT_WRITEOFF then calls PCM_OP_AR_BILLINFO_WRITEOFF to write off all the open items for each bill unit of the account.

The /event/billing/writeoff/account event is created to record the account write-off. The /event/billing/writeoff/billinfo event is created to record each bill unit write-off, and /event/billing/writeoff/tax_billinfo is created for each bill if a separate event for tax is required. A separate tax event can be generated by passing the PIN_FLD_FLAG as PIN_BILL_WRITEOFF_TAX in the input flist.

Your custom application should call PCM_OP_AR_ACCOUNT_WRITEOFF, not PCM_OP_AR_BILLINFO_WRITEOFF, to write off all bill units in an account.

About Bill Unit Write-Offs

PCM_OP_AR_BILLINFO_WRITEOFF performs write-off adjustments for a specific bill unit when there are open items with due amounts and it has been determined that these items will never be paid by a customer.

To write-off all bill units of an account, use PCM_OP_AR_ACCOUNT_WRITEOFF.

To write off a bill unit, PCM_OP_AR_BILLINFO_WRITEOFF performs the following error checks before performing the item write-offs for the bill unit:

• Ensures the due amount is not zero. Bill units with zero due are fully paid and do not need to be written off.

• Ensures that there are no partially allocated items (for example, a refund must be allocated before the write-off is performed).

PCM_OP_AR_BILLINFO_WRITEOFF then calls PCM_OP_AR_ITEM_WRITEOFF to write off each of the bill items in the bill unit.

When a bill unit is written off, a write-off item (/item/writeoff) is created. The total for this item is the sum of the balance due from all the open items for the A/R bill units and its nonpaying child bill units. This is the balance impact of the write-off. The write-off decreases the account balances and the transfer event moves the credit from the write-off item to the items being written off.

The /event/billing/writeoff/billinfo event is created to record a bill unit write-off, and the /event/billing/writeoff/tax_billinfo event is created for the bill unit if a separate event for tax is required. A separate tax event can be generated by passing the PIN_FLD_FLAG as PIN_BILL_WRITEOFF_TAX in the input flist.

About Bill Write-Offs

PCM_OP_AR_BILL_WRITEOFF performs write-off adjustments against a specified bill when there are open items with due amounts and it has been determined that these items will never be paid by a customer. The write-off decreases the account balances associated with the specified bill, and the transfer event moves the credit from the write-off item to the item being written off. To write off a bill, PCM_OP_AR_BILL_WRITEOFF ensures the due amount is not zero. Bills with a zero due are fully paid and do not need to be written off.

PCM_OP_AR_BILL_WRITEOFF then calls PCM_OP_AR_ITEM_WRITEOFF to write off each of the bill items in the bill.

When a bill is written off, a write-off item (/item/writeoff) is created. The write-off decreases the account balances associated with the specified bill, and the transfer event moves the credit from the write-off item to the item being written off.

The /event/billing/writeoff/bill event is created to record a bill write-off, and /event/billing/writeoff/tax_bill is created for the bill if a separate event for tax is required. A separate tax event can be generated by passing the PIN_FLD_FLAG as 1 in the input flist.

Flags You Should Use for Write-Offs

Set flags in the PIN_FLD_FLAGS field for the PCM_OP_AR_BILL_WRITEOFF input flist when creating write-offs. You can include these flags in any of the write-off opcodes.

• If the PIN_BILL_WRITEOFF_TAX flag is set, BRM creates a separate write-off event for taxes.

About Taxes for Write-Offs

To write off tax, BRM selects all the open items. For all open items, PCM_OP_AR_ITEM_WRITEOFF selects all events that point to these items, except for the tax events. After the events are selected, it calculates the sum of the total initial net and tax amount and groups the events based on tax rate. The write-off process starts with the lowest tax rate first and continues with the next lowest rate until it reaches the total write-off amount. The total write-off amount (VAT included) is the total due amount of the bill.

The following types of events are created for a write-off with tax:

• A write-off event holding the total net amount of the write-off with a G/L ID for the net amount

• A tax write-off event holding the VAT amount of the write-off with a G/L ID for tax amount

• Transfer events to close all the remaining open items of the bill

Customizing Write-Off Validation

You use PCM_OP_BILL_POL_VALID_WRITEOFF to customize how the item is validated for a write-off. The default implementation is:

• The item must be open.

• The write-off amount must be less than or equal to the amount due.

PCM_OP_BILL_POL_VALID_WRITEOFF is called by PCM_OP_AR_ITEM_WRITEOFF. It checks the validity of field values before processing. Field values either pass or fail. If one field fails, the entire operation fails.

You can customize the validation criteria for PCM_OP_BILL_POL_VALID_WRITEOFF by modifying the policy source file. 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.

About Initiating Write-Off Reversals

Write-off reversals are initiated when PCM_OP_PYMT_COLLECT encounters a payment for an account or bill unit that has been written off. PCM_OP_PYMT_COLLECT runs automatically as part of the payment collection process or can be called manually. PCM_OP_PYMT_COLLECT calls PCM_OP_AR_REVERSE_WRITEOFF to perform the write-off reversal.

The following opcodes perform the actual reversal:

• PCM_OP_AR_REVERSE_WRITEOFF: This opcode reverses the write-off and opens the original bill items so that the payment can be allocated.

  Note:

  Write-off reversals should only be performed automatically; you should not call PCM_OP_AR_REVERSE_WRITEOFF directly.

• PCM_OP_BILL_POL_REVERSE_PAYMENT: This opcode writes off an account that was previously written off, but which then received a payment that reversed the original write-off. For example, if a payment that reversed the write-off of an account is determined to be fraudulent, the account will again be written off.

Reversing Write-Offs

To reverse a write-off, BRM uses PCM_OP_AR_REVERSE_WRITEOFF. This opcode is called by PCM_OP_PYMT_COLLECT.

PCM_OP_AR_REVERSE_WRITEOFF reverses write-offs on all written-off bills and bill items associated with a written-off account or bill unit when a payment for the account or bill unit is received.

PCM_OP_AR_REVERSE_WRITEOFF accepts an array of written-off items to be reversed.

To perform a reversal of a written-off bill unit, specify the POID of the written-off bill unit.

Note:

If you want a separate event to record the tax amount, set the PIN_BILL_WRITEOFF_TAX flag in the input flist.

Note:

Write-off reversals can only be performed automatically; do not call PCM_OP_AR_REVERSE_WRITEOFF directly. The automatic write-off reversal feature must be enabled for this opcode to perform write-off reversals.

PCM_OP_AR_REVERSE_WRITEOFF performs the following tasks:

1. Validates that the item in the input flist is a written-off item.

   If the input flist contains no written-off items, PCM_OP_AR_REVERSE_WRITEOFF calls PCM_OP_AR_POL_REVERSE_WRITEOFF to supply a list of write-off items that require reversal if that list is not provided by any other means.

2. Opens the originally written-off items so that funds can be allocated.

3. Creates a write-off reversal item (/item/writeoff_reversal).

4. Creates a write-off reversal event (/event/billing/writeoff_reversal) that points to the write-off reversal item.

5. Updates the account's balance.

6. (Account write-off reversal only) Sets the value of the /profile/writeoff object's PIN_FLD_ITEM_OBJ field to NULL.

   PCM_OP_AR_REVERSE_WRITEOFF also sets the PIN_FLD_WRITEOFF_INFO flag in this object to the reversed state (2). If the payment is not equal to or greater than the sum of the written-off items, this flag is reset to the write-off state (1).

Reversing a Write-Off Reversal

When BRM receives a payment for a written-off account or bill unit, it reverses the account or bill unit write-off and then allocates the payment. If that payment must later be reversed (for example, if it fails financially), BRM must then write off the account or bill unit a second time.

This activity is performed by PCM_OP_BILL_POL_REVERSE_PAYMENT. This opcode is called by PCM_OP_BILL_REVERSE_PAYMENT, and the input flist for the opcode includes any flags passed by the standard opcode.

Note:

If any open unallocated items are in the account or bill unit at the time of the reversal, the second write-off on the account does not occur. You can either allocate and close the open items before performing the reversal or customize this opcode to perform the task.

PCM_OP_BILL_POL_REVERSE_PAYMENT performs the following operations if the PIN_FLD_STATUS value on the input flist is PIN_PYMT_WRITEOFF_SUCCESS and if the transaction ID of the payment to be reversed is valid and applied to a written-off amount.

1. Write off the account or bill unit again (if the original payment was an underpayment).

2. Assign a reason code for the second write-off.

3. Set the value of the PIN_FLD_FLAGS field to PIN_BILL_WRITEOFF_TAX to generate a separate tax event (if necessary), and assign a reason code for the tax event.

The PIN_FLD_INHERITED_INFO substruct in the output flist passes additional information to the calling opcode. If necessary, PCM_OP_BILL_REVERSE_PAYMENT returns any information in this substruct to the calling opcode.

Customizing Write-Off Reversals

You can customize two aspects of write-off reversals:

• Use PCM_OP_AR_POL_REVERSE_WRITEOFF to customize the rules that govern how BRM performs write-off reversals.

  See "Customizing the Rules for Performing Write-Off Reversals".

• Use PCM_OP_BILL_POL_REVERSE_PAYMENT to customize the way that BRM processes payments that reverse account write-offs but that are, in turn, reversed. Payments of this sort result in a second write-off of the account.

  See "Customizing Reversal of Payments Allocated to Written-Off Accounts".

Customizing the Rules for Performing Write-Off Reversals

You can customize PCM_OP_AR_POL_REVERSE_WRITEOFF to implement additional rules for performing write-off reversals and allocating funds to written-off accounts and bill units. For example, you can perform the write-off reversal only for accounts that were written off during a specified time period or for a minimum amount.

PCM_OP_AR_POL_REVERSE_WRITEOFF is called by PCM_OP_AR_REVERSE_WRITEOFF during the write-off reversal process. PCM_OP_AR_POL_REVERSE_WRITEOFF supplies a list of write-off items that require reversal if that list is not provided by any other means. The PCM_OP_AR_POL_REVERSE_WRITEOFF input flist includes any flags passed by the standard opcode. PCM_OP_AR_POL_REVERSE_WRITEOFF retrieves the write-off reversal items from the /profile/writeoff object.

Note:

If any open unallocated items are in the account or bill unit at the time of the reversal, the second write-off on the account does not occur. You can either allocate and close the open items before performing the reversal, or customize this opcode to perform the task.

About Automatic Write-Off Reversals during Payment Collection

You can configure BRM to reverse a write-off on an account or bill unit automatically when a payment is received for a written-off account or bill unit. BRM verifies that the write-off flag and write-off item are set in the account's /profile/writeoff object. If so, the following occurs:

1. The write-off flag in the account's /profile/writeoff object is set to 2, which is the reversed state.

2. All written-off bills and bill items are opened so the funds can be allocated.

3. The /event/billing/writeoff/billinfo balance amount is transferred to the original bill or bill item and then set to 0.

4. The paid bills and items are closed.

5. The write-off flag in the account's /profile/writeoff object is reset to 1, which is the written-off state.

   Note:

   To ensure that you can reverse a write-off on an account, the account status must be inactive before you write off the account.

For information about using the PCM_OP_AR_POL_REVERSE_WRITEOFF policy opcode to customize write-off reversal rules, see BRM Opcode Guide.

Customizing Reversal of Payments Allocated to Written-Off Accounts

When a payment that was applied to a written-off account or bill unit is reversed, the previously paid balance is returned to the account balance and then written off again. This enables the original written-off amount to be reestablished as unrecoverable debt.

Table 4-5 shows an example where multiple payments are received for an account with a $100 write-off amount.

Payment 1 is $40 (underpayment), so the $100 write-off amount is reversed and $60 is written off.

Payment 2 is $100 (overpayment); therefore, the $60 write-off amount is reversed, and $40 excess (credit) amount is left unallocated in the account.

Table 4-5 Reversing Payment Applied to a Written-Off Account

Transaction	Due Amount	Unrecovered Debt	Recovered Debt	Bank Deposit
Account balance	100	NA	NA	NA
Initial write-off	-100	100	NA	NA
Write-off reversal	100	NA	-100	NA
Payment	-40	NA	NA	40
Re–write-off	-60	NA	60	NA
Write-off reversal	60	NA	-60	NA
Payment Reversal	40	NA	NA	-40
Re–write-off	-100	NA	100	NA
Net Result	0	100	0	0

Note:

If a subsequent payment is received during this operation, or if an A/R action is performed, the account may not be restored to its previous state. This occurs if any open unallocated items are in the account at the time of the reversal.

If Payment 1 is reversed, the write-off is not reversed because there is no longer a written-off amount on the account; instead, a credit in the account balance remains. To avoid this scenario, customize the PCM_OP_BILL_POL_REVERSE_PAYMENT policy opcode to handle the allocation and write-off. Or allocate the credit balance to any open bills or bill items, and then manually write off the account.

PCM_OP_BILL_POL_REVERSE_PAYMENT performs optional processing on payments that were applied to written-off accounts, and that must be reversed. For example, PCM_OP_BILL_POL_REVERSE_PAYMENT allocates balances on open bills and bill items before performing write-off reversals.

If any open unallocated items are in the account at the time of the reversal, the re-writeoff on the account does not occur. You can either allocate and close the open items before performing the reversal, or customize PCM_OP_BILL_POL_REVERSE_PAYMENT to perform the task.

PCM_OP_BILL_POL_REVERSE_PAYMENT is called by PCM_OP_BILL_REVERSE_PAYMENT.

You can implement special processing for reversing payments that were applied to written-off accounts. To implement this processing, you customize PCM_OP_BILL_POL_REVERSE_PAYMENT to perform the following functions:

• Assign custom reason codes.

• Generate a tax event based on custom business policies.

• Not reverse write-offs when a payment is applied.

• Allocate any open items in the account before performing the reversal, before the reversal can occur. This is required if multiple payments are received, and a subsequent payment results in an overpayment.

  For example, if a $100 write-off amount is present for an account and a $40 payment is received, followed by a $90 payment, a $30 credit is left unallocated on the account.

  Because write-offs are valid only for debit items, if you reverse the $40 payment, BRM creates a $40 debit open item and a $30 credit open item, and the result would be a $10 unallocated balance. This is not possible; therefore, the unallocated credit of $30 must be allocated before the re–write-off can be performed.

  To enable automatic allocation, customize PCM_OP_BILL_POL_REVERSE_PAYMENTto call PCM_OP_BILL_ITEM_TRANSFER, and allocate the open credit amount to the available debit items before performing the re–write-off.

Retrieving A/R Information

You can retrieve various kinds of balance information, such as the following:

• Current balances for items and bills

• A list of open and pending bill items

• A list of bills

• A list of adjusted items

To retrieve balance information, use the following opcodes.

• PCM_OP_AR_GET_ACCT* opcodes: These opcodes retrieve the current balance for open and pending bill items associated with all the bill units (/billinfo objects) in the account or for a specified bill unit. In the latter case, you specify the bill unit in the input flist.

• PCM_OP_AR_GET* opcodes: These opcodes retrieve the current balance for open and pending bill items associated with the specified bill unit. Specify the bill unit in the input flist.

  Note:

  To retrieve information for all of an account's bill units by using PCM_OP_AR_GET*, implement custom code that recursively calls PCM_OP_AR_GET* for each bill unit. This technique produces results similar to using PCM_OP_AR_GET_ACCT*, but it involves the overhead of creating a customization.

Finding a Bill

To find a bill, BRM uses PCM_OP_BILL_FIND. You can use this opcode to search for all /bill objects instead of using PCM_OP_SEARCH and PCM_OP_STEP_SEARCH.

Note:

PCM_OP_BILL_FIND does not perform authentication.

• If you specify an array of bill numbers, PCM_OP_BILL_FIND returns the POID of the /bill object.

• If you specify the results array, the fields in the results array are returned.

• If you do not specify the results array, PCM_OP_BILL_FIND returns the entire contents of the object.

Finding a Bill Unit

To find the bill units for an account, BRM uses PCM_OP_BAL_GET_ACCT_BILLINFO. This opcode returns the main contact information for an account and a list of the account's bill units with the default bill unit marked.

The output flist contains:

• Contact information from the /account object, including the account's contact name, address, and phone number.

• The POIDs, names, and payment methods of all the bill units associated with that account. If more than one bill unit is returned, the default bill unit array contains a PIN_FLD_FLAGS entry of 1. The PIN_FLD_FLAGS entry for each of the other bill unit arrays is 0.

Finding a Balance Group and Its Balances

To retrieve a /balance_group POID and, optionally, the balances it contains, BRM uses PCM_OP_BAL_GET_BALANCES. This opcode returns the /balance_group and /billinfo POIDs for an account or service. Using the PIN_FLD_BALANCES array, you can also direct this opcode to return any or all of the balances contained in the /balance_group object.

PCM_OP_BAL_GET_BALANCES finds the /balance_group POID by using the event end time and the /service object's PIN_FLD_TRANSFER_LIST array. For more information, see "Transferring Services between Balance Groups".

You can specify the validity period for which to retrieve sub-balances for the given balance group by setting the PIN_FLD_FLAGS field to one of the following values:

• PIN_BAL_GET_BARE_RESULTS (0x1): This flag returns all sub-balances for the current cycle that are currently valid.

• PIN_BAL_GET_ALL_BARE_RESULTS (0x4): This flag returns the sub-balances that are valid currently and in the future. To return future sub-balances, there must be at least one valid sub-balance for the current period.

• PIN_BAL_GET_BASED_ON_PERIOD (0x10): This flag returns all sub-balances whose validity period falls within or overlaps a given period, specified by the PIN_FLD_START_T and PIN_FLD_END_T fields.

  For example, if the period is June 1 through June 30, the opcode retrieves all sub-balance that were valid for any time between June 1 and June 30, whether their validity period begins before June 1 or ends after June 30.

• PIN_BAL_GET_WITHIN_PERIOD (0x16): This value returns only the sub-balances whose start and end times fall entirely within the given time period specified by the PIN_FLD_START_T and PIN_FLD_END_T fields.

  For example, if the period is June 1 through June 30, the opcode retrieves only sub-balances that start on or after June 1 and end on or before June 30.

If no balance is available for the specified period, PCM_OP_BAL_GET_BALANCES returns 0.

To return the balances that were granted by a specific charge offer or discount offer, specify the POID of the granting charge offer or discount offer in the PIN_FLD_GRANTOR_OBJ field.

PCM_OP_BAL_GET_BALANCES returns balances that are configured to start when first impacted (on first usage) if their validity periods have not yet been set. When a balance's validity period has not been set, the PIN_FLD_VALID_FROM_DETAILS and PIN_FLD_VALID_TO_DETAILS fields are returned for that balance. These fields store three values in separate bits: the mode of the validity start and end times (such as first usage or relative), the relative offset unit, and the number of offset units in the relative period.

Note:

• A read/write transaction must be open before calling PCM_OP_BAL_GET_BALANCES. Otherwise, the object is locked, and the read operation returns an error.

• You can call PCM_OP_BAL_GET_BALANCES in a read-only operation, but the PIN_FLD_READ_BALGRP_MODE field in the input flist must be set to PIN_BAL_READ_BALGRP_CALC_ONLY.

Finding a Balance Group and Service for Bill Units

To retrieve a balance group and service for all the bill units in an account or for a single bill unit, BRM uses PCM_OP_BAL_GET_ACCT_BAL_GRP_AND_SVC.

To retrieve the balance group and service for a single bill unit, use PCM_OP_BAL_GET_BAL_GRP_AND_SVC.

These opcodes return the /balance_group and /service object POIDs based on the /account POID, /billinfo POID, and event end time (PIN_FLD_END_T) passed in the input flist. The balance groups for a specified bill unit do not have to be associated with a service yet to be returned.

If the CALC_ONLY flag is set, PCM_OP_BAL_GET_BAL_GRP_AND_SVC reads the balance groups and services from the cache instead of from the database.

The PIN_FLD_FLAGS field in the input flist controls the type of information returned in the output flist. The settings for this flag are:

• PIN_BAL_GET_SERVICE_DEFAULT (0): do not return login name and balance group name (default).

• PIN_BAL_GET_SERVICE_LOGIN (1): Return the login name and balance group name.

• PIN_BAL_GET_SERVICE_ALIAS_LIST (2): Return the alias list for the service.

• PIN_BAL_GET_DEFAULT_BAL_GRP (3): Return the default balance group of the bill unit.

• PIN_BAL_GET_DEFAULT_GRP_AND_SVC (4): Return the default balance group of the bill unit and the default service of the default balance group.

• PIN_ BAL_GET_ALL_BAL_GRP_AND_SVC (5): Return all balance groups, including balance groups not associated with a service, balance groups associated with a service, and the account default balance group.

  Note:

  You can also pass in flags to get the balance group name and service login aliases.

Balance groups not yet associated with a service are returned when the PIN_FLD_FLAGS value is not set or is set to 0, 1, or 2. If the balance group returned is the account default balance group, the service object field in the output flist is NULL. If the balance group returned is not the account default balance group, there is no service object field in the output flist.

If you are developing the interface between BRM and a third-party client application, you should typically favor PCM_OP_BAL_GET_ACCT_BAL_GRP_AND_SVC over PCM_OP_BAL_GET_BAL_GRP_AND_SVC because it gives you the additional flexibility of retrieving balance groups and services for either multiple or single bill units.

Getting a List of Bills

PCM_OP_AR_GET_ACCT_BILLS retrieves the list of bills for all bill units in an account or for a single bill unit. The input flist determines the filter conditions to use for retrieving the data from the database.

You can restrict the search by various means, for example, date, status, and number of bills to be retrieved. You can also choose to find bills for the bill units, or for the bill units and their nonpaying child bill units.

PCM_OP_AR_GET_ACCT_BILLS returns the last bill. It uses the value in PIN_FLD_FLAGS to return the following:

• The latest bill (regular or corrective) when PIN_FLD_FLAGS is set to PIN_AR_LAST_BILL

• The previous (regular or corrective) bill only when PIN_FLD_FLAGS contains PIN_AR_ ORIG_BILL

• All bills (the regular bill and all its corrective bills) when PIN_FLD_FLAGS contains PIN_AR_ALL_BILLS

The pin_ar.h file defines these constants as follows:

#define PIN_AR_LAST_BILL 0x01
#define PIN_AR_ORIG_BILL 0x02
#define PIN_AR_ALL_BILLS 0x04

PCM_OP_AR_GET_ACCT_BILL calls PCM_OP_AR_GET_BILLS to perform the search. For corrective bills, it provides the PIN_FLD_FLAGS as an input to PCM_OP_AR_GET_BILLS.

For corrective billing, PCM_OP_AR_GET_ACCT_BILLS optionally returns the following items in the PIN_FLD_RESULTS array:

• PIN_FLD_ORIG_NUM. The bill number from the previous bill

• PIN_FLD_NAME. The name for the bill object. The pin_bill.h file contains the following definitions for corrective bills:

  #define PIN_OBJ_NAME_CORRECTIVE_BILL "PIN Corrective Bill"
  #define PIN_OBJ_NAME_CORRECTIVE_BILL_NOW "PIN Corrective Bill Now"
  #define PIN_OBJ_NAME_CORRECTIVE_BILL_ON_DEMAND "PIN Corrective Bill On Demand"
  

• PIN_FLD_AMOUNT_ORIG. The PIN_FLD_DUE field for the previous bill

• PIN_FLD_CREATED_T. The date that the bill was generated. It is taken from the corresponding field from the /event/billing/corrective_bill object.

• PIN_FLD_REASON_DOMAIN_ID. The reason domain code for the corrective bill taken from the corresponding /event/billing/corrective_bill object.

• PIN_FLD_REASON_ID. The reason ID for the corrective bill taken from the corresponding /event/billing/corrective_bill object.

• PIN_FLD_INV_TYPE. The invoice type for the bill.

Getting Bill Items

If general ledger (G/L) collection is enabled, PCM_OP_AR_GET_BILL_ITEMS retrieves the data from G/L /journal objects. Otherwise, this opcode retrieves the data from the events for each bill item. Using /journal objects improves performance.

The pin_flds.h file contains two decimal fields PIN_FLD_BILLED_AMOUNT and PIN_FLD_UNBILLED_AMOUNT used to store billed and unbilled amounts respectively.

For corrective bills, PCM_OP_AR_GET_BILL_ITEMS uses the input PIN_FLD_FLAGS value to select items that have unbilled and/or billed amounts allocated to them (where the allocated amount is greater than zero):

• When PIN_FLD_FLAGS is set to PIN_AR_BILLED_ITEM, PCM_OP_AR_GET_BILL_ITEMS retrieves the items with billed amounts that are allocated to the specified bill. The PIN_FLD_BILLED_AMOUNT elements in PIN_FLD_RESULTS output array returned by this code contain the billed amounts for the allocated items where the allocated amount is greater than zero. In addition, this opcode calculates the sum of the billed amounts that it placed in the PIN_FLD_RESULTS output array and returns that amount in a separate field called PIN_FLD_BILLED_AMOUNT.

• When PIN_FLD_FLAGS is set to PIN_AR_UNBILLED_ITEM, PCM_OP_AR_GET_BILL_ITEMS retrieves the items with unbilled amounts that are allocated to the specified bill. The PIN_FLD_UNBILLED_AMOUNT element in PIN_FLD_RESULTS output array returned by this code contain the unbilled amounts for the allocated items where the allocated amount is greater than zero. In addition, this opcode calculates the sum of the unbilled amounts that it placed in the PIN_FLD_RESULTS output array and returns that amount in a separate field called PIN_FLD_UNBILLED_AMOUNT.

• If PIN_FLD_FLAGS is not present or is present but does not have either value, PCM_OP_AR_GET_BILL_ITEMS retrieves all items allocated to the specified bill. The PIN_FLD_RESULTS output array returned by this code contains all the items allocated to the bill. However, this opcode does not return the summation of the billed or unbilled amounts.

Getting Bills

To get data for corrective bills, PCM_OP_AR_GET_BILLS uses the value in the PIN_FLD_FLAGS input field:

• It returns the latest bill (regular or corrective) when PIN_FLD_FLAGS contains PIN_AR_LAST_BILL. This is the default behavior.

• It returns the previous (regular or corrective) bill only when PIN_FLD_FLAGS contains PIN_AR_ ORIG_BILL.

• It returns all bills (the regular bill and all its corrective bills) when PIN_FLD_FLAGS contains PIN_AR_ALL_BILLS. The bills are returned in PIN_FLD_RESULTS sorted by the time when they were created.

• PCM_OP_AR_GET_BILLS optionally returns the following items in the PIN_FLD_RESULTS array:

  • PIN_FLD_ORIG_NUM. The bill number from the previous bill

  • PIN_FLD_NAME. The name for the bill object. The pin_bill.h file contains the following definitions for corrective bills:

    #define PIN_OBJ_NAME_CORRECTIVE_BILL "PIN Corrective Bill"
    #define PIN_OBJ_NAME_CORRECTIVE_BILL_NOW "PIN Corrective Bill Now"
    #define PIN_OBJ_NAME_CORRECTIVE_BILL_ON_DEMAND "PIN Corrective Bill On Demand"
    

  • PIN_FLD_AMOUNT_ORIG. The PIN_FLD_DUE field for the previous bill

  • PIN_FLD_CREATED_T. The date that the bill was generated. It is taken from the corresponding field from the /event/billing/corrective_bill object.

  • PIN_FLD_REASON_DOMAIN_ID. The reason domain code for the corrective bill taken from the corresponding /event/billing/corrective_bill object.

  • PIN_FLD_REASON_ID. The reason id for the corrective bill taken from the corresponding /event/billing/corrective_bill object.

  • PIN_FLD_INV_TYPE. The invoice type for the bill.

Finding Items

To find items, BRM uses PCM_OP_PYMT_ITEM_SEARCH. This opcode searches for /item objects with a variable number of input parameters. It is called by other opcodes for handling adjustments and disputes.

• PCM_OP_PYMT_ITEM_SEARCH takes a variable number of arguments to restrict the scope of the search.

• The PIN_FLD_POID field is mandatory and is a dummy POID used for getting the database ID for the search.

• The bill unit field is optional. This field specifies the bill unit that owns the items. You can use either the /billinfo POID or the /billinfo ID. If a bill unit is not specified, the bill unit associated with the account's default balance group is selected.

• You can specify either PIN_FLD_ACCOUNT_OBJ or PIN_FLD_ACCOUNT_NO to narrow the search to a particular account.

• For collective bills, if they are not located in the bill table, PCM_OP_PYMT_ITEM_SEARCH checks the RejectPaymentForPreviousBill business parameter.

  • If RejectPaymentForPreviousBill is enabled to prevent BRM from accepting the payment, the opcode sends the payment to the suspense payment account.

  • If the RejectPaymentForPreviousBill is disabled to prevent BRM from accepting the payments, the opcode will search for the bill in the history_bills objects. If the bill is located in the history_bills objects, the payment is accepted for the bill with the same POID as the bill being processed. If such a bill is not located in history_bills objects, the payment is sent to a suspense payment account.

• If PIN_FLD_STATUS, PIN_FLD_BILL_OBJ, or both are specified, the search matches the items equal to these values.

• PIN_FLD_START_T and PIN_FLD_END_T specify the time range for the search. These arguments narrow the search to items whose PIN_FLD_CREATED_T value falls between the start and end times.

• The PIN_FLD_POID field in the PIN_FLD_ARGS array narrows the search to specific /item object types. This is a TYPE_ONLY POID. Different items have different POID object types.

  For example, to return only the cycle forward and usage items, create the POID for the PIN_FLD_POID field as follows:

  PIN_POID_CREATE(database, 
        " '/item/cycle_forward', '/item/usage' " -1, ebufp);
    

Finding Discounts in Bill Items

BRM uses PCM_OP_BILL_GET_ITEM_EVENT_CHARGE_DISCOUNT to retrieve the discount for events of a given bill item.

For each event it retrieves, this opcode calculates the total amount of each balance and the total discount amount of each balance.

If a bill has been corrected and the database contains a corrective bill for the bill unit, BRM retrieves the events associated with the corrective bill only. It does not retrieve the events for the prior bill.

Retrieving a Balance Summary

To retrieve the balance summary from an account, BRM uses PCM_OP_AR_GET_ACCT_BAL_SUMMARY. This opcode retrieves the unapplied, open bill due, pending bill due, and total dispute balances for all the bill units in a specified account or for a particular bill unit.

You can use PCM_OP_AR_GET_BAL_SUMMARY to get this information for a single bill unit.

For both opcodes, you can specify whether BRM returns the balance for:

• The specified bill units (for PCM_OP_AR_GET_BAL_SUMMARY, this is a single bill unit).

• The specified bill units and their nonpaying child bill units (for PCM_OP_AR_GET_BAL_SUMMARY, this is a single bill unit).

If you are developing the interface between BRM and a third-party client application, you should typically favor PCM_OP_AR_GET_ACCT_BAL_SUMMARY over PCM_OP_AR_GET_BAL_SUMMARY because it gives you the additional flexibility of retrieving balance summaries for either multiple or single bill units.

PCM_OP_AR_GET_ACCT_BAL_SUMMARY retrieves the following data for the specified bill unit:

Note:

The data includes the amounts of the bill unit's nonpaying child bill units if you set the appropriate flag.

• Unapplied amount.

• Amount due for the open bill.

• Amount due for the pending bill.

• Total disputed amount.

• For PCM_OP_AR_GET_BAL_SUMMARY, the Bill in Progress information when there are pending items and the balance is greater than or equal to 0 because of open disputes against the items.

You can use the following PCM_OP_AR_GET_BAL_SUMMARY input criteria for retrieving the balance:

• The POID of the A/R bill unit object or paying bill unit object.

• The POID of the bill unit for which to retrieve the balance summary.

• A flag indicating whether to retrieve the balances for only the given bill unit or for the given bill unit and its nonpaying child bill units:

  • To return bills for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN flag to 0.

  • To return bills for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN flag to 1.

• For PCM_OP_AR_GET_BAL_SUMMARY, whether to retrieve Bill in Progress information if there are any pending items but the balance is zero.

  To do so, PCM_OP_AR_GET_BAL_SUMMARY uses the PIN_FLD_ITEM_PENDING_FLAGS flag. If this flag is set to 1 in the output flist, the opcode provides access to Bill in Progress information on the balance summary. If is flag is set to 0, the opcode does not provide access to Bill in Progress information.

Retrieving a List of Bills for a Bill Unit

BRM uses PCM_OP_AR_GET_ACCT_BILLS to get a list of bills for all the bill units in a specified account or for a particular bill unit. The input flist determines the filter conditions to use for retrieving the data from the database.

You can restrict the search by various means, for example, date, status, and number of bills to be retrieved. You can also choose to find bills for the bill units, or for the bill units and their nonpaying child bill units.

You can use PCM_OP_AR_GET_BILLS to get this information for a single bill unit. You can restrict the search by various means, for example, date, status, and number of bills to be retrieved. You can also choose to find bills for the specific bill unit, or for it and its nonpaying child bill units.

If you are developing the interface between BRM and a third-party client application, you should typically favor PCM_OP_AR_GET_ACCT_BILLS over PCM_OP_AR_GET_BILLS because it gives you the additional flexibility of retrieving the bill list for either multiple or single bill units.

About the Bill Data Retrieved

PCM_OP_AR_GET_ACCT_BILLS and PCM_OP_AR_GET_BILLS retrieve a list of bills for the account's bill units or it retrieves the bill units and their nonpaying child bill units. PCM_OP_AR_GET_BILLS retrieves only the bill unit you specify in the input flist. For each bill, the output includes the following data:

• Current and previous total
• Total for nonpaying child bill units, provided you set the appropriate flag
• Amounts for adjustments, disputes, transfers, write-offs, and so on
• The bill's state

Specifying the Search Criteria for Retrieving Bills

When you use PCM_OP_AR_GET_ACCT_BILLS and PCM_OP_AR_GET_BILLS, you can use the following input criteria for retrieving the list of bills:

• The POID of the account, bill unit, or bill object.

  These opcodes list a specific bill if the bill object POID is passed in the input flist. If you specify an account POID for PCM_OP_AR_GET_ACCT_BILLS, the opcode retrieves the bills for all the bill units in the account.

• The POID of the A/R bill unit.

  Note:

  • For PCM_OP_AR_GET_ACCT_BILLS, this field is mandatory if the input flist specifies the bill unit or bill POID instead of the account POID.

  • For PCM_OP_AR_GET_BILLS, this field is mandatory unless you include the POID of the A/R account.

• The POID of the A/R account. This returns the default bill unit for the A/R account.

  Note:

  This field is not available for PCM_OP_AR_GET_ACCT_BILLS.

• A flag indicating whether to retrieve the balances for only the given bill unit or for the given bill unit and its nonpaying child bill units:

  • To return balances for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.

  • To return balances for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.

• The status of the bills to retrieve. If the PIN_FLD_STATUS flag is set to:

  • 2: The opcode retrieves open bills.

  • 4: The opcode retrieves closed bills.

  • 6: The opcode retrieves all bills.

• The number of bills to retrieve. If you use PCM_OP_AR_GET_ACCT_BILLS to retrieve bills from all the bill units in an account, this is the number of bills the opcode retrieves from each bill unit. It is not the total number of bills to retrieve from the account unless the account has only one bill unit.

• The start and end times for the bills to retrieve.

• The sort order, ascending or descending. If you use PCM_OP_AR_GET_ACCT_BILLS to retrieve bills from all the bill units in an account, this is the sort order the opcode applies to the bills in each bill unit, not across all the bill units.

Retrieving A/R Items That Apply to a Bill Unit

BRM uses PCM_OP_AR_GET_ACCT_ACTION_ITEMS to get a list of A/R items for all the bill units in a specified account or for a particular bill unit.

You can restrict the search by various means, such as date, status, and bill unit POID.

You can find items for the specific bill unit or for it and its nonpaying child bill units.

The A/R item types returned can be:

• /item/adjustment

• /item/dispute

• /item/payment

• /item/refund

• /item/writeoff

Items associated with the A/R items, such as, /item/payment/reversal, /item/adjustment_reversal, and /item/settlement, are returned in the PIN_FLD_RELATED_ACTION_ITEM_OBJ field.

You can use PCM_OP_AR_GET_ACTION_ITEMS to get this information for a single bill unit.

If you are developing the interface between BRM and a third-party client application, you should typically favor PCM_OP_AR_GET_ACCT_ACTION_ITEMS over PCM_OP_AR_GET_ACTION_ITEMS because it gives you the additional flexibility of retrieving the A/R items for either multiple or single bill units.

About the Item Data Retrieved

PCM_OP_AR_GET_ACCT_ACTION_ITEMS and PCM_OP_AR_GET_ACTION_ITEMS return the following data:

Note:

PCM_OP_AR_GET_ACCT_ACTION_ITEMS returns an array. If the PIN_FLD_POID field is the account POID in the input flist, each element in the array is one of the listed fields for a bill unit in the account. Otherwise, the returned fields are for the requested single bill unit.

• The /billinfo and A/R bill unit object (PIN_FLD_BILLINFO_OBJ and PIN_FLD_AR_BILLINFO_OBJ) that the item belongs to.

• The account's primary contact information (PIN_FLD_NAMEINFO array), such as company, first name, last name, middle name, and salutation.

• The number of A/R items that were found (PIN_FLD_THRESHOLD) only if this count exceeds the threshold specified in the input. If the specified threshold is not exceeded, all the A/R items found are returned.

• Either the A/R items for only the given bill unit or the A/R items for the given bill unit and its nonpaying child bill units, depending on the flag setting in the input flist.

• For payments and reversals (that apply):

  • The POID of the reversal item (PIN_FLD_RELATED_ACTION_ITEM_OBJ).

  • The revision time when the payment was reversed; that is, when the reversal was posted (PIN_FLD_POSTED_T).

• For disputes and settlements (that apply):

  • The POID of the settlement item (PIN_FLD_RELATED_ACTION_ITEM_OBJ).

  • The revision time when the dispute was settled; that is, when the settlement was posted (PIN_FLD_POSTED_T).

  • The bill item to which the dispute or settlement is made (PIN_FLD_RELATED_BILL_ITEM_OBJ).

• For PCM_OP_AR_GET_ACTION_ITEMS only:

  • For event adjustments, disputes, and settlements, PCM_OP_AR_GET_ACTION_ITEMS returns a PIN_FLD_AGGREGATE_AMOUNTS array for each balance affected by the adjustment, dispute, or settlement item. This array contains the aggregated amount of adjustments, disputes, and settlements for each balance.

  • For adjustments, disputes, and settlements, PCM_OP_AR_GET_ACTION_ITEMS indicates whether the adjustment, dispute, or settlement was created for an event or for an item. PCM_OP_AR_GET_ACTION_ITEMS also indicates whether the adjustment, dispute, or settlement affects single or multiple balances.

  • For adjustments, PCM_OP_AR_GET_ACTION_ITEMS reads both /item/adjustment and /item/adjustment_reversal for a bill unit. It filters out /item/adjustment_reversal from the output and adds the POID of /item/adjustment_reversal as PIN_FLD_RELATED_ACTION_ITEM_OBJ and then adds PIN_FLD_REVERSED in the output.

For possible return values of each A/R action retrieved, refer to the fields contained in the PIN_FLDS_RESULTS array in the output flist specification.

Specifying Search Criteria for Retrieving Items

PCM_OP_AR_GET_ACCT_ACTION_ITEMS and PCM_OP_AR_GET_ACTION_ITEMS take as input:

• The POID of the A/R bill unit (PIN_FLD_AR_BILLINFO_OBJ).

• The POID of the bill unit related to the A/R items.

  When retrieving A/R items for nonpaying child bill units, the bill unit object is that of the paying bill unit. Otherwise, it is the bill unit object of the specified bill.

• The POID of the bill unit for which to retrieve A/R items (PIN_FLD_AR_BILLINFO_OBJ). This field is required only when retrieving A/R items for a specific, nonpaying child bill unit.

• A flag indicating whether to retrieve the A/R items for only the given bill unit or for the given bill unit and its nonpaying child bill units:

  • To return A/R items for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.

  • To return A/R items for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.

• The maximum number, or threshold, of A/R items to retrieve.

  Note:

  • The threshold field is valid only for an A/R bill unit (that is, the paying bill unit of a parent account).

  • If you use PCM_OP_AR_GET_ACCT_ACTION_ITEMS to retrieve A/R items from all the bill units in an account, this is the maximum number of A/R items the opcode retrieves from each bill unit. It is not the total number of A/R items retrieved from the account unless the account has only one bill unit.

• The action-item type to retrieve (for example, /item/adjustment) specified as a comma-delimited string.

  Note:

  When retrieving only payments, both payments and reversals are specified. When retrieving only disputes, both disputes and settlements are specified.

• The time range for which to retrieve A/R items. The start date is inclusive and the end date is exclusive.

• The amount range. The from and to amounts are inclusive.

• The amount indicator for whether to retrieve credits or debits for the given range.

• The item status. You can query based on a status of open, closed, or reversed (valid for payments only).

  Note:

  There is no pending status for A/R items.

Retrieving a List of Bill Items for a Bill Unit

To retrieve a list of bill items for a bill unit, BRM uses PCM_OP_AR_GET_BILL_ITEMS.

You can restrict the search by various means (for example, date, status, and bill unit POID). You can also choose to find items for the specific bill unit or for it and its nonpaying child bill units.

Depending on the value of the following CM pin.conf entry, the charge and discount for the items is populated in the PCM_OP_AR_GET_BILL_ITEMS output flist. The value for this entry can be either 0 or 1. The default is 0.

- fm_ar skip_displaying_charge_and_discount_for_item 1

If the value specified is 1, the charge and discount for the items is not populated in the PCM_OP_AR_GET_BILL_ITEMS output flist.

Note:

PCM_OP_AR_GET_BILL_ITEMS is used by Billing Care and Customer Center to display the item details. Setting this flag to 1 skips the query to get the charge and discount from the events belonging to the item, thereby improving performance.

About the Bill Item Data Retrieved

PCM_OP_AR_GET_BILL_ITEMS returns the following:

• The bill items for only the specified bill unit if PIN_FLD_INCLUDE_CHILDREN is set to 0.

• The bill items for the specified bill unit and its nonpaying child bill units if PIN_FLD_INCLUDE_CHILDREN is set to 1.

• The bill items for the nonpaying child bill units if PIN_FLD_INCLUDE_CHILDREN is set to 2.

• The number of bill items that were found (PIN_FLD_THRESHOLD) only if this count exceeds the threshold specified in the input. If the specified threshold is not exceeded, all the bill items found are returned.

For each bill item retrieved, the fields in the PIN_FLDS_RESULTS array are returned.

If general ledger (G/L) collection is enabled, PCM_OP_AR_GET_BILL_ITEMS retrieves the data from G/L /journal objects. Otherwise, the opcode retrieves the data from the events for each bill item. Using /journal objects improves performance.

Customizing the Number of Items to Retrieve in a Search

PCM_OP_AR_GET_BILL_ITEMS uses step-search. The step size (the number of items it tries to retrieve simultaneously) is determined by the following CM pin.conf entry:

- fm_bill item_search_batch 10000

Specifying Search Criteria for Bill Items

PCM_OP_AR_GET_BILL_ITEMS takes as input:

• The POID of the A/R bill unit or paying bill unit object (PIN_FLD_AR_BILLINFO_OBJ).

• The POID of the bill object related to the bill items.

  When PCM_OP_AR_GET_BILL_ITEMS retrieves bill items for nonpaying child bill units, the bill object is that of the paying bill unit object. Otherwise, it is the bill object of the specified bill unit.

• The POID of the bill unit object (PIN_FLD_BILLINFO_OBJ) for which to retrieve bill items. This field is required only when retrieving bill items for a specific, nonpaying child bill unit.

• A flag indicating whether to retrieve the bill items for only the specified bill unit or for the specified bill unit and its nonpaying child bill units:

  • To return bill items for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.

  • To return bill items for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.

  • To return bill items for the nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 2.

• The service device ID or phone number or login name to retrieve the SERVICE_OBJ for the services with matching ALIAS or LOGIN_NAME. SERVICE_OBJ is used to retrieve the associated bill items.

• The maximum number, or threshold, of bill items to retrieve.

• The time range in which to retrieve bill items. The start date is inclusive and the end date is exclusive.

• The amount range. The from and to amounts are inclusive.

• The amount indicator for whether to retrieve credits or debits for the given range.

• The item status. You can query based on a status of open, closed, or pending.

Retrieving Details about a Specific A/R Item or Bill Item

You can retrieve details for an A/R item or bill item in a bill unit using either of two opcodes:

• PCM_OP_AR_GET_ITEMS: Use this opcode to retrieve the details of an A/R item or bill item for a bill unit. For adjustments, disputes, and settlements, this opcode retrieves the aggregated impact amount for each balance or the events associated with the item (/item/dispute, /item/adjustment, /item/adjustment_reversal, and so on). PCM_OP_AR_GET_ITEMS provides details for both currency and noncurrency balances.

• PCM_OP_AR_GET_ITEM_DETAIL: Use this opcode to retrieve the details of an A/R item or bill item for a bill unit. This opcode retrieves detailed information about a specific write-off or usage item. For reversed adjustments, it sends the POID of /item/adjustment_reversal as PIN_FLD_RELATED_ACTION_ITEM_OBJ and returns the reversed amount in the PIN_FLD_REVERSED field. It does not return the aggregated dispute amount for each balance for disputed events. More importantly, it does not return details about noncurrency balances for adjustments, disputes, or settlements unless the item has both a currency and noncurrency component.

You should base your choice of opcode on how much information you want to retrieve for the A/R items and bill items.

About the Item Data Retrieved

PCM_OP_AR_GET_ITEMS calls PCM_OP_AR_GET_ITEM_DETAIL to get the details of the A/R item or bill item. When returning details for adjustments, disputes, or settlements, it collects details for:

• Item adjustments, disputes, and settlements (/event/billing/dispute/item, /event/billing/adjustment/item, and so on).

• Event adjustments, disputes, and settlements (/event/billing/dispute/event, /event/billing/adjustment/event, and so on).

Depending on the contents of the input flist, PCM_OP_AR_GET_ITEMS takes one of the following actions:

• If the input flist contains the POID of a transfer event, PCM_OP_AR_GET_ITEMS calls PCM_OP_AR_GET_ITEM_DETAIL to get the details of the transfer and performs no further action. For information on what this opcode returns for transfer events, see "About the Item Detail Data Retrieved".

• If the input flist contains the POID of a bill item or an A/R action such as an adjustment, dispute, or settlement, PCM_OP_AR_GET_ITEMS calls PCM_OP_AR_GET_ITEM_DETAIL to get the details of the A/R action or bill item. It also calls PCM_OP_AR_RESOURCE_AGGREGATION to calculate and return the aggregated amount of any event adjustments, disputes, and settlements for each balance.

  For A/R actions, it determines whether the action was initiated at the item level or event level. If the action was initiated at the event level, it retrieves both currency and noncurrency balances for the event.

  For information on PCM_OP_AR_RESOURCE_AGGREGATION, see "Retrieving Details on Available Balances".

PCM_OP_AR_GET_ITEMS returns an array of details for the A/R action or bill item. The transfers_into array provides the details of all items that have a currency or noncurrency impact for the A/R item or bill item specified in the input flist. These details include the aggregated balance impacts for each event. The AGGREGATE_AMOUNTS array returns the PIN_FLD_REVERSED field if the corresponding adjustment is reversed.

For adjustments, disputes, and settlements, the details for each A/R action include a flag in the transfer array that indicates whether the action was initiated at the event level or item level:

• PIN_FLD_ADJUSTMENT_TYPE: Set to 0 for item adjustments or 1 for event adjustments.

• PIN_FLD_DISPUTE_TYPE: Set to 0 for item disputes or 1 for event disputes.

• PIN_FLD_SETTLEMENT_TYPE: Set to 0 for item settlements or 1 for event settlements.

The details also include a PIN_FLD_RESOURCE_IMPACTED flag in the transfer array for any adjustments, disputes, or settlements. If this flag is set to 0, the action affected one balance only. If the flag is set to 1, the action affected several different balances (for example, multiple currencies or both a currency and a noncurrency balance, such as minutes).

About the Item Detail Data Retrieved

PCM_OP_AR_GET_ITEM_DETAIL retrieves details of activities that had a currency impact for the specified A/R item or bill item. If the input flist contains the POID for the transfer event, that POID is used to retrieve the item details from the transfer event binary large object (BLOB) file. PCM_OP_AR_GET_ITEM_DETAIL returns an array of the bill items the transfer event affected and the input POID.

• The transfers_into array returns the details of all the items that received some currency amount from the item specified in the input flist. For example, when a customer service representative (CSR) opens a dispute for a subscription fee, money is transferred into the dispute item from the subscription bill item (the cycle forward item). When the cycle forward item is passed in the input flist, the details of all the disputes that received money from this bill item are returned in the transfers_into array.

• The transfers_out array returns the details of all those items that transferred some currency amount to the item specified in the input flist. For example, when a customer pays for service usage, money is transferred from the payment item to the bill item (usage item). When the usage item is passed in the input flist, the details of all the payments that transferred money to this bill item are returned in the transfers_out array.

For adjustments, disputes, and settlements, the details for the A/R action include a flag in the transfer array that indicates whether the action was initiated at the event level or item level:

• PIN_FLD_ADJUSTMENT_TYPE: Set to 0 for item adjustments or 1 for event adjustments.

• PIN_FLD_DISPUTE_TYPE: Set to 0 for item disputes or 1 for event disputes.

• PIN_FLD_SETTLEMENT_TYPE: Set to 0 for item settlements or 1 for event settlements.

PCM_OP_AR_GET_ITEM_DETAIL determines how to set this flag by checking to see whether the event is stored in an /event/billing/AR_action_type/item object or an /event/billing/action_type/event object. The opcode returns the following information:

• Item adjustments, disputes and settlements: Returns a transfer array that includes details of the adjustment, dispute, or settlement item in the PIN_FLD_EVENT_OBJ field. In this case, the only event PCM_OP_AR_GET_ITEM_DETAIL looks at is the single event associated with the /item object. For example, it looks at the single /event/billing/dispute/item event associated with the /item/dispute object.

• Event adjustments, disputes and settlements: Returns a transfer array that includes a PIN_FLD_EVENTS array with the details of all the events that make up the adjustment, dispute, or settlement. In this case, PCM_OP_AR_GET_ITEM_DETAIL looks at all the events identified in the /item object.

The details for each A/R action also include a PIN_FLD_RESOURCE_IMPACTED flag in the transfer array for any adjustments, disputes, or settlements. If this flag is set to 0, the action affected one balance only. If the flag is set to 1, the action affected several different balances (for example, multiple currencies or both a currency and a noncurrency balance, such as minutes).

In addition to retrieving the other details of the adjustment, dispute, or settlement, PCM_OP_AR_GET_ITEM_DETAIL determines whether there is a tax reversal already calculated for the event. If so, it adds this information to the PIN_FLD_TAX field in the output flist.

Note:

Tax reversals are calculated at adjustment, dispute, or settlement event creation time only if you have set up tax now as the tax method for adjustments, disputes, and settlements in the CM pin.conf file.

The details for each A/R action also include a PIN_FLD_RESOURCE_IMPACTED flag to indicate whether the action affects a single balance (0) or multiple balances (1).

Specifying Search Criteria for Retrieving Items

PCM_OP_AR_GET_ITEMS and PCM_OP_AR_GET_ITEM_DETAIL take as input:

• The POID of the item object or the POID of the transfer event. If the POID is for a transfer event, all other values are ignored.

• The POID of the disputed item (PIN_FLD_RELATED_BILL_ITEM_OBJ) if the bill item is disputed. This field is mandatory if the item object is a dispute, but you can also include this field for other types of item objects.

• The POID of the settlement item or the reversal item (PIN_FLD_RELATED_ACTION_ITEM_OBJ) if the item is for a dispute or payment and a dispute settlement or payment reversal exists.

Retrieving Dispute Details for a Bill Unit

You can retrieve dispute details for a bill unit by using either of the following opcodes:

• To return a complete set of dispute details, use PCM_OP_AR_GET_DISPUTE_DETAILS. This opcode retrieves the details of all event and item disputes for a bill unit and the aggregated disputed amount for the events associated with a dispute item (/item/dispute object).

  See "Retrieving a Full Set of Dispute Data".

• To return a limited set of dispute details, use PCM_OP_AR_GET_DISPUTES. This opcode retrieves details of event and item disputes for a bill unit. This opcode does not return as much information as PCM_OP_AR_GET_DISPUTE_DETAILS. For example, it does not return the aggregated disputed amount for each balance.

  See "Returning a Limited Set of Dispute Data".

You should base your choice of opcode on how much information you want to retrieve for the disputes.

Retrieving a Full Set of Dispute Data

PCM_OP_AR_GET_DISPUTE_DETAILS calls PCM_OP_AR_GET_DISPUTES to get the details of each dispute. It collects details for both item disputes (/event/billing/dispute/item) and event disputes (/event/billing/dispute/event).

When it has the details for each dispute, PCM_OP_AR_GET_DISPUTE_DETAILS creates an input flist that contains the A/R event POID of each dispute and passes it to PCM_OP_AR_RESOURCE_AGGREGATION. PCM_OP_AR_RESOURCE_AGGREGATION calculates and returns the aggregated disputed amount for each balance. Balances can be currency or noncurrency. For information on PCM_OP_AR_RESOURCE_AGGREGATION, see "Retrieving Details on Available Balances".

Data Retrieved by PCM_OP_AR_GET_DISPUTES

PCM_OP_AR_GET_DISPUTES returns an array of disputes. This array includes transfer arrays identifying the /item/dispute object for each event and item dispute. In addition, the arrays for the event disputes include an aggregated balance subarray.

Each dispute includes a PIN_FLD_DISPUTE_TYPE flag in the transfer array to indicate whether it was filed as an event dispute or an item dispute:

• If this flag is set to 0, the dispute is an item dispute.

• If this flag is set to 1, the dispute is an event dispute.

The details also include a PIN_FLD_RESOURCE_IMPACTED flag in the transfer array for the disputes. If this flag is set to 0, the action affected one balance only. If the flag is set to 1, the action affected several different balances (for example, multiple currencies or both a currency and a noncurrency balance, such as minutes).

Specifying Search Criteria for PCM_OP_AR_GET_DISPUTE_DETAILS

PCM_OP_AR_GET_DISPUTES takes as input:

• The POID of the bill unit that has a dispute. If the account object is specified, the default account bill unit is selected.

• The POID of the A/R bill unit or paying bill unit object (PIN_FLD_AR_BILLINFO_OBJ).

• A flag indicating whether to retrieve the dispute details for only the given bill unit or for the given bill unit and its nonpaying child bill units:

  • To return dispute details for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.

  • To return dispute details for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.

• A status flag indicating whether to retrieve open disputes, closed (settled) disputes, or both. If the PIN_FLD_STATUS flag is set to:

  • 2: The opcode retrieves open disputes.

  • 4: The opcode retrieves settled disputes.

  • 6: The opcode retrieves all disputes, open or settled.

Returning a Limited Set of Dispute Data

PCM_OP_AR_GET_DISPUTES calls PCM_OP_AR_GET_ACTION_ITEMS to get a list of disputes for the bill unit and passes each disputed item to PCM_OP_AR_GET_ITEM_DETAIL. PCM_OP_AR_GET_ITEM_DETAIL gathers the details on the disputed items. PCM_OP_AR_GET_DISPUTES then creates an output flist that provides the information transferred by PCM_OP_AR_GET_ITEM_DETAIL, including flags to indicate whether the dispute is an event dispute or an item dispute.

You can restrict the search by various means, for example, date, status, and bill unit POID. You can choose to find items for the specific bill unit, or for it and its nonpaying child bill units.

For open disputes, PCM_OP_AR_GET_DISPUTES retrieves unsettled disputes; for resolved disputes, it retrieves settled disputes.

Data Retrieved by PCM_OP_AR_GET_DISPUTES

PCM_OP_AR_GET_DISPUTES returns an array of disputes. Each dispute includes a PIN_FLD_DISPUTE_TYPE flag in the transfer array to indicate whether it was filed as an event dispute or an item dispute:

• If this flag is set to 0, the dispute is an item dispute.

• If this flag is set to 1, the dispute is an event dispute.

The details also include a PIN_FLD_RESOURCE_IMPACTED flag in the transfer array for the disputes. If this flag is set to 0, the action affected one balance only. If the flag is set to 1, the action affected several different balances (for example, multiple currencies or both a currency and a noncurrency balance, such as minutes).

Specifying Search Criteria for PCM_OP_AR_GET_DISPUTES

PCM_OP_AR_GET_DISPUTES takes as input:

• The POID of the bill unit that has a dispute. If the account object is specified, the default account bill unit is selected.

• The POID of the A/R bill unit or paying bill unit object (PIN_FLD_AR_BILLINFO_OBJ).

• A flag indicating whether to retrieve the dispute details for only the given bill unit or for the given bill unit and its nonpaying child bill units.

  • To return dispute details for the specified bill unit, set the PIN_FLD_INCLUDE_CHILDREN field to 0.

  • To return dispute details for the specified bill unit and nonpaying child bill units, set the PIN_FLD_INCLUDE_CHILDREN field to 1.

• A status flag indicating whether to retrieve open disputes, closed (settled) disputes, or both. If the PIN_FLD_STATUS flag is set to:

  • 2: The opcode retrieves open disputes.

  • 4: The opcode retrieves settled disputes.

  • 6: The opcode retrieves all disputes, open or settled.

Retrieving Details on Available Balances

BRM uses PCM_OP_AR_RESOURCE_AGGREGATION to retrieve the available balances for the events associated with a bill item. This opcode aggregates (combines) the balance impacts of all the events by balance, such as US dollars or included minutes.

If an adjustment, dispute, or settlement is associated with an event, this opcode also includes the dispute, adjustment, reversed adjustment, or settlement amount in the aggregated impacts for each balance. The balance types can include currency, noncurrency, or both. The output flist PIN_FLD_RESULTS array contains the remaining available amount for opening new adjustments, disputes, or settlements for each balance in the PIN_FLD_ALLOCATED field.

You can write a custom application to use the aggregated amounts to find the balance impact of an event and help determine how much of each balance for an event is available for A/R activities like adjustments. This opcode is also called by PCM_OP_AR_GET_DISPUTE_DETAILS and PCM_OP_AR_GET_ITEMS.

PCM_OP_AR_RESOURCE_AGGREGATION returns an array that lists the following information for each balance impacted by the events specified in the input flist:

Note:

If PCM_OP_AR_RESOURCE_AGGREGATION is returning adjustment, dispute, or settlement events, it includes a balance array for all the balances impacted by the event, whether or not a particular balance is impacted by the adjustment, dispute, or settlement. For example, given a currency adjustment of an event that impacts US dollars and minute balances, the opcode returns arrays for both balances, even though the adjustment did not affect minutes.

• Balance element ID.

• Aggregated event charges.

• If the balance was discounted, the discount amount.

• If the balance was adjusted, the adjustment amount.

• If an adjustment was reversed, the reversed amount and the amount of the original adjustment.

• If the balance was disputed, the dispute amount and the amount of the original dispute.

• If a settlement occurred, the settlement amount.

• The total balance currently available (PIN_FLD_ALLOCATED field). This is the amount in the PIN_FLD_AMOUNT field minus any discounts, adjustments, disputes (the dispute amount in PIN_FLD_DISPUTED only, not the original dispute amount), and settlements.

Finding Events Associated with an Account

To find all events associated with an account, BRM uses PCM_OP_BILL_POL_EVENT_SEARCH. This opcode is not called by any opcode.

For filtered searches, PCM_OP_BILL_POL_EVENT_SEARCH supports searching on the following criteria:

• POID of the bill unit

• POID of the bill

• POID of the item

• Date ranges

• Amount ranges

• Event type

• Service type

• Balance element ID

To specify the number of events to return, use a value for the threshold. If the threshold value is greater than or equal to the number of events, all events are returned. If the threshold value is less than the number of events, the number of events is returned.

By default, PCM_OP_BILL_POL_EVENT_SEARCH returns all the events for the account but discards dispute, adjustment, and settlement events. This opcode can be customized to retrieve all the events for the account and keep the dispute, adjustment, and settlement events.

Finding Events Associated with Bill Items

To find events associated with a bill item, BRM uses PCM_OP_BILL_ITEM_EVENT_SEARCH.

This opcode searches the /event object for details related to a specific item. This opcode retrieves a list of events for a given item POID and flag.

The PIN_FLD_SEARCH_TYPE field in the PCM_OP_BILL_ITEM_EVENT_SEARCH input flist can be set to one or all of the following fields:

• PIN_ITEM_EVENT_OWNED: Events owned by an item. If PIN_ITEM_EVENT_OWNED is selected, PCM_OP_BILL_ITEM_EVENT_SEARCH returns a list of events whose item POID matches the item POID passed in the input flist.

• PIN_ITEM_EVENT_SPONSORED: Events sponsored by the item. If the PIN_ITEM_EVENT_SPONSORED flag is selected, PCM_OP_BILL_ITEM_EVENT_SEARCH returns a list of events whose item POID in the event subtotal array matches the item POID passed in the input flist.

• PIN_ITEM_EVENT_TRANSFERRED: A/R events that affect the item's total. If the PIN_ITEM_EVENT_TRANSFERRED flag is selected, PCM_OP_BILL_ITEM_EVENT_SEARCH returns a list of events whose item POID matches POIDs stored in PIN_OBJ_TYPE_EVENT_ITEM_TRANSFER. Lists are returned in separate arrays so that a list can be returned for each selected flag.

In addition to the above criteria, the event search can be narrowed to reflect the type of event and when the event was created.

Performing Rollover Transfers

BRM performs rollover transfers by using PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER for each account or service that has a rollover-transfer profile associated with it.

PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER checks the rollover-transfer profile object, /profile/rollover_transfer, to make sure it is configured and valid for the balance and receiver and then transfers the entire rollover amount to the receiver.

BRM performs a rollover transfer as follows:

1. The BRM event notification system listens for the following events to occur:

   • /event/billing/cycle/rollover/monthly

   • /event/billing/cycle/rollover_correction

2. When one of the events occurs, the event notification system calls PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER.

3. PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER checks the rollover-transfer profile object (/profile/rollover_transfer) to make sure it is configured and valid for the balance and the receiver.

4. PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER transfers the rollover amount to the receivers' accounts.

5. PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER removes the rolled-over amount from the sender's sub-balance and creates new sub-balances for the receivers with the transferred amount.

   The validity of the new sub-balance is based on the accounting cycle of the receiver and is valid for the remainder of the current accounting cycle and the next accounting cycle. The receiver's new sub-balance is not subject to future rollovers and its valid-from date is the end date of the sub-balance that was rolled over.

6. PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER generates the /event/billing/cycle/rollover_transfer event, which has the same GLIDs as the balance impacts of the original rollover event.

7. If delayed billing is configured and rolled-over balances were consumed by the sender by delayed events, PCM_OP_SUBSCRIPTION_TRANSFER_ROLLOVER receives the rollover correction event and adjusts the rollover transfer amount of the receiver accordingly.

   Note:

   You must perform rerating for the receiver if events rated before the rollover correction were consumed from the rollover transfer amount.