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

E16696-07
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

12 Remitting Funds to Third Parties

This chapter describes how to use Oracle Communications Billing and Revenue Management (BRM) to remit a share of revenues to third parties. To use the remittance feature, you should be familiar with basic BRM functions, including pricing, rating, billing, and account creation. For an overview of these features, see BRM Concepts.

About Remittance

Use the BRM remittance feature to share the revenue you receive with third parties. You can direct BRM to calculate the amount of remittance in various ways: for example, you can pay a percentage of subscriber fees or a flat amount per new subscriber to third parties such as resellers or service providers.

Note:

Settlements is a widely used industry term for remittance.

Table 12-1 lists some scenarios for using the BRM remittance feature:

Table 12-1 Remittance Scenarios

Scenario Description

Service or Product Provider Payments

An Internet service provider (ISP) offers a service or product from a different company and needs to remit part of the revenue from the service or product to that company.

For example, an ISP offers online games to its subscribers for an extra fee and pays a portion of those fees to the company that provides the games.

Branded Service Provider Payments

A host service provider needs to share revenues with branded service providers.

For example, if subscribers pay their fees to the host provider, the host provider then remits a percentage of those fees to the branded service provider.

Or the host provider pays a flat fee, similar to a sales commission, for every new subscriber the branded service provider signs up.

Sales Commissions

An ISP pays a commission for each subscriber its sales people sign up.

Note: Sales commissions are supported only if the profile of the subscriber account contains information about a salesperson. See "Using Remittance for Sales Commissions".

Telephony Settlements

IP telephony calls connect with gateways and other telephony networks. A portion of the revenues collected for these calls go to the other carriers.

For example, you must pay a call termination fee to the carrier that completes a call.

Note: Implementing this example in BRM requires customizing the remittance fields file. See "Defining Custom Remittance Fields".


About Remittance Products

Using the remittance feature requires you to create special products as part of your price list. BRM uses a remittance product as the basis for calculating the remittance amount to be paid to a third party.

You use Pricing Center to create a remittance product. For information about products and prices lists, see "About Creating a Price List" in BRM Setting Up Pricing and Rating.

When you create a remittance product, you must specify the following:

  • The product applies to Account, instead of to a service.

  • The event type is Remittance Event.

  • The rate is measured by one of these metrics:

    • Number

    • Usage Time

    • Usage Size

    • Amount

    • A custom metric you create and load into BRM. For information, see "Ways to Rate Events" in BRM Setting Up Pricing and Rating.

      Important:

      You cannot mix remittance and non-remittance products in a deal or plan.

      Note:

      You can include one or more remittance products in a deal.

For more information, see "Creating a Remittance Product".

About Defining Remittance Specifications

A remittance specification defines a single remittance arrangement that specifies which third party receives remittance when particular events occur. A specification also includes the product BRM uses to calculate remittance when the criteria are met.

You define specifications in the remittance specification file. Each specification includes the following information:

  • Account number of the account that receives payment.

  • Status of the events that contribute to remittance. You can specify that you pay third parties only when the events have been billed or paid, or you can specify that you pay without reference to the billing status.

  • Name of the product that determines the rate that BRM uses to calculate remittance.

    Important:

    Whenever a product name changes, you must update the remittance specification and reload it into the database.
  • Remittance criteria that specify which events trigger payments to the remittance account. See "About Remittance Criteria".

    Note:

    • Remittance is not supported for pipeline-rated events.

    • You cannot use the same combination of remittance account and remittance product in more than one specification.

    • You cannot see the balance owed to a remittance account until you run the remittance utility.

About Remittance Criteria

You define a remittance criterion by assigning a value to a remittance field. Each field represents an attribute of a storable class.

The following remittance fields are available by default:

  • service type

  • product name

  • event type

  • name of a profile associated with an account

For example, you can specify that all cycle forward events for the product Internet Access and /service/ip contribute to remittance.

Important:

You must define an event type as one of your remittance criteria.

These fields are defined in the remittance fields file. You must load this file into BRM before you define remittance criteria.

A technical person can also create additional custom fields. Do this if you want remittance to depend on criteria other than the defaults. For example, if you want remittance to depend on a telephony gateway or a brand name, you must define custom fields in this file.

Customizing the remittance fields file requires an understanding of BRM storable classes. For more information, see "Defining Custom Remittance Fields".

About Calculating Remittance

You run the remittance utility, "pin_remittance", to calculate the amount you must pay to third parties.

When an event occurs that meets the defined criteria, BRM stores the remittance information about the event. BRM later uses the stored information to calculate payments when you run the remittance utility.

When BRM rates an event, it runs an opcode to evaluate the criteria defined in your remittance specification. If the event meets a set of criteria, BRM stores information relevant to remittance, such as the remittance account and product.

