Configuring Top-Ups

19 Configuring Top-Ups

Learn how to configure and implement top-ups in Oracle Communications Billing and Revenue Management (BRM).

Topics in this document:

Important:

Most top-up implementation tasks require a custom application. See "Managing Top-Ups" in BRM Opcode Guide.

About Standard Top-Ups

A standard top-up is a top-up that a customer makes to his or her own account. BRM supports the following types of standard top-ups:

Manual standard top-ups are initiated by a customer service representative (CSR) using a client application or by your customers using a self-care application.

Manual top-ups can occur at any time and can be performed on any account. They can be used to add assets to credit balances or to debit balances.
Automatic standard top-ups are initiated by ECE. They occur when a resource balance falls below a specified threshold amount.

To use automatic standard top-ups, an account must have one or more services that are configured for top-ups. In addition, an automatic standard top-up payment method, amount, and cap must be set for the account.
Recurring standard top-ups are initiated by the pin_balance_transfer utility when run with the -standard parameter.

To use recurring standard top-ups, an account must have one or more services that are configured for top-ups. In addition, a recurring standard top-up payment method, the top-up resource, the interval between recurring top-ups, and the number of recurring top-ups to make must be set for the account.

Customers can use the following payment methods for standard top-ups:

Cash or check (manual standard top-ups for topping up currency balances only)
Credit card or direct debit (manual, automatic, and recurring standard top-ups for topping up both currency and noncurrency balances)

When a customer uses a payment card to top up his account, BRM interacts with a credit card agency or direct debit company to collect payment.
Voucher (manual and recurring standard top-ups for topping up both currency and noncurrency balances)

When a customer uses a voucher, such as a prepaid phone card, to top up his account, the BRM API interacts with a voucher management system to validate the voucher and payment amount.

