NSN in CORBA Payment Plugin_Interface_new

DevelopmentApplication Interface

DMN:Payment Plugin Interface

A50020-A3245-K-2-76D6

2 A50020-A3245-K-2-76D6


Id:0900d80580208b4d

The information in this document is subject to change without notice and describes only the product defined in the introduction of this documentation. This documentation is intended for the use of Nokia Siemens Networks customers only for the purposes of the agreement under which the document is submitted, and no part of it may be used, reproduced, modified or transmitted in any form or means without the prior written permission of Nokia Siemens Networks. The documentation has been prepared to be used by professional and properly trained personnel, and the customer assumes full responsibility when using it. Nokia Siemens Networks welcomes customer comments as part of the process of continuous development and improvement of the documentation.

The information or statements given in this documentation concerning the suitability, capacity, or performance of the mentioned hardware or software products are given "as is" and all liability arising in connection with such hardware or software products shall be defined conclusively and finally in a separate agreement between Nokia Siemens Networks and the customer. However, Nokia Siemens Networks has made all reasonable efforts to ensure that the instructions contained in the document are adequate and free of material errors and omissions. Nokia Siemens Networks will, if deemed necessary by Nokia Siemens Networks, explain issues which may not be covered by the document.

Nokia Siemens Networks will correct errors in this documentation as soon as possible. IN NO EVENT WILL Nokia Siemens Networks BE LIABLE FOR ERRORS IN THIS DOCUMENTA-TION OR FOR ANY DAMAGES, INCLUDING BUT NOT LIMITED TO SPECIAL, DIRECT, INDI-RECT, INCIDENTAL OR CONSEQUENTIAL OR ANY LOSSES, SUCH AS BUT NOT LIMITED TO LOSS OF PROFIT, REVENUE, BUSINESS INTERRUPTION, BUSINESS OPPORTUNITY OR DATA,THAT MAY ARISE FROM THE USE OF THIS DOCUMENT OR THE INFORMATION IN IT.

This documentation and the product it describes are considered protected by copyrights and other intellectual property rights according to the applicable laws.

The wave logo is a trademark of Nokia Siemens Networks Oy. Nokia is a registered trademark of Nokia Corporation. Siemens is a registered trademark of Siemens AG.

Other product names mentioned in this document may be trademarks of their respective owners, and they are mentioned for identification purposes only.

Copyright © Nokia Siemens Networks 2008. All rights reserved

f Important Notice on Product Safety Elevated voltages are inevitably present at specific points in this electrical equipment. Some of the parts may also have elevated operating temperatures.

Non-observance of these conditions and the safety instructions can result in personal injury or in property damage.

Therefore, only trained and qualified personnel may install and maintain the system.

The system complies with the standard EN 60950 / IEC 60950. All equipment connected has to comply with the applicable safety standards.

The same text in German:

Wichtiger Hinweis zur Produktsicherheit

In elektrischen Anlagen stehen zwangsläufig bestimmte Teile der Geräte unter Span-nung. Einige Teile können auch eine hohe Betriebstemperatur aufweisen.

Eine Nichtbeachtung dieser Situation und der Warnungshinweise kann zu Körperverlet-zungen und Sachschäden führen.

Deshalb wird vorausgesetzt, dass nur geschultes und qualifiziertes Personal die Anlagen installiert und wartet.

Das System entspricht den Anforderungen der EN 60950 / IEC 60950. Angeschlossene Geräte müssen die zutreffenden Sicherheitsbestimmungen erfüllen.

A50020-A3245-K-2-76D6

3


Id:0900d80580208b4d

Table of ContentsThis document has 91 pages.

Change History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

1 Introduction to the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.1 Structure of this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.2 Conventions and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2 Overview of the Payment Plugin Interface . . . . . . . . . . . . . . . . . . . . . . . . . 102.1 Short Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2 General Interface Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

3 HTTP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.1 Payment Plugin Servlet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.2 Parameters for Payment Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183.2.1 Parameter Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.2.1.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.2.1.2 Parameters Used for the Payment Plugin Interface . . . . . . . . . . . . . . . . . . 203.2.1.3 Usage of the transactionID / subcount Parameters . . . . . . . . . . . . . . . . . . 263.2.1.4 Usage of the routingInfo and accountType Parameters . . . . . . . . . . . . . . . 273.2.1.5 Usage of the ClusterName Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.1.6 Confirmation Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.2 Parameters for the chargeAmount Operation . . . . . . . . . . . . . . . . . . . . . . . 293.2.3 Parameters for the authorizeAmount Operation . . . . . . . . . . . . . . . . . . . . . 313.2.4 Parameters for the authorizeAmount1 Operation . . . . . . . . . . . . . . . . . . . . 333.2.5 Parameters for the captureAmount Operation . . . . . . . . . . . . . . . . . . . . . . 353.2.6 Parameters for the transferAmount Operation . . . . . . . . . . . . . . . . . . . . . . 373.2.7 Parameters for the adviceOfCharge Operation . . . . . . . . . . . . . . . . . . . . . 393.2.8 Parameters for the adviceOfChargeConf Confirmation Operation . . . . . . . 403.2.9 Parameters for the refundTA Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.2.10 Parameters for the rechargeAmount Operation . . . . . . . . . . . . . . . . . . . . . 423.2.11 Parameters for the rechargeAmount1 Operation . . . . . . . . . . . . . . . . . . . . 443.2.12 Parameters for the rechargeAmountConf1 Confirmation Operation. . . . . . 463.2.13 Parameters for the refund Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.2.14 Parameters for the Simple Confirmation Operations . . . . . . . . . . . . . . . . . 493.2.15 Parameters for the getConsumerAccountList Operation . . . . . . . . . . . . . . 573.2.16 Parameters for the getAccountListConf Confirmation Operation . . . . . . . . 593.2.17 Parameters for the getTAState Operation . . . . . . . . . . . . . . . . . . . . . . . . . 62

4 Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634.1 Typical Usage Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644.2 Example of a Property File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

5 J2EE Connector Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705.1 J2EE Connector Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715.2 Usage Scenario for the J2EE Connector Interface . . . . . . . . . . . . . . . . . . . 72

6 Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736.1 Timeout Handling at the Client Side Using getTAState . . . . . . . . . . . . . . . 74

4 A50020-A3245-K-2-76D6


Id:0900d80580208b4d

6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776.2.1 Format of a Recharge Request Using GET Syntax . . . . . . . . . . . . . . . . . . . 786.2.2 Format of a Recharge Request Using POST Syntax. . . . . . . . . . . . . . . . . . 786.2.3 Example of a Recharge Request Using HTTP GET in Java . . . . . . . . . . . . 796.2.4 Example of a Recharge Request Using HTTP GET in C++. . . . . . . . . . . . . 816.2.5 Example of a Recharge Request Using the Java Library PaymentPlugin.jar .

846.2.6 Example of a GetTAState Request Using the Java Library PaymentPlugin.jar

866.2.7 Example of an EJB Using the J2EE Connector Interface . . . . . . . . . . . . . . 88

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

A50020-A3245-K-2-76D6

5

DMN:Payment Plugin Interface Change History

Id:0900d8058020fe8a

Change HistoryIssue K-2

The following listing details the modifications to this manual as compared to the previous edition.

Parameters for the adviceOfChargeConf Confirmation Operation (3.2.8)

– Parameter ErrorList_t changed, examples for the parameter added.

Parameters for the rechargeAmountConf1 Confirmation Operation (3.2.12)

– Parameter ErrorList_t changed, examples for the parameter added. Parameter DateOfLastRecharge default- no longer supported.

Parameters for the getConsumerAccountList Operation (3.2.15)

– For a parameter UserCredentials_t value loginname changed into MSISDN.

Issue History

Issue Number

Issue Date Reason for Update

J-2 2006/06/11 Parameter productID in captureAmount operation deleted.

K-1 2007/07/20 New software version. VisiBroker variant deleted. Values for error list added.

K-2 2008/06/04 Error information in rechargeAmount confirmations and getTAState behaviour changed.

6 A50020-A3245-K-2-76D6


Id:0900d8058020fe8a

Change History

A50020-A3245-K-2-76D6

7

DMN:Payment Plugin Interface Introduction to the Manual

Id:0900d805801577da

1 Introduction to the ManualIntroduction This manual describes the syntax of the Payment Plugin interfaces of Nokia Siemens

Networks charge@once V1.1 / Nokia Siemens Networks Charging@vantage V2.2.

The application server can use three methods to pass CORBA calls via the payment communication layer to the online charging server (Charging@vantage or charge@once):

• For J2EE servers, the J2EE connector interface may be used. • For web-based applications (HTTP), the Payment Plugin servlet may be used. • For non-web-based applications, the Payment Plugin library has to be loaded to the

application.

All these interfaces are functionally equivalent. To enable secure communication for the Payment Plugin interfaces it is possible to use the Secure Sockets Layer (SSL) protocol.

The behaviour of the CORBA charging service triggered by the Payment Plugin is project-specific.

Purpose Presents the information required in addition to general Charging@vantage / charge@once knowledge in order to understand and administrate the Payment Plugin interface.

Target group This manual is aimed at all those who want to know about and work with the Payment Plugin interface or parts of it.

Relateddocumentation

Please refer to the “Documentation Overview” for more detailed information on the operating documentation of the product.

The installation and configuration of the Payment Plugin are described in the manual “ADMN:Payment Plugin Installation and Configuration”.

Contents 1.1 Structure of this Manual

1.2 Conventions and Symbols

8 A50020-A3245-K-2-76D6


Id:0900d805801577da

Introduction to the Manual

1.1 Structure of this Manual

Contents This manual contains the following chapters:

1 Introduction to the Manual

This chapter describes some basics for working with this manual.

2 Overview of the Payment Plugin Interface

This chapter provides a brief introduction to the Payment Plugin interface and depicts its structure. It describes the behavior of internal and external interfaces.

3 HTTP Interface

This chapter describes the Payment Plugin interface for web-based applications. The main request/response methods of the Payment Plugin servlet are described in brief. The following chapters comprise parameter mapping tables to be used for various payment operations.

4 Java API

This chapter describes the Payment Plugin interface for non-web-based applications.

5 J2EE Connector Interface

This chapter describes the J2EE connector interface as a standard architecture for enabling J2EE components to interact with enterprise information systems (EIS). An example is used to describe how to use this interface.

6 Appendix

This chapter provides hints about the handling of timeouts and it describes the format of a recharge request using the GET and the POST syntax, and shows some examples of recharge requests.

7 "Index"

This chapter contains a list of keywords.

A50020-A3245-K-2-76D6

9

DMN:Payment Plugin Interface Introduction to the Manual

Id:0900d805801577da

1.2 Conventions and SymbolsDesignations, symbols and font styles used in this manual:

Designations, symbols, fonts

Description

Italics Used for – emphasis– software and hardware items– filenames, pathnames– interface items, such as names of windows, menus and

menu items, dialog boxes, field names, etc.

Example: Enter the value in the Parameter field.

Courier Used for – commands and characters to be typed into a user interface– scripts and system output.

Example: Type annoC017 in the Parameter field.

Boldface Used to mark keywords within the text.

Example: This is especially important!

Square brackets [ ] Used for keyboard shortcuts and command buttons.

Examples: Close the application with [Alt] + [F4].Acknowledge this message by clicking on [OK].

g Indicates supplementary information on the current topic. This supplementary information may be useful tips on operation, explanations, the description of master conditions or similar information.

f Indicates a warning. If the instructions given are not observed, errors or data loss can occur. To avoid errors, always observe all the instructions following a warning.

10 A50020-A3245-K-2-76D6


Id:0900d805801577d1

Overview of the Payment Plugin Interface

2 Overview of the Payment Plugin InterfaceIntroduction This chapter describes the Payment Plugin interface. The Payment Plugin consists of

different external interfaces and an internal interface. Only the external interfaces are described in this document.

Furthermore, it describes the general interface behavior and the possibility to enable secure communication for the Payment Plugin interfaces using the SSL (Secure Sockets Layer) protocol.

Contents 2.1 Short Description

2.2 General Interface Behavior

A50020-A3245-K-2-76D6

11

DMN:Payment Plugin Interface Overview of the Payment Plugin Interface

Id:0900d805801577d1

2.1 Short Description

Introduction This section describes the available external interfaces of the Payment Plugin and three possibilities of using the Payment Plugin. It also describes the possibility of secure com-munication via SSL.

Interfaces In general, the Payment Plugin is a client to the online charging server (Charging@van-tage or charge@once). It provides a synchronous HTTP-based interface for a web-based application and allows this application to send requests to the online charging server. The plugin handles the CORBA communication with the online charging server.

In addition, the Payment Plugin provides a Java-based API. This makes it possible to connect a non-web-based client to the online charging server in an easy manner.

The Java 2 Enterprise Edition (J2EE) connector interface allows for the deployment of the Payment Plugin to J2EE compliant servers.

Structure The following figure shows how the Payment Plugin can be used in order to connect different kinds of applications to the online charging server.

J2EE solution A Java 2 Enterprise Edition (J2EE) connector interface supports a standard architecture for connecting the J2EE platform to the online charging server, e.g. Charging@vantage. This interface is described in chapter 5 J2EE Connector Interface.

12 A50020-A3245-K-2-76D6


Id:0900d805801577d1


Web-based solution The HTTP client has to provide all the parameter values which are required in the IDL interface specification as name/value pairs. These name/value pairs (GET or POST requests) from web-based applications are mapped to CORBA parameters for the call at the Payment Plugin interface. Result values are also coded in this way. The parameter names are described in chapter 3 HTTP Interface.

Non-web-basedsolution

Non-web-based applications have to use the PaymentRequest classes of the Payment Plugin Java library to pass the parameters of the request to the CORBA calls. The usage of PaymentResponse classes enables the access to response parameters. Further information is given in chapter 4 Java API.

Securecommunication

It is possible to enable secure communication for the Payment Plugin interfaces using the SSL protocol. The Payment Plugin supports SSL for the IIOP communication to the online charging server and at the external HTTP interface.

Secure Sockets Layer(SSL)

Secure Sockets Layer (SSL) is the most widely used protocol for secure internet com-munication. SSL provides a secure enhancement to the standard Transport Control Protocol (TCP) running as a layer between TCP and application layer protocols, such as IIOP and HTTP.

The SSL implementation is provided by the Java Secure Socket Extension (JSSE), which has been integrated into the J2SDK version 1.4.2. It provides a framework and an implementation for a Java version of the SSL and TLS protocols and includes function-ality for data encryption, server authentication, message integrity, and optional client authentication.

Public key certificates SSL relies on public key certificates in the standard X.509 format. These certificates are presented in the authentication phase of the SSL handshake and used to compute and exchange session keys.

Administration of theSSL infrastructure

