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 Managing Customers" in BRM Concepts
"About Accounts Receivable" in BRM Managing Accounts Receivable
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:
Standard top-ups: Top-ups that customers make to their own accounts. See "About Standard Top-Ups".
Sponsored top-ups: Top-ups that are made from one customer's account to another customer's account. See "About Sponsored 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".
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:
For information about Voucher Manager, see "About Managing Voucher Inventory" in BRM Telco Integration.
To configure BRM to interact with a third-party voucher system, you must customize the PCM_OP_PYMT_POL_VALID_VOUCHER policy opcode. See "Customizing Voucher Validation" in BRM Telco Integration.
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.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".
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.All accounts that belong to a sponsored top-up group have one of the member statuses shown in Table 10-1:
Table 10-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:
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".
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.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".
To implement top-ups in your custom client application, see the following topics:
Implementing Automatic Sponsored Top-Ups
Note:
By default, Customer Center and Self-Care Manager are configured to perform manual standard top-ups. See "Topping Up Accounts in Customer Center and Self-Care Manager".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".
To implement the automatic standard top-up feature:
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.
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).
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.
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".
To implement the manual sponsored top-up feature:
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".
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".
To implement the automatic sponsored top-up feature:
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.
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".
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.
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
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".
To validate the top-up information prepared for an account, PCM_OP_CUST_CREATE_TOPUP and PCM_OP_CUST_MODIFY_TOPUP call the PCM_OP_CUST_POL_VALID_TOPUP policy opcode. For more information, see "Preparing an Account's Top-Up Information". 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.
If validation succeeds, the validated information is used to perform one of the following tasks:
For more information, see "Validating an Account's 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:
Creates a /group/topup object for the owner account
Creates a /topup object for the member account
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:
Creates a /topup object for the member account
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:
Creates a /group/topup object for the owner account
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
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
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:
To receive sponsored top-ups, a member's group status must be active. For more information, 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:
Use your custom client application to call PCM_OP_CUST_SET_TOPUP.
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.
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:
Use your custom client application to call PCM_OP_CUST_SET_TOPUP.
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.
By default, only groups owners can set a member's PIN.
To assign a top-up PIN to a member:
Use your custom client application to call PCM_OP_CUST_SET_TOPUP.
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.
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.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
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.
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:
Set up the discount in Pricing Center. See "Using Pricing Center to Configure Discounts" in BRM Configuring Pipeline Rating and Discounting.
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".
All top-ups are performed by PCM_OP_PYMT_TOPUP. This section describes how that opcode works.
PCM_OP_PYMT_TOPUP is triggered as follows:
Manual top-ups: When a customer or CSR uses a client application to top up a balance in an account (a manual top-up), the opcode is called by the client application.
To use Customer Center or Self-Care Manager to top up accounts, see "Topping Up Accounts in Customer Center and Self-Care Manager".
To use a custom client application to top up accounts, see "Implementing Top-Ups in Custom Client Applications".
Automatic standard top-ups: When a balance in an account configured for automatic standard top-ups falls below a specified threshold, PCM_OP_PYMT_TOPUP is called by the PCM_OP_ACT_POL_EVENT_NOTIFY policy opcode.
To configure accounts to receive automatic standard top-ups, see "Implementing Automatic Standard Top-Ups".
Automatic sponsored top-ups: When the next automatic top-up date of an account configured for automatic sponsored top-ups is within the time range specified in the "pin_balance_transfer" utility's command-line parameters, PCM_OP_PYMT_TOPUP is called by the utility. See "Performing Automatic Sponsored Top-Ups".
To configure accounts to receive automatic sponsored top-ups, see "Implementing Automatic Sponsored Top-Ups".
For information about how PCM_OP_PYMT_TOPUP performs top-ups, see the following topics:
PCM_OP_PYMT_TOPUP performs manual standard top-ups as follows:
Receives the top-up amount from a client application.
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:
Validate the voucher.
Associate the voucher with the account.
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:
Determines whether the voucher has a currency resource.
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.
Returns the preceding information and the voucher's balance impacts to PCM_OP_PYMT_TOPUP.
PCM_OP_PYMT_TOPUP then performs these operations:
If the validated voucher does not have a currency resource, creates an /event/billing/vouchertopup event to record the top-up balance impact.
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.Posts the top-up as an unallocated payment.
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.
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.PCM_OP_PYMT_TOPUP performs automatic standard top-ups as follows:
Retrieves the top-up amount from the specified /topup object.
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.
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".
PCM_OP_PYMT_TOPUP performs manual sponsored top-ups as follows:
Receives the top-up amount from a client application.
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.
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.
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".
PCM_OP_PYMT_TOPUP performs automatic sponsored top-ups as follows:
Retrieves the top-up amount from the specified /group/topup object.
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.
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.
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".
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.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.
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.
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:
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 10-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 10-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.
To perform manual standard top-ups in Self-Care Manager, see "Applying Voucher Top-Ups" in BRM Managing Customers.
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:
For an overview of automatic sponsored top-ups, see "About Sponsored Top-Ups".
To set up automatic sponsored top-ups for an account, see "Implementing Automatic Sponsored Top-Ups".
For information about how PCM_OP_PYMT_TOPUP implements top-ups, see "How BRM Performs Top-Ups".
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 &
To reverse voucher top-ups, see the following topics:
Reversing Vouchers That Have Currency and Non-Currency Resources
Caution:
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 resources cannot be reapplied to another account or balance group.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.
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. For more information, 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.
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.
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.
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
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
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.To cancel top-ups, see the following topics:
Sponsored top-ups can be canceled for a single member or for an entire group. For more information, see the following topics:
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:
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.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.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.
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. For more information, 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.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:
"Removing Accounts by Using the sample_del.c Program" in BRM Developer's Reference
PCM_OP_CUST_DELETE_ACCT
Caution:
Do not delete accounts in a production system.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
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