A voucher can be used to top up one or more balances in a specified balance group (you cannot allocate a voucher's balances to multiple balance groups). The balances can include one currency balance and an unlimited number of noncurrency balances. Top-ups for currency balances are added to the existing currency sub-balance, which maintains its original validity period. Top-ups for noncurrency balances are added to sub-balances according to their validity period.

About Taxes Applied During Voucher Top-Ups

By default, when you apply a voucher with tax to an account, BRM applies a negative balance impact to the account balance.

When you apply a voucher with tax to an account, you must set the tax to a negative value. For example, if a voucher grants $100 with -10% tax on the amount granted, BRM applies a balance impact of -100 for the voucher and +10 for the tax to the account balance. In this case, the final balance is 0 - (-100) - (+10) = $90.

Performing Recurring Standard Top-Ups

Recurring standard top-ups are initiated by the pin_balance_transfer utility. When run with the -standard parameter, the utility finds all accounts in your system with a recurring top-up and a top-up date of today.

To perform recurring standard top-ups, go to the BRM_home/apps/pin_balance_transfer directory and run the following command:

pin_balance_transfer -standard

For more information about the utility, see "pin_balance_transfer".

Reversing Voucher Top-Ups

When a voucher is associated with an account balance, its state becomes used and it cannot be associated with another account or balance group. Thus, although its impact on the balance to which it was applied can be reversed, its assets cannot be reapplied to another account or balance group.

If a voucher has only noncurrency balances, an /event/billing/vouchertopup event is generated when the voucher is associated with an account. To reverse the balance impact of this event, you must perform an adjustment.

If a voucher has currency and noncurrency balances, an /event/billing/payment/voucher event is generated when the voucher is associated with an account. To reverse the balance impact of this event, you must use testnap to perform a payment reversal.

About Vouchers Having Noncurrency Balances with a Positive Impact

By default, when you apply a voucher with noncurrency balances to an account, a negative balance impact is applied to the account balance. For example, if a voucher grants 30 minutes, a balance impact of -30 is applied to the customer's account balance. As the customer uses the minutes, the account balance approaches 0. For example, if the customer uses 20 of the 30 minutes, the account balance becomes -10. In this case, the noncurrency balance has a credit limit of 0 by default, or it can be changed to a negative value.

To have vouchers with noncurrency balances apply a positive balance impact to account balances, you must set the balance's credit limit to a positive nonzero value. For example, you must set the minutes balance to +2.

To set the credit limit for noncurrency balances to a positive value, perform one of the following:

Specify the credit limit in your package.
Specify the credit limit in an account.

About Sponsored Top-Ups

A sponsored top-up is a top-up that is performed by transferring assets from a balance group in one account to a balance group in another account. For example, a mother can top up her teenage son's account with a $50 payment from her account. Assets can be transferred from a debit balance to a credit balance or a debit balance.

BRM supports two types of sponsored top-ups:

Manual sponsored top-ups are initiated by a CSR using a custom client application or by your customers using a custom self-care application.

To receive manual sponsored top-ups, an account must be a member of a sponsored top-up group. For more information, see "About Sponsored Top-Up Groups".
Automatic sponsored top-ups are initiated by the "pin_balance_transfer" utility at intervals (such as daily, weekly, or monthly) and in amounts that you specify.

To receive automatic sponsored top-ups, an account must be a member of a sponsored top-up group. In addition, an automatic sponsored top-up amount must be specified for the group, and an automatic sponsored top-up frequency must be specified for the member account. For more information, see "About Sponsored Top-Up Groups".

Sponsored top-ups cannot be made between the following accounts:

Accounts with different primary currencies
Accounts in different database schemas in a BRM multischema system

About Sponsored Top-Up Groups

To top up other accounts, an account must own a sponsored top-up group. An account can own multiple sponsored top-up groups.

To receive top-ups from a group owner account, an account must be a member of one of the owner's sponsored top-up groups.

An account can be a member of only one sponsored top-up group at a time.

Note:

An account should be either a sponsored top-up group owner or member. It should not be both. If an account both owns sponsored top-up groups and belongs to one or more sponsored top-up groups, its accounts receivable (A/R) data may become inaccurate.

All accounts that belong to a sponsored top-up group have one of the member statuses shown in Table 19-1:

Table 19-1 Sponsored Top-Up Group Member Statuses

Status	Description
Active	Member account can receive top-ups from the group owner account.
Inactive	Member account's top-ups from the owner account are suspended, but member cannot join another sponsored top-up group.
Closed	Member account no longer receives top-ups from the group owner account. Member can join another sponsored top-up group.

Only member accounts whose member status is active can receive sponsored top-ups.

Each member account in a sponsored top-up group can be assigned a top-up PIN (personal identification number). A top-up PIN is required to authorize all manual sponsored top-ups requested by the member.

About Sponsored Top-Up Credit Limits

Sponsored top-ups are subject to the following credit limits. When either credit limit is reached, the account cannot make any more sponsored top-ups until the credit balance is reduced.

Credit limit of owner account's paying balance group

This credit limit controls the amount of currency and noncurrency debits that can accumulate in the owner's paying balance group.
Credit limit of group balance

Each balance supported by a sponsored top-up group has a group top-up cap. The cap specifies the maximum amount of the balance that the owner account can transfer to its members during each of the owner account's accounting cycles.

The cap applies to the sum of all top-ups associated with the group, not to an individual member's top-ups.

Note:

Member accounts do not have individual sponsored top-up credit limits.

Performing Automatic Sponsored Top-Ups

Automatic sponsored top-ups are initiated by the "pin_balance_transfer" utility. The utility triggers such top-ups for all member accounts in your system whose next automatic top-up date is within the time range specified in the utility's command-line parameters.

To run the "pin_balance_transfer" utility, use a cron job with a crontab entry. The following crontab entry runs pin_balance_transfer at 1:00 a.m. daily:

0 1 * * * BRM_home/bin/pin_balance_transfer &

Tracking Sponsored Top-Up Adjustments

To differentiate sponsored top-up adjustments (/event/billing/adjustment/account objects) from other types of account adjustments, the reasons.locale file includes the following reason codes and domain IDs:

Sponsored top-up debit reason code 4 and domain ID 1

DOMAIN = "Reason Codes-Debit Reasons" ;
STR
    ID = 4 ;
    VERSION = 1 ;
    STRING = "Sponsored Topup. Sponsor Debit" ;
    EVENT-GLID
        "/event/billing/adjustment/account"    105 ;
    EVENT-GLID-END
END

Sponsored top-up credit reason code 5 and domain ID 8

DOMAIN = "Reason Codes-Credit Reasons" ;
STR
    ID = 5 ;
    VERSION = 8 ;
    STRING = "Sponsored Topup. Sponsoree Credit" ;
    EVENT-GLID
        "/event/billing/adjustment/account"    105 ;
    EVENT-GLID-END
END

The following definitions for these new reason codes and domain IDs are in the pin_pymt.h file in the BRM_home/include directory:

Sponsored top-up reason code definitions

#define PIN_REASON_ID_TOPUP_CREDIT    5
#define PIN_REASON_ID_TOPUP_DEBIT     4

Sponsored top-up reason domain ID definitions

#define PIN_PYMT_TOPUP_CREDIT_REASON_DOMAIN_ID    8
#define PIN_PYMT_TOPUP_DEBIT_REASON_DOMAIN_ID     1

You can customize the default reason codes used for sponsored top-up adjustments as follows:

Change the G/L ID event mapping. (If you change the G/L ID mapping, be sure the G/L IDs you define in the reasons.locale and pin_glid files match).
Change the reason code domain identifier (version number).
Change the reason string.

To customize the default reason codes, edit the reasons.en_US sample file in the BRM_home/sys/msgs/reasoncodes directory.

To load the contents of the customized reasons.en_US file into the /strings and /config/map_glid objects, use the load_localized_strings utility.

To run the load_localized_strings utility, use this command:

load_localized_strings reasons.locale

For more information about loading the reasons.locale file and creating new strings for it, see "Loading Localized or Customized Strings" and "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.

Canceling a Single Member's Sponsored Top-Ups

To stop sponsored top-ups temporarily, inactivate the top-up group members.

To cancel a member account's sponsored top-ups, change the member's group status to closed. When the member's group status is closed, the account can use any outstanding topped-up credit in its topped-up balance group, but it can no longer receive sponsored top-ups from the group. It can, however, join another sponsored top-up group.

By default, only the group owner can change a member's group status to closed. To enable members to close their group status themselves, customize the PCM_OP_CUST_POL_PREP_TOPUP policy opcode.

To change a member's group status to closed:

Use your custom client application to call PCM_OP_CUST_SET_TOPUP.
Set the member's PIN_FLD_STATUS field in the PIN_FLD_GROUP_TOPUP_MEMBERS array of the opcode's input flist to the value associated with the PIN_STATUS_CLOSED status in the BRM_home/include/ops/pcm.h header file.

Note:

This changes only the member's group status. It does not change the member's account status.

You can also cancel a member account's sponsored top-ups by changing the account status of the member to closed. By default, when a member account is closed, its sponsored top-up group member status is set to closed. To change the status of an account, see "Changing Account and Service Status" in BRM Managing Customers.

Note:

When a member account is closed, any outstanding topped-up credit that it has is forfeited, not transferred back to the group owner account or refunded to either the owner or the member. Even if the member account's sponsored top-ups are reactivated, the forfeited credit is not reinstated.

Topping Up Accounts in Customer Center

Manual standard top-ups are performed by a CSR using a client application such as Customer Center or by a customer using a self-care application such as Self-Care Manager.

Changing the Default Top-up Payment Method

The default top-up payment method in Customer Center is voucher. To change this default, add the following parameter to the CCSDK_home/CustomerCareSDK/CustCntr/custom/Customized.properties file:

customized.default.topup.payment.method = payment_method

where payment_method is one of these values:

ONFILE (Payment method on file)
ONETIME (One-time credit card)
VOUCHER (Voucher)

Note:

If this parameter is not included in the file, voucher is the default payment method.

For information about modifying the Customized.properties file, see "Modifying Behaviors Defined by the Default Properties Files" in BRM Developer's Guide.

Turning off "Top-up Completed" Message

By default, Customer Center displays the message "Top-up completed" after you complete a top-up. If you typically perform multiple top-ups in a row and do not want to close this message after each of them, you can prevent the message from appearing. To do so, set the following parameter in the CCSDK_home/CustomerCareSDK/CustCntr/custom/Customized.properties file to true:

customized.turn.off.topup.completed.msg = true

By default, this parameter is set to false.

For information about modifying the Customized.properties file, see "Modifying Behaviors Defined by the Default Properties Files" in BRM Developer's Guide.

Canceling an Entire Group's Sponsored Top-Ups

To cancel the sponsored top-ups of every member in a group, change the account status of the sponsored top-up group owner to closed. By default, when the owner account is closed, the member status of its member accounts is set to closed.

To change the status of an account, see "Changing Account and Service Status" in BRM Managing Customers.

Reinstating Sponsored Top-Ups

When an account's sponsored top-up group member status is set to closed, its array element is not removed from the PIN_FLD_GROUP_TOPUP_MEMBERS array in the /group/topup object with which it was associated.

If you later reactivate the member's status and want to use its old MEMBERS array element, the client application must pass the called opcode the same receiving balance group POID that was used the last time the member belonged to the group. Otherwise, a new array element will be created for the member account.

Note:

If a lot of members have multiple MEMBERS array elements, your system's performance may be affected.

Voucher Top-Up Errors

Table 19-2 lists the default error messages that are displayed in Customer Center when errors associated with the corresponding error type and field name occur.

Table 19-2 Default Error Messages in Customer Center for Top-Ups

Error Message	Error Type	Field Name
Voucher has already been used	ERR_NOT_FOUND	PIN_FLD_EXTENDED_INFO
Invalid voucher ID/PIN combination	ERR_NOT_FOUND	PIN_FLD_POID
Voucher has already been used or has expired	ERR_BAD_VALUE	PIN_FLD_STATE_ID
Voucher has expired	ERR_BAD_VALUE	PIN_FLD_EXPIRATION_T
Invalid voucher ID/PIN combination	ERR_BAD_ARG	PIN_FLD_VOUCHER_PIN
Voucher has already been used or has expired	ERR_BAD_ARG	PIN_FLD_STATE_ID