The Payment Plugin does not provide any tools or interfaces to administer the infrastructure (keystores and truststores) necessary for SSL, e.g. generate key pairs, import/export of certificates, define trusted certificate authorities or ensure availability of valid certificates. This has to be done by the network operator with the help of external commands provided by the SSL implementation, e.g the keytool command of the J2SDK.

Initalization of the keys The keystores are only read once on startup. As a result switching from unsecure to secure communication and vice versa requires a restart of the Payment Plugin. Likewise the Payment Plugin has to be restarted when new certificates are to be used.

Thus, using SSL is a matter of Payment Plugin configuration, which has to be extended to take additional properties into account.

Global properties SSL properties are global, i.e they take effect for all online charging servers to be connected and include the following parameters:

• An indicator whether SSL communication is optional or mandatory. • The location of the keystore. • The password to open the keystore and access its keys.

Relateddocumentation

For additional information on the maintenance of the SSL infrastructure refer to the “ADMN:Payment Plugin Installation and Configuration” manual.

Installation and configuration of SSL support on Tomcat is described in the Tomcat documentation.

A50020-A3245-K-2-76D6

13


Id:0900d805801577d1

Enabling SSL at the HTTP interface is only a matter of Tomcat configuration and is therefore completely transparent to the Payment Plugin.

g Using secure communication reduces the communication throughput, because connection setup takes a bit longer due to additional messages exchanged in the SSL handshake and because of the computing overhead for decryption and encryp-tion of messages.

14 A50020-A3245-K-2-76D6


Id:0900d805801577d1


2.2 General Interface Behavior

Introduction This section describes the general message sequences of the internal and external Payment Plugin interfaces.

Internal interface The internal interface between the PaymentPlugin and the online charging server is an asynchronous message-based CORBA interface.

When the online charging server receives a request, it immediately sends back an acknowledgement for the reception and starts processing the transaction. After comple-tion it sends a confirmation message to the client which includes the result of the trans-action. The client in turn acknowledges that it has received this message.The sequence of these messages for a chargeAmount() request is shown in the following figure:

External interfaces The external interfaces of the Payment Plugin provide synchronous method calls for these operations.

To prevent infinite blocking of the interface method calls two timeouts are implemented:

After sending a request the Payment Plugin starts an internal timer and waits for the acknowledgement from the online charging server. If the timer expires before the acknowledgement is received, an error of type Response Timed Out is reported to the client and the request context is released. Otherwise a second timer is started while the Payment Plugin is waiting for the confirmation. Again, if no confirmation is received

A50020-A3245-K-2-76D6

15


Id:0900d805801577d1

within the specified time, a Confirmation Timed Out error is returned and the request is terminated.

Since the confirmation timeout is started no sooner than the response has been received, the maximum response time of the Payment Plugin to its clients is the sum of the parameters ResponseTimeout and ConfirmationTimout.

16 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3 HTTP InterfaceIntroduction This chapter describes the Payment Plugin interface for web-based (servlet)

applications. The main request/response methods of the Payment Plugin servlet are described briefly. The following sections comprise parameter mapping tables to be used for various payment operations.

Request and response The web-server-based application provides a parameter list of name/value pairs (HttpServletRequest from javax.servlet.http) for the payment request. Each pair is mapped to a parameter belonging to the online charging server. The response is returned as plain text.

g Values and ranges of parameters are not checked by the Payment Plugin interface. Constraints concerning values and ranges are described in section 3.2.1 Parameter Description. Additional parameter constraints may be imposed by the project-specific IP charging service.

The Payment Plugin interface provides synchronous request / response behaviour. The asynchronous behaviour of the CORBA layer is hidden.

Contents 3.1 Payment Plugin Servlet

3.2 Parameters for Payment Operations

A50020-A3245-K-2-76D6

17

DMN:Payment Plugin Interface HTTP Interface

Id:0900d8058021019d

3.1 Payment Plugin Servlet

Introduction This section describes the Payment Plugin servlet. Servlets are designed to work within a request/response processing model. The plugin servlet is a Java component plugged into a Java-enabled web server to enhance its functionality.

Servlet engine The servlet runs on the web server platform as part of the servlet engine. The servlet engine on the web server is responsible for initializing, invoking and destroying each servlet instance.

HTTP interface The plugin servlet provides a synchronous HTTP interface for payment requests. POST requests are mapped to CORBA calls at the online charging server Payment Execution Point (PEP) interface. The client of the plugin servlet, e.g. the HTTP client, has to provide all the parameter values which are required in the IDL interface specification as name-value pairs. Result values are also coded in this way, but in a free format not encoded as in a standard application/x-form-urlencoded manner. For an example see HTTP response in section 3.2.14 Parameters for the Simple Confirmation Operations.

18 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2 Parameters for Payment Operations

Introduction This section describes the data types and parameters as well as the parameter mapping scheme which is used for various payment operations.

Contents 3.2.1 Parameter Description

3.2.2 Parameters for the chargeAmount Operation

3.2.3 Parameters for the authorizeAmount Operation

3.2.4 Parameters for the authorizeAmount1 Operation

3.2.5 Parameters for the captureAmount Operation

3.2.6 Parameters for the transferAmount Operation

3.2.7 Parameters for the adviceOfCharge Operation

3.2.8 Parameters for the adviceOfChargeConf Confirmation Operation

3.2.9 Parameters for the refundTA Operation

3.2.10 Parameters for the rechargeAmount Operation

3.2.11 Parameters for the rechargeAmount1 Operation

3.2.12 Parameters for the rechargeAmountConf1 Confirmation Operation

3.2.13 Parameters for the refund Operation

3.2.14 Parameters for the Simple Confirmation Operations

3.2.15 Parameters for the getConsumerAccountList Operation

3.2.16 Parameters for the getAccountListConf Confirmation Operation

3.2.17 Parameters for the getTAState Operation

A50020-A3245-K-2-76D6

19


Id:0900d8058021019d

3.2.1 Parameter Description

Introduction This section briefly describes the parameters which are used in the mapping tables in the following sections.

Contents 3.2.1.1 Data Types

3.2.1.2 Parameters Used for the Payment Plugin Interface

3.2.1.3 Usage of the transactionID / subcount Parameters

3.2.1.4 Usage of the routingInfo and accountType Parameters

3.2.1.5 Usage of the ClusterName Parameter

3.2.1.6 Confirmation Parameters

3.2.1.1 Data Types

Introduction This section describes the data types which are used in the mapping tables of the following sections.

Data types The following simple data types are used for the Payment Plugin interface:

Data Type Description

String<n> Array of <n> characters.

Short 2 byte integer.

Int 4 byte integer.

Long 8 byte integer.

Byte - 128 ... 127

Boolean Binary value (true or false)

20 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2.1.2 Parameters Used for the Payment Plugin Interface

Introduction This section describes the parameters used for the Payment Plugin interface. These parameters are used in the mapping tables of the following sections:

IDL Parameter Description

access Fron-tendID

Values of this type describe the access frontend, which was used in a specific transaction (free form, length 0..80). Together with the UserID this is a valuable source of information for customer care and statistics. The value store of this parameter has to be defined project-specifically.

accountID The source account ID as parameter of the operation, which caused the entry in the transaction store.

accountList The loyalty accounts where the merchant is owner, or money accounts of the consumer. Empty if none of these exist.

accountType The account type of an account (prepaid etc.). The defined account types are listed in section 3.2.16 Parameters for the getAccountList-Conf Confirmation Operation.

additional MoneyTo Authorize

If finalizeAuthorization is false, the currently authorized sum of money can be increased by this value. The currencies of money and moneytoAuthorize must be the same. If finalizeAuthorization is true, the value of this parameter is ignored.

The additionalMoneyToAuthorize parameter comprises amount and currency.

Amount: see money parameter

Currency: see money parameter

approved deprecated: Values should be ignored.

When the account is not approved the user has a specific lower account balance limit which may not be passed. The parameter is only relevant for merchant and postpaid consumer accounts.

Values can be true or false.

calculated-Money

Sum and currency of money contained in the confirmation message (e.g. charged money). This amount is either calculated by means of the parameters received with the server request (if rating is performed) or is just the same value as the money parameter provided with the charging request.

In case an authorization takes place (authorizeAmount or captureAmount), this will be the authorized amount (not the captured amount).

This parameter comprises Amount and Currency.



This parameter can have defaults (currency string = "---", amount value = "0"), if internal calculations do not reveal this information or if the execution status indicates an error.

A50020-A3245-K-2-76D6

21


Id:0900d8058021019d

clearing Instru-ment

deprecated: Values should be ignored.

The identification of the associated clearing instrument of the account. This is one of the clearing instruments contained in the user profile.

clearingPeriod deprecated: Values should be ignored.

Defines the clearing period in days of the month. Values should be ignored.

clearing Threshold

deprecated: Values should be ignored.

The threshold for clearing an account. If the threshold is passed, the clearing is triggered. This parameter is only relevant if the clearingPolicy is set to 3 (= threshold).

clearingPolicy deprecated: Values should be ignored.

The clearing policy for the account.

currency Contains the currency of the account as a string (exactly 3 letters long); fixed to the local currency, e.g. EUR.

current Autho-rized Amount

The currently reserved sum in the account. The parameter is only relevant for consumer accounts.

currentBalance Current balance of the account. This parameter consists of the parts Amount and Currency.



dateOfLast Recharge

The date of the previously performed recharge.

Also see the description of the newExpiryDate.


22 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

error Indicates whether or not any account balance has been changed and lists any error occured during processing on the online charging server.

This parameter consists of the parts noMoneyFlow and list.

noMoneyFlow: Indicates whether money has definitively not been moved, i.e. no money was added or deducted from an account. If this parameter is set to false, money is transfered from/to any account and a manual recover (e.g. by means of tickets) may be necessary. In case of timeout situations the value of this flag is undefined.

list: An entry in the error list contains the ID of the unit/component which reports the error, the internal error ID from this unit/component and an additional description. If the error list is empty, the request is successfully executed.

For reported errors the following IDs are possible:

1 = Account management component (ACM)2 = Address resolution component (ADR)3 = CORBA charging service (CCS)4 = CORBA interface component (ECI)5 = User session managment component (PUS)6 = Transaction management component (TAM)7 = Request routing component (SRR)8 = Account accessing component (AAC)9 = SCP online interface (ONL)111 = Payment Plugin

For the IDs 1 to 9 the error location is the online charging server.

errorCause This parameter contains the error code the client associates with the refund. It is provided by the merchant application for statistical or bookkeeping purposes and to allow a (clearing server external) rating engine to calculate the amount to be granted in case no money is given.

execution Status

Confirmation parameter, which contains the result of the requested operation. The possible return codes are listed in section 3.2.14 Parameters for the Simple Confirmation Operations.

expiryDate Expiration date of the account. Only relevant for consumer accounts.

An absolute date is specified by the number of elapsed milliseconds since midnight, January 1, 1970 UTC.A time span is specified as the number of milliseconds to be added to the current time. The maximum time span is limited to 2 years.The possible values are described in section 3.2.10 Parameters for the rechargeAmount Operation.

finalize Autho-rization

Values are true or false. If true is set, the authorization is finalized.


A50020-A3245-K-2-76D6

23


Id:0900d8058021019d

firstRate The first rate of the total sum of money in case of payment in parts. This parameter consists of the parts Amount and Currency.



lastBalance ModDate

The date and time when the account balance was last modified.

merchantID The login name of the merchant for this operation (string, length 1 to 20). The merchantID may only contain printable ASCII characters and must contain at least one non-digit character. It is used for identification of the target account.

mode(type Authorization TimeoutClass)

Describes the timeout for authorization of money. There are two ways of specifying the timeout:

Classified: One of three (timeout) classes can be chosen. System constants preset the timeout in days for each of the classes.

Absolute: The timeout can be specified in days (1 to 99) or minutes (1..142560). Stepping is 1 day/minute.

The possible values are described in section 3.2.3 Parameters for the authorizeAmount Operation.

mode(type ExpiryDateOr Days_t)

Describes the absolute expiration date or the relative number of days until an expiration date which are added to an existing expiration date. There are four ways of specifying this parameter which are described in section 3.2.11 Parameters for the rechargeAmount1 Operation.

The minimum value is 1, the maximum value is 5 * 365.

money Sum and currency of money to be transferred. The currency of money must be the same as the currency in which the authorization was made. The money parameter comprises Amount and Currency.

Amount: the sum of money (-10E18+1 ... +10E18-1). The maximum number of digits is 18 (without decimal point). The default number of fractional digits is 5.

Currency: currency of the money to be transferred (string, exactly 3 letters long); fixed to the local currency, e.g. EUR.

Example: Money.Currency = EUR and Money.Amount = 560000 means EUR 5,60

moneyTo Authorize

Sum and currency of money to be transferred. Any subsequent parameter of this request or follow-on request within this transaction context has to have the same currency. This parameter comprises Amount and Currency.




24 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

newExpiryDate The expiration date after the recharge operation to which the rechargeAmountConf confirmation belongs.

An absolute date is specified by the number of elapsed milliseconds since midnight, January 1, 1970 UTC.A time span is specified as the number of milliseconds to be added to the current time. The maximum time span is limited to 2 years.The possible values are described in section 3.2.10 Parameters for the rechargeAmount Operation.

oldExpiryDate The expiration date before the recharge operation to which the rechargeAmountConf confirmation belongs.

Also see the description of the newExpiryDate.

original Char-geTime

The time at which the operation that caused this refund took place. It is provided by the merchant application for statistical or stockkeeping purposes. It allows a (clearing server external) rating engine to cal-culate the amount to be granted in the case no money is given. This parameter is optional. If the parameter is not to be used, a zero value must be passed.

originalPrice The money that was originally charged with the operation that causes this refund. It is provided by the merchant application for statistical or stockkeeping purposes. It allows a (clearing server external) rating engine to calculate the amount to be granted in case no money is given.

ownerID The user identification of an account owner (string, length 3 to 30). The ownerID is an MSISDN or a merchant login.

pin String for additional consumer identification (length 0 to 20). Normally, for consumers this will be the PPS PIN, otherwise empty.

productID The class of the product (good, service, etc.) a merchant offers. A productID could be, e.g. CD AUDIO JAZZ or CD SW OFFICE. It could also be a part number for ordering the product or similar.

productID is a free format string (length 40) defined by the merchant application and is used for statistical evaluation.The value store of this parameter has to be defined project-specifi-cally.

purpose Describes the purpose of a specific charging transaction. It is a free format string (length 0 .. 200), which has to be interpreted by the client applications.The value store of this parameter has to be defined project-specifically.

recharged Money

Sum and currency of money to be recharged. This parameter comprises amount and currency.




A50020-A3245-K-2-76D6

25


Id:0900d8058021019d

roleID Describes the possible role of a charging user (unsigned short).

Consumer = 1PSP = 3Merchant = 4

