Managing Deposits

19 Managing Deposits

Learn how to manage your customers’ deposits in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

About Deposits

Deposits are security amounts you can collect from customers to help avoid credit risks.

For example, you might want a customer deposit option for plans that include a modem or other equipment, or for international roaming plans.

About Configuring Deposits

Using Oracle Communications Billing Care, you create deposit specification profiles and deposit specifications that define rules and properties for deposits you create for customers. A specification includes a specification profile. An individual customer deposit includes a specification.

Each specification includes a single specification profile, but you can use the same profile with multiple specifications. You can use the same specification for any number of customer deposits.

Deposit specification profiles define the common business rules for the deposits in your organization, including:

Validity end date: The date after which the deposit specification profile is no longer available for creating new deposit specifications. The profile doesn't expire for specifications already using it.
Release type: The default for releasing a deposit to the customer after its validity expires. The options are prepayment and refund.
Refunds: If refunds are allowed, if they need approval, and if there are associated fees.
Transfers: Ability to transfer a deposit amount between the accounts.
Overrides: Whether CSRs can override the configured charge at the time of purchase.
Exemptibility: If CSRs can waive the deposit.
Interest: If the deposit accrues interest, and the details of the interest amount and how it's calculated.

Deposit specifications define the charging and billing behavior for deposits, including:

Type: Whether the specification is for accounts, devices, packages, or services.
Charge offer: A charge offer with the purchase deposit event that determines the charge for deposits.
Validity end date: The date after which the deposit specification is no longer available for creating deposits.
Billing: Whether the deposit is billed immediately or with the next bill.
Credit limit: Whether to enable increasing a customer's credit limit on the deposit amount.

When creating the deposit specification, you can save it as a draft. You can modify or delete draft specifications. A specification needs to be in active status before you can use it to create deposits, and you can't modify or delete active specifications. After a specification's end date is past, its status is expired.

About Creating and Managing Customer Deposits

Use Billing Care or a custom client application calling BRM deposit opcodes to work with customer deposits. For more information, see:

"Deposits" in Billing Care Online Help
"Deposit Opcode Workflows" in BRM Opcode Guide

To create deposits, you need a package or bundle containing a charge offer that has a purchase deposit event mapped to the charging rule of the deposit. Customers then purchase the package, bundle, or device with the deposit charge offer.

For example, a package or bundle includes a $50 per month connection fee, an iPhone, and a $500 security deposit. After the package is purchased, BRM charges the $50 connection fee and the $500 deposit.

If you use a custom client application instead of Billing Care, call the PCM_OP_DEPOSIT_PURCHASE_DEPOSIT opcode to purchase the deposit and charge the customer.

About Deposit Payments

Customers can pay for deposits in the following ways:

Pay all or part of the deposit amount immediately.
Pay the amount with the next billing cycle. In this case, the entire deposit amount is billed with other charges in the next bill on the customer’s next billing day. A customer pays the bill as part of their regular bill payment.
Pay with an advance payment. If a customer already has a payment credit in the account from a previous overpayment, they can use that to pay for the deposit.

Customers can also use a combination of these methods. For example, they can pay a $50 deposit from a $30 advanced payment and a $20 credit card payment.

After purchasing the deposit, payments can be made for an already purchased but partially paid deposit, using standard BRM payment functionality.

About Deposit Reversals

If a deposit is purchased by mistake, you can reverse the deposit amount in Billing Care or by using the PCM_OP_DEPOSIT_REVERSE_DEPOSIT opcode.

After the deposit is reversed, the charge is negated with a credit of an equal amount. If any payment is made towards the deposit, the payments are available as credit. Customers can use the credit to pay other charges or you can refund it.

Note:

Ensure that the deposit is reversed as soon as possible after it is created or purchased. You can't reverse transactions after releasing or transferring a deposit, or after interest is calculated.

About Interest Calculations

BRM calculates deposit interest according to the rules set in deposit specification profiles. Deposits can use one of three types of interest calculations:

Simple: The interest is calculated on the principal deposit amount.
Compound: The interest is calculated on the principal deposit amount plus the already accumulated interest.
Absolute: The interest is a specified amount instead of a percentage.

In deposit specification profiles, you set a percentage or amount, how often interest is calculated, whether to calculate interest on partial payments, and optionally a G/L ID for tracking interest payments.

You can calculate interest using the pin_deposit_calc_interest MTA application in the billing job. This utility calls the PCM_OP_DEPOSIT_ADD_INTEREST opcode to calculate interest

Note:

When you release or transfer part or all of a deposit, interest is calculated on the released or transferred amount.

About Transferring Deposits

You can transfer a customer’s deposit amount from one service or account to another service or account. You can do this using Billing Care or the PCM_OP_TRANSFER_DEPOSIT opcode. When the transfer happens, BRM closes the deposit from which the amount is transferred and creates a new deposit.

