cybersource payment manager™...2007/03/29 · cpm nova debit controller administration guide •...

CyberSourcePayment Manager™NOVA Debit Controller Administration Guide

October 2006

CPM NOVA Debit Controller Administration Guide • CyberSource Corporation • October 2006 ii

CyberSource Contact InformationFor questions about CyberSource Payment Manager, [email protected].

For general information about our company, products, and services, go tohttp://www.cybersource.com.

For sales questions about any CyberSource Service, email [email protected] or call 650-965-6000 or 888-330-2300 (toll-free in the United States).

For support information about any CyberSource service, visit the Support Center athttp://www.cybersource.com/support.

Copyright© 10/12/06 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource") furnishes this document and the software described in this document under the applicable agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may use this document and/or software only in accordance with the terms of the Agreement. Except as expressly set forth in the Agreement, the information contained in this document is subject to change without notice and therefore should not interpreted in any way as a guarantee or warranty by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear in this document. The copyrighted software that accompanies this document is licensed to You for use only in strict accordance with the Agreement. You should read the Agreement carefully before using the software. Except as permitted by the Agreement, You may not reproduce any part of this document, store this document in a retrieval system, or transmit this document, in any form or by any means, electronic, mechanical, recording, or otherwise, without the prior written consent of CyberSource.

Restricted Rights LegendsFor Government or defense agencies. Use, duplication, or disclosure by the Government or defense agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement.

For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at 52.227-19 and the limitations set forth in CyberSource Corporation's standard commercial agreement for this software. Unpublished rights reserved under the copyright laws of the United States.

TrademarksCyberSource, the CyberSource logo, SmartCert, and PaylinX are registered trademarks of CyberSource Corporation in the U.S. and other countries. The Power of Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision Manager, and CyberSource Connect are trademarks and/or service marks of CyberSource Corporation. All other brands and product names are trademarks or registered trademarks of their respective owners.

mailto:[email protected]://www.cybersource.commailto:[email protected]://www.cybersource.com/support/

Contents

Chapter 1Getting Started................................................................................................................................1Components of the NOVA Debit Controller...............................................................................1Installing and Configuring the Controller...................................................................................2Configuring the NOVA Debit Gateway Settings........................................................................5

Controller Host .........................................................................................................................5Controller Port ..........................................................................................................................5Enable Controller Checkbox...................................................................................................5

Processing Without the Controller .................................................................................5Using the Controller .........................................................................................................6

Configuring the NOVA Debit Agreement Settings....................................................................7Launching the Controller .............................................................................................................10

Chapter 2Using the Administration Client...............................................................................................11Main Window ................................................................................................................................12Fields in the TID Pool ...................................................................................................................12Adding a Record to the TID Pool................................................................................................14Editing a Record in the TID Pool ................................................................................................15Deleting a Record from the TID Pool .........................................................................................16Refreshing the Main Window .....................................................................................................17Monitoring the Server Status.......................................................................................................18

Chapter 3Application Logging with Log4j ...............................................................................................19

CPM NOVA Debit Controller Administration Guide • CyberSource Corporation • October 2006 iii

Chapter 1

Getting Started

This chapter covers the following topics:

Components of the NOVA Debit ControllerInstalling and Configuring the ControllerConfiguring the NOVA Debit Gateway SettingsConfiguring the NOVA Debit Agreement SettingsLaunching the Controller

Components of the NOVA Debit ControllerThe NOVA Debit Controller consists of the following components:

• Controller ServerThe Controller Server lets CPM access the TID Pool. Your application does not need to access the Controller Server because CPM calls the Controller functions.

• TID PoolThe TID Pool is the Controller’s database. For each merchant ID in the TID Pool, there is a set of TIDs, and each TID has a Last Record Number. The Controller keeps track of the Last Record Number for each TID.

• Controller Administration ClientUse the Controller Administration Client to manage the TID Pool.

CPM NOVA Debit Controller Administration Guide • CyberSource Corporation • October 2006 1

Getting Started Installing and Configuring the Controller

Installing and Configuring the ControllerNote If you are using Oracle, you must use version 9 or later.

To install and configure the controller:

1 The Controller can run from any location on any machine. Copy the Nova_Debit_TID_Controller folder from your installation CD to your hard drive. You may want to put the Nova_Debit_TID_Controller folder in Program Files\CyberSource\PaymentManager. This folder contains the following directories:

2 To create the TID Pool database table, do one of the following:– Run one of the scripts that are in the tablecreate.sql file, which is in the

database directory. One script is for Oracle and one script is for SQL Server.

– Let DBUTIL create the table. You can run the DBUTIL create tables function or update tables function. If you reinstall or upgrade CPM, the TID Pool table will automatically be created.

