12 Managing Externally Initiated Payments

This chapter describes how to use Oracle Communications Billing and Revenue Management (BRM) to handle externally initiated payments, such as check or cash payments.

For information about handling BRM-initiated payments, see "About BRM-Initiated Payment Processing".

About Externally Initiated Payments

With externally initiated payments, such as payment by check or cash, an invoice is sent to the customer, who responds by sending the payment. Typically, payments are sent to a bank, and the bank sends you a list of payments that have been received and deposited. You then use Payment Tool to update the customer's account and close outstanding payments. For more information, see "Processing a Batch of Payments by Using Payment Tool".

Figure 12-1 shows how BRM collects externally initiated payments:

Figure 12-1 BRM Collection of Externally Initiated Payments

Description of ''Figure 12-1 BRM Collection of Externally Initiated Payments''

Supported Externally Initiated Payment Methods

You can submit the following externally initiated payments to BRM by using Payment Tool:

• Check

• Cash

• Wire transfer

• Postal order

• Inter-bank transfer

  Note:

  If unconfirmed payment processing is enabled, you can submit a batch of failed payments for unconfirmed payments that later fail. For more information, see "About Unconfirmed Payment Processing".

To add more payment methods, see "Rules for Modifying Payment and Reversal Fields".

Processing a Batch of Payments by Using Payment Tool

Processing payments with Payment Tool typically follows this procedure. This example shows how to process a batch of payments. Processing payment reversals and refunds is a nearly identical procedure.

1. You receive a batch of check payments. (A batch of check payments is typically a record of checks received and deposited in your bank.) Review the batch of payments to determine the number of payments and the total of all payments in the batch.

2. Open Payment Tool.

3. If you have branding enabled, choose the brand containing the accounts you must process. (You can work in only one brand at a time.)

4. Choose the type of payment batch to create (for example, check payments).

5. Enter the following batch properties:

   • The number of payments that you are processing.

   • (Optional) The projected total for the payments in the batch. You use this total to validate that you have entered all the payments.

   • (Optional) The currency.

   • (Optional) The payment channel.

   • (Optional) The effective date of the batch. You can backdate a batch, but not before the date of the last posted general ledger transaction report.

   • (Optional) The Lockbox ID and Lockbox date.

   • The allocation level. You can allocate payments to specific items or to an entire bill.

6. Record the data for each payment in the batch window, as shown in Figure 12-2.

Figure 12-2 Payment Tool Check Payment Batch Window

Description of ''Figure 12-2 Payment Tool Check Payment Batch Window''

1. After each entry is complete, Payment Tool displays the updated batch total in the Calculated Total field. When you finish entering all the data in a batch, compare the entry in the Calculated Total field with the entry in the Specified Total box. If you expect the entries to match and they do not, check the values in the Payment Amount column.

   Note:

   If Payment Suspense Manager is enabled, the Suspended Total box may contain an entry. This entry displays the total for all payments that cannot be submitted to the correct accounts and are therefore submitted to the payment suspense account.=poi

   For information about Payment Suspense Manager, see "About Payment Suspense Manager". For information about handling suspended payments, see Payment Tool Help.

2. When all the payments are recorded, click Validate to validate the batch of payments. If you entered a projected total when you created the batch and the calculated total of the payments in the batch does not equal the projected total, Payment Tool asks whether you want to continue. You can change the payment amounts before submitting the batch.

   If a customer paid too much or too little, an entry might not be validated (depending on your BRM configuration). You can create a batch that includes only payments that are not valid. You can use that batch to process the payments that are not valid, usually by allocating payments. See "About Allocating Payments".

3. When all payments are validated, submit the batch to BRM.

   For information about manually suspending payments, see Payment Tool Help.

Who Uses Payment Tool?

Payment Tool is used mostly by data entry personnel. Batches of payments that cannot be validated because they require allocation are typically processed by a senior customer service representative (CSR) or an accountant.

Note:

If your BRM system contains brands, you can see only the brands that you have permission to access. Before you can process payments, you must select a brand to work in.

Running Payment Tool on Windows 7 and Windows 8.1

On Windows 7 and Windows 8.1, Payment Tool must be run as an administrator. See the Windows 7 or Windows 8.1 online Help for information.

About Allocating Payments

When customers pay more or less than they owe, you can allocate payments. For example, if a customer pays too little, you can specify which items on the bill to apply the payment to. If your batch supports bill-level allocation, you can also allocate a payment to a specific bill when there are multiple unpaid bills for an account.

When you validate data, if you see a message in the status bar that says something similar to ”Payment allocation required,” you must allocate payments.

You can also allocate an account-level payment when the payment is applied to an account with multiple bill units.

When applying payments to an account, you can allocate the payments before or after you validate them.

For the steps to allocate payments, see Payment Tool Help.

About Required and Suggested Allocations

Payment allocations can be required or suggested. If an allocation is required, you must make the payment allocation before the payment can be submitted. If an allocation is suggested, your business policy should recommend that you allocate the payment, but allocation is not required.

About Allocating Multiple Payments for the Same Bill

When a payment clerk submits a payment batch that contains multiple payments for the same bill, BRM views each payment portion as an underpayment and displays a message requiring the payment to be allocated manually.

By default, BRM views each payment as an underpayment and prompts the payment clerk to manually allocate it. To disable the underpayment validation so underpayments are not returned with an error, set the NoManualAllocation flag in the PaymentTool.ini configuration file to 1. This also disables the Allocate button in Payment Tool. When the batch is submitted to BRM, the payments are allocated correctly.