For example, a customer purchases a plan or service. After a few months, you cancel the service and give the customer the option to either transfer the deposit amount to pay for another service under the same account or transfer the amount to another account, maybe to a friend or family member.

About Transferring Multiple Deposits Simultaneously

You can transfer multiple deposits simultaneously to other accounts or services. For example, if a service has been stopped, multiple customers subscribing to that service might want to transfer their deposit amount to another service.

This type of transfer is called a bulk transfer and runs as a batch job from the command line. The batch file for the bulk transfer defines the purchased deposits involved in the transfer. The file is in CSV format and is typically supplied by an external source program. Bulk transfers use the BRM multithreaded application (MTA) framework to process the batch file and perform the transfers defined in this file for each listed deposit. For information on the MTA framework, see "About the BRM MTA Framework" in BRM Developer's Guide.

When BRM processes a bulk transfer, it performs each transfer as a separate transaction. Therefore, there is no need to roll back the successful transfers if some transfers fail. BRM reports any deposit transfers that failed the bulk transfer in a log file so that you can examine them and correct the problem.

About CSV Files for Bulk Deposit Transfers

For a bulk transfer, you generate a CSV file that lists each deposit being transferred. BRM creates an input flist for each transfer in the CSV file.

Create a standard CSV file with commas as field delimiters, line breaks as record delimiters, and no blank lines. Use the following format for each record:

purchased_deposit_POID, target_account_POID, target_billinfo_POID, target_service_POID, transfer_amount

In this record:

These fields are required: purchased_deposit_POID, target_account_POID or target_service_POID, and transfer_amount. Make sure to include a comma for each omitted field.
If you omit target_billinfo_POID, BRM transfers the deposit to the account.

This is an example of records from a CSV file for bulk transfers:

0.0.0.1 /purchased_deposit 1702640 0, 0.0.0.1 /account 1720950 0, 0.0.0.1/billinfo 1724022 0, 0.0.0.1 /service 1727894 0, 1500

0.0.0.1 /purchased_deposit 1726823 0, 0.0.0.1 /account 17355482 0, 0.0.0.1 /billinfo 1732794 0, 0.0.0.1 /service 1724901 0, 10000

The first record in this example shows a transfer of 1500 to the target account.

Check the CSV file you create for format problems and spurious blank lines.

Running a Bulk Deposit Transfer

To do a bulk deposit transfer, run the pin_deposit_transfer_deposit utility with the CSV file you created.

Note:

To connect to the BRM database, pin_deposit_transfer_deposit needs a configuration file in the BRM_home/apps/pin_deposits/pin_deposit_transfer_deposit directory. Run pin_deposit_transfer_deposit from this directory.

Run the following command:

 pin_deposit_transfer_deposit -f input_file.csv

If the CSV file is not in your working directory, use the full path to the file.

 pin_deposit_transfer_deposit -f /files/bulk_transfer/input_file.csv

Check the ${PIN_LOG_DIR}/pin_deposits/pin_deposit_transfer_deposit.pinlog file for any failed transfers.

The bulk deposit transfer application generates an intermediate file in flist format. The default name of this file is pin_mta_search.flist.

About Releasing Deposits

If a service is canceled or the deposit is about to reach the end of its validity period, the subscriber can get back the deposit amount. You set this up in deposit specification profiles, using Billing Care or the PCM_OP_RELEASE_DEPOSIT opcode.

You can release deposits in one of the following ways:

Convert to prepayments: All or part of the deposit pays other billed charges. Customers can use any extra amount to pay off future billed charges.
Refunds: You refund the deposit to customers using standard payment methods. If the deposit specification is configured to require a refund review, then the refund request must be approved before you can issue it. You can use Billing Care or the PCM_OP_DEPOSIT_UPDATE_REFUND_REQUEST opcode to approve or reject a refund request.
Zeroize: You can release the customer deposit if you need to settle a customer's account balance. For example, when a service is disconnected, the customer might want to close the account and settle the account balance. When this happens, the entire deposit amount is refunded to the subscriber after settling any billed and unbilled balances. The account balance then becomes zero.

This method is not available in Billing Care.

About Refunding Deposits

BRM refunds deposits based on their configurations and release types.

Before refunding the deposit amount, validations are performed and, if required, an authorized person approves the refund request after reviewing it.

If any deposits have refund handling fees, the transaction is recorded to the G/L ID, a charge is applied on the deposit, the refund fee is deducted from the deposit amount, and the remaining amount is refunded to the customer.

About the Deposit Utilities

The deposit utilities perform the following actions:

pin_deposit_calc_interest: Finds the purchased deposits for which interest must be calculated, then calculates the interest amount based on the specified interest type and frequency.
pin_deposit_transfer_deposit: Transfers the deposit balance to a specified account or service.
pin_deposit_release_purchased_deposit: Searches purchased deposits whose end date is less than the current system date and releases the deposit amount based on the release type.

