Skip Headers
Oracle® Communications Billing and Revenue Management Configuring and Collecting Payments
Release 7.5

E16712-08
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 Configuring Top-Ups

This chapter describes how to implement the Oracle Communications Billing and Revenue Management (BRM) top-up features.

Before reading this chapter, you should be familiar with the following topics:

About Topping Up Accounts

The BRM top-up features enable your customers to top up: add currency and non-currency resources to: balances in their own accounts or in other customer accounts.

BRM supports two types of top-ups:

About Standard Top-Ups

A standard top-up is a top-up that a customer makes to his or her own account. For example, a customer can top up her account balance with a $50 payment from her credit card.

BRM supports two types of standard top-ups:

  • Manual 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. For example, $100 can be added to an account balance by a CSR using Customer Center or by a customer using Self-Care Manager.

    Manual top-ups can occur at any time and can be performed on any account (no special account configuration is required). They can be used to add resources to credit balances or to debit balances. For example, a customer can add $50 to the balance associated with his prepaid mobile phone service to extend the life of the service, or he can use the top-up feature to lower the balance due on his next bill by making an early, instant payment to his account. For more information, see "Topping Up Accounts in Customer Center and Self-Care Manager".

  • Automatic standard top-ups

    Automatic standard top-ups are initiated by BRM, not by a CSR or a customer. They occur when an account balance falls below a specified threshold amount. When BRM rates a usage event and updates the account balance, it checks whether the balance dropped below the threshold. If it did, BRM automatically tops up the balance. For example, whenever a customer's balance falls below $20, BRM can charge her credit card $50 and credit the balance with that amount.

    To receive 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. For more information, see "Implementing Automatic Standard Top-Ups".

Standard Top-Up Payment Methods

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

  • Credit card or direct debit (manual and automatic standard top-ups)

    When a customer charges a top-up to her credit card or bank account, BRM automatically contacts a payment service for authorization through an application such as Paymentech. BRM then debits the credit card or bank account and tops up the customer's BRM account.

  • Voucher (manual standard top-ups only)

    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. The voucher management system can be Voucher Manager or a third-party voucher manager:

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

    For example, suppose on February 20 you apply a voucher with $50 and 100 free minutes to a balance group with a prepaid currency sub-balance of $10 that expires on March 30 and a free-minutes sub-balance of 100 with a validity period from February 1 to March 1. The balance group would now have:

    • One currency sub-balance of $60 that expires on March 30.

    • One free-minutes sub-balance of 100 with a validity period from February 1 to March 1.

    • One free-minutes sub-balance with a validity period from February 10 to the date specified in Pricing Center.

      Note:

      Vouchers can be used for manual standard top-ups only. They cannot be used for automatic standard top-ups because a voucher ID and PIN must be manually entered when a voucher top-up is performed.

About Sponsored Top-Ups

A sponsored top-up is a top-up that is performed by transferring resources 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. Resources 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

    Manual sponsored top-ups are initiated by a CSR using a custom client application or by your customers using a custom self-care application. For example, $50 might be transferred from a mother's account to her son's account. Like manual standard top-ups, manual sponsored top-ups can occur at any time.

    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" and "Implementing Manual Sponsored Top-Ups".

  • Automatic sponsored top-ups

    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" and "Implementing Automatic Sponsored Top-Ups".

About Sponsored Top-Up Groups

To top up other accounts, an account must own a sponsored top-up group (/group/topup object). 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. To be a member of a sponsored top-up group, an account must have a /topup object, and that object must be linked to the appropriate /group/topup object.

Note:

The PIN_FLD_GROUP_OBJ field in a receiving account's /topup object specifies the /group/topup object with which the receiving account is associated. If the value is NULL, the account is not associated with a /group/topup object. In such cases, the account's /topup object is used only to enable the account to receive standard top-ups.

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

Caution:

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.

About Member Status

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

Table 9-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. For more information about member status, see these topics:

About member top-up PINs

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.

For more information about top-up PINs, see "Setting an Account's Sponsored Top-Up Member Status and PIN".

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 non-currency debits that can accumulate in the owner's paying balance group.

  • Credit limit of group resource

    Each resource supported by a sponsored top-up group has a group top-up cap. The cap specifies the maximum amount of the resource 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. For example, if a sponsored top-up group with three members has a $90 cap for US dollars, the cap can be reached as follows:

    • All three members receive $30.

    • Member A receives $50, and member B receives $40.

    • Member A receives $90.

    To set this credit limit, see "Implementing Manual Sponsored Top-Ups".

    Note:

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

Sponsored Top-Up Limitations

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

  • Accounts in different brands

About Top-Up Discount Incentives

You can offer discount incentives to customers whenever they top up an account balance by a specified amount. For example, you can offer 60 free off-peak minutes for every $100 top-up.

For more information, see "Offering Discount Incentives with Top-Ups".

Implementing Top-Ups in Custom Client Applications

To implement top-ups in your custom client application, see the following topics:

Implementing Manual Standard Top-Ups