routingInfo This parameter (length 0 ... 100) is used by the server to route requests to a specific account handling system. If the value of parameter routingInfo is an empty string and the parameter accountType is set to 0, the online charging server does not reject the request, but automatically tries to resolve the location of the account.

transactionID Represents the unique ID to identify a transaction context over the interface. It is defined by the initiator of a transaction.

For details refer to section 3.2.1.3 Usage of the transactionID / subcount Parameters.

transparent Data

Confirmation parameter which is used to send project-specific defined information back to the client. The default value is an empty free-format string (length 0..80).

userID The identification of a user. For a merchant, this is a string (length 1..20, one must be a nondigit). For consumers, this is the MSISDN (length 3 to 20, all digits).

value(type ExpiryDateOr Days_t)

See description of mode (type ExpiryDateOrDays_t).

value(type Authorization TimeoutClass)

See description of mode (type AuthorizationTimeoutClass).


26 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2.1.3 Usage of the transactionID / subcount Parameters

Introduction The transactionID is a unique ID generated by the client system and used to identify each specific charging operation performed by the online charging system. A transac-tionID is a sequence of exactly either 18 or 20 digits. Depending on the transactionID format, the subcount is part of the transactionID.

Conventions The uniqueness of transactionIDs in a distributed installation of brokers and servers is achieved by the following conventions: • The 4 leading digits are the hostid, which is a uniquely administered ID of the brokers

or servers in the scope of the installation. These digits may be used for load control and default transactionID mapping. The value 1000 is reservedf or internal use and should not be selected.

• The 14 following digits are a continuously growing integer (i.e. one by one) starting (at least) with 0, which has to be generated and administered by the client.

g This restriction has been lifted. The leading 18 characters need not be digits but may be arbitrary ASCII characters. It is still strongly recommended to use the scheme described, since uniqueness among all transaction IDs must still be provided for by the clients.

• The trailing 2 digits are optional and represent the transaction subcount (0..99) which allows to enumerate sub-parts of a long term transaction.

Format oftransactionID

The online charging system supports two formats of the transactionID parameter:

• The original 18 digit format:– Is used for all calls which trigger simple transactions (chargeAmount,

transferAmount, rechargeAmount) and for authorizeAmount.– Is used optionally for captureAmount.– All 18 digits are significant for checking the uniqueness of a transaction.

The HostId can be defined in the property file of the Payment Plugin.In that case, the Payment Plugin automatically prefixes all transactionIDs created by the client with that HostId. If the HostId is not defined, the total 18 digits are filled with this counter.

• The 20 digit format, which extends the original transactionID by a subcount:– Is used optionally for captureAmount.– All 20 bytes are used for checking uniqueness of a transaction.– The first 18 digits are used for selecting the transaction context. The structure is

the same as described for the 18 digit format of the transactionID.– The last 2 digits (subcount) will be checked on constantly growing with wrap

around (see details later).

In case of captureAmount, the two formats are available simultaneously.

Uniqueness check oftransactionID

If a client uses the 18 digit format, the uniqueness check is performed as described for the original format of the transactionID.

If the client wants to use the subcount, it can use the 20 digit format and use the uniqueness check as described for the new format of the transactionID.

Subcount generationscheme and check

The following generation scheme will be applied to generate a subcount and to check the validity of a subcount during an authorize/capture transaction:

• The subcount (SUBC) runs from 00..99. • The first value of an SUBC must be out of 0..2.

A50020-A3245-K-2-76D6

27


Id:0900d8058021019d

• If the SUBC reaches the value 99, the SUBC wraps around and starts from 0 again. • The maximum gap between SUBC values for captureN and captureN+1 must not

exceed two: 0 < (SUBCN+1 - SUBCN) <= 2 or 0 < (SUBCN+1 + 100 - SUBCN) <= 2

The gap is greater than zero to allow losing of single requests in a routed network due to timeouts.

The server checks the subcount according to this generation scheme. If this scheme is violated, an InvalidTransaction exception is thrown by the server. This InvalidTransaction exception does not terminate the authorisation. A subsequent capture using the same TransactionID and a valid subcount will be successful.

Examples of subcountpairs

Examples of pairs of consequent subcounts are: • Valid: { 0, 1 }, { 0, 2 }, { 97, 99 }, { 99, 0 }, { 99, 1 } • Invalid: { 0, 4 }, { 47, 62 }, { 47, 46 }, { 97, 1 }, { 99, 3 }

3.2.1.4 Usage of the routingInfo and accountType Parameters

Routing information routingInfo and accountType are parameters. If the location and type of the subscriber's account are known to the client application, it is possible to bypass the address resolution function in the online charging server. This is done by providing the necessary routing information in the request.

Handling of operations The CORBA interface of the online charging server offers separate versions of operations, with and without routing and account type information. At the HTTP interface the Payment Plugin transparently calls the correct operation depending on the setting of these parameters. At the J2EE Connector interface and the Java API the user of the Payment Plugin has to select the operation with the appropriate set of arguments.

Values The possible values for accountType are described in the following table:

g If the value of routingInfo is an empty string and if the value of accountType is 0, the online charging system automatically tries to resolve the location/type of the target account. In a standard online charging system configuration setting routingInfo should always be set to ““ and accountType should be set to 0.

Value Account type

0 unknown

1 consumer prepaid account

2 consumer postpaid account

28 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2.1.5 Usage of the ClusterName Parameter

Cluster selection ClusterName is an optional parameter. As described in section 2.1 Short Description, it is possible to connect the Payment Plugin to more than one online charging system cluster. When using the HTTP interface the cluster name may be specified in the list of request parameters. For all other interfaces the cluster name has to be provided before sending requests to the online charging server.

For all other interfaces the cluster selection has to be done in the application code, see 4 Java API.

3.2.1.6 Confirmation Parameters

Possible parameters Execution of requests will be reported by confirmations which contain the following parameters: • TransactionID • ExecutionStatus • TransparentData • CalculatedMoney • ErrorList

These parameters are described in section 3.2.1.2 Parameters Used for the Payment Plugin Interface. A complete list of values for ExecutionStatus is presented in section 3.2.14 Parameters for the Simple Confirmation Operations.

Mandatoryparameters

The parameters TransactionID and ExecutionStatus are always part of a confirmation.

Optional parameters The presence of the remaining parameters depends on the interface version defined in the Payment Plugin configuration file:

– If the interface version is greater or equal to 2.0 confirmations aditionally contain the TransparentData parameter.

– If the interface version is greater than or equal to 2.1 there will also be the parameters CalculatedMoney and ErrorList in addition to all the parameters mentioned before.

A50020-A3245-K-2-76D6

29


Id:0900d8058021019d

3.2.2 Parameters for the chargeAmount Operation

Introduction The chargeAmount operation is used if immediate payment without separate authoriza-tion and reservation is requested.

Parameters The following table shows the parameter mapping scheme for the chargeAmount oper-ation. For a description of the parameters, refer to section 3.2.1 Parameter Description.

Confirmation The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).

CORBA operationsmapping

Depending on the setting of the routingInfo and accountType parameters, the request is mapped to the following CORBA operations:

• chargeAmountif routingInfo and accountType are not part of the request parameters

• chargeAmount1if routingInfo and / or accountType are part of the request parameters

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value

TransactionID_t transactionID TransactionId String<4+14> 300000110077355864

UserCredentials_t roleID

userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

4 (merchant)

merchant login

merchant PIN

Access

FrontendID_t

access

FrontendID

AccessFrontendId String<80> AFI_011

AccountHandle_t userID

accountID

pin

ConsumerId

ConsumerAccountId

ConsumerPIN

String<30>

Long

String<20>

consumer MSISDN

0

consumer PIN

UserID_t merchantID MerchantId String<30> merchant login

(has to be identical to ReqCred.User.Id)

ProductID_t productID ProductId String<40> PREMIUM MMS

PurposeOf

Transaction_t

purpose Purpose String<200> Order no. 123

Money_t money Money.Currency

Money.Amount

String<3>

Long

EUR

560000

RoutingInfo_t routingInfo RoutingInfo String<100> 3

AccountType_t accountType AccountType Short 1 (prepaid consumer)

not available not available ClusterName String c1

not available not available RequestType String with fixed value

chargeAmount

30 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

g The RoutingInfo, AccountType and ClusterName attributes are optional. Please refer to sections 3.2.1.4 Usage of the routingInfo and accountType Parameters and 3.2.1.5 Usage of the ClusterName Parameter for further information.

g If the account type and the account location are not known, RoutingInfo is left empty and AccountType is set to 0. Using chargeAmount without RoutingInfo and AccountType is deprecated.

A50020-A3245-K-2-76D6

31


Id:0900d8058021019d

3.2.3 Parameters for the authorizeAmount Operation

Introduction The authorizeAmount operation is used if deferred payment or payment in parts is requested. This operation comprises following transactions:

• Authorizing and reserving a sum of money. • Executing the first rate for payment in parts.

Parameters The following table shows the parameter mapping scheme for the authorizeAmount operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value



userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

4 (ext. merchant)

merchant login

merchant PIN

AccessFrontendID_t

access Fronten-dID



accountID

pin

ConsumerId

ConsumerAccountId

ConsumerPIN

String<30>

Long

String<20>

consumer MSISDN

0

consumer PIN




PurposeOf Transaction_t

purpose Purpose String<200> Order no.003

Money_t moneyTo Authorize

Autho.Currency

Autho.Amount

String<3>

Long

EUR

5600000

Money_t firstRate Rate.Currency

Rate.Amount

String<3>

Long

EUR

120000

Authorization TimoutClass

mode Mode Byte 1 = classified

2 = absolute


value Value Byte for classified:

1 = short range

2 = medium range

3 = long range

for absolute:1 .. 99 days



authorizeAmount

32 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface


g If the AuthorizationTimoutClass mode is set to classified, the value for AuthorizationTimoutClass refers to 3 parameters described in the Technical Project Data (ChargeTransactionLifetime for short, medium and long).

g The ClusterName attribute is optional. Please refer to section 3.2.1.5 Usage of the ClusterName Parameter for further information.

A50020-A3245-K-2-76D6

33


Id:0900d8058021019d

3.2.4 Parameters for the authorizeAmount1 Operation

Introduction The authorizeAmount1 operation is used if deferred payment or payment in parts is requested. This operation comprises the following transactions:

• Authorizing and reserving a sum of money. • Executing the first rate for payment in parts.

Differences toauthorizeAmount

The authorizeAmount1 operation uses a parameter set other than the authorizeAmount operation. The authorization timeout is specified in minutes instead of days.

Parameters The following table shows the parameter mapping scheme for the authorizeAmount operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value



userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

4 (external merchant)

merchant login

merchant PIN

AccessFrontendID_t

access Fronten-dID


AccountHandle1_t userID

accountID

pin

routingInfo

accountType

ConsumerId

ConsumerAccountId

ConsumerPIN

RoutingInfo

AccountType

String<30>

Long

String<20>

String<100>

Short

consumer MSISDN

0

consumer PIN

3

1 (prepaid consumer)




PurposeOf Transaction_t

purpose Purpose String<200> Order no.003

Money_t moneyTo Authorize

Autho.Currency

Autho.Amount

String<3>

Long

EUR

5600000

Money_t firstRate Rate.Currency

Rate.Amount

String<3>

Long

EUR

120000


mode Mode Byte 1 = not used

2 = not used

3 = minutes classified

4 = minutes absolute

34 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface


g If the AuthorizationTimoutClass mode is set to classified, the value for Authori-zationTimoutClass refers to 3 parameters described in the Technical Project Data (ChargeTransactionLifetime for short, medium and long).

g The ClusterName attributes are optional. Please refer to section 3.2.1.5 Usage of the ClusterName Parameter for further information.


value Value Long for classified:

1 = short range

2 = medium range

3 = long range

for absolute:1 ... 142,560 minutes or 1 .. 99 days



authorizeAmount1

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value

A50020-A3245-K-2-76D6

35


Id:0900d8058021019d

3.2.5 Parameters for the captureAmount Operation

Introduction The captureAmount operation is used if payment with separate authorization and reser-vation is requested. This operation comprises the following transactions:

• Transferring the required sum of money from the source to the target virtual account. • Reducing the sum of currently authorized money within its transaction context. • An additional sum of money can be authorized or the authorization can be finalized.

Each captureAmount operation within a transaction context can have a subcounter as a postfix of the transaction_ID. The range of the subcounter is 0 ... 99.

Parameters The following table shows the parameter mapping scheme for the capture Amount oper-ation. For a description of the parameters, refer to section 3.2.1 Parameter Description.


IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value

TransactionID_t transactionID TransactionId String<4+14+2> refer to section 3.2.1 Parameter Description


userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

4 (external merchant)

merchant login

merchant PIN

Access

FrontendID_t

access

FrontendID



accountID

pin

routingInfo

accountType

ConsumerId

ConsumerAccountId

ConsumerPIN

RoutingInfo

AccountType

String<30>

Long

String<20>

String <100>

Short

consumer MSISDN

0

consumer PIN

3