Allocating Payments to Bills and Items

You can allocate a payment to a specific bill or to individual charges (items) on a bill. A payment batch can contain either bill-level allocations or item-level allocations, but not both. You must choose the allocation level before you create a payment batch.

If you enter a bill number and a payment amount when creating a batch, and the payment amount matches the bill amount, the bill is closed automatically when the payment is submitted. If the payment amount does not equal the amount due for the bill, your business policies should handle the underpayment or overpayment.

For example, an account has an unpaid bill of $30 and the customer pays $35. If the CSR records the payment and indicates the bill number in the payment batch, the bill is closed automatically and the overpayment is allocated to another open bill or recorded at the account level, according to your business policies.

For more information on configuring overpayment and underpayment rules, see "Handling Overpayments and Underpayments".

Allocating an Account-Level Payment to Multiple Bill Units

You can allocate an account-level payment to multiple bill units of an account. Payment Tool allocates the payment according to the business policies defined in the PCM_OP_PYMT_POL_MBI_DISTRIBUTE policy opcode. However, you can manually allocate the payment to override the default payment distribution.

Default payment distribution follows these rules:

• Bills having older due dates receive the payment amount first.

• If all the bills have the same due date, the bills with the higher due amounts are considered first.

• In the case of overpayment, the excess payment remains unallocated to the default bill unit of the account.

• In the case of underpayment, bills with later due dates or low due amounts do not get any payment amount.

  Note:

  The Payment Suspense Management feature must be enabled in your BRM system for you to allocate payments to accounts with multiple bill units. For more information, see "Enabling Payment Suspense in BRM".

Payment Tool performs the following steps to allocate an account-level payment to multiple bill units:

1. When you validate a payment, Payment Tool calls the PCM_OP_PYMT_VALIDATE_PAYMENT opcode, which is wrapper opcode for the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode. The PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode validates that the account-level payment requires distribution to multiple bill units. This validation opcode adds the reason ID as PIN_REASON_ID_MBI_DISTRIBUTION_REQD and domain ID as PIN_PYMT_SUSPENSE_REASON_DOMAIN_ID to the PIN_FLD_PAYMENT_REASONS array in the return flist if:

   • The payment is made to an account with multiple bill units.

   • The payment is not suspended or failed.

2. After validating the payment, Payment Tool distributes the payment.

   1. Payment Tool calls the PCM_OP_PYMT_MBI_DISTRIBUTE opcode to get the payment distribution across multiple bill units. PCM_OP_PYMT_MBI_DISTRIBUTE invokes the PCM_OP_PYMT_POL_MBI_DISTRIBUTE policy opcode. The PCM_OP_PYMT_POL_MBI_DISTRIBUTE policy opcode distributes the payment according to the default distribution logic.

   2. Payment Tool calls the PCM_OP_PYMT_SELECT ITEMS opcode by giving the output of PCM_OP_PYMT_MBI_DISTRIBUTE (bill unit-level distribution) as input. PCM_OP_PYMT_SELECT_ITEMS identifies the item-level distribution.

   3. Payment Tool calls the PCM_OP_PYMT_MBI_ITEM_SEARCH opcode to retrieve the bills/item across multiple bill units of the account.

      You can override the default distribution by manually allocating the payment. After manual allocation of payment, revalidate the payment. For more information on how to manually allocate payment to multiple bill units, see Payment Tool Help.

3. After distributing the payment, Payment Tool calls the PCM_OP_PYMT_COLLECT opcode. For more information on how PCM_OP_PYMT_COLLECT allocates the payment to multiple bill units, see "Allocating Account-Level Payments to Multiple Bill Units".

   Note:

   For manually allocated payments, the input flist contains the status as PIN_SELECT_STATUS_MBI_DISTRIBUTED. PCM_OP_PYMT_VALIDATE_PAYMENT is already called from Payment Tool. So, PCM_OP_PYMT_VALIDATE_PAYMENT does not perform previous actions again when PCM_OP_PYMT_COLLECT calls it.

Allocating Payments Later

You can create a batch for only those payments that need allocations. See "Managing Nonvalidated Batch Entries".

As an alternative, you can apply a payment to an account and allocate it later by using Customer Center. When you apply a payment at the account level, the account balance is reduced, but items and bills are not closed.

Allocating Payments in More Than One Currency

Each batch accepts payments in only one currency. If your customers pay bills in an EMU national currency and the euro, be sure to create a separate batch for each currency.

Important:

For countries that joined the EMU before February, 2002, the euro is the only legal currency. Countries that joined the EMU after 2/28/2002 can continue to use their national currency during the crossover period; however, the accounts should also use the euro, not the EMU currency, as the primary account currency. If you are unsure whether you should create an additional batch for the EMU currency, ask your supervisor.

Improving Payment Allocation Performance

You can improve the payment allocation performance for batch processing by disabling the payment validation for due amounts. When the payment validation is disabled for the due amounts, the due amounts are not displayed in the Due Amount column in Payment Tool.

To improve performance of payment allocation:

1. Open the Payment Tool INI file (C:\Windows\PaymentTool.ini).

2. Add the following entry in the CONFIG section:

   DisableBatchDue=1
   

3. Save and close the file.

You do not need to exit Payment Tool; the change takes effect the next time you allocate a payment.

Allocating Externally Initiated Payments by Due Amount

When allocating an externally initiated payment, such as a payment made by check or cash, that is associated with a valid account number but not a valid bill POID, BRM uses the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode to find the appropriate bill as follows:

1. If the element associated with the payment in the PIN_FLD_CHARGES array of the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode input flist has a bills array (PIN_FLD_BILLS) and the array contains a bill number (PIN_FLD_BILL_NO), the policy opcode searches for the bill POID associated with the bill number.

2. If the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode finds the POID, it adds it to the bills array in its output flist. The information in the output flist is passed to the PCM_OP_PYMT_SELECT_ITEMS opcode by Payment Tool or by the PCM_OP_PYMT_COLLECT opcode.

3. If the payment is not associated with a valid bill number, the opcode searches for a bill whose total due amount matches the payment amount. The search is restricted to bills linked to the account with which the payment is associated.

   Note:

   By default, this search is disabled. To enable it, see "Finding Bills by Due Amount".

Finding Bills by Due Amount

Note:

If the DisableBatchDue entry is set to 1, you cannot search bills by the due amount.

If the payment element in the PIN_FLD_CHARGES array does not have a bills array or if the bills array does not contain a valid bill POID or bill number, the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode searches for a bill whose total due amount matches a specified payment amount. BRM uses this search to find a bill to allocate a payment to when the bill POID and bill number associated with the payment are unknown. The search is restricted to bills that belong to the account with which the payment is associated. By default, this search is disabled.

If the PCM_OP_PYMT_POL_VALIDATE_PAYMENT policy opcode finds the bill, it adds its POID to the bills array in its output flist. If the bills array is missing, the opcode creates the array before adding the POID.

To enable the search, you modify a field in the ar instance /config/business_params object created during the BRM installation. Use the pin_bus_params utility or perform this modification.

To enable this search:

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

   pin_bus_params -r BusParamsAR bus_params_AR.xml 
   

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

2. Search the XML file for following line:

   <SearchBillAmount>disabled</SearchBillAmount>
   

3. Change disabled to enabled.

   Caution:

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

4. Use the following command to load the change into the /config/business_params object:

   pin_bus_params bus_params_AR.xml 
   

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

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

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

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

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

   Caution:

   If an account that uses balance forward accounting receives an underpayment when this search is enabled, some bill items in the account might remain open even after funds to cover the underpayment are submitted and the account balance (amount due for all bills) returns to zero. As the open items age, they might trigger debt management programs such as BRM Collections Manager.

   For example, Account A has a monthly billing cycle. At the end of May:

   • Total due amount for Bill 1 is $10 (Item 1a = $5, Item 1b = $5).

   • Customer makes a $5 payment.

   • Item 1a is closed, Item 1b remains open, and the total due for the account is set to $5.

   At the end of June:

   • Total due for Bill 2 is $15 (Item 2a = $5, Item 2b = $5, and the amount due from previous bills = $5).

   • Customer makes a $15 payment.

   • Neither a bill POID nor a bill number was submitted with the payment, so BRM uses the payment amount to find a bill to apply the payment to. It finds Bill 2 because the total due amount for Bill 2 matches the payment amount.

   • Items 2a and 2b are closed, $5 is left unallocated at the account level (it remains in the open payment item), and the total due for the account is set to $0.

   • Item 1b remains open.

   To close bill items such as 1b:

   • Use a database reporting tool such as BRM Reports to find all the open payment items in your BRM database.

   • In Customer Center, manually allocate the amount in each open payment item to the corresponding open bill item.

About Reversing Payments

Payment reversals are necessary when a payment is recorded in the BRM database, but the payment is not deposited. For example, you could record a check payment for a check that does not clear. To reopen the bill so the payment can be made again, you reverse the payment. Reversing the payment enables BRM to treat the payment as if it never happened.

You use Payment Tool to process batches of payment reversals. For more information on how BRM reverses payments, see "How BRM Reverses Payments".

Note:

• To reverse failed unconfirmed payments, create a failed payment batch.

• The reversals discussed in this section are referred to as direct reversals. They differ from indirect reversals that occur due to payment recycling during suspended payment processing. For information on reversals and how they relate to payment recycling, see "Understanding Payment Recycling".

• To reverse account-level payment made to an account having multiple bill units, you pass the original payment's transaction ID to Payment Tool. When you submit a reversal batch, the reversal batch reverses all the sub-payments created during the account-level payment allocation to multiple bill units.

Supported Payment Reversal Types

You can directly reverse the following types of payments:

• Check

• Credit card

• Direct debit

• Inter-bank transfers

• Postal order

• Wire transfer

  Important:

  Cash reversals enable cash payments to be recycled during payment suspense processing. They are not intended to directly reverse cash payments from the BRM database. For more information on payment reversals and recycling, see "How Payments Are Reversed".

Processing a Batch of Payment Reversals by Using Payment Tool

To process payment reversals, follow the basic procedure described in "Processing a Batch of Payments by Using Payment Tool".

• Instead of entering the bill number, you enter the payment ID. To find the payment ID, search for the account to see a list of payments.

• (Optional) Enter the original transaction date in the batch window. See "About the Columns in Batch Windows".

About Externally Initiated Refunds

To make refunds to customers with invoice accounts, first create the refund items, either manually or by using the pin_mass_refund utility. See "About Refunds" in BRM Managing Accounts Receivable. You then make the refund payments by check or other externally initiated payment, and record those payments by using Payment Tool. See "Processing a Batch of Refunds by Using Payment Tool".

• You cannot refund suspended payments. For information on suspended payment processing, see "Configuring Payment Suspense Manager".

• You cannot reverse a refund. If you refund a customer account by mistake, adjust the account for the refunded amount. See "Performing Adjustments with Your Custom Application" in BRM Managing Accounts Receivable.

Supported Batch Refund Types