To implement the manual standard top-up feature, configure your custom client application to accept the following top-up information and pass it in the input flist to the PCM_OP_PYMT_TOPUP opcode:

  • For voucher top-ups, pass the following information in the PIN_FLD_VOUCHERS_INFO array:

    • Voucher serial number

    • Voucher PIN number

    • Bill unit to top up

    • Balance group to top up

    • Service to top up

      Note:

      To apply the voucher top up to a service-level balance group, you must pass the /service object POID in the PIN_FLD_SERVICE_OBJ field of the PIN_FLD_VOUCHERS_INFO array.
  • For credit card top ups, pass the following information in the PIN_FLD_TOPUP_INFO array:

    • Bill unit to top up

    • Balance group to top up

    • Credit card number

    • Credit card expiration date

    • Credit card owner's name and address information.

  • For direct debit top ups, pass the following information in the PIN_FLD_TOPUP_INFO array:

    • Bill unit to top up

    • Balance group to top up

    • Bank routing number

    • Bank account number

    • Direct debit owner's name and address information.

For more information, see "How PCM_OP_PYMT_TOPUP Handles Manual Standard Top-Ups".

Implementing Automatic Standard Top-Ups

To implement the automatic standard top-up feature:

  1. In the Pricing Center, set a credit floor and credit threshold for any plan that contains deals whose service balances you want your customers to top up. For example, to trigger an automatic standard top-up when an account balance falls below $30, set the credit floor to -100 and the threshold to 70%.

    For more information, see "About Credit Thresholds and Credit Floors" in BRM Setting Up Pricing and Rating.

  2. Configure your custom client application to accept the following top-up information:

    • Payment method

      To specify the payment method for automatic standard top-ups, set the appropriate value in the PIN_FLD_PAYINFO field in the PIN_FLD_TOPUP_INFO array of the called opcode's input flist (see step 3 for opcode names).

      See "Standard Top-Up Payment Methods".

    • Automatic top-up amount

      To specify the payment amount of each automatic standard top-up, set the appropriate value in the PIN_FLD_TOPUP_AMT field in the PIN_FLD_TOPUP_INFO array of the called opcode's input flist.

    • Automatic top-up cap

      To specify the aggregate amount of automatic standard top-ups that the account can receive during an accounting cycle, set the appropriate value in the PIN_FLD_TOPUP_CAP field in the PIN_FLD_TOPUP_INFO array of the called opcode's input flist.

    • Bill unit to top up

      To specify the bill unit (/billinfo object) that contains the balance to top up, set the appropriate value in the PIN_FLD_BILLINFO field in the PIN_FLD_TOPUP_INFO array of the called opcode's input flist.

  3. Pass the information to one of these opcodes:

    • PCM_OP_CUST_COMMIT_CUSTOMER when creating accounts

    • PCM_OP_CUST_UPDATE_CUSTOMER when modifying accounts

      Note:

      Both of these opcodes call PCM_OP_CUST_SET_TOPUP, which is a wrapper opcode that calls other standard opcodes to set up or modify top-up information.

For more information, see "How BRM Sets Up Top-Up Information for an Account".

Implementing Manual Sponsored Top-Ups

To implement the manual sponsored top-up feature:

  1. Configure your custom client application to accept the following top-up information:

    • The POID of the account that initiates the creation or modification of the top-up configuration. Set this value in the level-one PIN_FLD_POID field of the called opcode's input flist (see step 2 for opcode names).

    • The POID of the account that will receive the top-ups (the member account). Set this value in the PIN_FLD_ACCOUNT_OBJ field in the PIN_FLD_TOPUP_INFO array of the called opcode's input flist.

    • The POID of the /topup object associated with the account that will receive the top-ups. If the account does not have a /topup object, specify the POID type. Set this value in the PIN_FLD_POID field in the PIN_FLD_TOPUP_INFO array of the called opcode's input flist.

    • Group to add member to

      To specify the sponsored top-up group to add the member account to, set the POID of the appropriate /group/topup object in the PIN_FLD_POID field in the PIN_FLD_GROUP_TOPUP_INFO array of the called opcode's input flist.

      If the object does not exist, pass the POID type.

      For information about how BRM searches for existing groups if the POID is not specified, see "Finding Sponsored Top-Up Groups".

    • Group name

      To specify the name of the sponsored top-up group, set the appropriate value in the PIN_FLD_NAME field in the PIN_FLD_GROUP_TOPUP_INFO array of the called opcode's input flist.

      If you do not specify a group name, the group will be named default. See "Finding Sponsored Top-Up Groups".

    • Group owner

      To specify the sponsored top-up group owner account, set the POID of the owner account in the PIN_FLD_PARENT field in the PIN_FLD_GROUP_TOPUP_INFO array of the called opcode's input flist.

    • Paying balance group

      To specify the owner account's balance group to transfer top-up resources from, set the POID of the balance group in the PIN_FLD_BAL_GRP_OBJ field in the PIN_FLD_GROUP_TOPUP_INFO array of the called opcode's input flist.

    • Resources to top up

      To specify the resources to be topped up in the member account, set the IDs of the appropriate currency and non-currency resources in the PIN_FLD_RESOURCE_ID fields in the PIN_FLD_GROUP_TOPUP_LIMITS array of the called opcode's input flist.

    • Resource top-up cap

      To specify the maximum amount of a resource that the owner can transfer to its members during the owner's accounting cycle, set the appropriate value in the resource's PIN_FLD_TOPUP_CAP field in the PIN_FLD_GROUP_TOPUP_LIMITS array.

      Important:

      This cap applies to the sum of all top-ups in the group, not to an individual member's top-ups. The cap should not exceed the credit limit of the paying balance group. See "About Sponsored Top-Up Credit Limits".
    • Receiving balance group

      To specify the member account's balance group to transfer sponsored top-ups to, set the POID of the balance group in the member's PIN_FLD_BAL_GRP_OBJ field in the PIN_FLD_GROUP_TOPUP_MEMBERS array of the called opcode's input flist.

    • Top-up PIN

      To specify the member's sponsored top-up PIN, set the appropriate value in the PIN_FLD_PIN field in the PIN_FLD_GROUP_TOPUP_MEMBERS array of the called opcode's input flist. See "About member top-up PINs".

    • Top-up status

      To specify the member's sponsored top-up status, set the appropriate value in the PIN_FLD_STATUS field in the PIN_FLD_GROUP_TOPUP_MEMBERS array of the called opcode's input flist. See "About Member Status".

  2. Pass the information to one of these opcodes:

    • PCM_OP_CUST_COMMIT_CUSTOMER when creating accounts

    • PCM_OP_CUST_UPDATE_CUSTOMER when modifying accounts

      Note:

      Both of these opcodes call PCM_OP_CUST_SET_TOPUP, which is a wrapper opcode that calls other standard opcodes to set up or modify top-up information.