The remittance utility uses that information to calculate the amount to pay each remittance account.

The remittance utility does the following:

  • Collects the remittance information that BRM previously stored in separate objects.

  • Creates a new event for each combination of remittance account and product.

  • Calculates the amount to pay each account for each event by rating the event and stores that data for reporting purposes.

Typically, you run the remittance utility monthly. You can run it separately or as part of the monthly remittance script, pin_remit_month.

Before running the remittance utility, you should first run billing on all accounts except remittance accounts. This is especially true if you defined your remittance specifications so that events that contribute to remittance must be billed or paid before you pay the third parties. For more information, see "Running Billing Utilities".

You then do the following, either by running pin_remit_month or as separate steps:

  1. Run the remittance utility to calculate the amount owed to each remittance account.

  2. Run the billing utility on only the remittance accounts.

  3. Run invoicing on only the remittance accounts.

For more information on how to calculate remittance, see "Calculating Remittance".

Setting Up Remittance

To set up remittance, use the following steps. Each step includes a link to a detailed procedure.

  1. Create one or more remittance products in Pricing Center, based on the remittance event, and include them in a deal. See "Creating a Remittance Product".

  2. Create an account in Customer Center for each third party that you want to receive funds. See "Creating a Remittance Account".

  3. Load the remittance fields file into the BRM database. You do this whether or not you add custom fields to the remittance fields file. This makes the fields available to the remittance specification. See "Loading the Remittance Fields File".

  4. Create your remittance specifications. Each specification matches a remittance product and account with a set of remittance criteria. See "Defining Remittance Specifications".

  5. Load the remittance specification. This makes the specification available to BRM so it can begin collecting remittance information. See "Loading the Remittance Specifications".

Creating a Remittance Product

To create a remittance product, follow the procedure in Pricing Center Help. The following steps are specific to a remittance product:

  1. In the Product Creation Wizard or in the General Product Info tab, select /account instead of a service in the Applies To field. This indicates that the remittance product is not connected with a service.

  2. In the Event Map, select Remittance Event for Event.

  3. In the Event Map, select one of the following metrics for Measured By: Number, Usage Time, Usage Size, and Amount.

    Important:

    Do not use the metric Occurrence. Pricing Center enables you to use it in your remittance product, but this metric will not work with remittance.

    Use each metric as shown in Table 12-2:

    Table 12-2 Examples of Metrics

    Metric Use To Example

    Number

    Calculate remittance for a given event type based on a flat fee per occurrence.

    You want to remit $5 for each cycle forward event.

    Usage Time

    Calculate remittance based on a flat fee for the duration of an event.

    You want to remit $1 for each hour of Internet usage.

    Usage Size

    Calculate remittance based on the size of the event.

    You want to remit $1 for each 5megabytes (MB) of storage space a customer uses each month.

    Amount

    Calculate remittance based on a percentage of the rated dollar amount

    You want to remit 25% of a customer's total monthly fees for Internet usage to the customer's branded service provider.


    Note:

    You can also create custom metrics. See "About Setting Up RUMs for Real-Time Rating" in BRM Setting Up Pricing and Rating.
  4. In Rate Plan Properties, specify the balance impact as follows:

    • If Number, Usage Time, or Usage Size is the metric, specify a negative value. For example, if the metric is Number, the balance impact might be -5 US dollars.

      The number is negative because you want BRM to credit the account that owns this product.

If Amount is the metric, specify a negative value that represents a percentage. For example, -.05 represents -5%.

Note:

Pricing Center lets you use positive values in the product balance impact. If you do this, BRM debits, rather than credits, the remittance account.

Important:

Pricing Center does not validate your remittance product to ensure that you used a valid metric or entered a balance impact that makes sense.

Creating a Remittance Account

You must create an account for each third party that you pay remittance. That account can only purchase plans and deals that contain remittance products.

Follow the normal procedure for creating accounts in Customer Center. See the discussion about creating a consumer or business account in the Customer Center Help.

Use Invoice for the payment method. The invoices will show a negative balance due for remittance accounts.

Most other payment methods do not make sense for remittance. In particular, using Credit card or Direct debit as the payment method causes errors when you run the remittance utility, pin_remittance.

Loading the Remittance Fields File

The remittance fields file makes fields from storable classes available for setting up remittance criteria. You must load this file into BRM before you define your remittance specifications.

This file contains default fields you can use to define specifications that cover many common remittance scenarios. Custom fields can also be added. For more information, see "About Defining Remittance Specifications" or the description in the remittance fields file, pin_remittance_flds.