1 (prepaid consumer

PurposeOf

Transaction_t



Money.Amount

String<3>

Long

EUR

660000

boolean finalize

Authorization

Final String<5> true or false

Money_t additional

MoneyTo

Authorize

Add.Currency

Add.Amount

String<3>

Long

EUR

16000



captureAmount

36 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

g The parameters ConsumerId, ConsumerAccountId, ConsumerPIN, RoutingInfo and AccountType are optional. They may be specified all together or not at all. The ClusterName attribute is optional. Please refer to section 3.2.1.5 Usage of the Clus-terName Parameter for further information.

A50020-A3245-K-2-76D6

37


Id:0900d8058021019d

3.2.6 Parameters for the transferAmount Operation

Introduction The transferAmount operation is used if a general transfer of money between internal accounts, without any restrictions regarding the type of accounts, is requested.

Parameters The following table shows the parameter mapping scheme for the transferAmount oper-ation. For a description of the parameters, refer to section 3.2.1 Parameter Description.


IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value



userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

1 (consumer)

consumer login

consumer PIN

Access

FrontendID_t

access

FrontendID



accountID

pin

SourceId

SourceAccountId

SourcePIN

String<30>

Long

String<20>

consumer MSISDN

0

source PIN

RoutingInfo_t routingInfo SourceRoutingInfo String<100> 3

AccountType_t accountType SourceAccountType Short 1 (prepaid consumer)


accountID

pin

TargetId

TargetAccountId

TargetPIN

String<30>

Long

String<20>

login or MSISDN

0

target PIN

RoutingInfo_t routingInfo TargetRoutingInfo String<100> 3

AccountType_t accountType TargetAccountType Short 1 (prepaid consumer)

UserID_t merchantID MerchantId String<20> merchant login has to be identical to ReqCred.UserId


PurposeOf

Transaction_t



Money.Amount

String<3>

Long

EUR

560000



transferAmount

38 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface


Depending on the setting of the routingInfo, accountType, merchantID and productID parameters, the request is mapped to the following CORBA operations:


A50020-A3245-K-2-76D6

39


Id:0900d8058021019d

3.2.7 Parameters for the adviceOfCharge Operation

Introduction The adviceOfCharge operation is used for price inquiry before service delivery.

Parameters The following table shows the parameter mapping scheme for the adviceOfCharge operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.

Confirmation The execution result is returned using the adviceOfChargeConf operation (refer to section 3.2.8 Parameters for the adviceOfChargeConf Confirmation Operation).


IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value



userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

4 (ext. merchant)

merchant login

merchant PIN

Access

FrontendID_t

access

FrontendID



accountID

pin

routingInfo

accountType

ConsumerId

ConsumerAccountId

ConsumerPIN

RoutingInfo

AccountType

String<30>

Long

String<20>

String<100>

Short

consumer MSISDN

0

consumer PIN

3





PurposeOf

Transaction_t



Money.Amount

String<3>

Long

EUR

560000



adviceOfCharge

40 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2.8 Parameters for the adviceOfChargeConf Confirmation Operation

Introduction The confirmation operation for the adviceOfCharge operation containes the transac-tionID, executionStatus, transparentData, error, timeStampForRating and Calculated-Money parameters.

Parameters The following table shows the parameter mapping scheme for the adviceOfChargeConf operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.

Result values to returnsuccess or error

The result value of the ExecutionStatus_t type is used to asynchronously confirm the execution of the request in the online charging system and to return the success or error code to the Payment Plugin. The values are the same as described for the simple con-firmation operations (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).

Example Response: TransactionID=123456789012345678 ExecutionStatus=1TransparentData=""CalculatedMoney.Currency=EURCalculatedMoney.Amount=9893ErrorList.noMoneyFlow=trueErrorList.list={}TimeStampForRating=1084956846481

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value


ExecutionStatus_t executionStatus

ExecutionStatus Short 1 = successful

refer to section 3.2.14 Parameters for the Simple Confirmation Opera-tions for permitted values

TransparentData_t transparentData

TransparentData String<500> 51

Money_t Calculated Money

CalculatedMoney. Currency

CalculatedMoney. Amount

String<3>

Long

EUR

160000 (same precision as in the request)

ErrorList_t error ErrorList.noMoneyFlow

ErrorList.list

Boolean

String

true

{(8,1859,"SCP error")}

Date_t timeStampForRating

TimeStampForRating

Long 1036136490713 UNIX system time in millisec-onds since 1970 = Monday, July 09, 14:53:30 CEST 2001

A50020-A3245-K-2-76D6

41


Id:0900d8058021019d

3.2.9 Parameters for the refundTA Operation

Introduction The refundTA operation is used to refund a successful transaction.

Parameters The following table shows the parameter mapping scheme for the refundTA operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.


IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value


The ID for the transaction which is to be refunded. Dif-fering from most other requests, this ID is not created but must be an existing ID coming from either a previous charge request or authorize request.


userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

4 (ext. merchant)

merchant login

merchant PIN

Access

FrontendID_t

access

FrontendID



accountID

pin

routingInfo

accountType

ConsumerId

ConsumerAccountId

ConsumerPIN

RoutingInfo

AccountType

String<30>

Long

String<20>

String<100>

Short

consumer MSISDN

0

consumer PIN

3


PurposeOf

Transaction_t




refundTA

42 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2.10 Parameters for the rechargeAmount Operation

Introduction The rechargeAmount operation triggers a recharging transaction on the clearing server. The expiry date is passed as an absolute date or as a number of days.

Virtual accounts Virtual accounts are recharged by the sum defined by the money parameter.

g This operation is deprecated, but has been kept due to compatibility reasons. Clients should use operation rechargeAmount1 with parameters RoutingInfo = "" and AccountType = 0 instead.

Parameters The following table shows the parameter mapping scheme for the rechargeAmount operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.



IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value



userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

3 (PSP)

PSP login

" "

Access

FrontendID_t

access

FrontendID



accountID

pin

ConsumerId

ConsumerAccountId

ConsumerPIN

String<30>

Long

String<20>

consumer MSISDN

0

consumer PIN

PurposeOf

Transaction_t



Money.Amount

String<3>

Long

EUR

560000

Date_t newExpiryDate ExpiryDate Long see Values for ExpiryDate



rechargeAmount

A50020-A3245-K-2-76D6

43


Id:0900d8058021019d

Values for ExpiryDate The following values may be specified for ExpiryDate:

Value Description

-1 The date is not specified. It is calculated by the SCP/SEP.

0 The date is not set, i. e. the expiration date is not changed.

date > 0 && < 2 years (365 * 2 * 24 * 60 * 60 * 1000)

Delta mode: the expiration date is a time span in milliseconds which is limited up to 2 years.

date > (current time - 24 h)

Absolute mode: the expiration date is an absolute date (UTC)

(e.g. Monday, July 09, 2001, 14:53:30 Central European Summer Time (CEST) = 994683210000 UNIX system time in milliseconds since 1970).

44 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2.11 Parameters for the rechargeAmount1 Operation

Introduction The rechargeAmount1 operation triggers a recharging transaction on the clearing server.

Virtual accounts Virtual accounts are recharged by the sum defined by the money parameter.

Expiry date The handling of the expiry date is specified by the parameters mode and value.

Parameters The following table shows the parameter mapping scheme for the recharge Amount operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value



userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

3 (PSP)

PSP login

" "

Access

FrontendID_t

access

FrontendID



accountID

pin

ConsumerId

ConsumerAccountId

ConsumerPIN

String<30>

Long

String<20>

consumer MSISDN

0

consumer PIN

UserID_t merchantID MerchantId String<20> merchant login has to be identical to ReqCred.UserId


PurposeOf

Transaction_t



Money.Amount

String<3>

Long

EUR

560000

ExpiryDateOrDays_t:Mode_t

mode Expiry.Mode byte 1 = absolute setting

2 = relative setting

3 = default setting

4 = no setting

For a description, please refer to Values for Expiry.Mode

ExpiryDateOrDays_t:Value_t

value Expiry.Value Long 90

A50020-A3245-K-2-76D6

45


Id:0900d8058021019d

Confirmation The execution result is returned using the rechargeAmountConf1 operation. The confir-mation also contains the new expiration date and the new balance of the account which has been recharged.


Depending on the setting of the routingInfo, accountType, merchantID and productID parameters, the request is mapped to the following CORBA operations:

• rechargeAmount1if routingInfo and accountType are not specified

• rechargeAmount2if routingInfo and accountType are specified, but merchantID and productID are not specified

• rechargeAmount3if routingInfo, accountType, merchantID and productID are specified


Values forExpiry.Mode

The handling of the expiration date is specified by the mode and value parameters. The confirmation contains the new expiration date and the new balance of the account that has been recharged.

The following values may be specified for Expiry.Mode:



rechargeAmount1

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value

Expiry.Mode

Description

1 Absolute setting:

The Expiry.Value parameter specifies the new expiration date as the number of milliseconds since midnight , January 1, 1970 UTC.

2 Relative setting:

The Expiry.Value parameter specifies the number of days to be used as input for the calculation of the new current expiration date. This calculation is project-specific and may be based on either the current date or the current expiry date stored in the subscriber data.

3 Default setting:

The new expiration date is calculated by the online charging server. The Expiry.Value parameter has to be set to -1.

4 No setting:

The expiration date is not changed. The Expiry.Value parameter has to be set to 0.

46 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

g If the account does not have an expiration date property the parameters mode and value are ignored by the online charging server.

3.2.12 Parameters for the rechargeAmountConf1 Confirmation Operation

Introduction The rechargeAmount1Conf confirmation operation contains the following parameters.

Parameters The following table shows how these parameters, which occur within the confirmation operation, are mapped. For a description of the parameters, refer to section 3.2.1 Parameter Description.

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value


ExecutionStatus_t executionStatus ExecutionStatus Short 1 = successful

refer to section 3.2.14 Parameters for the Simple Confirmation Oper-ations for permitted values

TransparentData_t transparentData TransparentData String<500> 51

ErrorList_t error ErrorList.noMoney-Flow

ErrorList.list

Boolean

String

true

{(8,1859,"SCP error")}


accountID

pin

ConsumerId

ConsumerAccountId

ConsumerPIN

String<30>

Long

String<20>

consumer MSISDN

0

consumer PIN

Money_t recharged Money

RechargedMoney. Currency

RechargedMoney. Amount

String<3>

Long

EUR


Money_t ID CurrentBalance. Currency

CurrentBalance. Amount

String<3>

Long

EUR


Date_t dateOfLast Recharge

DateOfLastRecharge Long 1036136490713 UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001

Currently not supported, contains only default values.

A50020-A3245-K-2-76D6

47


Id:0900d8058021019d

Result value The value of the ExecutionStatus_t parameter contains the result of the transaction. The values are the same as described for the simple confirmation operations (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).

Example Response: TransactionID=300000110077355864 ExecutionStatus=1TransparentData="51"ErrorList.noMoneyFlow=falseErrorList.list={}ConsumerId=cons_xyzConsumerAccountId=0ConsumerPIN=****RechargedMoney.Currency=EURRechargedMoney.Amount=55500000CurrentBalance.Currency=EURCurrentBalance.Amount=55510000DateOfLastRecharge=0OldExpiryDate=1034458556121NewExpiryDate=1033619588825

g In the case of an error, the list of attributes contains only default values.

Date_t oldExpiryDate OldExpiryDate Long 1034458556121 UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001

Date_t newExpiryDate NewExpiryDate Long 1033619588825 UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value

48 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2.13 Parameters for the refund Operation

Introduction The refund operation triggers a refund in the clearing server in order to undo a previous charge operation.

Parameters The following table shows the parameter mapping scheme for the refund operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.


IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value



userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

3 (PSP)

PSP login

" "

Access

FrontendID_t

access

FrontendID



accountID

pin

routingInfo

accountType

ConsumerId

ConsumerAccountId

ConsumerPIN

RoutingInfo

AccountType

String<30>

Long

String<20>

String<100>

Short

consumer MSISDN

0

consumer PIN

3





PurposeOf

Transaction_t


long long errorCause ErrorCause Long 13

Date_t originalCharge Time

OriginalChargingTime Long 994683210000

UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001

Money_t originalPrice OriginalPrice.Currency

OriginalPrice.Amount

String<3>

Long

EUR

560000



refund

A50020-A3245-K-2-76D6

49


Id:0900d8058021019d


3.2.14 Parameters for the Simple Confirmation Operations

Introduction The previously mentioned confirmation operations contain the transactionID, execution-Status, transparentData, CalculatedMoney and error parameters.

Parameters The following table shows how these parameters, which occur within the confirmation operations, are mapped. For a description of the parameters, refer to section 3.2.1 Parameter Description.

Result values to returnsuccess or error

The result values of ExecutionStatus_t type are used to confirm the execution of the request in the online charging system and to return the success or error code to the Payment Plugin.

g Values > 0 are sent from the online charging server.

Values < 0 are errors detected by the Payment Plugin.

Every value except "1" indicates an error.

Result classification The following table describes the result classification of the execution status which occurs in the next table:

IDL Parameter Type IDL Parameter Name Response Attribute Name AttributeType Example for Value

TransactionID_t transactionID "TransactionId" String<4+14+2> 300000110077355864

ExecutionStatus_t executionStatus "ExecutionStatus" Short 1 = successful

refer to the following table for possible values

TransparentData_t transparentData "TransparentData" String<500> "51"

Money_t CalculatedMoney "CalculatedMoney.Currency"

"CalculatedMoney.Amount"

String<3>

Long

"EUR"

160,000

(same precision as in request)

ErrorList_t error "ErrorList.noMoneyFlow"

"ErrorList.list"

Boolean

String

true

{(8,1859,"SCP error")}

Result

classification

Execution

Status

ErrorL-ist.noMoney-

Flow

Description

A Successful The transaction was executed suc-cessfully.

B Limits violated The transaction was not executed successfully.

The account limits are exceeded.

C Failure true The transaction was not executed successfully.

The account is not changed.

50 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

Execution status The execution status is transported as part of asynchronous responses (confirmation) after the execution of a transaction has been processed by the online charging server. The following table describes the values of execution status:

D Failure false The transaction was not executed successfully.

The account is possibly changed.

Result

classification

Execution

Status

ErrorL-ist.noMoney-

Flow

Description

Execu-tion

status

Result

classification

Status Description Requested action

1 A Successful The transaction is executed successfully. None

2 C Invalid account The account is invalid or unknown for the requested operation.

The reason why the online charging server sends this execution status has to be analy-sed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).

No automatic repetition of the request is rec-ommended.

3 C Invalid access rights

The insufficient access rights which are based on the roles

- password or PIN or

- the subscriber is locked or

- the first call is not set.

4 B Limits violated The limits, e.g., threshold values, of an account or any limits set by the software (hard-coded limits) are violated.

No repetition of the payment request.

5 C Data not available The currency data table is not available from the Payment broker.



6 C Invalid user ID The user with this ID is unknown to the system.

7 D Internal error The transaction is not completed because of an internal error.

Use getTAState to check the status of the transaction or check the tickets at the online charging server.

8 C Invalid transaction The transaction is unknown, because either an error occurred or because the transaction has timed out at either at the online charging server side or at the Payment broker side.



A50020-A3245-K-2-76D6

51


Id:0900d8058021019d

Error cases The following error cases are possible:

• Default valuesIn error cases, the return values are supplied with dummies by operations which carry more return values than an execution status. I.e., constant values that only

9 C Transaction already open

The transaction to be opened is already open.

The reason why the application sent a trans-actionID already in use has to be analysed. The appropriate action has to be taken atap-plication side. Then it must be decided if the request has to be repeated with a new trans-actionID.

10 C Transaction busy This status is returned if the transaction is in a status that does not allow to handle the current request. E.g., a capture is tried for a transaction and another capture is already in progress.

Wait a couple of seconds and repeat the request.

11 C Authorization not available

This status is returned if a capture is tried and the authorized money is not suffi-cient.

Authorize/capture is not a use case for Ferma VoMS.

12 C Invalid money Either an incorrect currency is used (cur-rency string is unknown to the system) or the requested amount of money is higher than the maximum allowed value (accounting component configuration parameter).



13 C Invalid parameter Wrong parameters or parameter values are used by the client that issues the request.

14 C No resources The application is temporarily in a status where it cannot accept the current request due to overload protection.


15 C Authorization not possible

This status is returned if a capture is executed and an additional authorization is tried which is not granted.

Authorize/capture is not a use case for Ferma VoMS.

16 C Feature not sup-ported

This status is returned if a feature is not supported for a specific set of users. E.g., loyalty point management is not sup-ported for postpaid consumers.

The reason why the application sends a request with an unsupported feature has to be analysed. The appropriate action has to be taken at application side.