Payment Tool supports the following types of refunds:

• Check

• Cash

• Wire transfer

• Postal order

• Inter-bank transfer

  Note:

  Payment Tool does not support batches of credit card refunds. BRM-initiated refunds are handled by the pin_refund utility.

Processing a Batch of Refunds by Using Payment Tool

To process refunds, you follow the same procedure described in "Processing a Batch of Payments by Using Payment Tool". The only difference is that you do not allocate payments for refunds.

Managing Refunds with Your Custom Application

For background information, see "About Refunds" in BRM Managing Accounts Receivable.

To create a refund, use the PCM_OP_BILL_ITEM_REFUND opcode. This opcode creates a refund item for a /bill or /billinfo object.

POIDs passed in to either the PIN_FLD_BILL_OBJ field or the PIN_FLD_BILLINFO_OBJ field specify the billing entity to receive the refund.

There are two ways to run PCM_OP_BILL_ITEM_REFUND: calculate-only mode or regular mode.

In calculate-only mode, PCM_OP_BILL_ITEM_REFUND:

• Computes the total refund amount without actually creating the refund item or committing any changes to the database.

• It shows the amount that a CSR can refund, based on both credit and debit items.

In the regular mode, PCM_OP_BILL_ITEM_REFUND does the following:

• Creates a refund item for the account if it has an open credit. Otherwise the refund fails and an error message is returned.

• Transfers amounts from any open credit items to the new refund item, and closes the credit items.

  Note:

  For any transfers, PCM_OP_BILL_ITEM_REFUND calls the PCM_OP_BILL_ITEM_TRANSFER opcode.

• Transfers amounts from the /billinfo or /bill object to any open debit items.

  Each transfer from the new refund item to debit items decreases the value of the new refund item.

• Creates the /item/refund object, which contains the total credit amount.

• Closes these credit and debit items.

• Returns the refundable amount in the /item/refund object.

If you use a custom program to perform refunds, you can put the program name in the input flist optional field PIN_FLD_PROGRAM_NAME. If this field is used to contain the name of the program refunding a customer's account, the program name is recorded in the events associated with an item refund. If the program name is not specified, the default value, Refund Opcode, is used.

Note:

• You cannot refund suspended payments. For more information, see "How Direct Reversals and Refunds Relate to Suspense".

• You cannot reverse a refund. If you refund a customer account by mistake, adjust the account for the refunded amount. See "Performing Adjustments with Your Custom Application" in BRM Managing Accounts Receivable.

Managing Nonvalidated Batch Entries

While processing a payment, refund, or reversal batch, you might have some entries that cannot be validated easily. You can create a batch that includes only those entries with validation errors. This enables you to submit the entries that can be validated. If Payment Suspense Manager is enabled, you can manually suspend any invalid payments and continue with submitting the batch.

To create a batch of nonvalidated entries, first validate the batch, then choose Tools - Create Exception Batch. A new batch is created that includes only non-valid batches. The non-valid batches are removed from the validated batch.

Processing Lockbox Batches

Lockbox processing is a typical way to handle externally initiated payments, reversals, and refunds. With lockbox processing, the bank sends you a record of the data, which you enter into the BRM database by using Payment Tool.

Most banks that perform lockbox processing can format a text file according to your specifications, which might include:

• Which data is included.

• The format (fixed width or delimited).

• The order of the entries.

• A batch header or footer. The batch header and footer can contain information common to all payments in the payment batch, and information specific to the batch, including the lockbox number, date, number of checks, and total payment amount. If a payment is missing information, the batch data is used.

You can have the bank deliver the file electronically, and you can use Payment Tool to import data directly from the file. See "Importing Batch Data into Payment Tool".

Note:

• You might need to create a utility to retrieve the file.

• If the bank creates the file with the EBCDIC character set, you must create a utility to convert it to ASCII.

• Payment Tool does not support the EDI 823 format.

About the Columns in Batch Windows

This table describes the columns in the Payment Tool batch window. Most types of batches use the same columns. Depending on the type of payment batch, and the functionality that is enabled, some columns might not be displayed. For example, the Receipt No. column appears only for cash payment batches, and the Suspense Description column appears only if Payment Suspense Manager is enabled.

The only required columns are the Bill Number and Account Number columns, but you only need one of them. For example, if you enter the account number, the bill number is not required.

You can configure custom columns for each type of batch. For example, a cash payment batch might include a column for entering the name of the person who signed the receipt.

Entering data in optional columns makes it easier for a BRM administrator to find payment information as shown in Table 12-1.

Table 12-1 Payment Data