To load the remittance fields file:

  1. Go to a directory with a valid configuration file.

    Typically, you go to the directory that contains the remittance fields file: /sys/data/pricing/example. The "load_pin_remittance_flds" utility uses the configuration file for information on how to connect to the BRM database. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  2. Enter this command:

    BRM_Home/bin/load_pin_remittance_flds file_name
    

    where BRM_Home is the directory where you installed BRM components.

    In place of file_name, enter the name and path of the pin_remittance_flds file.

    You do not need to specify a file name if you use the default file name of pin_remittance_flds and you run the command from the same directory where the file resides.

To verify that the pin_remittance_flds file was loaded, you can display the /config/remittance_flds object by using the Object Browser, or use the robj command with the testnap utility.

For general instructions on using testnap, see "Using testnap" in BRM Developer's Guide. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

Defining Remittance Specifications

You define the conditions that cause BRM to pay funds to a third party in a remittance specification. For more information, see "About Defining Remittance Specifications".

To create a remittance specification:

  1. Open the remittance specification file (BRM_Home/sys/data/pricing/example/pin_remittance_spec) in any text editor.

    The next steps refer to the following example of a simple specification:

    ACCOUNT_BEGIN
    
       remittance_account_number  0.0.0.1-9617
       remittance_type            B
       remittance_product_name    Product 6a - Flat Fee Remittance
    
       CRITERIA_BEGIN
          field   service_type    = /service/ip 
          field   product_name    = Product 1a - Internet Access 
          field   event_type      = /event/session/dialup
       CRITERIA_END
    
    ACCOUNT_END
    
  2. Enter ACCOUNT_BEGIN to start a new specification.

  3. Enter the number of the account that receives the remittance. For example:

    remittance_account_number  0.0.0.1-9617
    
  4. Enter the remittance type, which is one of three values:

    • B: Billed. BRM does not credit the remittance account until the event that triggers the remittance has been billed.

    • P: Paid. BRM does not credit the remittance account until the event that triggers the remittance has been paid and the corresponding bill item closed.

      A bill item is closed for a BRM-initiated payment when you run pin_collect, and for an externally initiated payment when you submit a batch of payments through Payment Tool. You can also close a bill item when you transfer amounts between bill items through the Bill Details panel in Customer Center.

      For more information on pin_collect, see BRM Configuring and Collecting Payments.

    • U: Unbilled. BRM credits the remittance account whether or not the event that triggers the remittance has been billed or paid.

    For example:

    remittance_type            B 
    
  5. Enter the remittance product name. BRM uses this product to determine the remittance rate. The remittance account must own the product you specify. For example:

    remittance_product_name    Product 6a - Flat Fee Remittance 
    
  6. Enter CRITERIA_BEGIN to start the criteria section of the specification.

  7. Enter one or more remittance criteria. These criteria are a series of statements. Each statement includes a field from the remittance fields file, an operator, and a value. For example:

    field   event_type    = /event/session/dialup 
    

    In this statement:

    • field identifies the item that follows (service_type) as a field from the remittance fields file. It must start every line within the list of criteria.

    • event_type is a field from the remittance fields file. Typically, you use at least three default fields as criteria: event_type, service_type, and product_name.

      Note:

      Whenever the product name changes, you must update the pin_remittance_spec file and reload it into the database.

      You can also use the default field profile_name or a custom field. For information on using custom fields, see "About Adding Custom Remittance Criteria".

      You must include the event_type field as one of your criteria.

    • = (equal sign) is the operator. This is the only valid operator for service_type, product_name, event_type, and profile_name. For a list of operators you can use with other fields, see the pin_remittance_spec file.

    • /service/ip is the value for service_type.

  8. Enter CRITERIA_END at the end of the criteria.

  9. Enter ACCOUNT_END at the end of the specification.

    Note:

    If you want the same remittance account to receive payment for additional remittance products, then create a separate remittance specification for each product. You cannot use the same combination of remittance account and remittance product in more than one specification.

For more details on creating remittance specifications, see the instructions in the pin_remittance_spec file.

Loading the Remittance Specifications

Load the remittance specifications into your database by following one of these procedures:

Loading Remittance Specifications on Single-Schema Systems

Use the utility "load_pin_remittance_spec" to load the remittance specification file into BRM:

  1. Go to a directory that contains a valid configuration file.

    Typically, you go to the directory that contains the remittance criteria file: BRM_Home/sys/data/pricing/example. The load_pin_remittance_spec utility uses information in the configuration file to connect to the BRM database. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  2. Enter this command:

    BRM_Home/bin/load_pin_remittance_spec file_name
    

    where file_name is the name and path of the pin_remittance_flds file.

    You do not need to specify a file name if you use the default file name pin_remittance_spec and you run the command from the directory in which the file resides.

  3. Stop and restart the Connection Manager (CM). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

    Note:

    You must follow this procedure every time you change the remittance specification file.