For more information, see "How BRM Sets Up Top-Up Information for an Account".

Implementing Automatic Sponsored Top-Ups

To implement the automatic sponsored top-up feature:

  1. Configure your custom client application to accept the following top-up information:

    • All top-up information listed in "Implementing Manual Sponsored Top-Ups".

    • Automatic top-up amount

      To specify the amount of a resource to transfer from the owner to the member during each automatic sponsored top-up, set the appropriate value in the resource's PIN_FLD_TOPUP_AMT field in the PIN_FLD_GROUP_TOPUP_LIMITS array.

      This amount applies to every member in the group.

    • Automatic top-up frequency

      To specify the number of days in the member's automatic sponsored top-up cycle, set the appropriate value in the member's PIN_FLD_TOPUP_INTERVAL field in the PIN_FLD_GROUP_TOPUP_MEMBERS array of the called opcode's input flist (see step 2 for opcode names).

      This interval applies only to the member account.

  2. Pass the information to one of these opcodes:

    • PCM_OP_CUST_COMMIT_CUSTOMER when creating accounts

    • PCM_OP_CUST_UPDATE_CUSTOMER when modifying accounts

      Note:

      Both of these opcodes call PCM_OP_CUST_SET_TOPUP, which is a wrapper opcode that calls other standard opcodes to set up or modify top-up information.

For more information, see "How BRM Sets Up Top-Up Information for an Account".

How BRM Sets Up Top-Up Information for an Account

After your custom client application passes the required top-up information to PCM_OP_CUST_COMMIT_CUSTOMER or PCM_OP_CUST_UPDATE_CUSTOMER, that opcode calls PCM_OP_CUST_SET_TOPUP.

To create or modify an account's top-up information, PCM_OP_CUST_SET_TOPUP calls one of the following opcodes:

  • PCM_OP_CUST_CREATE_TOPUP

  • PCM_OP_CUST_MODIFY_TOPUP

See "Creating or Modifying an Account's Top-Up Information".

If successful, the PCM_OP_CUST_SET_TOPUP output flist contains the PIN_FLD_POID set to the POID of the created or modified /topup object.

If unsuccessful, the PCM_OP_CUST_SET_TOPUP output flist contains the following:

  • PIN_FLD_FIELD_NUM set to the field that failed.

  • PIN_FLD_TYPE set to the type of field that failed.

  • PIN_FLD_RESULT set to the validation error code.

For standard top-ups, an account's top-up information is stored in one object (/topup), but for sponsored top-ups, an account's top-up information is stored in two objects (/topup and /group/topup). Sometimes, one of the objects must be created and the other modified. For example, to add a member account to a sponsored top-up group, BRM might need to create a /topup object for the member and associate it with an existing /group/topup object. To determine which opcode to call in such cases, PCM_OP_CUST_SET_TOPUP uses these rules:

  • If at least one of the objects is being created, PCM_OP_CUST_SET_TOPUP calls PCM_OP_CUST_CREATE_TOPUP. This is true even if the other object is being modified.

  • If neither object is being created, PCM_OP_CUST_SET_TOPUP calls PCM_OP_CUST_MODIFY_TOPUP.

Preparing an Account's Top-Up Information

To prepare top-up information for an account, PCM_OP_CUST_CREATE_TOPUP and PCM_OP_CUST_MODIFY_TOPUP call the PCM_OP_CUST_POL_PREP_TOPUP policy opcode. The policy opcode prepares information required to perform one of these tasks:

  • Create a standalone /topup object for standard top-ups. This occurs when the following information is not passed to PCM_OP_CUST_POL_PREP_TOPUP:

    • A /topup object POID

    • A sponsored top-up group owner account POID

  • Modify a standalone /topup object for standard top-ups. This occurs when the following information is passed to PCM_OP_CUST_POL_PREP_TOPUP:

    • A /topup object POID

    But this information is not passed to it:

    • A sponsored top-up group owner account POID

    • A /group/topup POID

  • Create one or both objects (/topup and /group/topup) for sponsored top-ups. This occurs when the following information is passed to PCM_OP_CUST_POL_PREP_TOPUP:

    • A sponsored top-up group owner account POID

    But this information is not passed to it:

    • A /topup object POID

    • A /group/topup POID

      Note:

      Before creating a /group/topup object, the opcode checks for an existing /group/topup object that matches the criteria in its input flist. For more information, see "Finding Sponsored Top-Up Groups".
  • Modify both objects (/topup and /group/topup) for sponsored top-ups. This occurs when the following information is passed to PCM_OP_CUST_POL_PREP_TOPUP:

    • A /topup object POID

    • A /group/topup POID