3 Templates have been provided for populating the TID Pool table. Use one of the lines in the testdata.sql file, which is in the database directory, to create a script for populating the TID Pool database table and then run the script.

After you have created and populated the TID Pool database table, you can use the Controller Administration Client to modify the TID Pool. See Chapter 2, Using the Administration Client, on page 11.

Table 1 Directories for the NOVA Debit Controller

Directory Files in the Directory

bin Batch files for launching the Controller Server and the Controller Administration Client

config Controller configuration properties file and templates for the configuration properties file

database SQL scripts for creating and populating the TID Pool

lib Application filesNote The Microsoft JDBC files can be replaced by a single JAR (mssqlsvr_jdbc.jar). The JDBC driver libraries will vary according to the DBMS version and patch level that is currently installed.

log Log file



4 The config directory contains templates for creating the configuration properties file. Use one of the templates, tidcontroller.properties.oracle or tidcontroller.properties.sqlserver, to create a file named tidcontroller.properties, which contains the Controller configuration properties. Set the following values in the Controller configuration property file:

Table 2 Controller Configuration Properties

Property Description

listener.url IP address or DNS name of the Controller Server

listener.port Port number for the port that the Controller Server listens to

thread.pool.size Number of worker threads created by the Controller Server thread pool during startup

maximum.sequence.number Maximum Last Record Number value after which a rollover occurs. This value should be set to 949.

tid.timeout Maximum length of time in seconds that a TERMINAL_ID can be locked. If this length of time is reached, the Controller unlocks the TERMINAL_ID.

database.driver JDBC driver class name

database.url JDBC URL string used to establish a connection

database.name Name of the database. This property is optional. You must either set this property or embed the database name in the database.url property.

database.user Database username credential for establishing a connection

database.password Database password credential for establishing a connection



Example Controller Configuration Properties File for Microsoft SQL Server

If using Microsoft SQL Server, you must provide values for all the Controller properties as shown in the following example:

Example Controller Configuration Properties File for Oracle

If using Oracle, you must provide values for all the Controller properties as shown in the following example:

listener.url=localhost

listener.port=2001

thread.pool.size=10

maximum.sequence.number=949

database.driver=com.microsoft.jdbc.sqlserver.SQLServerDriver

database.url=jdbc:microsoft:sqlserver://localhost:1433;DatabaseName=CPM;SelectMethod=Cursor

database.name=CPM

database.user=usr

database.password=pwd

listener.url=localhost

listener.port=2001

thread.pool.size=10

maximum.sequence.number=949

database.driver=oracle.jdbc.driver.OracleDriver

database.url=jdbc:oracle:thin:@localhost:1521:xe

database.name=CPM

database.user=usr

database.password=pwd


Getting Started Configuring the NOVA Debit Gateway Settings

Configuring the NOVA Debit Gateway SettingsThe CPM Administration Client’s Gateway Settings dialog includes values for the Controller:

Controller HostThe hostname or IP address of the Controller Server.

Controller PortThe IP port to which the Controller Server listens.

Enable Controller CheckboxThe Enable checkbox lets you enable and disable the Controller.

Processing Without the ControllerDebit transactions are submitted to NOVA on a Terminal ID (TID) basis. Typically, each PIN pad device is assigned a unique TID for which a sequential count of debit


Getting Started Configuring the NOVA Debit Gateway Settings

transactions is maintained. You need to assign a TID to each PIN device and keep track of the Last Record Number for each TID as follows:

• NOVA batches PIN-based transactions by TID on a daily basis. For each TID that you have, NOVA assigns a Last Record Number to each transaction (each sale or return) in the TID’s daily batch. The Last Record Number is 0 for the first transaction in the TID’s daily batch and increments by 1 for each subsequent transaction. After the TID’s daily batch is closed, the numbering again starts with 0 for the first transaction in the TID’s next batch.

• You must provide the Last Record Number API field for each transaction. You will not know when NOVA closes the TID’s batch, so you will not know when the numbering starts again at 0. However, NOVA replies to each transaction with the Last Record Number that you should use for the next transaction that you send for that TID. When a TID’s batch closes, the reply for the next transaction will have a 1 as the Last Record Number, indicating that the transaction you just sent was the first transaction (the 0 transaction) for the TID’s new batch. Use Last Record Number=1 for the next transaction that you send.

• To stay in sync with NOVA for each TID, store the most recent Last Record Number sent by NOVA for that TID. Use the stored number as the Last Record Number for the next transaction you submit for the TID.