To verify that the pin_remittance_spec file was loaded, display the /config/remittance_spec object by using the Object Browser, or use the robj command with the testnap utility.

For general instructions on using testnap, see "Using testnap" in BRM Developer's Guide. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

Loading Remittance Specifications on Multischema Systems

To load remittance specifications on a multischema system, perform the following procedure on your primary BRM installation system:

Important:

You must follow this procedure every time you change the remittance specification file.
  1. Combine the remittance specifications for all database schemas into one master remittance specification file.

  2. Go to a directory that contains a valid configuration file (pin.conf) for connecting to your BRM database schemas. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  3. Run the load_pin_remittance_spec utility by entering this command:

    BRM_Home/bin/load_pin_remittance_spec file_name
    

    where file_name is the name of your master remittance specification file. For information, see "load_pin_remittance_spec".

  4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  5. Stop and restart the CM and all primary and secondary Data Managers (DMs). See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

  6. (Optional) To verify that the pin_remittance_spec file was properly loaded, display the /config/remittance_spec object by using the Object Browser or the robj command with the testnap utility.

    For general instructions on using testnap, see "Using testnap" in BRM Developer's Guide. For information about reading an object and writing its contents to a file, see "Reading an Object and Writing Its Contents to a File" in BRM Developer's Guide.

Running Remittance

Before running remittance, you should run billing for all non-remittance accounts. This ensures that BRM will calculate all remittance that depends on events being billed or paid. For more information, see "Running Billing Utilities".

Use the following steps each time you run remittance. Each step includes a link to a detailed procedure:

  1. Calculate remittance. Then run billing and invoicing for the remittance accounts. See "Calculating Remittance".

  2. Run a BRM report that summarizes the amount due to each remittance account. See "Creating Remittance Reports".

  3. Change the balance of each remittance account to reflect payments you made. See "Changing the Balance of a Remittance Account".

When you run remittance, you can use the pin_remittance utility -b parameter to choose whether to trigger billing of remittance accounts before calculating remittance. By default, the pin_remit_month script runs the pin_remittance utility with the -b parameter which ensures that remittance is calculated before the remittance account is billed.

If you do not use the -b parameter, remittance owed to the account in the current billing cycle is not credited to it until the next billing cycle.

Calculating Remittance

Use the pin_remittance utility to calculate the amount you must pay to each third party. You can run remittance as part of a monthly remittance script or you can run it separately.

For information on how BRM calculates remittance, see "About Calculating Remittance".

Running the Monthly Remittance Script

To calculate remittance:

  1. Run the daily, weekly, and monthly billing scripts.

    By default, these scripts run billing on non-remittance accounts only. You should keep this default. You want to bill remittance accounts after calculating remittance, so the bills and invoices for these accounts are up-to-date.

    For information on running these scripts, see "Running Billing Utilities".

  2. Run the monthly remittance script:

    pin_remit_month 
    

    This script does the following:

    • Runs the remittance utility, pin_remittance. For more information on this utility, see "Running the Remittance Utility Separately".

    • Runs billing for remittance accounts.

    • Runs invoicing for remittance accounts.

      Note:

      You can run pin_remit_month at any time interval that is appropriate for your business. Running it monthly is one common approach.

Running the Remittance Utility Separately

To run the utilities in pin_remit_month separately:

  1. Change to a directory with a valid configuration file. See "Creating Configuration Files for BRM Utilities" in BRM System Administrator's Guide.

  2. Run the remittance utility:

    pin_remittance 
    

    By default, pin_remittance does the following:

    • Calculates remittance for all remittance accounts.

    • Includes events that occurred up to midnight the previous day in its calculations.

    • Creates a remittance report in a text file. See "Creating Remittance Reports".

    For information on changing these defaults and on the utility's syntax, see "pin_remittance".

    The remittance utility is located in BRM_Home/bin.

  3. Run the billing utility on inactive, closed, and active remittance accounts:

    pin_bill_accts -inactive -remit only 
    pin_bill_accts -close -remit only 
    pin_bill_accts -active -remit only 
    

    For more information, see "Billing Accounts with the pin_bill_accts Utility" or "pin_bill_accts".

  4. Run the invoice utility:

    pin_inv_accts -pay_type 10001 
    

    For more information, see "Generating Invoices" in BRM Configuring and Running Billing or "pin_inv_accts" in BRM Designing and Generating Invoices.

Creating Remittance Reports

You can get two reports for remittance:

  • The pin_remittance utility creates a report that lists the amount remitted to each account each time you run the utility. The report is in a text file named rem_date.rep, where date is the end date for which remittance events are included in the calculation. By default, the end date is the current date.

    Table 12-3 contains an example of this report:

    Table 12-3 Remittance Report Example

    Acct No. Start Date End Date Amount Remitted

    0.0.0.1-9929

    06/07/2001

    08/13/2001

    -676.2

    0.0.0.1-10057

    06/07/2001

    08/13/2001

    -9382.25

    0.0.0.1-10185

    06/07/2001

    08/13/2001

    0


    Note:

    The negative values in the report represent balances owed to third parties.

    You use this report to review the amounts that pin_remittance calculated and to verify that the information is correct.

