1. Configuring and Collecting Payments
  2. Customizing Payment Applications

15 Customizing Payment Applications

Learn how to customize payment details displayed in Oracle Communications Billing and Revenue Management (BRM) client applications.

Topics in this document:

Customizing Payment Details Displayed in BRM Client Tools

BRM uses /config/paymenttool objects to create payment, reversal, and refund batch type actions in the Payment Tool database. While you can handle most of your payment decisions using Payment Tool, you can also customize actions in the database. This section describes the characteristics of /config/paymenttool objects that you can customize.

When you customize /config/paymenttool, follow the rules defined in "Rules for Modifying Payment and Reversal Fields".

/config/paymenttool is defined in the init_objects.source file, which BRM reads when it starts. The init_objects.source file provides information that determines:

  • What Payment Tool displays, including the columns that are displayed and whether the columns can be used for entering data or are read-only.

  • What the Customer Center Payments tab displays, including the payment method and credit card numbers.

    Note:

    You should make a backup copy of the init_objects.source file each time you modify it. When you upgrade BRM, the installation program overwrites init_objects.source, including your customizations. You can use the backup to restore your changes.

About the Default /config/paymenttool Object

The following is the default config/paymenttool object as defined in init_objects.source. 

! PaymentTool Payment Config object
! Mandatory fields for creation for each PIN_FLD_PAY_TYPES element specified
!
!    PIN_FLD_NAME
!    for each PIN_PAYMENT_TOOL_FIELDS
!        PIN_FLD_FIELD_NAME
!        PIN_FLD_COLUMN_NAME
!        PIN_FLD_PURPOSE
!        PIN_FLD_BATCH_TYPE

TYPE   =   /config/paymenttool
FIELDS =
 array PIN_FLD_PAY_TYPES (           type = PIN_FLDT_ARRAY,      perms = ORW,);
 field * PIN_FLD_NAME (              type = PIN_FLDT_STR(255),   perms = MRW,);
 array * PIN_FLD_PAYMENTTOOL_FIELDS( type = PIN_FLDT_ARRAY,      perms = ORW,);
 field * * PIN_FLD_FIELD_NAME (      type = PIN_FLDT_STR(255),   perms = MRW,);
 field * * PIN_FLD_COLUMN_NAME (     type = PIN_FLDT_STR(255),   perms = MRW,);
 field * * PIN_FLD_PURPOSE (         type = PIN_FLDT_INT,        perms = MRW,); 
 field * * PIN_FLD_BATCH_TYPE(
                 type = PIN_FLDT_INTINT,
                 perms = MRW,
);

Rules for Modifying Payment and Reversal Fields

All changes you make in /config/paymenttool are reflected in the Payment Tool graphical user interface when you stop and restart BRM. If you are changing or adding values to the payment or reversal fields, follow these rules:

  • If you add a bill type in the /config/paymenttool storable class, you must add a corresponding entry in the /config/payment storable class.

  • All user-defined fields for a particular type (data entry or display) for a given batch should be from the same array in the /event object.

    See the /config/paymenttool and /event storable class definitions.

  • If the charge opcode fields in /config/payment are valid, the display fields for the corresponding reversal batch should be from /event/billing/charge/name, where name can be defined as a credit card, direct debit, and so on.

    Note:

    The charge object contains a lot of payment information; therefore, it might be useful to display the charge object information when reversing a payment.

  • There must be at least one /config/paymenttool object for each supported language.

    You can set a language as the default by entering Default in PIN_FLD_NAME as shown below: 

    0 PIN_FLD_NAME     STR [0] "PaymentTool payment Types: Default"

    By default, the language is set to English (United States).

    The Customer Center, Payment Tool, and Payment Center client applications read the /config/paymenttool object that has PIN_FLD_NAME set to Default.

    To customize the client applications to read a specific locale of English, update PIN_FLD_NAME in the /config/paymenttool object as shown in the following examples:

    • For English (United States): 

      0 PIN_FLD_NAME 			          STR [0] "PaymentTool payment Types: English(United States)"

    • For English (United Kingdom): 

      0 PIN_FLD_NAME           STR [0] "PaymentTool payment Types: English(United Kingdom)"

    You can also use the PCM_OP_WRITE_FLDS opcode to set the locale.

    Note:

    The country name you specify should exactly be the same as the country name in the language parameter for that particular locale.

  • In the /config/paymenttool definition, an array element must always begin with PIN_FLD_PAYMENTTOOL_FIELDS. Each array corresponds to an array element in the /config/payment object. The sequence of array elements determines the order of columns displayed in Payment Tool.

  • A payment batch must have only data-entry fields. A reversal batch can have display and data-entry fields.

  • All the fields you use to enter or display data in Payment Tool for a particular batch grid must be defined in the same array in the object definition.

  • Objects for payment reversal are created as subclasses from /event/billing/payment or /event/billing/reversal.