17 C External ARS error The external user repository, e.g., LDPA server, does not response to a location request.

18 C External AMS error The account is stored on and the backend server does not answer the request, but no timeout happens.

19 D External AMS timeout

The account is stored on and the backend server does not answer the request, due to a timeout.

9999 maximum reserved Up to this value: All execution status codes are reserved for further exten-sions.

Do not use any values between 1-9999 for any project specific extensions.

Execu-tion

status

Result

classification


52 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

satisfy formal interface criteria, but do not make sense. Be sure to check the execu-tion status before using the supplied data.

• Disaster recoveryIn the case, the whole system fails, the client connects to a stand-by system which is available. This includes any resolving of names in a newly available naming service.

Result values causedby Payment Plugin

The following values are detected by the Payment Plugin. These return codes are caused by exceptions which occur immediately after the call of the CORBA operation.

Execution status

Result

classification


-100 C Transaction already open

The transaction to be opened is already open.

The reason why the application sends a transactionID already in use has to be anal-ysed. The appropriate action has to be taken on application side.

Then it must be decided if the request has to be repeated with a new transactionID.

-101 C Invalid transaction The transaction is not known, because either an error occurred or because the transaction has timed out at either at the online charging server side or at the Payment Broker side.

The reason why the online charging server sends this execution status has to be anal-ysed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).

No automatic repetition of the request is recommended.

-102 C Duplicate transac-tion ID

The reason why the application sends a transactionID already contained in the internal administration table of the Payment Plugin has to be analysed. The appropriate action has to be taken on application side.

-103 D Confirmation timeout The transaction is not completed because of an internal error.


-104 C CORBA communi-cation error

There is a critical problem in CORBA communication. No requests can be sent to online charging server.

It is recommended that the Payment Plugin log file is evaluated by Nokia Siemens Networks staff.

-105 C Overload detected The Payment Plugin was not able to process the request due to an overload situation.


-106 C Invalid user ID The user with this ID is unknown to the system.



-107 C Invalid access rights The insufficient access rights which are based on the roles

- password or PIN or

- the subscriber is locked or

- the first call is not set.



A50020-A3245-K-2-76D6

53


Id:0900d8058021019d

Result values causedby CORBA layer

exceptions

The following values are subcodes of -104 CORBA communication error execution status . The values are created by the Payment Plugin. These return codes are caused by exceptions which occur immediately after the call of the CORBA operation.

-108 C Limits exceeded The limits, e.g., threshold values, of an account or any limits set by the software (hard-coded limits) are violated.

No repetition of the payment request.

-109 D Response timeout A timeout occured while the Payment Plugin is waiting for the online charging server to acknowledge the reception of the request.


-110 C No server resources A temporary overload situation has been reported by the online charging server.

The server was not able to process the request due to an overload situation. The payment Plugin rejects rejects further requests with execution status -110 until an internal timer has expired and the overload situation is cleared. The timeout is specified by configuration property ServerOverload-Timeout.

Wait a couple of seconds and repeat the request. There is no automatic repetition by the Payment Plugin.

Execution status

Result

classification


Error Code

Description

-1 Exception from online charging server when sending chargeAmount request

-2 Exception from online charging server when sending authorizeAmount request

-3 Exception from online charging server when sending captureAmount request

-4 Exception from online charging server when sending getVersion request

-5 Naming service not available

-6 CorbaObjectPool initialization error

-7 No online charging server available

-8 No ChargingBroker available

-9 NamingContext creation error

-10 NamingContext resolve error

-11 NamingContext not found

-12 Exception during the ChargingBroker creation

-13 Exception during refresh online charging server objects

-14 StoreResponse not possible because OrderMapEntry does not exist

-15 Exception from online charging server when sending transferAmount request

-16 Exception from ClearingServer when sending rechargeAmount request

-17 No ClearingServer available

-18 Exception during refresh ClearingServerObjects

54 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

g The value of FunctionalUnitID is always set to 111. The value of error text is set to the error message dynamically generated by the CORBA runtime environment.

Result values causedby parameter

validation errors

The following values are results from validation of request parameters at the HTTP interface, e.g., due to missing parameters or illegal parameter values:

-19 No ClearingBroker available

-20 Exception during ClearingBroker creation

-21 Exception from online charging server when sending getTAState request

-22 Exception from online charging server when sending forgetTAState request

-23 CORBA "bad parameter" exception is thrown

-24 Invalid order map entry state when trying to store response

-25 Exception from AccountManagementServer when sending getConsumerAc-countList request

-26 Exception from AccountManagementServer when sending getVersion request

-27 No AccountManagementServer available

-28 No AccountManagementBroker available

-29 Exception during refreshAccountManagementObjects

-30 Exception during AccountManagementBroker creation

-31 Unexpected exception from ClearingServer when sending refund request

-32 Unexpected exception from online charging server when sending adviceOf-Charge request

Error Code

Description

Execu-tion

status

Result

classification


-200 C Request Type not valid

Without the request type the appropriate request object cannot be created with the given parameters.

1Specify a valid request type.

-201 C Parameter or attribute not found

A parameter or attribute needed for the operation is not found in the http request.

1Specify the missing parameter or attribute.

-202 C Number Format error

A request attribute of type Integer, Long, Short or Double cannot be parsed from the attribute or parameter value of the http request, e.g. "mike55" cannot be parsed to Long.

1Correct the wrong parameter.

-203 C Class Cast error A class cast exception occurred due to an invalid parameter value.

This plugin return code does not exist any more. It is only mentioned for complete-ness.

-204 C Account Handle Specification error

Indicates that the number of elements in the attribute lists specifying the account handles is inconsistent.

1Correct the account type.

A50020-A3245-K-2-76D6

55


Id:0900d8058021019d

HTTP responseformat

The response for users of the HTTP interface is sent as plain text.

If the request is syntactically correct, the format is:HTTP/1.1 200 OKDate: Wed, 03 Mar 2004 14:34:25 GMTServer: Apache/2.0.48 (Unix) mod_jk2/2.0.2Content-Type: text/plain;charset=ISO-8859-1Connection: close

Response: TransactionID=300000110077355864 ExecutionStatus=1TransparentData=""CalculatedMoney.Currency=EURCalculatedMoney.Amount=7688ErrorList.noMoneyFlow=trueErrorList.list={}

Response in case ofsuccess

If the response was sucsessful, the syntax of the response is as follows:HTTP/1.1 200 OKDate: Wed, 03 Mar 2004 14:34:25 GMTServer: Apache/2.0.48 (Unix) mod_jk2/2.0.2Content-Type: text/plain;charset=ISO-8859-1Connection: close

Response: TransactionID=300000110077355865 ExecutionStatus=-104TransparentData=""CalculatedMoney.Currency=EURCalculatedMoney.Amount=7688ErrorList.noMoneyFlow=trueErrorList.list={(111,-31," org.omg.CORBA.OBJECT_NOT_EXIST: minor code: 0 completed: No")}

Response in case oferror

In case of success the ErrorList attributes noMoneyFlow and list are undefined and therefore must not be evaluated.

According to the specification of the HTTP Protocol (RFC 2068) the following is valid:HTTP applications MUST accept CRLF, bare CR, and bare LF as being represen-tative of a line break in text media received via HTTP.

If the request is invalid, e.g., because of missing attributes, the syntax of the response is as follows:HTTP/1.1 200 OKDate: Wed, 03 Mar 2004 14:34:25 GMT

-205 C Multiple user IDs error

Indicates that multiple values have been specified for the user IDs in the list of account handles.

1Correct the userIDs.

-206 C Multiple PINs error Indicates that multiple values have been specified for the PINs in the list of account handles.

1Correct the PINs.

-207 C Multiple routing info error

Indicates that multiple values have been specified for the routing information in the list of account handles.

This plugin return code does not exist any more. It is only mentioned for complete-ness.

-208 C Multiple account types error

Indicates that multiple values have been specified for the account types in the list of account handles.

1Correct the account types.

-230 C Cluster name not found

Indicates that the cluster name specified in the request has not been configured.

1Correct the cluster name.

1The error was detected by the Payment Plugin. The request was not sent to the online charging server.

Execu-tion

status

Result

classification


56 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

Server: Apache/2.0.48 (Unix) mod_jk2/2.0.2Content-Type: text/plain;charset=ISO-8859-1Connection: close"

*** ERROR ExecutionStatus=<status> *** StatusMessage=<msg>"

g The evaluation of the response is only necessary if the HTTP result code is 200 OK. Otherwise, the HTTP request has caused a protocol error. In this case, the exact format of the response depends on the web server in use.

A50020-A3245-K-2-76D6

57


Id:0900d8058021019d

3.2.15 Parameters for the getConsumerAccountList Operation

Introduction This asynchronous getConsumerAccountList operation retrieves information about a list of user accounts.

Parameters The following table shows the parameter mapping scheme for the getConsumerAccoun-tList operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.

Confirmation The execution result is returned using the getConsumerAccountListConf operation and contains information including the balance and currently authorized amount.


Depending on the setting of the routingInfo and accountType parameters, the request is mapped to the following CORBA operations:

• getConsumerAccountListif routingInfo and accountType are not specified

• getConsumerAccountList1if routingInfo and accountType are specified


AccountHandleListdata type

The AccountHandleList data type depends on whether the Java API or the HTTP inter-face is used:

• Java APIIf the Java API is used, the AccountHandleList is a data structure of type Array. The structure is composed of UserId, AccountId and PIN.

IDL Parameter Type IDL Parame-ter Name

Request Attribute

Name

Attribute

Type

Example

for Value



userID

pin

ReqCred.Role

ReqCred.UserId

ReqCred.PIN

Short

String<30>

String<20>

1 (consumer)

consumer MSISDN

PIN

Access

FrontendID_t

access

FrontendID


AccountHandleList_t userID UserIdList each UserId is String<30>

consumer MSISDN

AccountHandleList_t accountID AccountIdList Long (list) a list of account IDs sepa-rated by commas

AccountHandleList_t pin PINList String<20> PIN





getConsumerAccoun-tList

58 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

• HTTP interfaceIf the HTTP interface is used, the AccountHandleList is represented by three name/value pairs where the values are separated by commas.

Example 1: Oneaccount for one user

TransactionId= "300000110077355864" … UserIdList="Miller" AccountIdList="1" PINList ="pin_5678"

Example 2: Threeaccounts for one user

TransactionId= "300000110077355864" … UserIdList="Miller" AccountIdList="1,4,6" PINList="pin_5678"

An empty string for PINList is possible (PINList=" ").

g A user can have up to seven subaccounts.

A50020-A3245-K-2-76D6

59


Id:0900d8058021019d

3.2.16 Parameters for the getAccountListConf Confirmation Operation

Introduction The confirmation operation for getConsumerAccountList contains the transactionID, executionStatus, transparentData and accountList parameters.

Parameters The following table shows how these parameters, which occur within the confirmation operations, are mapped. For a description of the parameters, refer to section 3.2.1 Parameter Description.

Result values The result value of ExecutionStatus_t type is used to confirm the execution of the request in the online charging system asynchronously and to return the success or error code to the Payment Plugin. The values are the same as described in section 3.2.14 Parameters for the Simple Confirmation Operations.

Record structure forAccount_t

The accountList IDL parameter type is a sequence of records of Account_t type. The account-specific information has the following record structure (Account_t):

IDL Parameter Type

IDL Parameter Name

Response Attribute

Name

Attribute

Type

Example

for Value


ExecutionStatus_t executionStatus ExecutionStatus Short 1

refer to section 3.2.15 Parameters for the getConsumerAccountList Operation for possible values

TransparentData_t transparentData TransparentData String<500> 51

AccountList_t accountList Special representation for each list element described below

IDL Parameter Type IDL Parameter Name

Response

Attribute Name

Attribute

Type

Example

for Value

AccountID_t accountID AccountId. Long 1234567890

AccountType_t::Value_t accountType AccountType. Short 0 unknown1 consumer prepaid2 consumer postpaid3 merchant sales4 merchant fees5 psp sales6 psp merchant paid fees7 psp consumer paid fees8 loyalty account

UserID_t::Value_t ownerID OwnerId. String<30> MSISDN or merchant login

Currency_t::Value_t currency Currency. String<3> EUR

boolean approved deprecated

60 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

The appendix string . denotes the i-th element of the list, with a range for i from "1" to "N" with "N" being the number of elements in the list.

AccountList data type The AccountList data type depends on whether the Java API or the HTTP interface is used:

• Java APIIf the Java API is used, the AccountList is a data structure of type Array.

• HTTP interfaceIf the HTTP interface is used, the AccountList is represented by a string containing all parameters as name / value pairs where the values are separated by commas.

Amount_t::Value_t currentBalance Balance. Long 50000

Amount_t::Value_t current Autho-rized Amount

AuthoAmount. Long 60000

PaymentInstrument_t clearing Instru-ment

deprecated

ClearingPolicy_t clearingPolicy deprecated

short clearingPeriod deprecated

Amount_t::Value_t clearing Thresh-old

deprecated

Date_t lastBalance ModDate

BalModDate. Long 994683210000 = UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001

Date_t expiryDate ExpiryDate. Long 994683210000 = UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001

IDL Parameter Type IDL Parameter Name

Response

Attribute Name

Attribute

Type

Example

for Value

A50020-A3245-K-2-76D6

61


Id:0900d8058021019d

Example for N = 2

g In the case of an error, the list of attributes contains only default values.

HTTP/1.1 200 OKDate: Wed, 16 Feb 2005 14:34:45 GMTServer: Apache/2.0.48 (Unix) mod_jk2/2.0.2Content-Type: text/plain;charset=ISO-8859-1Connection: closeTransactionID = 300000110077355864 ExecutionStatus = 1TransparentData = "100"AccountId.1 = 987654, AccountType.1 = 1, OwnerId.1 = 'Miller', Currency.1 = 'EUR', Approved.1 = true, Balance.1 = 23200, AuthoAmount.1 = 0, ClearInstr.1 = 2, ClearPolicy.1 = 1 ClearPeriod.1 = 17, ClearThresh.1 = 0, BalModDate.1 = 0,ExpiryDate.1 = 0,…, …,AccountId.2 = 987654, AccountType.2 = 1, OwnerId.2 = 'Miller', Currency.2 = 'EUR', Approved.2 = true, Balance.2 = 23200, AuthoAmount.2 = 0, ClearInstr.2 = 2, ClearPolicy.2 = 1 ClearPeriod.2 = 17, ClearThresh.2 = 0, BalModDate.2 = 0,ExpiryDate.2 = 0

depracated depracateddepracateddepracateddepracated depracated depracateddepracateddepracateddepracated

62 A50020-A3245-K-2-76D6


Id:0900d8058021019d

HTTP Interface

3.2.17 Parameters for the getTAState Operation

Introduction This synchronous operation returns transaction information for the given TransactionId. The type of the return value is TransactionStatus_t (enumeration type).