You can create a report that provides a summary of remittance due to each account for your payables department. You can generate this report for different time periods, account numbers, states, countries, and item types. For more information, see pin_remittance in BRM Configuring and Running Billing.

Caution:

In a multischema system, the Remittance report is accurate only when each service provider account's associated remittance objects, remittance events, content connector events, and user accounts are in the same database schema. If they are not all in the same schema, some data is not included in the reports.

Changing the Balance of a Remittance Account

When you send funds to a remittance account, you use an adjustment in BRM to change the account's balance. For example, if the account shows a balance of -50, and you pay $50 to the third party, you must create an adjustment of $50 to change the balance to 0.

For information on adjustments, see "About Adjustments" in BRM Managing Accounts Receivable.

Using Remittance with Brands

If your BRM system has Brand Manager, you can set up remittance to work with brands. Typically, you want to pay a different third party depending on which brand a subscriber account belongs to.

For example, if a subscriber account belongs to Brand A, you want to remit funds to Remittance Account A. But if the subscriber account belongs to Brand B, you want to pay Remittance Account B.

To do this:

  1. Define a field in the remittance fields file called, for example, brand_name. For more information, see "Defining Custom Remittance Fields".

  2. Set up a separate remittance specification for each brand. In each specification, include the following:

    • As one of the criteria, make brand_name equal to a particular brand.

    • Make the remittance_account equal to the account that receives remittance from subscribers of this brand.

This is a sample brand-specific remittance specification:

ACCOUNT_BEGIN

   remittance_account_number      0.0.0.1-9617
   remittance_type                B
   remittance_product_name        Product 7a - Brand A Remittance
   CRITERIA_BEGIN
      field   service_type        =          /service/ip 
      field   product_name        =          IP async bulk 10 
      field   event_type          =          /event/session/dialup
      field   brand_name          contains   Brand A
   CRITERIA_END

For more information on creating specifications, see "Defining Remittance Specifications".

Using Remittance with Multiple Database Schemas

If you have multiple BRM database schemas, you must run the remittance utility (pin_remittance) for each schema. You can do this in either of these ways:

Depending on your setup, a single event can contribute remittance to more than one remittance account. In a multischema environment, those remittance accounts can be in different schemas. All remittance account balances are updated only when you run the remittance utility for all schemas.

Running Remittance on One Schema at a Time

Running the remittance utility on multiple database schemas one at a time requires that you edit the remittance utility configuration file every time you run the remittance utility. Perform the following procedure before you run remittance:

  1. Open the remittance utility configuration file BRM_Home/apps/pin_remit/pin.conf.

  2. Change the value of the userid entry to the schema against which you want to run remittance.

    For example, to run remittance on schema number 0.0.0.2, change the userid entry as follows:

    - - userid 0.0.0.2 /service/pcm_client 1
    
  3. Change the value of the login_name entry to an account that resides in the schema against which you want to run remittance.

    For example, to run remittance using the root.0.0.0.2 account, change the login_name entry as follows:

    - nap login_name root.0.0.0.2 
    
  4. Save the file.

  5. Run the remittance utility. See "Running Remittance".

Running Remittance on Multiple Schemas Simultaneously

Running remittance on multiple database schemas simultaneously requires that you create parallel instances of the remittance utility configuration file, each of which is configured for a particular schema. Then, you run all instances of your remittance utility.

  1. For each schema you want to run remittance on, create a subdirectory in BRM_Home/apps/pin_remit.

    For example, BRM_Home/apps/pin_remit/db1 for schema 1, BRM_Home/apps/pin_remit/db2 for schema 2, and so on.

  2. Copy the BRM_Home/apps/pin_remit/pin.conf file into each new subdirectory.

  3. In each subdirectory, do the following:

    1. Open the pin.conf file.

    2. Change the schema number in the login_name entry to an account that resides in the schema against which you want to run remittance.

      For example, to run remittance against schema number 0.0.0.2, change the login_name entry as follows:

      - nap login_name root.0.0.0.2 
      
    3. Save the file.

  4. Run the remittance utility from the new subdirectories. See "Running Remittance".

Improving Remittance Performance

If remittance-related events occur frequently in your BRM system, it can affect your system's performance. You can improve performance by increasing the time interval for refreshing the status of remittance accounts and products.

BRM caches remittance account-product status information and refreshes the information based on the time interval specified in the CM configuration file.