Creating an Object Definition for a New Payment or Reversal Event

To create a payment or reversal event, start a new PIN_FLD_PAYMENTTOOL_FIELDS array. Use the following example to define your custom fields. Before you define an object, see "Rules for Modifying Payment and Reversal Fields".

PIN_FLD_PAY_TYPES is the first line. The 0 to the left of this line indicates that this is the beginning of a sequence of arrays. 

0  PIN_FLD_PAY_TYPE   ARRAY [0]   allocated 3, used 3

PIN_FLD_NAME indicates that the array has been allocated 5 items and 3 have been used. This line is at the same level as the following PIN_FLD_PAYMENTTOOL_FIELDS items. 

1  PIN_FLD_NAME   ARRAY [10003]   allocated 5, used 3

10003 comes from a corresponding entry in /config/payment/.

PIN_FLD_PAYMENTTOOL_FIELDS begins the definition of an individual, user-defined array. The 1 to the left of the line shows that this is a subset of PIN_FLD_PAYMENTTOOL_FIELDS but of equal status to PIN_FLD_NAME. 

1  PIN_FLD_PAYMENTTOOL_FIELDS   ARRAY [0]   allocated 3, used 3

An example of individual arrays is shown below.

Within the first PIN_FLD_BATCH_TYPE array the numeral 1, not [1], says that this is a reversal batch type while 0 is a payment method. The second PIN_FLD_BATCH_TYPE in this example is also a reversal batch type. Remember that while a payment batch only has data entry fields, a reversal batch can have display and data entry fields.

The first PIN_FLD_PURPOSE, with a value of 1 indicates that this field is read-only. The second PIN_FLD_PURPOSE value is 0, indicating that data can be entered in this field. In other words, you cannot enter information in "Credit Card No.", but you can enter a value for "Chargeback Date". PIN_FLD_FIELD_NAME is the database field name, not the column name (PIN_FLD_COLUMN_NAME).

The values in brackets, [0], [1], and [2] are index values dealing with the sequence of fields. 

1 PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [0] allocated 3, used 3
2   PIN_FLD_BATCH_TYPE       INT [0] 1
2   PIN_FLD_COLUMN_NAME      STR [0] "Credit Card No."
2   PIN_FLD_FIELD_NAME       STR [0] "PIN_FLD_DEBIT_NUM"
2   PIN_FLD_PURPOSE          INT [0] 1
1 PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [1] allocated 3, used 3
2   PIN_FLD_BATCH_TYPE       INT [0] 1
2   PIN_FLD_COLUMN_NAME      STR [0] "Chargeback Date"
2   PIN_FLD_FIELD_NAME       STR [0] "PIN_FLD_EFFECTIVE_T"
2   PIN_FLD_PURPOSE           INT [0] 0

Changing the Order of Columns in Payment Tool

The sequence of fields, PIN_FLD_PAYMENTTOOL_FIELDS, determines the order of columns in Payment Tool. If you are not satisfied with the default settings and you want to add another column of information or change a column name, you must customize Payment Tool. To do this, you must change the /event/billing/payment, /event/billing/reversal, and /config/paymenttool objects.

To change the order of the columns, you must change the order of PIN_FLD_PAYMENTTOOL_FIELDS arrays in /config/paymenttool because the column order is determined by the order in which they appear in this object.

In the following example, the three configurable, user-defined columns are in the order:

  • Credit Card No.

  • Chargeback Date

  • Reason Code

