Running Payment Collection Utilities

1 Running Payment Collection Utilities

Learn how to use the pin_collect and pin_deposit utilities to collect and deposit your customers' payments in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

See also "Overview of Payments" in BRM Concepts.

About the Payment Collection Utilities

You use the following utilities to collect payments from your customers:

pin_collect collects the balance due for bills that are paid by credit card or direct debit.
pin_deposit deposits pre-authorized credit card payments and PINless debit payments into your account.

The pin_collect utility performs credit card authorizations and payment deposits at the same time. The pin_deposit utility only deposits credit card payments that have been pre-authorized.

You typically run the pin_collect and pin_depost utilities in the same scripts that run other billing utilities. See "Running Billing Scripts" in BRM Configuring and Running Billing.

If a payment fails, you can use the pin_clean utility and the pin_recover utility to resolve the failure. See "Resolving Failed BRM-Initiated Payment Transactions" for information.

Running the pin_collect Utility to Collect BRM-Initiated Payments

The pin_collect utility collects payments for bills whose payment collection date is on the day the utility is run or on the day before the utility is run. For example, if you run pin_collect on 01/01/23, payments are collected from 00:00:00 a.m. on 12/31/22 to 00:00:00 a.m. on 01/02/23.

Use the -start and -end parameters to collect payments on a range of dates.

Use the -rebill parameter to collect on any outstanding bills. Run this option in the weekly and monthly billing scripts.

Use the -pay_type parameter to collect payments for only one payment method, such as credit card or SEPA.

You can configure payment collection:

To increase billing performance, you run multiple threads of the pin_collect utility. See "Tuning the Number of Children for Billing Utilities" in BRM System Administrator's Guide.
By default, pin_collect does not collect amounts less than two dollars. To change the minimum amount, see "Specifying the Minimum Payment to Collect" in BRM Configuring and Running Billing.

For information about collecting payments for corrective bills, see "Billing Accounts By Using the pin_make_corrective_bill Utility" in BRM Configuring and Running Billing.

For information about the pin_collect utility syntax, see "pin_collect".

When to Run the pin_collect Utility

Run the pin_collect utility at the following times:

In the pin_bill_day script for all accounts. Run the pin_bill_accts utility before running the pin_collect utility.
In the pin_bill_week script with the -rebill option on all active accounts.
In the pin_bill_month script with the -rebill option on all closed/inactive accounts.

Note:

When you use multiple payment processors, you run this utility for each payment processor. See "Using More Than One Payment Processor".

You can also run the pin_collect utility manually to rebill accounts from a specific date.

Setting Start and End Dates for pin_collect

When any of the following conditions are met, the pin_collect utility collects payments for 2 days: the day before the utility is run and the day on which the utility is run:

The -start and -end parameters are not set (this is the default).
The -start and -end parameters are set to the same value.
The -start parameter is set to the current date, and the -end parameter is not set.

To collect payments only on the day you run pin_collect, set the -start parameter to 0. For example:

pin_collect -start 0

You can also specify exact start and end dates, and you can specify a number of days before the current date for the start and end time calculation. The pin_collect utility only processes bills with a collection date within the start and end date range.

Note:

For open item accounting, the end date of the bill is not used to determine whether the bill falls within the specified range and qualifies for collection: only the start date is used.

Running the pin_deposit Utility to Deposit BRM-Initiated Payments

The pin_deposit utility deposits pre-authorized credit card payments and PINless debit payments into your account.

Pre-authorization occurs in two cases:

When a customer specifies a credit card payment method.
When a CSR issues a charge in Billing Care or Customer Center.

For credit cards, the pin_deposit utility searches for all pre-authorized but unpaid credit card transactions made within the past 30 days (from yesterday), and then sends the credit card authorization codes and the transaction dates to the credit card processor for depositing.

For direct debit, the pin_deposit utility searches for all unpaid PINless debit transactions, and then sends the authorization codes, transactions dates, trace number, and method of payment (MOP) to the debit network for depositing.

To increase billing performance, run multiple threads of the pin_deposit utility. See "Tuning Billing Performance" in BRM System Administrator's Guide.

For information about the pin_deposit utility's syntax, see "pin_deposit".

When to Run pin_deposit

Run the pin_deposit utility daily as part of the pin_bill_day script.

You should run the pin_deposit utility daily because credit-card authorizations can expire. You can deposit pre-authorized payments after the authorization has expired, but the transactions cost more to process.

Note:

When you use multiple payment processors, you run this utility for each payment processor. See "Using More Than One Payment Processor".

To adjust performance, you can modify the scope of the search by using the -start and -end parameters to change the starting and ending dates of the search.

Using More Than One Payment Processor

You can use more than one payment processing Data Manager (DM) simultaneously to collect and validate payments. To use multiple payment processors, you must run the following utilities for each payment processor you use:

pin_collect
pin_deposit
pin_refund

These utilities are typically run by the following billing scripts:

pin_bill_day

By default, this script is scheduled to run pin_collect, pin_deposit, and pin_refund.
pin_bill_week

By default, this script runs pin_collect.
pin_bill_week

By default, this script runs pin_collect.

To modify the pin_bill* scripts to run the collect, deposit, and refund scripts for every payment processor:

Go to the BRM_home/bin directory and open the pin_bill* utility in a text editor.

Find the entries for the billing utility and add new entries that specify the additional payment processors.

For example, if you use dm_fusa and another payment processor, find these existing entries:

pin_refund -active -pay_type 10003 -vendor fusa
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
...
pin_collect -inactive -pay_type 10003 -vendor fusa
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
...
pin_deposit -pay_type 10003 -vendor fusa
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
...

And add entries to run the utility for each payment processor:

pin_refund -active -pay_type 10003 -vendor fusa
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
pin_refund -active -pay_type 10003 -vendor new_vendor
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
...
pin_collect -inactive -pay_type 10003 -vendor fusa
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
pin_collect -inactive -pay_type 10003 -vendor new_vendor
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
...
pin_deposit -pay_type 10003 -vendor fusa
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
pin_deposit -pay_type 10003 -vendor new_vendor
IF %ERR% EQU 0 IF %ERRORLEVEL% NEQ 0 SET ERR=%ERRORLEVEL%
...

Note:

There might be several sets of entries for each payment processor. Be sure to add new entries for each set of existing entries.