Column	Batch Type	Description
Status	All batches	The status of the entry.
Payment ID	Payment reversal batches	The amount of payment to reverse.
Allocation	Payment batches	The expansion level of the entries that include payment allocations. If you allocate payments, you can see all of the open bill items for the account. This column appears in refund batches but is not used.
*	Payment batches	When checked, the payment is allocated to the account, but is not allocated to any bills or items. You can record a payment at the account level, and allocate it later by using Customer Center. When you record a payment at the account level, the account balance is reduced, but items and bills are not closed.
Bill Number	Payment batches and refund batches	The bill number that the payment or refund applies to. If the account number is not supplied, the bill number is required.
Account Number	All batches	The account number that the payment applies to. If the bill number is not supplied, the account number is required.
Payment Transaction ID	All batches	The transaction ID of the payment.
Check Date	All check batches	The date on the check.
Receipt Date	All cash batches	The date on the receipt.
Original transaction date	Payment reversal batches	The date that the payment was originally closed.
Chargeback date	Payment reversal batches	The date that the payment reversal was made.
Check Number	All check batches	The serial number on the customer's check.
Receipt No.	All cash batches	The serial number on the receipt.
Credit card No.	Credit card payment reversal batches	The credit card number for the payment.
Bank RDFI No.	Direct debit payment reversal batches	The direct debit card number for the payment.
Order ID	All postal order batches All inter-bank batches	The serial number of the postal order or the inter-bank payment order.
Wire-Transfer ID	All wire transfer batches	The serial number of the wire transfer receipt.
Bank Code	All check batches All inter-bank batches All wire transfer batches	The bank branch ID number.
Bank Account	All check batches All inter-bank batches All wire transfer batches	The customer's personal account number.
Channel	All batches	The payment channel ID.
Suspense Description	Payment batches	The reason why the payment failed validation and was suspended.
Status Description	Payment batches	The reason why the payment status was set.
Status Code	Payment batches	The status code for the payment, which is used by BRM during validation.
Comment	All batches	Comments about the entry.
Payment Amount	Payment batches	The amount paid. The payment amount is required.
Reason code	Payment reversal batches	A number representing a reason for reversing the payment.

Importing Batch Data into Payment Tool

You can import data from text files into Payment Tool batch format. For example, if you have electronic files of data formatted in columns, you can import that data into a batch instead of entering it manually.

To import a batch, the information must be in a text file. Payment Tool supports a wide variety of formats, including almost any delimiter character. Data can be in any order: the columns do not need to match the columns in the Payment Tool batch windows.

Data must be in a format that can be imported. Before you begin importing data, ensure that you know how your data is formatted:

• When you import data, you must specify how the data is separated in columns (for example, with spaces or tabs). Open a file containing your data to see how it is formatted.

• Your data can include information that is not formatted in columns (for example, a document heading). This information can be imported as the batch header and batch footer.

• For payment data and refund data, there are two required columns:

  • The amount paid

  • Either the account number or the bill number

• For payment reversal data, the only required column is the payment ID.

A typical input file looks like this:

Account Number,Payment Amount,Date,Check Number
0.0.0.1-887,19.95,5/11/99,1243
0.0.0.1-425,19.95,5/11/99,1543
0.0.0.1-776,19.95,5/11/99,1273
0.0.0.1-143,19.95,5/11/99,1254

Figure 12-3 shows how an input file, such as the one shown above, appears in the Batch Import Wizard. The data is organized in columns, as defined by the delimiter character (in this case, a comma).

Figure 12-3 Batch Import Wizard

Description of ''Figure 12-3 Batch Import Wizard''

Handling Overpayments and Underpayments by Using Payment Tool

If a customer pays too much or too little, you allocate the payment as required by your BRM business policies. For example, these are alternative underpayment policy configurations:

• Automatically apply payments to bill items.

• Suggest payment allocation in Payment Tool.

• Require payment allocation in Payment Tool.

For more information, see "Handling Overpayments and Underpayments".

Working with Multiple Currency Types in the Payment Tool

When you process payments with Payment Tool, you choose the currency to use for each batch of payments. You can make a payment to an account in any currency. The amount will be converted to the account's primary currency and then posted to the account. For information on how BRM uses currencies, see "About System and Account Currencies" in BRM Managing Customers.

Applying Multiple Payments to the Same Account

By default, to prevent duplicate entries, you cannot use Payment Tool to apply more than one payment in a batch to a single account. However, you might need to apply more than one payment if the account uses open item accounting and you need to apply payments to more than one bill.

To apply more than one payment to an account:

1. Open the Payment Tool INI file (C:\Windows\PaymentTool.ini).

2. Change this entry:

   ALLOWACCOUNTDUP=0
   

   To this:

   ALLOWACCOUNTDUP=1
   

   You do not need to exit Payment Tool; the change takes effect the next time you validate a payment.

Manually Allocating Account-Level Payments to Accounts with Multiple Bill Units

When you submit an account-level payment to an account with multiple bill units, BRM applies the payment across multiple bill units. You can override the default payment distribution by manually allocating the payment to multiple bill units.

By default, BRM enables you to manually allocate the payment to multiple bill units. To disable the manual payment allocation, set the NoManualAllocation flag in the PaymentTool.ini configuration file to 1. In this case, you are not allowed to manually allocate the payment, and the default BRM payment distribution applies.

Enabling Overallocation to an Item

Submitting duplicate payments for the same account with a single payment tool batch can cause an overallocated payment, resulting in a credit to the customer's account. The new ItemOverallocation business parameter checks for item overallocation and determines if an item can be allocated beyond what the customer owes.

By default, the item overallocation feature is disabled in BRM. You can enable this feature by modifying a field in the billing instance of the /config/business_params object.

You modify the /config/business_params object by using the pin_bus_params utility. For more information, see "pin_bus_params" in BRM Developer's Guide.

To enable overallocation to an item:

1. Go to BRM_home/sys/data/config.

2. Create an editable XML file from the /config/business_params object by running the following command:

   pin_bus_params -r BusParamsBilling bus_params_billing.xml
   

3. Search the XML file for the following line:

   <ItemOverallocation>disabled</ItemOverallocation>
   

4. Change disabled to enabled.

5. Save the file as bus_params_billing.xml.

6. Load the XML file into the BRM database by running the following command:

   pin_bus_params bus_params_billing.xml
   

7. Stop and restart the CM.

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

Configuring Payment Tool to Lock at the Account Level during Batch Processing