See "Customer Management Utilities".

Updating Deposits

You can update the following in an existing deposit:

Validity: For example, you can change the validity period from 6 months to 3 months by changing the end date.
Release type: For example, you can change the release type from prepayment to refund.

You can update using Billing Care or the PCM_OP_DEPOSIT_UPDATE_DEPOSIT opcode.

You can also use PCM_OP_DEPOSIT_UPDATE_DEPOSIT to update the deposit amount. If the deposit amount needs to be increased or decreased, the system reverses the old deposit and purchases a new deposit with the new amount. Any payment collected for the old deposit is allocated to the new deposit. If the new deposit amount is larger and the previous payment insufficient, you collect an additional payment. See "About Deposit Payments".

You can't update the amount in Billing Care.

Any additional deposit amount that remains after allocation is refunded to the customer or allocated against any other billed charges through standard BRM business processes.

Note:

Ensure that the deposit is updated as soon as possible after it is created or purchased. No transactions can be reversed after a deposit is released or transferred or if the interest is calculated. This can also cause bad debt to the service providers.

Setting up Your System to Support Deposits

To set up BRM to support deposits, do the following:

Create deposit specification profiles, deposit specifications, and deposits in Billing Care or your third-party tool. See "Deposits" in Billing Care Online Help.
Create nightly cron jobs to run the following utilities:
- pin_deposit_release_purchased_deposit. See "About Releasing Deposits".
- pin_deposit_calc_interest. See "About Interest Calculations".
- pin_deposit_transfer_deposit. See "About Transferring Deposits".
Customize the deposit process as needed by using the deposit policy opcodes. See "Customizing Deposit Management".

Customizing Deposit Management

You can customize deposit management with policy opcodes in these ways:

Validate and implement deposit specification profile information by using the PCM_OP_DEPOSIT_POL_VALID_SPECIFICATION_PROFILE policy opcode.
Validate and implement deposit specification information by using the PCM_OP_DEPOSIT_POL_VALID_SPECIFICATION policy opcode.
Validate and implement any customizations while purchasing a deposit by using the PCM_OP_DEPOSIT_POL_VALID_PURCHASE_DEPOSIT policy opcode.
Validate and implement any customizations while updating a deposit by using the PCM_OP_DEPOSIT_POL_VALID_UPDATE_DEPOSIT policy opcode.
Validate and implement any customizations while collecting the deposit payments by using the PCM_OP_DEPOSIT_POL_VALID_COLLECT_PAYMENT policy opcode.
Validate and implement any customizations while reversing the deposit by using the PCM_OP_DEPOSIT_POL_VALID_REVERSE_DEPOSIT policy opcode.
Validate and implement any customizations while releasing the deposit by using the PCM_OP_DEPOSIT_POL_VALID_RELEASE_DEPOSIT policy opcode.
Validate and implement any customizations while transferring the deposit by using the PCM_OP_DEPOSIT_POL_VALID_TRANSFER_DEPOSIT policy opcode.
Modify the effective date for calculating interest for the purchased deposit by using the PCM_OP_DEPOSIT_POL_PRE_ADD_INTEREST policy opcode. Modify the calculated interest amount and interest period as needed with the PCM_OP_DEPOSIT_POL_POST_ADD_INTEREST policy opcode.
Validate and implement any customizations while requesting a refund of the deposit amount by using the PCM_OP_DEPOSIT_POL_VALID_REFUND_REQUEST policy opcode.

For more information, see "Deposit Opcode Workflows" in BRM Opcode Guide.

Specifying the Minimum Deposit Amount to Refund

You can specify the minimum amount to provide as a refund. The deposit refund action validates the configuration if an amount is greater than the amount you specified.

The minimum value is expressed in terms of the account currency. By default, the minimum amount is 0.

Open the CM configuration file (BRM_home/sys/cm/pin.conf) in a text editor.
Change the value of the MinimumRefundValue entry. For example, to process refund items only for amounts greater than 0:
```
- fm_deposit_pol MinimumRefundValue 10.00 
```
Save the file.

You do not need to restart the CM to enable this entry.

Specifying the Minimum Days to Refund after Account Closure

You can specify the minimum number of days to refund a deposit after closing an account or service. The deposit refund action validates the configuration days. The refund request will be raised only if the current date is less than the number of days of the account or service termination date.

The minimum value is expressed in terms of days. By default, the minimum number of days is 0.

Open the CM configuration file (BRM_home/sys/cm/pin.conf) in a text editor.
Change the value of the RefundMechanismStartDays entry. For example, to process the refund items only 3 days after the service closure date:
```
- fm_deposit_pol RefundMechanismStartDays 3 
```
Save the file.

You do not need to restart the CM to enable this entry.