By default, this interval is set to 300 seconds (five minutes). If the status of an account or product changes, BRM does not get the status change for calculating remittance until the next interval. For more information on what happens when BRM calculates remittance, see "About Calculating Remittance".

To change the time interval for refreshing the status of remittance accounts and products:

  1. Open the CM configuration file (BRM_Home/sys/cm/pin.conf).

  2. Change the value of the remit_cache_refresh_interval entry:

    - fm_remit remit_cache_refresh_interval 300 
    

    The interval value is in seconds, with a default of 300 seconds. You can change it as follows:

    • To improve remittance performance, increase the interval to refresh the status of accounts and products less frequently. The longer the interval, the more you must increase it to get equivalent performance improvements.

      For example, increasing the interval from 5 to 10 gives you a much greater performance improvement than increasing it from 300 to 305.

    • To refresh account and product status information more frequently, reduce the interval. This could affect your BRM system's performance.

    • If you want BRM to be immediately aware of status changes, comment out this entry by adding a # symbol at the beginning of the line. If you do this, BRM reads the status information from the database each time an event matches your remittance criteria.

  3. Save the file.

  4. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

Using Remittance for Sales Commissions

You can use the BRM remittance feature to pay commissions to salespeople, but this requires customizing remittance. One approach is to do the following:

  1. For each new subscriber account, have a programmer create a customer profile and include the name of the salesperson in that profile. For information on creating and using profiles, see "About Storing Customer Profile Information" in BRM Developer's Guide.

  2. Create a custom field in the remittance fields file, for example, profile_value. For more information, see "Defining Custom Remittance Fields" or the description in the pin_remittance_flds file.

  3. Create a separate remittance specification for each salesperson. For each specification, include the following criteria:

    • profile_name: This is a default remittance field. Set it to the name of the profile that contains the salesperson's name.

      You must include profile_name as one of the criteria if you are also using an attribute of a profile as one of your criteria.

    • profile_value: Set the custom remittance field you created in step 2 to the salesperson's name.

Example of Setting Up a Remittance Specification

This is an example of how to set up a simple remittance specification. In this example, the remittance account receives 5% of purchase and cycle forward fees from subscribers to a specific product.

  1. In Pricing Center, create a product with the settings shown in Table 12-4:

    Table 12-4 Example Settings for a Remittance Product

    Field Value

    Name

    Remittance Product 1

    Description

    Credit to remittance accounts 5% of the applicable rated purchase and cycle forward events paid by subscribers to a particular Internet access product.

    Product Type

    Subscription

    Applies To

    Account

    Event

    Remittance Event

    Measured By

    Amount

    Rate Plan Structure

    Single Rate Plan

    Balance Impact:

     None

    Resource

    US Dollar

    Scaled Amount

    -.05

    Units

    None


  2. In Pricing Center, create a deal and plan, as shown in Table 12-5:

    Table 12-5 Example Deal and Plan

    Field Deal Plan

    Name

    Remittance Deal 1

    Remittance Plan 1

    Include

    Remittance Product 1

    Remittance Deal 1


  3. In Pricing Center, add Remittance Plan 1 to the CSR-new plan list and commit the plan list to your BRM database.

  4. In Customer Center, create an account that includes the settings shown in Table 12-6:

    Table 12-6 Settings for Account

    Field Value

    Plan

    Remittance Plan

    Name

    Service Provider 1 (representing the name and contact information for a service provider you are sharing revenues with)

    Payment Method

    Invoice


    This account will receive 5% of rated events as defined in the product Remittance Product 1.

  5. Load the default remittance field file into BRM. Go to BRM_Home/data/pricing/examples and enter:

    load_pin_remittance_flds pin_remittance_flds
    
  6. In a text editor, open the remittance specification file, BRM_Home/sys/data/pricing/example/pin_remittance_spec.

  7. Add the following to the end of the file:

    ACCOUNT_BEGIN
    
       remittance_account_number  0.0.0.1-8422
       remittance_type            B
       remittance_product_name    Remittance Product 1
    
       CRITERIA_BEGIN
          field   service_type    = /service/ip 
          field   product_name    = Product 1a - Internet Access 
          field   event_type      = /event/billing/product/fee/purchase
       CRITERIA_END
    
      CRITERIA_BEGIN
          field   service_type    = /service/ip 
          field   product_name    = Product 1a - Internet Access 
          field   event_type      = /event/billing/product/fee/cycle/cycle_forward_monthly
       CRITERIA_END
    
    ACCOUNT_END
    
  8. Load the remittance specification file into BRM. Go to BRM_Home/data/pricing/examples and enter:

    load_pin_remittance_spec pin_remittance_spec
    
  9. Stop and restart the CM. See "Starting and Stopping the BRM System" in BRM System Administrator's Guide.