Parameters The following table shows the parameter mapping scheme for the getTAState operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.

With this operation the value of the parameter UserId may be used for address resolu-tion, if multiple charging servers are connected to the Payment Plugin. However, the address resolution functionality has to be implemented project-specifically.


Transaction status For the getTAState operation, the current status of the transaction is contained in the executionStatus field of the confirmation. The values and their meaning are explained in section 6.1 Timeout Handling at the Client Side Using getTAState).

IDL Parameter Type

IDL Parameter Name

Request Attribute

Name

Attribute

Type

Example

for Value


UserID_t userID UserId String<30> MSISDN (has to be identical to the parameter Consum-erId in the original transac-tion)



getTAState

A50020-A3245-K-2-76D6

63

DMN:Payment Plugin Interface Java API

Id:0900d80580208e80

4 Java APIIntroduction This chapter describes the Payment Plugin interface for non-web-based applications.

Applications written in Java may load the Payment Plugin as a library and use the Java API to send requests to the online charging server.The design of the Java API is similar to the J2EE Connector API. A PaymentConnectionFactory manages a set of logical con-nections to the charging server which in turn may be used to send requests to the online charging server.

Requests to the charging server are represented by instances of subclasses of PaymentRequest.

Interface classes Thus, the Application Programming Interface (API) consists of the following interface classes:

• PluginProperties • PaymentConnectionFactory • PaymentConnection • subclasses of PaymentRequest and PaymentResponse

g HTML documentation for all interface classes is included in the Payment Plugin package.

The binaries of the above mentioned classes and of all generated CORBA classes are stored in the PaymentPlugin.jar file, which needs to be installed on the client machine. Additionally, a CORBA runtime environment has to be installed. Currently there are two separate Payment Plugin variants for the VisiBroker or the JacORB.

Contents 4.1 Typical Usage Scenario

4.2 Example of a Property File

64 A50020-A3245-K-2-76D6


Id:0900d80580208e80

Java API

4.1 Typical Usage Scenario

Introduction This section describes a typical usage scenario of the Payment Plugin interface. Examples for the usage of the API classes can be found in chapter 6 Appendix.

Interface usagescenario

Proceed as follows:

Step Action

1 Initialize the Payment Plugin properties:

PluginProperties.getReference().load( new FileInput Stream( <name of property file> ) );

The PluginProperties class implements the singleton pattern.

2 Initialize the logging framework from the properties:

org.apache.log4j.PropertyConfigurator.configure( Payment-Plugin.getReference() )

3 Obtain a reference to the PaymentConnectionFactory:

PaymentConnectionFactory pcf = PaymentConnectionFac-tory.getReference();

If multiple online charging system clusters have been configured in the Pay-mentPlugin.properties file, a factory to a specific cluster may be aquired by:

PaymentConnectionFactory pcf = PaymentConnectionFac-tory.getReference(alias);

Provided that alias has been configured as an alias name for that cluster, i.e. there is an entry like the following in the PaymentPlugin.properties file.

Cluster.<n>=<alias>,<NameServiceURL of the cluster>

4 Get a new connection from the factory:

PaymentConnection conn = pcf.getConnection();

5 Instantiate a payment request.

A payment request can be instantiated by calling the default constructor and subsequent set methods or by calling the overloaded constructor with argu-ments for all request parameters.

PaymentRequest req = new ChargeAmountReq( tid, role, ... );

or

PaymentRequest req = new ChargeAmountReq();

req.setTransactionID( tid );

req.setRoleID( role );

... // Same for the rest of the attributes.

If using the second approach, PaymentRequest objects may be instantiated once and reused for subsequent requests. However, the caller has to make sure that all attributes are set and reset correctly.

The attributes of these requests are described in the API documentation which is part of the Payment Plugin package.

A50020-A3245-K-2-76D6

65


Id:0900d80580208e80

6 Use the connection to execute requests on the online charging server.

The connection may be reused for subsequent requests. If the client is multi-threaded, separate connections should be used for each thread.

PaymentResponse conf = conn.execute( req );

The execute() call returns if either a response has been received from the charging server or a timeout has expired.

7 Check the status of execution. Error codes are documented in section 3.2.14 Parameters for the Simple Confirmation Operations.

int status = conf.getExecutionStatus();

8 Finally, close the PaymentConnection:

conn.close();

This frees all resources allocated for this connection.

Step Action

66 A50020-A3245-K-2-76D6


Id:0900d80580208e80

Java API

4.2 Example of a Property File

Introduction This section describes an example of a property file which contains the configuration parameters of the Payment Plugin. During start up, the Payment Plugin reads this file and sets the appropriate internal control variables.

Property file The following table comprises a sample property file:

Property name Value Comment

NameServiceUrl corbaloc::zahlnix:2061/NameService

The URL of the CORBA Name Ser-vice.Syntax: corbaloc::<IP-Addr>: <Port>/NameService

Cluster.<unique number> Cluster.0=c1,corbaloc::testserv1: 2061/NameService

Cluster.1=c2,corbaloc::testserv2: 2061/NameService

A list of online charging system clusters to be accessed. The syntax is as follows:

<logical name>, <URL of cluster specific CORBA NameService>

interface.version.major 2 If the interface.version.major property has a value less than 2, confirmation messages are compatible with earlier ver-sions, i.e. do not contain transparent data. If the interface version is not set, the version defaults to 2.1.

interface.version.minor 1

log4j.rootLogger log4j.rootLogger=WARN, logfile, console

Defines the logging configuration to be used.

The property value consists of the specifi-cation of a logging level (FATAL, ERROR, WARN, INFO, DEBUG) and a list of appenders.

Please see the log4j documentation avail-able at: http://jakarta.apache. org/log4j/docs/index.html

log4j.appender.logfile.File /opt/jakarta-tomcat-4.1.29/logs/PaymentPlugin.log

Absolute path of PaymentPlugin log file.${java.io.tmpdir}/ PaymentPlugin.log

TransactionHostId 4444 HostId of the sender used as a prefix for the TransactionId if the string is not empty (maximum 4 digits).

A50020-A3245-K-2-76D6

67


Id:0900d80580208e80