• If you get out of sync with NOVA and submit a Last Record Number that NOVA does not expect for the TID, you will receive Authorization Response Message=SEQ ERR PLS CALL. The Last Record Number that NOVA replies with is the one they expected to receive. You do not need to call NOVA; all you need to do is resubmit the transaction with the Last Record Number that NOVA provided in the reply. This error does not occur when you send the first transaction of a batch with a value other than the expected 0; NOVA will accept that transaction (assuming you supply the rest of the required information correctly) and will reply with Last Record Number=1.

Using the ControllerIf you have multiple merchant IDs and multiple PIN devices for each merchant ID, then you might want to use the Controller so that you don’t have to keep track of the TIDs and Last Record Numbers. The NOVA Debit Controller lets CPM dynamically assign the TID and Last Record Number for each NOVA Debit transaction. When you enable the Controller, the following happens:

• The Controller has access to a pool of TIDs and their associated Last Record Numbers. For each merchant ID in the TID Pool, there is a set of TIDs, and each TID has a Last Record Number. The Controller keeps track of the Last Record Number for each TID.


Getting Started Configuring the NOVA Debit Agreement Settings

• When you send a NOVA Debit transaction, CPM uses the Controller to access the TID Pool. The Controller finds a TID for the transaction’s merchant ID. You do not need to include the TID or Last Record Number in your transaction requests.

• After choosing a TID from the TID Pool, the Controller returns the TID and its associated Last Record Number to CPM. CPM inserts the TID and Last Record Number into the transaction and forward the transaction to NOVA.

• If CPM gets out of sync with NOVA and submits a Last Record Number that NOVA does not expect for the TID, the Controller resets the TID’s Last Record Number and CPM resubmits the transaction to NOVA.

Configuring the NOVA Debit Agreement SettingsThe way you use the CPM Administration Client’s Agreement Settings dialog depends on whether or not you are using the Controller:

If you are not using the Controller, you have Agreement Settings for each terminal. In this situation, the Agreement Settings Terminal ID identifies a specific terminal at the merchant location. NOVA provides you with this value. As the following figure shows,



the NOVA Terminal ID (the Terminal ID that is sent to NOVA) consists of the Agreement Settings Bank Number and the Agreement Settings Terminal ID:

Figure 1 Terminal ID Without the Controller

If you are using the Controller, you have Agreement Settings for each merchant ID. In this situation, the Agreement Settings Terminal ID is the first part of the identifier for a specific terminal at the merchant location. The last part of the identifier is the 2-digit TERMINAL_ID in the TID Pool, which is described in Fields in the TID Pool on page 12. To configure these values:

1 For each merchant ID, you need multiple terminal IDs. NOVA provides you with these values.

2 For each terminal ID:a Enter the first part of the value (everything except the last 2 digits) into the

Agreement Settings dialog.

b Enter the last 2 digits into the TID Pool. See Adding a Record to the TID Pool on page 14.

As the following figure shows, the NOVA Terminal ID (the Terminal ID that is sent to NOVA) consists of the TID Pool MERCHANT_ID and the TID Pool TERMINAL_ID. The



TID Pool MERCHANT_ID consists of the Agreement Settings Bank Number and the Agreement Settings Terminal ID:

Figure 2 Terminal ID with the Controller


Getting Started Launching the Controller

Launching the ControllerRun the following batch files, which are in the bin directory, to launch the Controller and the Controller Administration Client:

• runserver.batThis script launches the NOVA Debit Controller Server. The arguments are optional:

• runclient.batThis script launches the NOVA Debit Controller Administration Client. The arguments are required:

-P Location of the TIDController.properties file

-verbose Flag that causes JVM to be set to verbose mode

-P Location of the TIDController.properties file

-Dicons Definition for the icons System property for JVM


Chapter 2

Using the Administration Client

The NOVA Debit Controller Administration Client lets you manage the TID Pool. The TID Pool is the Controller’s database. The pool consists of a list of Terminal IDs (TIDs) and a Last Record Number for each TID. When you send a NOVA Debit transaction request, the Controller accesses the TID Pool to get a TID and its corresponding Last Record Number. The TID Pool does not contain sensitive data.

The rest of this chapter covers the following topics:

Main WindowFields in the TID PoolAdding a Record to the TID PoolEditing a Record in the TID PoolDeleting a Record from the TID PoolRefreshing the Main WindowMonitoring the Server Status


Using the Administration Client Main Window

Main WindowWhen you launch the Administration Client, all the records in the TID Pool are displayed in the main window:

Fields in the TID PoolEach entry in the TID Pool has the following values, which are displayed in the main window of the Administration Client, as shown in the previous section:

Table 3 Fields in the TID Pool

Field Description Data Type