0 PIN_FLD_PAY_TYPES       ARRAY [10003] allocated 5, used 5
1   PIN_FLD_NAME                STR [0] "Credit Card"
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [0] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Credit Card No."
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_DEBIT_NUM"
2      PIN_FLD_PURPOSE            INT [0] 1
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [1] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Chargeback Date"
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_EFFECTIVE_T"
2      PIN_FLD_PURPOSE            INT [0] 0
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [2] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Reason Code"
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_REASON_CODE"
2      PIN_FLD_PURPOSE             INT [0] 0

To change the order of the columns in Payment Tool, you must change the order of each array. In the following example, the columns are in the order:

  • Credit Card No.

  • Reason Code

  • Chargeback Date

0 PIN_FLD_PAY_TYPES      ARRAY [10003] allocated 5, used 5
1   PIN_FLD_NAME                STR [0] "Credit Card"
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [0] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Credit Card No."
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_DEBIT_NUM"
2      PIN_FLD_PURPOSE            INT [0] 1
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [1] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Reason Code"
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_REASON_CODE"
2      PIN_FLD_PURPOSE            INT [0] 0
1   PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [2] allocated 3, used 3
2      PIN_FLD_BATCH_TYPE         INT [0] 1
2      PIN_FLD_COLUMN_NAME        STR [0] "Chargeback Date"
2      PIN_FLD_FIELD_NAME         STR [0] "PIN_FLD_EFFECTIVE_T"
2      PIN_FLD_PURPOSE             INT [0] 0

Adding a New Column to Payment Tool

To add a new column to Payment Tool, you add a new column section to an array in /config/paymenttool. The new section contains information needed for that column.

The following example shows the information for a Customer Complaint column: 

1 PIN_FLD_PAYMENTTOOL_FIELDS  ARRAY [0] allocated 3, used 3
2   PIN_FLD_BATCH_TYPE          INT [0] 1
2   PIN_FLD_COLUMN_NAME         STR [0] "Customer Complaint"
2   PIN_FLD_FIELD_NAME          STR [0] "PIN_FLD_COMPLAINT"
2   PIN_FLD_PURPOSE              NT32 [0] 1

Adding Direct Debit Details to the Customer Center Payments Tab

By default, the Customer Center Payments tab does not display details from payment vendors on whether direct debit payments were authorized. To have the direct debit details added to the Payments tab, add the direct debit fields to the PIN_FLD_PAY_TYPES array of the /config/paymenttool storable class.

  1. Use the PCM_OP_WRITE_FLDS opcode to add the direct debit vendor details to the /config/paymenttool storable class. Call the opcode using flag 32. For example: 

    0 PIN_FLD_POID POID [0] 0.0.0.1 /config/paymenttool 10574 0 
0 PIN_FLD_OP_CORRELATION_ID STR [0] "2:CT1255:UnknownProgramName:0:AWT-EventQueue-0:5:1226568418:0:root.0.0.0.1::user1:123456789" 
0 PIN_FLD_PAY_TYPES ARRAY [10005] allocated 2, used 2 
1 PIN_FLD_NAME STR [0] "Direct Debit" 
1 PIN_FLD_PAYMENTTOOL_FIELDS ARRAY [4] allocated 4, used 4 
2 PIN_FLD_BATCH_TYPE INT [0] 0 
2 PIN_FLD_COLUMN_NAME STR [0] "Authorization Result" 
2 PIN_FLD_FIELD_NAME STR [0] "PIN_FLD_RESULT" 
2 PIN_FLD_PURPOSE INT [0] 9 
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/paymenttool 10574 0 
0 PIN_FLD_OP_CORRELATION_ID STR [0] "1:user:UnknownProgramName:0:AWT-EventQueue-0:5:1226568418:0" 
0 PIN_FLD_PAY_TYPES ARRAY [10005] allocated 2, used 2 
1 PIN_FLD_NAME STR [0] "Direct Debit" 
1 PIN_FLD_PAYMENTTOOL_FIELDS ARRAY [5] allocated 4, used 4 
2 PIN_FLD_BATCH_TYPE INT [0] 0 
2 PIN_FLD_COLUMN_NAME STR [0] "Authorization Code" 
2 PIN_FLD_FIELD_NAME STR [0] "PIN_FLD_AUTH_CODE" 
2 PIN_FLD_PURPOSE INT [0] 9 
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/paymenttool 10574 0 
0 PIN_FLD_OP_CORRELATION_ID STR [0] "1:user:UnknownProgramName:0:AWT-EventQueue-0:5:1226568418:0" 
0 PIN_FLD_PAY_TYPES ARRAY [10005] allocated 2, used 2 
1 PIN_FLD_NAME STR [0] "Direct Debit" 
1 PIN_FLD_PAYMENTTOOL_FIELDS ARRAY [6] allocated 4, used 4 
2 PIN_FLD_BATCH_TYPE INT [0] 0 
2 PIN_FLD_COLUMN_NAME STR [0] "Vendor Results" 
2 PIN_FLD_FIELD_NAME STR [0] "PIN_FLD_VENDOR_RESULTS" 
2 PIN_FLD_PURPOSE INT [0] 9 
0 PIN_FLD_POID POID [0] 0.0.0.1 /config/paymenttool 10574 0 
0 PIN_FLD_OP_CORRELATION_ID STR [0] "1:user-idc:UnknownProgramName:0:AWT-EventQueue-0:5:1226568418:0" 
0 PIN_FLD_PAY_TYPES ARRAY [10005] allocated 2, used 2 
1 PIN_FLD_NAME STR [0] "Direct Debit" 
1 PIN_FLD_PAYMENTTOOL_FIELDS ARRAY [7] allocated 4, used 4 PIN_FLD_BATCH_TYPE INT [0] 0 
2 PIN_FLD_COLUMN_NAME STR [0] "Authorization Date" 
2 PIN_FLD_FIELD_NAME STR [0] "PIN_FLD_AUTH_DATE" 
2 PIN_FLD_PURPOSE INT [0] 9

  2. Stop and restart the CM.

    Note:

    All changes you make in /config/paymenttool are reflected in the Customer Center UI when you restart BRM.