Additional Preparation for Sponsored Top-Ups

For sponsored top-ups, PCM_OP_CUST_POL_PREP_TOPUP also prepares this information:

  • If the group owner account did not initiate the object creation or modification, the policy opcode sets the following values in its output flist:

    • PIN_FLD_STATUS (member account's group membership status) = the value associated with the PIN_STATUS_INACTIVE status in the BRM_Home/include/ops/pcm.h header file

    • PIN_FLD_PIN (member account's top-up PIN) = NULL

  • If the group owner account did initiate the object creation or modification, the policy opcode does the following:

    • If the status of the member account's group membership is not specified in the input flist, sets it to the value associated with the PIN_STATUS_ACTIVE in the BRM_Home/include/ops/pcm.h header file

    • (Creation only) If the group name is not specified in the input flist, sets the name to default

    For more information, see "Setting an Account's Sponsored Top-Up Member Status and PIN".

Validating an Account's Top-Up Information

To validate the top-up information prepared for an account (see "Preparing an Account's Top-Up Information"), PCM_OP_CUST_CREATE_TOPUP and PCM_OP_CUST_MODIFY_TOPUP call the PCM_OP_CUST_POL_VALID_TOPUP policy opcode. The policy opcode performs these tasks:

  • Verifies that the status of the account to be debited for each top-up (the paying account) is active.

  • Verifies that the standard or sponsored top-up amount is less than or equal to the corresponding top-up cap.

  • (Sponsored top-ups only) Verifies that the member is not trying to join a group that it owns.

  • (Sponsored top-ups only) Verifies that the prospective member's account is not closed.

  • (Sponsored top-ups only) Verifies that the prospective member is not a member of any other sponsored top-up group.

You can customize PCM_OP_CUST_POL_VALID_TOPUP to change the way it validates the output flist of the PCM_OP_CUST_POL_PREP_TOPUP policy opcode.

In its own output flist, PCM_OP_CUST_POL_VALID_TOPUP returns a PIN_FLD_RESULT value that is associated with one of the following values:

  • PIN_RESULT_PASS (validation succeeded)

  • PIN_RESULT_FAIL (validation failed)

The associated values are defined in the pcm.h header file. For more information, see "Header Files" in BRM Developer's Guide.

Creating or Modifying an Account's Top-Up Information

If validation succeeds (see "Validating an Account's Top-Up Information"), the validated information is used to perform one of the following tasks:

Creating Top-Up Information

PCM_OP_CUST_CREATE_TOPUP uses the validated information to perform one of these operations:

  • If the information does not include the POID of a sponsored top-up group owner account, the opcode creates a standalone /topup storable object that contains information for automatic standard top-ups.

  • If the information includes the POID of a sponsored top-up group owner account and /group/topup and /topup POID types, the opcode creates a sponsored top-up relationship as follows:

    1. Creates a /group/topup object for the owner account

    2. Creates a /topup object for the member account

    3. Associates the new /topup object with the new /group/topup object

  • If the information includes the POID of a sponsored top-up group owner account, the POID of an existing /group/topup object, and a /topup POID type, PCM_OP_CUST_CREATE_TOPUP creates a sponsored top-up relationship as follows:

    1. Creates a /topup object for the member account

    2. Associates the new /topup object with the existing /group/topup object

  • If the information includes the POID of a sponsored top-up group owner account, a /group/topup POID type, and an existing /topup object, PCM_OP_CUST_CREATE_TOPUP creates a sponsored top-up as follows:

    1. Creates a /group/topup object for the owner account

    2. Associates the existing /topup object with the new /group/topup object

If successful, the PCM_OP_CUST_CREATE_TOPUP output flist contains the following:

  • PIN_FLD_POID set to the POID of the /topup object created

If unsuccessful, the output flist contains the following:

  • PIN_FLD_FIELD_NUM set to the field that failed

  • PIN_FLD_TYPE set to the type of field that failed

  • PIN_FLD_RESULT set to the validation error code

Modifying Top-Up Information

PCM_OP_CUST_MODIFY_TOPUP uses the validated information to perform one of these operations:

  • If the information does not include the POID of an existing /group/topup object, the opcode modifies the automatic standard top-up information in a standalone /topup object.

  • If the information includes the POID of an existing /group/topup object, the opcode modifies the sponsored top-up information in the /group/topup and /topup objects.

If successful, the PCM_OP_CUST_MODIFY_TOPUP output flist contains the following:

  • PIN_FLD_POID set to the POID of the /topup object modified

If unsuccessful, the PCM_OP_CUST_MODIFY_TOPUP output flist contains the following:

  • PIN_FLD_FIELD_NUM set to the field that failed

  • PIN_FLD_TYPE set to the type of field that failed

  • PIN_FLD_RESULT set to the validation error code

Setting an Account's Sponsored Top-Up Member Status and PIN

If an account is a member of a sponsored top-up group, its group status and top-up PIN are set as follows:

  • When an owner account initiates adding a member to the group, the member's group status and PIN are set according to the information in the PCM_OP_CUST_SET_TOPUP input flist. If member status is not specified in the flist, it is set to active.

  • When a member account initiates adding itself to a group, the member's group status is set to inactive and the PIN is set to NULL no matter what values are provided for those items in the input flist. After the member is added to the group, the group owner must activate the member's member and sets its top-up PIN. See "Activating Sponsored Top-Up Group Members" and "Setting Sponsored Top-Up Member PINs".

  • When a member account initiates a modification of its sponsored top-up settings after being added to a group, its group status is reset to inactive. This occurs even if the modification is not related to member status. The group owner must then reactivate the member. See "Activating Sponsored Top-Up Group Members".

For related information, see the following topics:

Activating Sponsored Top-Up Group Members

To receive sponsored top-ups, a member's group status must be active (see "About Member Status"). By default, only groups owners can activate a member. To enable members to activate themselves, customize the PCM_OP_CUST_POL_PREP_TOPUP policy opcode.

To activate members whose group status is inactive or closed:

  1. Use your custom client application to call PCM_OP_CUST_SET_TOPUP.

  2. Set the member's PIN_FLD_STATUS field in the MEMBERS array of the opcode's input flist to the value associated with the PIN_STATUS_ACTIVE status in the BRM_Home/include/ops/pcm.h header file.

Inactivating Sponsored Top-Up Group Members

A member whose group status is inactive can use any outstanding topped-up credit in its topped-up balance group, but it cannot receive any more top-ups from the group until its member status is reactivated. In addition, it cannot join another sponsored top-up group.

To inactivate a member's group status:

  1. Use your custom client application to call PCM_OP_CUST_SET_TOPUP.

  2. Set the member's PIN_FLD_STATUS field in the MEMBERS array of the opcode's input flist to the value associated with the PIN_STATUS_INACTIVE status in the BRM_Home/include/ops/pcm.h header file.

    Note:

    You can also inactivate sponsored top-ups by changing the status of the member account to inactive. To change the status of an account, see "Changing Account and Service Status" in BRM Managing Customers.

To cancel a sponsored top-up relationship, see "Canceling Top-Ups".

For more information about member status, see "About Member Status".

Inactivating all the members in a sponsored top-up group

To inactivate the group status of every member in a group, change the status of the sponsored top-up group owner account to inactive.

When a group owner account is inactive, the members of its sponsored top-up groups can use any outstanding topped-up credit in their topped-up balance groups, but they cannot receive any more top-ups from the group until the owner account is reactivated, and they cannot join another sponsored top-up group.

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

Setting Sponsored Top-Up Member PINs

By default, only groups owners can set a member's PIN.

To assign a top-up PIN to a member:

  1. Use your custom client application to call PCM_OP_CUST_SET_TOPUP.

  2. Set the member's PIN_FLD_PIN field in the MEMBERS array of the opcode's input flist to the appropriate string value.

    Note:

    • By default, top-up PINs do not have to be unique. Members in the same group and in different groups can have the same top-up PIN.

    • To enable members to set their own PINs, customize the PCM_OP_CUST_POL_PREP_TOPUP policy opcode.

Finding Sponsored Top-Up Groups

When setting up sponsored top-ups, the PCM_OP_CUST_POL_PREP_TOPUP policy opcode uses the following information from the PCM_OP_CUST_SET_TOPUP input flist to determine whether the prospective member account can be added to an existing group:

  • The group owner account POID (PIN_FLD_PARENT)

  • The name of the group (PIN_FLD_NAME)

    Note:

    Each group owned by the same account must have a unique name. Groups owned by different accounts can have the same name.

If a group name is not provided, the policy opcode searches for a group by owner account POID and the ID of the resource or resources that you want to top-up in the member account (PIN_FLD_RESOURCE_ID in the LIMITS array). The search has the following results:

  • If the policy opcode finds the group by name but a resource is specified in the input flist that the group does not support, the following occurs:

    • If the group owner account initiated the transaction, the resource is added to the group.

    • If the member account initiated the transaction, an error is returned.

  • If the policy opcode finds the group by resource and the search returns multiple groups, the groups are listed alphabetically by PIN_FLD_NAME value and the member is added to the group at the top of the list.

  • If the policy opcode fails to find a group by name or by resource, the following occurs:

    • If the group owner account has a group named default, the member is added to that group.

    • If the group owner account does not have a group named default, such a group is created based on the information in the input flist. (Each group owner can have only one sponsored top-up group named default.)

      Note:

      To change the way the search is performed, customize the PCM_OP_CUST_POL_PREP_TOPUP policy opcode.

About Tracking Sponsored Top-Up Adjustments

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

  • 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 have been added to 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
    

The new reason codes and domain IDs are used by the following opcodes:

  • PCM_OP_PYMT_TOPUP

  • PCM_OP_BILL_TRANSFER_BALANCE

  • PCM_OP_AR_ACCOUNT_ADJUSTMENT

Customizing and Loading Sponsored Top-Up Reason Codes

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

Note:

If you load a localized version of this file, use the correct file extension for your locale. For a list of file extensions, see "Locale Names" in BRM Developer's Guide.

Caution:

The load_localized_strings utility overwrites the /config/map_glid object. If you are updating this object, you cannot load new G/L ID maps only. You must load complete sets of data each time you run the load_localized_strings utility. This is also true if you specify the -f parameter when updating the /strings object. Otherwise, the load_localized_strings utility appends the new data to the /strings object.

For more information about loading the reasons.locale file, see "Loading Localized or Customized Strings" in BRM Developer's Guide.

For information about creating new strings for this file, see "Creating New Strings and Customizing Existing Strings" in BRM Developer's Guide.

Offering Discount Incentives with Top-Ups

You can offer customers discount incentives whenever they top up an account balance by a specified amount. For example, you can offer 20 free peak minutes whenever a customer makes a $50 top-up.

To offer top-up discount incentives:

  1. Set up the discount in Pricing Center. See "Using Pricing Center to Configure Discounts" in BRM Configuring Pipeline Rating and Discounting.

  2. Configure the PCM_OP_PYMT_POL_PURCHASE_DEAL policy opcode to validate the discount.

    By default, this policy opcode is an empty hook provided to facilitate customization. You can customize it to apply discounts to account balances when they are topped up. For example, this policy opcode might grant 60 free minutes of usage for every $50 top-up.

    PCM_OP_PYMT_POL_PURCHASE_DEAL is called by PCM_OP_PYMT_TOPUP. See "How BRM Performs Top-Ups".

How BRM Performs Top-Ups

All top-ups are performed by PCM_OP_PYMT_TOPUP. This section describes how that opcode works.

Triggering PCM_OP_PYMT_TOPUP

PCM_OP_PYMT_TOPUP is triggered as follows:

Performing Top-Ups with PCM_OP_PYMT_TOPUP

For information about how PCM_OP_PYMT_TOPUP performs top-ups, see the following topics:

How PCM_OP_PYMT_TOPUP Handles Manual Standard Top-Ups

PCM_OP_PYMT_TOPUP performs manual standard top-ups as follows:

  1. Receives the top-up amount from a client application.

  2. For top-ups paid with a voucher, calls the PCM_OP_PYMT_POL_VALID_VOUCHER policy opcode to use Voucher Manager or a third-party voucher management system to perform these operations:

    1. Validate the voucher.

    2. Associate the voucher with the account.

    3. Retrieve the balance impacts of the voucher's resources.

    After the voucher is validated, the PCM_OP_PYMT_POL_VALID_VOUCHER policy opcode performs these operations:

    1. Determines whether the voucher has a currency resource.

    2. Uses the resource with the earliest validity start date and the resource with the latest validity end date to determine the validity period of the voucher.

    3. Returns the preceding information and the voucher's balance impacts to PCM_OP_PYMT_TOPUP.

    PCM_OP_PYMT_TOPUP then performs these operations:

    1. If the validated voucher does not have a currency resource, creates an /event/billing/vouchertopup event to record the top-up balance impact.

    2. If the voucher has a currency resource, calls PCM_OP_PYMT_COLLECT, which passes the balance group impacted by the top up and the top-up resource information and in its input flist to PCM_OP_BILL_RCV_PAYMENT.

      If there are non-currency balance impacts in the top-up resource information, PCM_OP_BILL_RCV_PAYMENT adds them to the input flist of PCM_OP_ACT_USAGE, which records them in the /event/billing/payment/voucher object that it generates to record the top-up balance impact.

      Note:

      When called by PCM_OP_PYMT_TOPUP, PCM_OP_PYMT_COLLECT does not call the payment suspense manager PCM_OP_PYMT_VALIDATE_PAYMENT opcode.
    3. Posts the top-up as an unallocated payment.

  3. For top-ups paid by credit card or direct debit, collects payment from the credit card agency or direct debit company, and then updates the specified balance.

  4. For all top-ups, applies any top-up discount incentives to the account by calling the PCM_OP_PYMT_POL_PURCHASE_DEAL policy opcode. See "Offering Discount Incentives with Top-Ups".

    Note:

    The PIN_FLD_DESCR field in the input flist contains a description of the topup. This value is stored in the /event/billing/payment/cc object and is used by Customer Center when making a ”One time credit card” or ”Charge credit card now” payment.

How PCM_OP_PYMT_TOPUP Handles Automatic Standard Top-Ups

PCM_OP_PYMT_TOPUP performs automatic standard top-ups as follows:

  1. Retrieves the top-up amount from the specified /topup object.

  2. Verifies that the top-up amount will not cause the sum of all automatic standard top-ups received during the current accounting cycle to exceed the account's automatic standard top-up cap.

  3. Applies any top-up discount incentives to the account by calling the PCM_OP_PYMT_POL_PURCHASE_DEAL policy opcode. See "Offering Discount Incentives with Top-Ups".

How PCM_OP_PYMT_TOPUP Handles Manual Sponsored Top-Ups

PCM_OP_PYMT_TOPUP performs manual sponsored top-ups as follows:

  1. Receives the top-up amount from a client application.

  2. Verifies the following:

    • The status of the member is active. See "About Member Status".

    • (Member-initiated top-ups only) The top-up PIN is valid. See "About member top-up PINs".

    • The top-up amount will not cause the total amount of credit charged to the owner account's balance group to exceed the credit limit of the associated resource in that balance group. See "About Sponsored Top-Up Credit Limits".

    • The top-up amount will not cause the sum of all top-ups received during the current accounting cycle of the owner account to exceed the group's top-up cap.

  3. Performs these operations:

    • Calls PCM_OP_BILL_TRANSFER_BALANCE to transfer the top-up resources from the paying balance group to the receiving balance group. See "About Transferring Sponsored Top-Ups from Debit Balances".

    • Passes the reason ID and the reason domain ID used to differentiate sponsored top-up adjustments from other types of adjustments to PCM_OP_BILL_TRANSFER_BALANCE, which passes them to PCM_OP_AR_ACCOUNT_ADJUSTMENT. See "About Tracking Sponsored Top-Up Adjustments".

    • Updates the sum of all sponsored top-ups credited to members of the group during the group owner account's current accounting cycle. This value is stored in the PIN_FLD_CYCLE_TOPPED_AMT field of the LIMITS array in the /group/topup object.

      If the last sponsored top-up occurred in the owner account's current accounting cycle, PCM_OP_PYMT_TOPUP adds the amount of the current top-up to the value already in this field.

      If the last sponsored top-up occurred in the owner account's previous accounting cycle, the opcode sets this field to the amount of the current top-up.

  4. Applies any top-up discount incentives to the account by calling the PCM_OP_PYMT_POL_PURCHASE_DEAL policy opcode. See "Offering Discount Incentives with Top-Ups".

How PCM_OP_PYMT_TOPUP Handles Automatic Sponsored Top-Ups

PCM_OP_PYMT_TOPUP performs automatic sponsored top-ups as follows:

  1. Retrieves the top-up amount from the specified /group/topup object.

  2. Verifies the following:

    • The status of the member is active. See "About Member Status".

    • The top-up amount will not cause the total amount of credit charged to the owner account's balance group to exceed the credit limit of the associated resource in that balance group. See "About Sponsored Top-Up Credit Limits".

    • The top-up amount will not cause the sum of all top-ups received during the current accounting cycle of the owner account to exceed the group's top-up cap.

  3. Performs these operations:

    • Calls PCM_OP_BILL_TRANSFER_BALANCE to transfer the top-up resources from the paying balance group to the receiving balance group. See "About Transferring Sponsored Top-Ups from Debit Balances".

    • Passes the reason ID and the reason domain ID used to differentiate sponsored top-up adjustments from other types of adjustments to PCM_OP_BILL_TRANSFER_BALANCE, which passes them to PCM_OP_AR_ACCOUNT_ADJUSTMENT. See "About Tracking Sponsored Top-Up Adjustments".

    • Updates the time that the member's last automatic sponsored top-up occurred to the current time.

      This value is stored in the PIN_FLD_LAST_TOPUP_T field of the LIMITS array in the /group/topup object. PCM_OP_PYMT_TOPUP uses this value to determine when to execute the member's next automatic sponsored top-up.

    • Calculates the time that the member's next automatic sponsored top-up will occur. This value is stored in the PIN_FLD_NEXT_TOPUP_T field of the LIMITS array in the /group/topup object.

    • Updates the sum of all sponsored top-ups credited to members of the group during the group owner account's current accounting cycle. This value is stored in the PIN_FLD_CYCLE_TOPPED_AMT field of the LIMITS array in the /group/topup object.

      If the last sponsored top-up occurred in the owner account's current accounting cycle, PCM_OP_PYMT_TOPUP adds the amount of the current top-up to the value already in this field.

      If the last sponsored top-up occurred in the owner account's previous accounting cycle, the opcode sets this field to the amount of the current top-up.

  4. Applies any top-up discount incentives to the account by calling the PCM_OP_PYMT_POL_PURCHASE_DEAL policy opcode. See "Offering Discount Incentives with Top-Ups".

About Transferring Sponsored Top-Ups from Debit Balances

To perform a sponsored top-up, PCM_OP_BILL_TRANSFER_BALANCE must transfer resources from a debit balance in a group owner account to a debit or credit balance in a member account. By default, however, this opcode transfers resources only from credit balances. To enable the opcode to transfer resources from a debit balance, the PIN_FLD_VERIFY_BALANCE field in its input flist is set to PIN_BOOLEAN_FALSE by PCM_OP_PYMT_TOPUP.

Note:

If this field is not set (default) or is set to PIN_BOOLEAN_TRUE, the opcode cannot transfer resources from debit balances.

About Retrieving Balance Impact Information for Voucher Top-Ups

To retrieve the balance impacts associated with a voucher top-up, such as the tax payment and original top-up amount, use Event Browser to retrieve the balance impacts from the PIN_FLD_BAL_IMPACTS array in the /event/billing/payment/voucher object. The /event/billing/payment/voucher object contains the net amount and tax amount in separate PIN_FLD_BAL_IMPACTS arrays.

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.

Topping Up Accounts in Customer Center and Self-Care Manager

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.

To perform manual standard top-ups in Customer Center and Self-Care Manager, see the following topics:

Performing Top-Ups in Customer Center

To perform manual standard top-ups in Customer Center, see "Topping Up Accounts in Customer Center and 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.

For information about standard top-up payment methods, see "Standard Top-Up Payment Methods".

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.

About voucher top-up error handling

When an error occurs during a voucher top-up in Customer Center, the PCM_OP_VOUCHER_ASSOCIATE_VOUCHER opcode creates an EBufException. The EBufException includes the error type and the name of the field associated with the error in the error buffer (ebuf). Customer Center uses this information to determine which error message to display to the user.

Table 9-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 9-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

Voucher and account brands do not match

ERR_PERMISSION_DENIED

PIN_FLD_BRAND_OBJ

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


These error messages are stored in the CustomerCenterResources.properties file. To modify them, see "Modifying the Customer Center Properties Files" in BRM Developer's Guide.

Performing Top-Ups in Self-Care Manager

To perform manual standard top-ups in Self-Care Manager, see "Applying Voucher Top-Ups" in BRM Managing Customers.

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 perform the top-ups, the utility calls PCM_OP_PYMT_TOPUP.

For more information, see the following topics:

Running the pin_balance_transfer Utility

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 & 

About Reversing Voucher Top-Ups

To reverse voucher top-ups, see the following topics:

Reversing Vouchers That Have Only Non-Currency Resources

If a voucher has only non-currency resources, 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. See "About Adjustments" in BRM Managing Accounts Receivable.

Reversing Vouchers That Have Currency and Non-Currency Resources

If a voucher has currency and non-currency resources, 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 (see "Using testnap" in BRM Developer's Guide). The payment reversal will be recorded in an /event/billing/reversal/voucher event by PCM_OP_BILL_REVERSE_PAYMENT.

About Vouchers Having Non-Currency Resources with a Positive Impact

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

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

To set the credit limit for non-currency resources to a positive value, perform one of the following:

  • Specify the credit limit in your plan.

  • Specify the credit limit in an account.

Viewing Sponsored Top-Up History

To display information about sponsored top-up transactions, configure your custom client application to call PCM_OP_PYMT_FIND_TOPUP_EVENTS to retrieve balance transfer events (/event/billing/adjustment/account objects) in which top-up transactions are recorded.

Historic sponsored top-up information can be displayed for both sponsored top-up owner accounts and member accounts:

  • Member accounts can view only the sponsored top-ups that they received.

  • Owner accounts can view all sponsored top-ups associated with their sponsored top-up groups.

Displaying All Sponsored Top-Ups Associated with an Account

To retrieve all sponsored top-up events associated with a group owner account or a member account, include the following values in the PCM_OP_PYMT_FIND_TOPUP_EVENTS input flist:

  • Account's POID in the PIN_FLD_POID field

    Note:

    This field stores the POID of the account that initiates the search. If a POID type rather than an actual POID is provided, an actual balance group POID must be set in the flist's PIN_FLD_BAL_GRP_OBJ field.
  • No value in these fields:

    • PIN_FLD_BAL_GRP_OBJ

      Note:

      If no account POID is provided, a balance group POID must be provided. In such cases, the opcode retrieves top-up events associated only with the specified balance group.
    • PIN_FLD_REASON_ID

    • PIN_FLD_REASON_DOMAIN_ID

Displaying Sponsored Top-Ups Associated with Only One Group

If an owner account has multiple sponsored top-up groups, retrieve sponsored top-up events related only to one group by including the following values in the PCM_OP_PYMT_FIND_TOPUP_EVENTS input flist:

  • Group owner account's POID in the PIN_FLD_POID field

  • Paying balance group's POID in the PIN_FLD_BAL_GRP_OBJ field

  • No value in these fields:

    • PIN_FLD_REASON_ID

    • PIN_FLD_REASON_DOMAIN_ID

Displaying Only Sponsored Top-Up Credits or Debits

By default, PCM_OP_PYMT_FIND_TOPUP_EVENTS retrieves all sponsored top-up debit and credit adjustment events associated with the initiating account. Thus, if a sponsored top-up group owner account initiates the search, the opcode retrieves two events for each top-up:

  • An event for debiting the top-up amount from the owner's paying balance group

  • An event for crediting the top-up amount to a member's receiving balance group

To limit the search to debit or credit adjustment events, include the appropriate reason ID and reason domain ID in the PIN_FLD_REASON_ID and PIN_FLD_REASON_DOMAIN_ID fields of the opcode's input flist. For more information, see "About Tracking Sponsored Top-Up Adjustments".

Note:

If you create custom reason and reason domain IDs for sponsored top-up events, PCM_OP_PYMT_FIND_TOPUP_EVENTS returns events associated with all the IDs unless you limit the search to specified IDs.

Canceling Top-Ups

To cancel top-ups, see the following topics:

Canceling Sponsored Top-Ups

Sponsored top-ups can be canceled for a single member or for an entire group. For more information, see the following topics:

Canceling a Single Member's Sponsored Top-Ups

To cancel a member account's sponsored top-ups, see the following topics:

To stop sponsored top-ups temporarily, see "Inactivating Sponsored Top-Up Group Members".

Canceling Top-Ups by Changing a Member's Group Status

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:

  1. Use your custom client application to call PCM_OP_CUST_SET_TOPUP.

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

Canceling Top-Ups by Closing a Member Account

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.

Caution:

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.

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 (see "Implementing Top-Ups in Custom Client Applications"). 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.

Deleting Accounts That Are Sponsored Top-Up Owners or Members

This section describes what happens to /group/topup and /topup objects when the accounts with which they are associated are deleted.

For general information about deleting accounts, see the following topics:

About Deleting Owner Accounts

When a sponsored top-up group owner account is deleted, the sponsored top-ups for all its member accounts end. In addition, the following occurs:

  • If a /topup object is associated with the owner account, it is deleted.

  • All /group/topup objects associated with the owner account are deleted.

  • The following fields in all /topup objects of accounts that were members of the deleted /group/topup objects are set to NULL:

    • PIN_FLD_GROUP_OBJ

    • PIN_FLD_GROUP_INDEX

About Deleting Member Accounts

When a sponsored top-up group member account is deleted, PCM_OP_CUST_DELETE_ACCT calls PCM_OP_CUST_DELETE_TOPUP, which performs these operations:

  • Deletes the /topup object associated with the member account.

  • Removes the member's array element from the MEMBERS array of the /group/topup object with which the /topup object was associated.

    Important:

    PCM_OP_CUST_DELETE_TOPUP should not be used to cancel an account's membership in a sponsored top-up group. See "Canceling Top-Ups".

If successful, the PCM_OP_CUST_DELETE_TOPUP output flist contains the following:

  • PIN_FLD_POID set to the POID of the deleted /topup object

If unsuccessful, the PCM_OP_CUST_DELETE_TOPUP output flist contains the following:

  • PIN_FLD_FIELD_NUM set to the field that failed

  • PIN_FLD_TYPE set to the type of field that failed

  • PIN_FLD_RESULT set to the validation error code