log4j.renderer.[Lde.siemens. advantage.payment.payplu-gin. impl.processing.Account;

de.siemens.advantage.payment. payplugin.impl.logging.AccountListRenderer

Registration of object renderers

Note: Values do not need to be changed.

log4j.renderer.de.siemens. advantage.payment.payplu-gin. impl.processing. RechargeAmountResponse

de.siemens.advantage.payment. payplugin.impl.logging.Recharge AmountResponseRenderer

log4j.renderer.de.siemens. advantage.payment.payplu-gin. impl.processing.Payment-Response

de.siemens.advantage.payment. payplugin.impl.logging. Payment-ResponseRenderer

log4j.renderer.[Lde.siemens. advantage.payment.payplu-gin. impl.corba. AccountMan-agementTypes. Account_t;

de.siemens.advantage.payment. payplugin.impl.logging. Account_tListRenderer

log4j.renderer.[Lorg.omg. CORBA.Policy;

de.siemens.advantage.payment. payplugin.impl.logging. PolicyLis-tRenderer

log4j.appender.console org.apache.log4j. ConsoleAp-pender

Definition of console appender

Note: Values do not need to be changed.log4j.appender.console.layout org.apache.log4j.PatternLayout

log4j.appender.console. Threshold

ERROR

log4j.appender.console. lay-out.ConversionPattern

%d %5p [%t] %x (%F:%L) - %m%n Definition of the output pattern of:

• the file name of the caller

• the line number


log4j.appender.logfile org.apache.log4j. RollingFileAp-pender

log4j.appender.logfile. Max-FileSize

10MB Definition of console appender


log4j.appender.logfile. Max-BackupIndex

5 Definition of number of logfiles to be kept

Note: Values do not need to be changed.log4j.appender.logfile.Append false

log4j.appender.logfile.layout org.apache.log4j.PatternLayout Definition of the output pattern for the logfiles

Note: Values do not need to be changed.log4j.appender.logfile.layout. ConversionPattern

%d %5p [%t] %x (%F:%L) - %m%n

AliveTestInterval 30 000 Interval (in milliseconds) for sending get-Version calls to the online charging server for alive tests.

Note: Value does not need to be changed.


68 A50020-A3245-K-2-76D6


Id:0900d80580208e80

Java API

AliveTestTimeout 20 000 Timeout value (in milliseconds) for getVersion calls to the online charging server for alive tests. A warning is written to the log file if the timeout has expired.


NameServiceTimeout 20 000 Timeout value (in milliseconds) for NameService responses using the loca-tions specified in NameServiceUrl.


ResponseTimeout 20 000 Timeout value (in milliseconds) for the response from online charging server to a payment request.


ConfirmationTimeout 30 000 Timeout value (in milliseconds) for callback from the online charging server for a previously sent payment request.


CorbaObjectPoolRefreshInter-val

300 000 Time interval (in milliseconds) for refresh-ing the CorbaObjectPool.


MaxNumParallelReq 100 Maximum number of parallel requests for overload protection. Also controls the maximum number of concurrent instances of PaymentConnection.


ServerOverloadTimeout 5000 Maximum duration (in milliseconds) allowed for an overload situation reported by the server. If exceeded, the overload situation is automatically cleared and the Payment Plugin resumes sending requests to the online charging server.


ChargingServerNamingCon-text Path

PaymentInterface/Server Naming Context Path under which the CORBA ChargingServer server objects can be found.

Note: Value must not be changed.

ChargingServerClusterName ChargingServer Name of the ChargingServer server cluster.



A50020-A3245-K-2-76D6

69


Id:0900d80580208e80

ChargingBrokerNaming Con-textPath

PaymentInterface/Broker Naming Context Path under which the CORBA ChargingBroker server object(s) can be found.


ChargingBrokerName ChargingBroker Name of the ChargingBroker server object.


ClearingServerNaming Con-textPath

PaymentInterface/Server Naming Context Path under which the CORBA ClearingServer server objects can be found.


ClearingServerClusterName ClearingServer Name of the ClearingServer server cluster.


ClearingBrokerNaming Con-textPath

PaymentInterface/Broker Naming Context Path under which the CORBA ClearingBroker server object(s) can be found.


ClearingBrokerName ClearingBroker Name of the ClearingBroker server object.


AccountManagementServer NamingContextPath

PaymentInterface/Server Naming Context Path under which the CORBA AccountManagementServer server objects can be found.


AccountManagementServer ClusterName

AccountManagementServer Name of the AccountManagementServer server cluster.


AccountManagementBroker NamingContextPath

PaymentInterface/Broker Naming Context Path under which the CORBA AccountManagementBroker server object(s) can be found.


AccountManagementBroker Name

AccountManagementBroker Name of the AccountManagementBroker server object.


Corba.OAPort 49677 The port used for the local object adapter (range 1024 ... 65535). The port number must not be used by anyother application.NOTE:The port may be overwritten by the vbroker.se.iiop_tp.scm.iiop_tp.listener.port JAVA Virtual Machine (JVM) option.


70 A50020-A3245-K-2-76D6


Id:0900d80580208e6b

J2EE Connector Interface

5 J2EE Connector InterfaceIntroduction This chapter describes the Java 2 Enterprise Edition (J2EE) connector interface as a

standard architecture for enabling J2EE components to interact with enterprise informa-tion systems (EIS). An example is used to describe how to use this interface.

Contents 5.1 J2EE Connector Architecture

5.2 Usage Scenario for the J2EE Connector Interface

A50020-A3245-K-2-76D6

71

DMN:Payment Plugin Interface J2EE Connector Interface

Id:0900d80580208e6b

5.1 J2EE Connector Architecture

Introduction This section describes the J2EE connector architecture (JCA) and the restrictions with regard to the use of this interface.

J2EE connectorarchitecture

The JCA defines a standard architecture for enabling J2EE components such as enter-prise beans, servlets or Java Server Pages (JSP) to interact with enterprise information systems (EISs). J2EE components use connections to access services provided by the EIS. Connection objects are pooled by the application server. This provides a scalable application environment that can support a large number of clients requiring access to an EIS. Using connection factories, connection is obtained between the application and the EIS through the application server. On receiving a client request, connections from the pool are given to the client. After use, these connections are released by the client and are put back in the connection pool.

JCA specification andrestrictions

The JCA is specified in the respective Java Connector Architecture Specification (e.g. version 1.0, final release August 22, 2001).

Restrictions with respect to the JCA specification: • The optional common client interface (CCI) is not supported. • All connections are non-transactional. • The security management interface is not supported. Requester credentials are not

required when establishing connections, but have to be provided as request param-eters.

• Since the Payment Plugin uses the log4j logging framework internally, it is not possible to change the destination of the logging output by calling the setLogWriter() method.

The J2EE connector interface is very similar to the Java API. Both interfaces use differ-ent classes for connection factories and connections. The request classes are identical.

72 A50020-A3245-K-2-76D6


Id:0900d80580208e6b

J2EE Connector Interface

5.2 Usage Scenario for the J2EE Connector Interface

Introduction This section described in an example how to use this interface. It is assumed that the connector has been configured and deployed to the application server and that the con-nection factory has been bound to the Java Naming and Directory Interface (JNDI) name eis/PayAdvConnector.

Precondition This section shows how to use this interface to send a charging request to the online charging server.

Example // import required packages and classesimport javax.naming.*;import de.siemens.advantage.payment.payplugin.intf.connector.*;import de.siemens.advantage.payment.payplugin.impl.processing.ChargeAmountReq;import de.siemens.advantage.payment.payplugin.impl.processing.PaymentResponse; ...// create initial contextContext initCtx = new InitialContext();

// perform JNDI lookup// the naming context is specific to the application serverPayAdvConnectionFactory factory =(PayAdvConnectionFactory) initCtx.lookup( "java:comp/env/eis/PayAdvConnector" );// get a connection to the payment serverPayAdvConnection conn = factory.getConnection();

// instantiate a requestChargeAmountReq req = new ChargeAmountReq( ... );

// execute the requestPaymentResponse resp = conn.execute( req );

// evaluate the responseSystem.out.println( "executed request, executionstatus = " +resp.getExecutionStatus() );

// finally close the connection to put it back to the poolconn.close();

g The error handling code has been omitted for clarity.

Additional information HTML documentation for all interface classes is included in the Payment Plugin software package.

The source code for the usage of the connector in a sample EJB is shown in section 6.2.7 Example of an EJB Using the J2EE Connector Interface.

A50020-A3245-K-2-76D6

73

DMN:Payment Plugin Interface Appendix

Id:0900d8058020b05e

6 AppendixIntroduction This chapter contains a hint on how to handle timeouts and examples showing how to

use the recharge request.

Contents 6.1 Timeout Handling at the Client Side Using getTAState

6.2 Examples

74 A50020-A3245-K-2-76D6


Id:0900d8058020b05e

Appendix

6.1 Timeout Handling at the Client Side Using getTAState

Introduction This section gives a hint on how to handle timeouts.

Network problems In a network it is always possible that the link between client and server is interrupted. It depends on the configuration of the network elements (e.g. routers) how long messages survive in these situations. In the best case, a message may be stored tem-porarily to be transmitted later. In the worst case, the message is completely lost.

Client application This situation of delayed or lost messages cannot be controlled by the Payment Plugin or the online charging server. In fact, it is the client who is responsible for the correct completion of the transactions.

Message flow The following figure shows the typical message flow:

Timeout If the online charging server does not acknowledge in time that it has received the request, the Payment Plugin reports a ResponseTimeout error. A ConfirmationTimeout error is reported, if no confirmation indicating the result of the transaction is received during a specified period of time.After a ResponseTimeout (-109) or a ConfirmationTim-eout (-103) there are two possible situations:

• The request may have been received and processed by the online charging server and the confirmation may have been lost.

• The request was not received by the online charging server at all.

In general, transactions, which result in any account changes, are still stored for a short time at the online charging server, so that their states could be queried by getTAState afterwards. However, transactions which do not change any accounts like the getAc-countTransactionList and getTAState transactions are not stored and usually should not be queried by getTaState. There may be internal reasons, for which even some of these

A50020-A3245-K-2-76D6

75


Id:0900d8058020b05e

transactions are stored. There are also several reasons, due to which failed transactions are not stored, for example if the transaction cannot be processed at all because of any parameter errors or because of rejection due to traffic limitation or overload. Neverthe-less, again there might be internal reasons, for which even some of such transactions are stored.

In older systems it was possible to query transactions only, which had been processed in the PaymentCore and not the ones, which had been processed in the CCS. So the getTAState request had been available in a Charging@vantage configuration only. In charge@once configurations the getTaState implementation had to be ordered project-specifically. In CPOCS the getTaState transaction works for CCS transactions too - with slightly changed behaviour due to the different internal implementation.

The timeframe the transaction status is available varies with the used online charging system:

Using the PaymentCore the transaction status is available for at least 15 minutes after the processing. With CPOCS and direct Service access the timeframe depends also on success. For successful transaction the timeframe can be administered on Tarifftool. In a product configuration it is 10 minutes. Most non successful transactions need not to be stored by the CCS.

getTAState request After recognizing a ResponseTimeout or a ConfirmationTimeout, the client sends a get-TAState request to check the status of the transaction. Depending on the received infor-mation the client reacts as described in the table below.

g After the Payment Plugin has declared timeout for a transaction, any response from the online charging server concerning this transaction is ignored. The client applica-tion must not base any decisions on these 'late' responses which might have been buffered somewhere in the network. Decisions must be based solely on the result of the getTAState request.

g If a confirmation to the client at the Payment Plugin cannot be transferred, the online charging server will not execute rollbacks. The client application using the Payment Plugin has to decide whether to initiate actions to rollback or rollforward or admin-ister, if it does not receive confirmations from the online charging server.

Transaction statusvalues

The following table specifies and explains the possible transaction status values:

Transaction status values

Comment

0 = requested Depending on the operation, this internal status means:

- chargeRequested- authorizationRequested- captureRequested- rechargeRequested.

Note: This status is an intermediate internal status with a short life-time.

76 A50020-A3245-K-2-76D6


Id:0900d8058020b05e

Appendix

1 = processed The final status, if

- the chargeAmount or

- the final captureAmount or

- the rechargeAmount

has been processed successfully by the online charging server.

2 = timeout Not used. The transaction status value 3 (failed) is used instead.

3 = failed The confirmation contains an ExecutionStatus > 1 due to problems; e.g. authorization check failed, consumer is unknown, ...

4 = expired Not used. The transaction status value 3 (failed) is used instead.

5 = authorized The internal status after a successful authorizeAmount.Any number of captureAmount requests may be received via the CORBA inter-face. In this case, the transaction status is changed to captureRe-quested.

6 = capture Requested

The internal status after a captureAmount has been received.

Note: This status is an intermediate internal status with a short life-time.

7 = partly Captured

Not used. The transaction status value 5 (authorized) is used instead.

The following error codes are sent if the getTAState request was unsuccessful:

-101 = Invalid transaction

The getTAState request has failed, because the transaction is not known by the online charging server

-104 = CORBA communica-tion error

The getTAState request has failed, because there is a problem in the CORBA communication between the Payment Plugin and the online charging server.

-105 = Overload detected

The getTAState request has failed due to a temporary overload sit-uation in the online charging server.

-109 = Response Timeout

There was no response from the online charging server to the getT-AState request.

-110 = No server resources

The getTAState request has failed due to a temporary overload sit-uation reported by the online charging server.

Transaction status values

Comment

A50020-A3245-K-2-76D6

77


Id:0900d8058020b05e

6.2 Examples

Introduction This section provides some basic information about the HTTP protocol and shows examples of recharge requests.

For further information on this protocol, refer to RFC 1945 (HTTP/1.0) and RFC 2616 (HTTP/1.1) which can be downloaded from http://www.rfc-editor.org.

HTTP request An HTTP request consists of a request method, a request URL, header fields and a body. HTTP defines the following request methods: • GET: retrieves the resource identified by the request URL • HEAD: returns the headers identified by the requested URL • POST: sends data of unlimited length to the web server

The Payment Plugin servlet handles both GET and POST. The POST request is recom-mended because there is no length limitation.

HTTP response An HTTP response contains a result code, header fields and a body. The HTTP protocol expects the result code and all header fields to be returned before any body content.

A GET request does not have a body (i.e. the body is empty). The response contains a body with the response data and header fields which describe the body (especially Content-Type and Content-Encoding). With a GET request, the parameters are encoded in the URL, whereas with a POST request they are transmitted in the body.

Status codes Some commonly used status codes include the following:

The following sections show simple examples of a rechargeAmount request using GET and POST syntax.

All request parameters are specified as tag-value pairs separated by the "&" character. Tags and values are separated by the "=" character. The list has to be provided in URL-encoded format. Please see RFC 1738 for details.

Contents 6.2.1 Format of a Recharge Request Using GET Syntax

6.2.2 Format of a Recharge Request Using POST Syntax

Status Code

Description

200 The request has succeeded.

204 The server has fulfilled the request, but there is no new information to send back.

400 The request could not be understood by the server due to invalid syntax.

401 The request requires user authentication.

403 The server understood the request, but is refusing to fulfill it.

404 The server has not found anything matching the request URL.

500 The server encountered an unexpected condition which prevented it from ful-filling the request.

501 The server does not support the functionality required to fulfill the request.

503 The server is currently unable to handle the request due to temporary over-loading or maintenance of the server.

78 A50020-A3245-K-2-76D6


Id:0900d8058020b05e

Appendix

6.2.3 Example of a Recharge Request Using HTTP GET in Java

6.2.4 Example of a Recharge Request Using HTTP GET in C++

6.2.5 Example of a Recharge Request Using the Java Library PaymentPlugin.jar


6.2.7 Example of an EJB Using the J2EE Connector Interface

6.2.1 Format of a Recharge Request Using GET Syntax

Introduction This section describes the format of a recharge request using the GET syntax.

Syntax GET/PaymentPlugin/servlet/PaymentPluginServlet?TransactionId=300000110077355864 &ReqCred.Role=3&ReqCred.UserId=PSPLogin&ReqCred.PIN=8888&AccessFrontendId=JSUNICOM&ConsumerId=8613072506800&ConsumerAccountId=0&ConsumerPIN=1234&Purpose=cash-in+Recharge&Money.Currency=RMB&Money.Amount=20000&ExpiryDate=1043977423&Request Type=rechargeAmount HTTP/1.0<NEWLINE>

g The entire request is in one line.

6.2.2 Format of a Recharge Request Using POST Syntax

Introduction This section describes the format of a recharge request using the POST syntax.

Syntax POST /PaymentPlugin/servlet/PaymentPluginServlet HTTP/1.0<NEWLINE>User-Agent: None<NEWLINE>Content-Type: application/x-www-form-urlencoded<NEWLINE>Content-Length: 285<NEWLINE><NEWLINE>TransactionId=300000110077355864&ReqCred.Role=3&ReqCred.UserId=PSPLogin&ReqCred.PIN=&AccessFrontendId=%2F%2Fhttp%3A&ConsumerId=8613001114206&ConsumerAccountId=0&ConsumerPIN=&Purpose=Online+Recharging&Money.Currency=RMB&Money.Amount=10000&ExpiryDate =1014937200000&RequestType=rechargeAmount<NEWLINE><NEWLINE>

A50020-A3245-K-2-76D6

79


Id:0900d8058020b05e

6.2.3 Example of a Recharge Request Using HTTP GET in Java

Introduction The sample code below shows a Java implementation of a simple client using the HTTP interface to send a recharge request and print the response to the standard output.

Example /* Copyright (c) Siemens AG 2000,2001 All Rights Reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/

import java.io.*;import java.net.*;import java.util.*;

// example for a HTTP GET recharge amount request for the Payment Plugin // Servlet residing on a Web Server public class HTTPGetRecharge { public static final String classVersion = "@(#) HTTPGetRecharge.java : /main/5 : ";

public static void main(String[] args) throws Exception {

// define the servlet String servletURL =

"http://localhost:8080/PaymentPlugin/servlet/PaymentPluginServlet?";

// define the name value pairs used for one recharge amount request String par1 = "RequestType=rechargeAmount";

String par2 = "TransactionId=300000110077355864"; String par3 = "ReqCred.Role=3";

// The class URLEncoder contains a utility method for converting a // String into a MIME format called "x-www-form-urlencoded" format. // The conversion is necessary to transfer the space character ' ' // as a plus sign '+'. String par4 = "ReqCred.UserId=" + URLEncoder.encode("Jimmy Smith"); String par5 = "ReqCred.PIN=8888"; String par6 = "AccessFrontendId=HTTP_Tester"; String par7 = "ConsumerAccountId=0815"; String par8 = "ConsumerId=Miller"; String par9 = "ConsumerPIN=1234"; String par10 = "Purpose=test_of_rechargeAmount"; String par11 = "Money.Currency=EUR"; String par12 = "Money.Amount=500000";

// the expiration date is today plus 30 days Date today = new Date(); long expiryDate = today.getTime() + 30 * 24 * 60 * 60 *1000L; String par13 = "ExpiryDate=" + expiryDate;

// build a string containing the servlet url and the params String spec = servletURL + par1 + "&" + par2 + "&" + par3 + "&" + par4 + "&" + par5 + "&" + par6 + "&" + par7 + "&" + par8 +

"&" + par9 + "&" + par10 + "&" + par11 + "&" + par12 + "&" + par13;

System.out.println("The spec of the URL: " + spec);

try {

80 A50020-A3245-K-2-76D6


Id:0900d8058020b05e

Appendix

// Class URL represents a Uniform Resource Locator, a pointer to // a "resource" on the World Wide Web. URL url = new URL(spec);

// build a connection to this URL and send the request URLConnection urlConn = url.openConnection();

// If it is an HTTP connection, display some additional// information. if (urlConn instanceof HttpURLConnection) { HttpURLConnection h = (HttpURLConnection) urlConn; System.out.println(" Request Method: " + h.getRequestMethod()); System.out.println(" Response Message: " + h.getResponseMessage()); System.out.println(" Response Code: " + h.getResponseCode());

}

// get an input stream InputStream urlconninstr = urlConn.getInputStream(); // get an InputStreamReader InputStreamReader isr = new InputStreamReader( urlconninstr ); // use a BufferedReader BufferedReader br = new BufferedReader( isr ); // read the response from the Payment Plugin Servlet line by line

System.out.println("The result of the RechargeAmount is ..."); String line = br.readLine(); while (line != null) { System.out.println(line); line = br.readLine();

} // close the BufferedReader br.close(); } catch (MalformedURLException mue) { System.out.println(mue.getMessage());

} // catch MalformedURLException catch (IOException ioe) { System.out.print("general IO exception "); System.out.println(ioe.getMessage()); } // catch IOException } // end main}

As the standard Java library provides convenience classes to handle URL connections, the implementation is quite simple.

A50020-A3245-K-2-76D6

81


Id:0900d8058020b05e

6.2.4 Example of a Recharge Request Using HTTP GET in C++

Introduction The sample code in this section shows an implementation of a simple client in C++, which sends a recharge request using the HTTP interface and prints the response to the standard output. Unlike the Java example in section 6.2.3 Example of a Recharge Request Using HTTP GET in Java, this implementation requires somewhat more code, as the socket connection to the web server has to be established explicitly by the client.

Example /* Copyright (c) Siemens AG 2000,2002 All Rights Reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/

#include <iostream.h>#include <strstream.h>#include <sys/types.h>#include <sys/socket.h>#include <arpa/inet.h>#include <netdb.h>#include <unistd.h>#include <errno.h>#include <string.h>#include <stdlib.h>#include <limits.h>

const char * SERVLET_NAME = "/PaymentPlugin/servlet/PaymentPluginServlet";

/* * generate header for a HTTP GET request */

void fillInHeader( ostrstream& ostr ) { ostr << "GET "; ostr << SERVLET_NAME;/* *encode parameters for a dummy Recharge request */

void fillInParams( ostrstream& ostr ) { const char DELIM = '&'; ostr << "RequestType=rechargeAmount"<< DELIM << "TransactionId=300000110077355864"<< DELIM << "ReqCred.Role=3"<< DELIM << "ReqCred.UserId=Jimmy+Smith"<< DELIM << "ReqCred.PIN=8888"<< DELIM << "AccessFrontendId=HTTP_Tester"<< DELIM << "ConsumerAccountId=0815"<< DELIM << "ConsumerId=Miller"<< DELIM << "ConsumerPIN=1234"<< DELIM << "Purpose=test_of_rechargeAmount"<< DELIM << "Money.Currency=EUR"<< DELIM << "Money.Amount=500000"<< DELIM << "ExpiryDate=99999";}

/* * generate the request */

82 A50020-A3245-K-2-76D6


Id:0900d8058020b05e

Appendix

void fillInRequest( ostrstream& ostr ) { fillInHeader( ostr ); ostr << "?"; fillInParams( ostr ); ostr << " HTTP/1.0"; ostr << "\r\n\r\n"; ostr << ends;

}

/* * open an internet socket to the web server * the web server is specified by an IP address and a port number */

int openConnection( const char *hostName, const short port ) { int sd = socket( AF_INET, SOCK_STREAM, 0 ); if ( sd < 0 ) { cerr << strerror( errno ) << endl; } else { hostent *entry = gethostbyname( hostName ); if ( entry == NULL ) { cerr << "ERROR: host \"" << hostName << "\" not found." << endl; sd = -2; } else { in_addr in; memcpy( &in.s_addr, entry->h_addr_list[0], sizeof in.s_addr );

sockaddr_in addr; memset( &addr, 0, sizeof addr ); addr.sin_family = AF_INET; addr.sin_port = htons( port ); addr.sin_addr.s_addr = in.s_addr; cout << "Connecting to \"" << hostName << "\" (" << inet_ntoa( in ) << "), "

<< port << endl; int rc = connect( sd, (sockaddr *) &addr, sizeof addr ); if ( rc < 0 ) { cerr << "ERROR: " << strerror( errno ) << endl; sd = rc; } } }

return sd;}

/* * close the socket connection */

void closeConnection( int sd ) { shutdown( sd, 2 ); close( sd );

}

/* * main routine */

int main( int argc, char *argv[] ) {

const int RESULT_LEN = 2048; char resultBuffer[RESULT_LEN];

A50020-A3245-K-2-76D6

83


Id:0900d8058020b05e

int rc;

/* * 0. process command line */ if ( argc < 3 ) { cerr << "Usage: HTTPRecharge <hostname of the web server running the PaymentPlugin> <port>" << endl; return 1;

}

char * hostName = argv[1]; int port = atoi( argv[2] ); if ( port == 0 || port <= SHRT_MIN || port >= SHRT_MAX ) { cerr << "invalid port number" << endl; return 2; }

/* * 1. establish a connection to the web server */ int sd = openConnection( hostName, port ); if ( sd < 0 ) { cerr << "Connection to \"" << hostName << "\", port " << port << "

failed." << endl;

return 3; }

/* * 2. generate a Recharge request */ ostrstream requestBuffer; fillInRequest( requestBuffer ); char * request = requestBuffer.str(); cout << "sending GET request:\n" << request << endl;

/* * 3. send the request */ rc = write( sd, request, strlen( request ) );// error handling omitted !!! cout << "request sent, waiting for response" << endl;

/* * 4. wait for the response * keep on reading until the response is complete */ int bytesRead = rc; int msgLen = 0; while ( bytesRead > 0 ) { bytesRead = read( sd, resultBuffer + msgLen, RESULT_LEN - msgLen ); msgLen += bytesRead; } cout << "result is:\n" << resultBuffer << endl;

/* * 5. close the connection to the web server */ closeConnection( sd );

return 0;}

84 A50020-A3245-K-2-76D6


Id:0900d8058020b05e

Appendix

6.2.5 Example of a Recharge Request Using the Java Library PaymentPlugin.jar

Introduction The sample code in this section shows an implementation of a simple client using the classes of the processing layer.

The following recharge request examples are shown below:

• Client application

• Startup script for JacORB

Example of a clientapplication

/* Copyright (c) Siemens AG 2000,2002 All Rights Reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/

import de.siemens.advantage.payment.payplugin.impl.processing.*;import de.siemens.advantage.payment.payplugin.impl.corba.Common.*;import de.siemens.advantage.payment.payplugin.impl.PluginProperties;import org.apache.log4j.Logger;import org.apache.log4j.PropertyConfigurator;

import java.util.*;import java.io.*;

// example for usage of the Payment Plugin API

public class APIRecharge {

// Retrieve a Logger for class APIRecharge. // Logger is the central class in the log4j package. public static Logger logger = Logger.getInstance( APIRecharge.class.getName() );

public static void main(String[] args) {

try { if ( args.length > 0 ) {

// read the Payment Plugin property file and // initialize the PluginProperties class PluginProperties.getReference().load( new FileInputStream( args[0] ) ); }

// extends class BasicConfigurator from log4j // to provide configuration from an external file PropertyConfigurator.configure( PluginProperties.getReference() );

// verify the properties specified by the user PluginProperties.getReference().verify();

// obtain a reference to the PaymentConnectionFactory// for the charge@once cluster "SEP01" // NOTE: there must be a configuration entry // Cluster.0=SEP01,corbaloc::<hostname_or_ip>:2061/NameService // in the PaymentPlugin.properties file PaymentConnectionFactory factory = PaymentConnectionFactory.getReference( "SEP01" );

// if only one cluster is used the method call above may be reduced to // PaymentConnectionFactory factory = // PaymentConnectionFactory.getReference();

A50020-A3245-K-2-76D6

85


Id:0900d8058020b05e

// get a new connection from the factory// .PaymentConnection conn = factory.getConnection();// Instantiate a payment request// either calling the default constructor and subsequent set// methods or the overloaded constructor with arguments for all// request parameters

RechargeAmountReq req = new RechargeAmountReq(); req.setTransactionID("300000110077355864"); req.setRoleID( (short)3 ); req.setUserID("Jimmy Smith"); req.setPin("8888"); req.setAccessFrontendID("API_Tester"); req.setConsumerAccountID( Long.parseLong("0815")); req.setConsumerID("Miller"); req.setConsumerPIN("1234"); req.setPurpose("test_of_rechargeAmount"); req.setCurrency("EUR"); req.setAmount(500000);

// the expiration date is today plus 30 days Date today = new Date(); long expiryDate = today.getTime() + 30 * 24 * 60 * 60 *1000L; req.setExpiryDate(expiryDate); System.out.println(req);

// Use the connection to execute requests on the Charging@vantage// server. PaymentResponse conf = conn.execute( req );// Check the status of the execution.// Error codes are documented in the // Charging@vantage Interface Specification.// Additional error codes are generated by the PaymentPlugin. int status = conf.getExecutionStatus(); System.out.println("ExecutionStatus=" + status + " for TransactionID " + conf.getTransactionID());

// Finally close the PaymentConnection.// This will free all the resources allocated for this connection. conn.close();

} catch ( Exception ex ) { System.out.println( "Uncaught exception: " + ex.getLocalizedMessage() );

} System.exit( 0 ); }}

Example of a simplestartup script

f In order to run the application make sure the CORBA runtime environment is set up correctly.

#! /bin/bashJAVA_HOME=/usr/java1.4.2JVM=${JAVA_HOME}/bin/java

JACORB_HOME=/opt/INTPaqasp/libJACORB_LIBS=${JACORB_HOME}/lib/jacorb.jar:${JACORB_HOME}/lib/logkit-.jar:${JACORB_HOME}/lib/avalon-framework.jarLOG4J=/opt/INTPaqasp/lib/log4j-1.2.8.jarPLUGIN_JAR=/opt/INTPaqasp/lib/PaymentPlugin.jar

LOCAL_CLASSPATH=".:${PLUGIN_JAR}:${LOG4J}"

exec ${JVM} ${JVM_FLAGS} \ -classpath "${LOCAL_CLASSPATH}" \

86 A50020-A3245-K-2-76D6


Id:0900d8058020b05e

Appendix

-Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB \ -Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton \ APIRecharge $1


Introduction The example code in this section shows an implementation of a simple client executing a GetTAState request using the Java API.

Example /* Copyright (c) Siemens AG 2000,2001 All Rights Reserved

The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/

import de.siemens.advantage.payment.payplugin.impl.processing.*;import de.siemens.advantage.payment.payplugin.impl.corba.Common.*;import de.siemens.advantage.payment.payplugin.impl.PluginProperties;import de.siemens.advantage.payment.payplugin.impl.sim.servlet.RequestBuilder;import org.apache.log4j.Category;import org.apache.log4j.PropertyConfigurator;

import java.util.*;import java.io.*;

// example for usage of the Payment Plugin API

public class APIGetTAState { public static final String classVersion = "@(#) APIGetTAState.java : /main/1 :";

// Retrieve a category for class APIGetTAState. Category is the central // class in the log4j package. public static Category cat = Category.getInstance( APIGetTAState.class.getName() );

public static void main(String[] args) {

try { if ( args.length > 0 ) { // read the Payment Plugin property file and initialize the // PluginProperties class PluginProperties.getReference().load( new FileInputStream( args[0] ) );

}

// extends class BasicConfigurator from log4j to provide // configuration from an external file PropertyConfigurator.configure( PluginProperties.getReference() );

// verify the properties specified by the user // PluginProperties.getReference().verify();

// obtain a reference to the PaymentConnectionFactory // PaymentConnectionFactory factory = PaymentConnectionFactory.getReference();

// get a new connection from the factory

A50020-A3245-K-2-76D6

87


Id:0900d8058020b05e

PaymentConnection conn = factory.getConnection(); // Instantiate a payment request // either calling the default constructor and subsequent set // methods or the overloaded constructor with arguments for all // request parameters TAStateReq req = new TAStateReq(); req.setTransactionID("100000000001");

// Use the connection to execute requests on the payment@vantage // server. PaymentResponse conf = conn.execute( req ); // Check the status of the execution. // Error codes are documented in the Payment@vantage Interface // Specification. // Additional error codes are generated by the PaymentPlugin. int status = conf.getExecutionStatus(); System.out.println( "Status for TransactionID " + conf.getTransactionID() + " = " + status );

// Finally close the PaymentConnection. // This will free all the resources allocated for this connection. conn.close(); } catch ( Exception ex ) { System.out.println( "Uncaught exception: " + ex.getLocalizedMessage() ); } System.exit( 0 ); }

g The start script is similar to that used in section 6.2.5 Example of a Recharge Request Using the Java Library PaymentPlugin.jar.

88 A50020-A3245-K-2-76D6


Id:0900d8058020b05e

Appendix

6.2.7 Example of an EJB Using the J2EE Connector Interface

Introduction This section gives an example of a simple EJB implementation that uses the J2EE con-nector interface of the Payment Plugin to send chargeAmount requests to the online charging server.

Example /* Copyright (c) Siemens AG 2000,2001,2002 All Rights Reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/

import javax.ejb.SessionContext;import javax.ejb.EJBException;import java.rmi.RemoteException;import javax.ejb.SessionBean;import javax.naming.*;import de.siemens.advantage.payment.payplugin.intf.connector.*;import de.siemens.advantage.payment.payplugin.impl.processing.ChargeAmountReq;import de.siemens.advantage.payment.payplugin.impl.processing.PaymentResponse;

public class ChargingBean implements SessionBean {

public ChargingBean() { System.out.println( "ChargingBean()" ); }

public void setSessionContext( SessionContext sc ) throws javax.ejb.EJBException, java.rmi.RemoteException { ctx = sc; }

public void ejbCreate() throws javax.ejb.EJBException, java.rmi.RemoteException { System.out.println("ChargingBean.ejbCreate()"); try { Context initCtx = new InitialContext(); Object obj = initCtx.lookup( "java:comp/env/eis/PaymentConnector"); factory = (PayAdvConnectionFactory) obj; }

catch ( Exception ex ) { System.err.println( ex ); throw new RemoteException( ex.getMessage() );

} }

public void ejbRemove() throws javax.ejb.EJBException, java.rmi.RemoteException { System.out.println("ChargingBean.ejbRemove()"); factory = null;

}

public void ejbActivate() throws javax.ejb.EJBException, java.rmi.RemoteException { System.out.println("ChargingBean.ejbActivate()");

}

public void ejbPassivate() throws javax.ejb.EJBException, java.rmi.RemoteException { System.out.println("ChargingBean.ejbPassivate()");

}

A50020-A3245-K-2-76D6

89


Id:0900d8058020b05e

public int charge( String tid, String userId, long accountId, String pin, String productId, String purpose, long amount ) throws java.rmi.RemoteException { // System.out.println("ChargingBean.charge()"); PayAdvConnection conn = null; ChargeAmountReq req = new ChargeAmountReq( tid, (short) 0, "Mr. Bean", "0815", "www.dummy.org", purpose, userId, accountId, pin, "merchant name", productId, "EUR", amount ); PaymentResponse resp = null; try { conn = factory.getConnection(); resp = conn.execute( req ); return resp.getExecutionStatus(); } catch ( Exception ex ) { System.err.println( "exception in charge: " + ex );

ex.printStackTrace(); throw new RemoteException( ex.getMessage() );

} finally { if ( conn != null ) { try { conn.close(); } catch (Exception ex) { System.err.println( "charge: Error while closing connection: " + ex ); ex.printStackTrace(); }

} } }

private SessionContext ctx; private PayAdvConnectionFactory factory;}

g Some of the attributes of the ChargeAmountReq instance are hardcoded for conve-nience.

90 A50020-A3245-K-2-76D6


Id:0900d80580208b4d

Index

Aabsolute date 22, 24accessFrontendID 20accountID 20accountList 20accountType 20additionalMoneyToAuthorize 20adviceOfCharge

operation 39adviceOfChargeConf

operation 40approved 20AuthorizationTimeoutClass 23, 25authorizeAmount

operation 31, 33

CcalculatedMoney 20captureAmount

operation 35certificate 12chargeAmount

operation 29clearingInstrument 21clearingPeriod 21clearingPolicy 21clearingThreshold 21confirmation 14confirmation message 14confirmation timeout 15currency 21currentAuthorizedAmount 21currentBalance 21

Ddata types 19date 22dateOfLastRecharge 21

EEIS 71enterprise information system 71error 22executionStatus 22expiry date 44expiryDate 22

values 43ExpiryDateOrDays 23, 25ExpiryMode 45

FfinalizeAuthorization 22firstRate 23

GgetConsumerAccountList

confirmation operation 59operation 57

HHTTP request 77HTTP response 77

Iinterface

external 14internal 14

internal timer 14

JJ2EE 70J2EE connector architecture 71Java 2 Enterprise Edition 70Java Secure Socket Extension (JSSE) 12JCA 71

LlastBalanceModDate 23

Mmanual

conventions 9purpose 7structure 8target group 7

mapping tableauthorizeAmount 31, 33captureAmount 35chargeAmount 29getAccountListConf 59getConsumerAccountList 57, 62rechargeAmount 42, 44refund 48simple confirmation 49transferAmount 37, 39, 40, 41

merchantID 23message sequence 14

A50020-A3245-K-2-76D6

91


Id:0900d80580208b4d

modeof AuthorizationTimeoutClass 23of ExpiryDateOrDays 23

money 23moneyToAuthorize 23

NnewExpiryDate 24, 43, 45

OoldExpiryDate 24online charging server 7, 11originalChargeTime 24originalPrice 24ownerID 24

Ppayment operation 16pin 24productID 24purpose 24purpose of the manual 7

RrechargeAmount

operation 42, 44rechargedMoney 24refund

operation 48refundTA

operation 41request 14response timeout 14RoleID 25routingInfo 25

Ssample property file 66Secure Sockets Layer (SSL) 12sequence of messages 14servlet application 17simple confirmation

operation 49SSL 12structure of manual 8styles used in manual 9symbols 9

Ttarget group

manual 7time span 22, 24

timeout 14timer

internal 14transactionID 25, 26transferAmount

operation 37transparentData 25

UuserID 25

Vvalue

of AuthorizationTimeoutClass 25of ExpiryDateOrDays 25

virtual account 44

NSN in CORBA Payment Plugin_Interface_new

Documents

Transcript of NSN in CORBA Payment Plugin_Interface_new