Customizing the Date Format of Batch Files in Payment Tool

By default, when processing both imported and manually created batch files, Payment Tool uses the date format of the system locale of the client on which it is running. For example, if the locale is United States English, Payment Tool uses MM/dd/yyyy format. If the locale is New Zealand English, Payment Tool uses dd/MM/yyyy format.

To configure Payment Tool to use a different date format from the one used by your client system:

  1. Open the Payment Tool INI file (C:\Windows\PaymentTool.ini).

  2. In the file, find this entry: 

    DefaultDateFormat=

  3. Set the entry to the appropriate date format.

    Possible values:

    • MM[sc]dd[sc]yyyy

    • dd[sc]MM[sc]yyyy

    where [sc] is the date separator character, such as slash (/) or dot (.), specified in the regional settings of the Windows client.

    Note:

    The values are case sensitive.

    For example:

    DefaultDateFormat=dd/MM/yyyy

    If no date format is specified, Payment Tool uses the default format of the system locale.

You do not need to exit Payment Tool after updating the INI file; the change takes effect the next time you create or import a payment batch.

Customizing the Date Format for Payment Center

You can customize the format of the date displayed in the Payment Search dialog box, the Undo Allocation dialog box, and the Payment Results screen in Payment Center.

To customize the date format for Payment Center:

  1. Open the PaymentCenter_home/paymentcenter.properties file in a text editor, where PaymentCenter_home is the directory in which Payment Center is installed.

    Note:

    If the paymentcenter.properties file does not exist, you must create it manually.

  2. Add the following entry:

    DefaultDateFormat=format

    where format is one of the following:

    • dd/MM/yyyy

    • dd/MMM/yyyy

    • dd.MMMM.yyyy

      where MMMM is the spelled-out name of the month (for example, September).

    • yyyy/dd/MM

    • MMM/dd/yyyy

    • MM/dd/yyyy

    The default is MM/dd/yyyy.

    For example, if you set DefaultDateFormat=dd/MM/yyyy, Payment Center displays June 30, 2012 as 30/06/2012.

  3. Save and close the file.

Improved Performance of Searches for Payment Events in Payment Center

By default, Payment Center retrieves five payment events for each step of a search. You can improve Payment Center's performance of payment event searches by configuring the paymentsearch.stepsize entry in the paymentcenter.properties configuration file.

To configure the step search size:

  1. Open the Payment_Center_home/paymentcenter.properties file in a text editor, where Payment_Center_home is the directory in which Payment Center is installed.

  2. Set the paymentsearch.stepsize entry to a value based on the number of events in your system and your client/server memory configuration. For example: 

    paymentsearch.stepsize=100

  3. Save the file.