When processing a batch of payments, Payment Tool, by default, locks all accounts associated with the batch and keeps them locked until it finishes processing the batch. This can cause problems if your batches contain a large number of payments, because other processes cannot access the accounts during payment processing.

You can configure Payment Tool to lock only the account that it is currently processing rather than the entire batch.

When processing payments in a batch, Payment Tool initiates the transaction for the entire batch and any errors that are encountered while processing any payment entry in the batch is ignored. However, when you configure Payment Tool to lock only the account it is currently processing, the payment item and payment event is recorded in the BRM database only when the payment entry is processed successfully. The payment is not recorded if any errors are encountered while processing the payment entry.

Important:

Processing payments at the account level rather than at the batch level can produce problems if the CM or Data Manager (DM) fails during payment processing; Payment Tool cannot determine which payments in the batch failed or were successfully processed. Thus, when you resubmit the batch for processing, Payment Tool may process a payment twice for the same account.

To find out which payments failed or were successful after a CM or DM failure, you must either check the logs or check in the database for failed /event/billing/payment/pay_type events with the correct batch ID. Then, you must batch only the failed payments and submit it to Payment Tool for processing.

To configure Payment Tool to lock at the account level when processing a batch of payments:

1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf) in a text editor.

2. Edit the payment_batch_lock entry:

   - fm_pymt payment_batch_lock 0
   

   Use 0 to lock at the account level or 1 to lock at the batch level.

3. Save and close the file.

4. Stop and restart the CM. For more information, see "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Customizing Payment Details Displayed in BRM Client Tools

BRM uses /config/paymenttool objects to create payment, reversal, and refund batch type actions in the Payment Tool database. While you can handle most of your payment decisions using Payment Tool, you can also customize actions in the database. This section describes the characteristics of /config/paymenttool objects that you can customize.

When you customize /config/paymenttool, follow the rules defined in "Rules for Modifying Payment and Reversal Fields".

/config/paymenttool is defined in the init_objects.source file, which BRM reads when it starts. The init_objects.source file provides information that determines:

• What Payment Tool displays, including the columns that are displayed and whether the columns can be used for entering data or are read-only.

• What the Customer Center Payments tab displays, including the payment method and credit card numbers.

  Important:

  You should make a backup copy of the init_objects.source file each time you modify it. When you upgrade BRM, the installation program overwrites init_objects.source, including your customizations. You can use the backup to restore your changes.

About the Default /config/paymenttool

The following is the default config/paymenttool as defined in init_objects.source.

! PaymentTool Payment Config object
! Mandatory fields for creation for each PIN_FLD_PAY_TYPES element specified
!
!    PIN_FLD_NAME
!    for each PIN_PAYMENT_TOOL_FIELDS
!        PIN_FLD_FIELD_NAME
!        PIN_FLD_COLUMN_NAME
!        PIN_FLD_PURPOSE
!        PIN_FLD_BATCH_TYPE

TYPE   =   /config/paymenttool
FIELDS =
 array PIN_FLD_PAY_TYPES (           type = PIN_FLDT_ARRAY,      perms = ORW,);
 field * PIN_FLD_NAME (              type = PIN_FLDT_STR(255),   perms = MRW,);
 array * PIN_FLD_PAYMENTTOOL_FIELDS( type = PIN_FLDT_ARRAY,      perms = ORW,);
 field * * PIN_FLD_FIELD_NAME (      type = PIN_FLDT_STR(255),   perms = MRW,);
 field * * PIN_FLD_COLUMN_NAME (     type = PIN_FLDT_STR(255),   perms = MRW,);
 field * * PIN_FLD_PURPOSE (         type = PIN_FLDT_INT,        perms = MRW,); 
 field * * PIN_FLD_BATCH_TYPE(
                 type = PIN_FLDT_INTINT,
                 perms = MRW,
); 

Rules for Modifying Payment and Reversal Fields

All changes you make in /config/paymenttool are reflected in the Payment Tool graphical user interface when you stop and restart BRM. If you are changing or adding values to the payment or reversal fields, follow these rules:

• If you add a bill type in the /config/paymenttool storable class, you must add a corresponding entry in the /config/payment storable class.

• All user-defined fields for a particular type (data entry or display) for a given batch should be from the same array in the /event object.

  See the /config/paymenttool and /event storable class definitions.

• If the charge opcode fields in /config/payment are valid, the display fields for the corresponding reversal batch should be from /event/billing/charge/name, where name can be defined as a credit card, direct debit, and so on.

  Tip:

  The charge object contains a lot of payment information; therefore, it might be useful to display the charge object information when reversing a payment.

• There must be at least one /config/paymenttool object for each supported language.

  You can set a language as the default by entering Default in PIN_FLD_NAME as shown below:

  0 PIN_FLD_NAME     STR [0] "PaymentTool payment Types: Default"
  

  By default, the language is set to English (United States).

  The Customer Center, Payment Tool, and Payment Center client applications read the /config/paymenttool object that has PIN_FLD_NAME set to Default.

  To customize the client applications to read a specific locale of English, update PIN_FLD_NAME in the /config/paymenttool object as shown in the following examples:

  • For English (United States):

    0 PIN_FLD_NAME                              STR [0] "PaymentTool payment Types: English(United States)"
    

  • For English (United Kingdom):

    0 PIN_FLD_NAME           STR [0] "PaymentTool payment Types: English(United Kingdom)"
    

  You can also use the PCM_OP_WRITE_FLDS opcode to set the locale.

  Note:

  The country name you specify should exactly be the same as the country name in the language parameter for that particular locale.