MERCHANT_ID Identifies the merchant store that the TERMINAL_ID belongs to. It consists of the bank number and the Agreements Settings Terminal ID. See Figure 2 on page 9. This value cannot be NULL.

varchar(20, 0)


Using the Administration Client Fields in the TID Pool

TERMINAL_ID Last 2 digits of the Terminal ID. This value cannot be NULL. This value is combined with the MERCHANT_ID to create a NOVA Terminal ID. See Figure 2 on page 9. When the MERCHANT_ID and TERMINAL_ID are combined, the resulting value must be unique.

Integer

LAST_RECORD_NUMBER The Last Record Number for the TERMINAL_ID. This value cannot be NULL.Note This counter automatically rolls over to zero after it reaches the value of 949, which is a value that is defined by NOVA.

Integer

STATUS Status of the TERMINAL_ID. Possible values:

• 0: Available, • 1: In Use.This value cannot be NULL.

Integer

LAST_USED_TIME Date-timestamp for the last time the TERMINAL_ID was used.

Datetime

Table 3 Fields in the TID Pool

Field Description Data Type


Using the Administration Client Adding a Record to the TID Pool

Adding a Record to the TID PoolTo add a record, choose the Add Record command in the Controller Data menu or click the Add Record button:

The command displays the following dialog:

Use the default value of 0 for Last Record Number and Status.

Table 4 Add Record Command and Button

Add Record Command Add Record Button


Using the Administration Client Editing a Record in the TID Pool

Editing a Record in the TID PoolTo edit a record, select a row in the main window and choose the Edit Record command in the Controller Data menu:

The command displays the following dialog:

Table 5 Edit Record Command

Edit Record Command


Using the Administration Client Deleting a Record from the TID Pool

Deleting a Record from the TID PoolWhen you quit using a merchant ID, you need to delete its records from the TID Pool. To delete a record, select one or more rows in the main window and choose the Delete Record(s) command in the Controller Data menu or click the Delete Record(s) button:

The command displays the following confirmation message:

After you click Yes, the Administration Client displays the total number of records deleted:

Table 6 Delete Record Command and Button

Delete Record Command Delete Record Button


Using the Administration Client Refreshing the Main Window

Refreshing the Main WindowTo refresh the main window, choose the Refresh command in the Controller Data menu:

Table 7 Refresh Command

Refresh Command


Using the Administration Client Monitoring the Server Status

Monitoring the Server StatusYou can monitor the Controller Server to verify that the server is running and to reveal network connectivity problems. To check the server status, choose the Check Status command in the Server menu

For a successful connection, the following type of message is displayed:

Otherwise, an error message is displayed:

Table 8 Check Status Command

Check Status Command


Chapter 3

Application Logging with Log4j

The NOVA Debit Controller and Administration Client use Log4j for logging different levels of messages. The message levels are user-defined. Log4j provides the following advantages:

• You do not have to write your own logging framework.• It is open source–no licensing required.• It lets you define a different level of logging for each module.• It is easy to integrate and configure.

The Log4j package can output log statements to a variety of user-defined output targets. The logging behavior can be controlled by editing a configuration file (log4j.xml), without modifying the application.

One of the distinctive features of log4j is the notion of inheritance in loggers. By using a logger hierarchy it is possible to control the log statement output with fine granularity. This helps reduce the volume of logged output and minimize the cost of logging.

The target of the log output can be a file, an OutputStream, a java.io.Writer, a remote log4j server, a remote Unix Syslog daemon, or even an NT Event logger among many other output targets.

Log4j has three main types of components: loggers, appenders, and layouts. These components work together to let developers log messages based on message type and level, and control at runtime how these messages are formatted and where they are reported. Log4j can also auto-archive and roll-over log files according to date or time settings.

Log4j is distributed at no charge for commercial or non-commercial use. More information about log4j can be found at http://logging.apache.org/log4j.

The most recent Log4j version can be downloaded from http://logging.apache.org/log4j/docs/download.html.

Note The log4j logging engine initializes using the configuration file log4j.xml,which is in the config directory.


CyberSource Payment Manager™ContentsGetting StartedComponents of the NOVA Debit ControllerInstalling and Configuring the ControllerConfiguring the NOVA Debit Gateway SettingsController HostController PortEnable Controller CheckboxProcessing Without the ControllerUsing the Controller

Configuring the NOVA Debit Agreement SettingsLaunching the Controller

Using the Administration ClientMain WindowFields in the TID PoolAdding a Record to the TID PoolEditing a Record in the TID PoolDeleting a Record from the TID PoolRefreshing the Main WindowMonitoring the Server Status

Application Logging with Log4j

cybersource payment manager™...2007/03/29 · cpm nova debit controller administration guide •...

Documents