You have now implemented this remittance specification. When you run pin_remittance, BRM credits 5% of the purchase and cycle forward fees from the Internet Access product to the remittance account you created.

About Customizing Remittance

BRM provides a default set of fields in storable classes mapped to remittance fields, which you can use to specify remittance criteria.

You can customize remittances in the following ways:

About Adding Custom Remittance Criteria

To add custom remittance criteria, you must specify the BRM fields used to define these criteria, and map each BRM field to a corresponding remittance field in the pin_remittance_flds file. BRM then validates each criterion based on the fields specified in the pin_remittance_flds file.

To add custom remittance criteria, you must perform these tasks:

  1. Create a remittance product in Pricing Center. For more information, see "Creating a Remittance Product".

  2. Create a remittance account in Customer Center. For more information, see "Creating a Remittance Account".

  3. Select the criteria for remittance. For example, you may want to add a new criteria called brand_name in addition to the criteria already provided.

  4. Define the remittance field for every criterion selected, if a BRM field is not already defined in the pin_remittance_flds file, and map each field to the corresponding remittance criterion.

  5. In the pin_remittance_spec file, specify the criteria that determine which third party receives remittance and the product BRM uses to calculate remittance.

    The pin_remittance utility calculates the remittance amount for all events that meet the criteria you define in this file.

Defining Custom Remittance Fields

The pin_remittance_flds file contains default fields that help you calculate remittance. You must load this file into the BRM system to define remittance specifications. For more information, see "Loading the Remittance Fields File".

You can add more fields to this file, to define custom criteria in the pin_remittance_spec file.

Each field in the remittance fields file makes an attribute of the BRM storable class available for defining remittance criteria in the pin_remittance_spec file. To specify custom fields in this file, you must know about BRM fields and storable classes. For more information, see "About Storable Classes and Storable Objects" in BRM Developer's Guide.

A custom remittance field definition contains four columns separated by one or more spaces:

<remittance field name> <base class> <substruct> <BRM field>

Remittance Field Name

This name is the field identifier. You must provide this name when you specify remittance criteria in the remittance specification file.

Precede the name with the word ”field” followed by a space. For example, "field origination_gw".

Do not use blank spaces within the name itself. You cannot specify a name already in use for one of the reserved attributes.

Base Class of the Attribute

BRM supports attributes for these base storable classes:

  • EVENT

  • ACCOUNT

  • PROFILE

You must always specify the base class for an attribute.

Substruct Name

The name of the substruct within which the field is located. This must be a valid substruct name as specified in the BRM data dictionary. For example, for a telco call event, the PIN_FLD_CALLING_FROM field is contained within the substruct PIN_FLD_TELCO_INFO. If there are no substructs, specify NONE. You cannot use arrays or fields within arrays.

Attribute Name

The name of the attribute specified in the BRM data dictionary. For example, for the origination gateway of a telco call event, specify the PIN_FLD_CALLING_FROM field.

This example shows the remittance field definition for other call origination:

field origination    EVENT    PIN_FLD_TELCO_INFO    PIN_FLD_CALLING FROM
  • The first column is the remittance field name, which identifies the field defined in the pin_remittance_spec file.

  • The second column is the base class of the attribute. You can specify only EVENT, ACCOUNT, or PROFILE.

    The third column is the name of the substruct in the BRM database that contains the field.

  • If the attribute is contained within a substruct name, specify the BRM name of the substruct; otherwise specify NONE.

  • The fourth column is the BRM field name for the attribute.

To add a brand_name field to indicate the brand, add the following line beneath the reserved fields:

field    brand_name    ACCOUNT NONE    PIN_FLD_GL_SEGMENT 

Important:

Do not change or delete the reserved attributes in the remittance fields file. However, you can edit this file to add fields.

This example shows you how to add custom remittance fields:

service_type             RESERVED
event_type               RESERVED
product_name             RESERVED
profile_name             RESERVED
field Origination     EVENT      PIN_FLD_TELCO_INFO         PIN_FLD_CALLING FROM
field Destination     EVENT      PIN_FLD_TELCO_INFO         PIN_FLD_CALLED TO
field Brand_name         ACCOUNT    NONE                 PIN_FLD_GL_SEGMENT
field Profile_value      PROFILE    PIN_FLD_LDAP_INFO    PIN_FLD_DN

Specifying Custom Remittance Criteria

In the remittance specification file, specify the custom criteria you want to use in remittance calculation and then define the corresponding fields in the remittance fields file.

For syntax and instructions on specifying single and multiple sets of criteria for an account, see the pin_remittance_spec file.

Specifying Remittance Criteria for Sales Commissions