• In the /config/paymenttool definition, an array element must always begin with PIN_FLD_PAYMENTTOOL_FIELDS. Each array corresponds to an array element in the /config/payment object. The sequence of array elements determines the order of columns displayed in Payment Tool.

• A payment batch must have only data-entry fields. A reversal batch can have display and data-entry fields.

• All the fields you use to enter or display data in Payment Tool for a particular batch grid must be defined in the same array in the object definition.

• Storable objects for payment reversal are created as subclasses from /event/billing/payment or /event/billing/reversal.

Creating an Object Definition for a New Payment or Reversal Event

To create a payment or reversal event, start a new PIN_FLD_PAYMENTTOOL_FIELDS array. Use the following example to define your custom fields. Before you define an object, see "Rules for Modifying Payment and Reversal Fields".

PIN_FLD_PAY_TYPES is the first line. The 0 to the left of this line indicates that this is the beginning of a sequence of arrays.

0  PIN_FLD_PAY_TYPE   ARRAY [0]   allocated 3, used 3

PIN_FLD_NAME indicates that the array has been allocated 5 items and 3 have been used. This line is at the same level as the following PIN_FLD_PAYMENTTOOL_FIELDS items.

1  PIN_FLD_NAME   ARRAY [10003]   allocated 5, used 3

10003 comes from a corresponding entry in /config/payment/.

PIN_FLD_PAYMENTTOOL_FIELDS begins the definition of an individual, user-defined array. The 1 to the left of the line shows that this is a subset of PIN_FLD_PAYMENTTOOL_FIELDS but of equal status to PIN_FLD_NAME.

1  PIN_FLD_PAYMENTTOOL_FIELDS   ARRAY [0]   allocated 3, used 3

An example of individual arrays is shown below.

Within the first PIN_FLD_BATCH_TYPE array the numeral 1, not [1], says that this is a reversal batch type while 0 is a payment method. The second PIN_FLD_BATCH_TYPE in this example is also a reversal batch type. Remember that while a payment batch only has data entry fields, a reversal batch can have display and data entry fields.

The first PIN_FLD_PURPOSE, with a value of 1 indicates that this field is read-only. The second PIN_FLD_PURPOSE value is 0, indicating that data can be entered in this field. In other words, you cannot enter information in "Credit Card No.", but you can enter a value for "Chargeback Date". PIN_FLD_FIELD_NAME is the database field name, not the column name (PIN_FLD_COLUMN_NAME).

The values in brackets, [0], [1], and [2] are index values dealing with the sequence of fields.

1 PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [0] allocated 3, used 3
2   PIN_FLD_BATCH_TYPE       INT [0] 1
2   PIN_FLD_COLUMN_NAME      STR [0] "Credit Card No."
2   PIN_FLD_FIELD_NAME       STR [0] "PIN_FLD_DEBIT_NUM"
2   PIN_FLD_PURPOSE          INT [0] 1
1 PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [1] allocated 3, used 3
2   PIN_FLD_BATCH_TYPE       INT [0] 1
2   PIN_FLD_COLUMN_NAME      STR [0] "Chargeback Date"
2   PIN_FLD_FIELD_NAME       STR [0] "PIN_FLD_EFFECTIVE_T"
2   PIN_FLD_PURPOSE           INT [0] 0

Changing the Order of Columns in Payment Tool

The sequence of fields, PIN_FLD_PAYMENTTOOL_FIELDS, determines the order of columns in Payment Tool. If you are not satisfied with the default settings and you want to add another column of information or change a column name, you must customize Payment Tool. To do this, you must change the /event/billing/payment, /event/billing/reversal, and /config/paymenttool objects.

To change the order of the columns, you must change the order of PIN_FLD_PAYMENTTOOL_FIELDS arrays in /config/paymenttool because the column order is determined by the order in which they appear in this object.

In the following example, the three configurable, user-defined columns are in the order:

• Credit Card No.

• Chargeback Date

• Reason Code

0 PIN_FLD_PAY_TYPES       ARRAY [10003] allocated 5, used 5
1   PIN_FLD_NAME                STR [0] "Credit Card"
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [0] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Credit Card No."
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_DEBIT_NUM"
2      PIN_FLD_PURPOSE            INT [0] 1
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [1] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Chargeback Date"
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_EFFECTIVE_T"
2      PIN_FLD_PURPOSE            INT [0] 0
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [2] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Reason Code"
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_REASON_CODE"
2      PIN_FLD_PURPOSE             INT [0] 0

To change the order of the columns in Payment Tool, you must change the order of each array. In the following example, the columns are in the order:

• Credit Card No.

• Reason Code

• Chargeback Date

0 PIN_FLD_PAY_TYPES      ARRAY [10003] allocated 5, used 5
1   PIN_FLD_NAME                STR [0] "Credit Card"
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [0] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Credit Card No."
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_DEBIT_NUM"
2      PIN_FLD_PURPOSE            INT [0] 1
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [1] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Reason Code"
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_REASON_CODE"
2      PIN_FLD_PURPOSE            INT [0] 0
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [2] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Chargeback Date"
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_EFFECTIVE_T"
2      PIN_FLD_PURPOSE             INT [0] 0

Adding a New Column to Payment Tool

To add a new column to Payment Tool, you add a new column section to an array in /config/paymenttool. The new section contains information needed for that column.

The following example shows the information for a Customer Complaint column:

1 PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [0] allocated 3, used 3
2   PIN_FLD_BATCH_TYPE          INT [0] 1
2   PIN_FLD_COLUMN_NAME         STR [0] "Customer Complaint"
2   PIN_FLD_FIELD_NAME          STR [0] "PIN_FLD_COMPLAINT"
2   PIN_FLD_PURPOSE              NT32 [0] 1