Use multiple criteria specification to remit sales commissions to salespersons. For example, to remit $1 to every salesperson for each cycle of the salesperson's IP accounts, do the following:

  1. For each salesperson, create a remittance account (remittance product and plan can be shared).

  2. When you create customer accounts, use the salesperson's name in the profile.

  3. Create custom criteria for each salesperson.

This example shows how to use multiple criteria specification to remit sales commissions:

ACCOUNT_BEGIN
remittance_account_number0.0.0.1-10001  
#sales person A's remittance account
remittance_typeP
remittance_product_name   SalesCommissionProduct
CRITERIA_BEGIN
field service_type=/service/ip 
field event_type =/event/billing/product/fee/cycle/cycleforward_monthly
fieldprofile_name= SalesA
CRITERIA_END
ACCOUNT_END
ACCOUNT_BEGIN
remittance_account_number0.0.0.1-10002 
#salesperson B's remittance account
remittance_typeP
remittance_product_name   SalesCommissionProduct
CRITERIA_BEGIN
fieldservice_type=/service/ip 
fieldevent_type=/event/billing/product/fee/cycle/cycle_forward monthlyfieldprofile_name= SalesB
CRITERIA_END
ACCOUNT_END
ACCOUNT_BEGIN
remittance_account_number0.0.0.1-10003 
#salesperson C's remittance account
remittance_typeP
remittance_product_name   SalesCommissionProduct
CRITERIA_BEGIN
fieldservice_type =/service/ip 
fieldevent_type =/event/billing/product/fee/cycle/cycle_forward_monthlyfieldprofile_name = SalesC
CRITERIA_END
ACCOUNT_END

For more information about using remittance for sales commissions, see "Using Remittance for Sales Commissions".

About Using Custom Ratable Usage Metrics to Calculate Remittance

Remittance products use the /event/billing/remittance event type. To calculate remittance for an event type, set its ratable usage metric (RUM) to the appropriate name. For a list of RUMs you can use to create a remittance product, see "Creating a Remittance Product".

BRM supplies a set of default ratable usage metrics (RUMs) for remittance products, but you can also calculate remittance based on custom RUMs.

For information on how to create and load custom RUMS into the BRM database, see "About Setting Up RUMs for Real-Time Rating" in BRM Setting Up Pricing and Rating.

Calculating Remittance Using Custom RUMs

The BRM system recognizes the ratable quantity only for default RUMs. To use a custom RUM, you must modify the PCM_OP_REMIT_POL_SPEC_QTY policy opcode. See "Customizing Remittance".

How Remittance Works

Use the following opcodes to manage remittance:

Retrieving Remittance Accounts

Use PCM_OP_REMIT_GET_PROVIDER to retrieve a list of remittance accounts that are owed for a particular event.

PCM_OP_REMIT_GET_PROVIDER performs the following:

  1. Determines whether an event meets any criteria that you specified in the pin_remittance_spec file. See "Defining Remittance Specifications".

  2. Retrieves the following remittance information from the event itself and the /config/remittance_spec object:

    • Event object POID

    • Item object POID

    • Remittance account object POID

    • Remittance product object POID

    • Quantity to rate for the remittance calculation

      Note:

      If the event uses a custom RUM, PCM_OP_REMIT_GET_PROVIDER calls PCM_OP_REMIT_POL_SPEC_QTY to retrieve the quantity. See "Customizing Remittance".
  3. Creates a /remittance_info object.

  4. Returns the POID of the /remittance_info object.

Calculating the Remittance Amount

Use PCM_OP_REMIT_REMIT_PROVIDER to calculate the remittance amount owed to third-party companies. This opcode retrieves remittance data from /remittance_info objects and then calculates the total remittance amount owed to third parties.

This opcode is called directly by the "pin_remittance" utility.

Verifying the Remittance Specification File

Use PCM_OP_REMIT_VALIDATE_SPEC_FLDS to validate remittance criteria before loading it into the BRM database. This opcode validates that the criteria fields you specify in the pin_remittance_spec file are defined in the /config/remittance_flds object.

When the pin_remittance_spec file passes the validation, PCM_OP_REMIT_VALIDATE_SPEC_FLDS returns the PIN_FLD_RESULT field set to PIN_RESULT_PASS. This notifies the calling application to load the specification data into the /config/remittance_spec object.

When the file fails validation, PCM_OP_REMIT_VALIDATE_SPEC_FLDS returns the PIN_FLD_RESULT field set to PIN_RESULT_FAIL. This notifies the calling application to stop the loading process.

This opcode is called directly by the "load_pin_remittance_spec" utility.

Customizing Remittance

Use the PCM_OP_REMIT_POL_SPEC_QTY policy opcode to retrieve the remittance quantity to rate for a custom RUM. By default, this policy opcode returns the PIN_FLD_QTY field for the specified balance impact element. However, you can modify this policy opcode to retrieve the remittance quantity for custom RUMs.