Adding Direct Debit Details to the Customer Center Payments Tab

By default, the Customer Center Payments tab does not display details from payment vendors on whether direct debit payments were authorized. To have the direct debit details added to the Payments tab, add the direct debit fields to the PIN_FLD_PAY_TYPES array of the /config/paymenttool class.

1. Use the PCM_OP_WRITE_FLDS opcode to add the direct debit vendor details to the /config/paymenttool class. Call the opcode using flag 32. For example:

   0 PIN_FLD_POID POID [0] 0.0.0.1 /config/paymenttool 10574 0 
   0 PIN_FLD_OP_CORRELATION_ID STR [0] "2:CT1255:UnknownProgramName:0:AWT-EventQueue-0:5:1226568418:0:root.0.0.0.1::user1:123456789" 
   0 PIN_FLD_PAY_TYPES ARRAY [10005] allocated 2, used 2 
   1    PIN_FLD_NAME STR [0] "Direct Debit" 
   1    PIN_FLD_PAYMENTTOOL_FIELDS ARRAY [4] allocated 4, used 4 
   2       PIN_FLD_BATCH_TYPE INT [0] 0 
   2       PIN_FLD_COLUMN_NAME STR [0] "Authorization Result" 
   2       PIN_FLD_FIELD_NAME STR [0] "PIN_FLD_RESULT" 
   2       PIN_FLD_PURPOSE INT [0] 9 
   0 PIN_FLD_POID POID [0] 0.0.0.1 /config/paymenttool 10574 0 
   0 PIN_FLD_OP_CORRELATION_ID STR [0] 
   "2:CT1255:UnknownProgramName:0:AWT-EventQueue-0:5:1226568418:0:root.0.0.0.1::user1:123456789" 
   0 PIN_FLD_PAY_TYPES ARRAY [10005] allocated 2, used 2 
   1    PIN_FLD_NAME STR [0] "Direct Debit" 
   1    PIN_FLD_PAYMENTTOOL_FIELDS ARRAY [5] allocated 4, used 4 
   2       PIN_FLD_BATCH_TYPE INT [0] 0 
   2       PIN_FLD_COLUMN_NAME STR [0] "Authorization Code" 
   2       PIN_FLD_FIELD_NAME STR [0] "PIN_FLD_AUTH_CODE" 
   2       PIN_FLD_PURPOSE INT [0] 9 
   0 PIN_FLD_POID POID [0] 0.0.0.1 /config/paymenttool 10574 0 
   0 PIN_FLD_OP_CORRELATION_ID STR [0] "2:CT1255:UnknownProgramName:0:AWT-EventQueue-0:5:1226568418:0:root.0.0.0.1::user1:123456789" 
   0 PIN_FLD_PAY_TYPES ARRAY [10005] allocated 2, used 2 
   1    PIN_FLD_NAME STR [0] "Direct Debit" 
   1    PIN_FLD_PAYMENTTOOL_FIELDS ARRAY [6] allocated 4, used 4 
   2       PIN_FLD_BATCH_TYPE INT [0] 0 
   2       PIN_FLD_COLUMN_NAME STR [0] "Vendor Results" 
   2       PIN_FLD_FIELD_NAME STR [0] "PIN_FLD_VENDOR_RESULTS" 
   2       PIN_FLD_PURPOSE INT [0] 9 
   0 PIN_FLD_POID POID [0] 0.0.0.1 /config/paymenttool 10574 0 
   0 PIN_FLD_OP_CORRELATION_ID STR [0] "1:MCHELLAM-idc:UnknownProgramName:0:AWT-EventQueue-0:5:1226568418:0" 
   0 PIN_FLD_PAY_TYPES ARRAY [10005] allocated 2, used 2 
   1    PIN_FLD_NAME STR [0] "Direct Debit" 
   1    PIN_FLD_PAYMENTTOOL_FIELDS ARRAY [7] allocated 4, used 4 PIN_FLD_BATCH_TYPE INT [0] 0 
   2       PIN_FLD_COLUMN_NAME STR [0] "Authorization Date" 
   2       PIN_FLD_FIELD_NAME STR [0] "PIN_FLD_AUTH_DATE" 
   2       PIN_FLD_PURPOSE INT [0] 9 
   

2. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

   Note:

   All changes you make in /config/paymenttool are reflected in the Customer Center UI when you restart BRM.

Customizing the Date Format of Batch Files in Payment Tool

By default, when processing both imported and manually created batch files, Payment Tool uses the date format of the system locale of the client on which it is running. For example, if the locale is United States English, Payment Tool uses MM/dd/yyyy format. If the locale is New Zealand English, Payment Tool uses dd/MM/yyyy format.

To configure Payment Tool to use a different date format from the one used by your client system:

1. Open the Payment Tool INI file (C:\Windows\PaymentTool.ini).

2. In the file, find this entry:

   DefaultDateFormat=
   

3. Set the entry to the appropriate date format.

   Possible values:

   • MM[sc]dd[sc]yyyy

   • dd[sc]MM[sc]yyyy

   where [sc] is the date separator character, such as slash (/) or dot (.), specified in the regional settings of the Windows client.

   Important:

   The values are case sensitive.

   For example:

   DefaultDateFormat=dd/MM/yyyy
   

   If no date format is specified, Payment Tool uses the default format of the system locale.

You do not need to exit Payment Tool after updating the INI file; the change takes effect the next time you create or import a payment batch.