NSN in CORBA Payment Plugin - Interface - New

Development
Application Interface
DMN:Payment Plugin Interface

A50020-A3245-K-2-76D6
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 DOCUMENTATION OR FOR ANY DAMAGES, INCLUDING BUT NOT LIMITED TO SPECIAL, DIRECT, INDIRECT, 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
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 zwangslufig bestimmte Teile der Gerte unter Spannung. Einige Teile knnen auch eine hohe Betriebstemperatur aufweisen. Eine Nichtbeachtung dieser Situation und der Warnungshinweise kann zu Krperverletzungen und Sachschden fhren. 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 Gerte mssen die zutreffenden Sicherheitsbestimmungen erfllen.
Id:0900d80580208b4d
A50020-A3245-K-2-76D6
Table of Contents
This document has 91 pages. Change History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1 1.1 1.2 2 2.1 2.2 3 3.1 3.2 3.2.1 3.2.1.1 3.2.1.2 3.2.1.3 3.2.1.4 3.2.1.5 3.2.1.6 3.2.2 3.2.3 3.2.4 3.2.5 3.2.6 3.2.7 3.2.8 3.2.9 3.2.10 3.2.11 3.2.12 3.2.13 3.2.14 3.2.15 3.2.16 3.2.17 4 4.1 4.2 5 5.1 5.2 6 6.1 Introduction to the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Structure of this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 Conventions and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Overview of the Payment Plugin Interface . . . . . . . . . . . . . . . . . . . . . . . . . 10 Short Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 General Interface Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 HTTP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Payment Plugin Servlet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters for Payment Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters Used for the Payment Plugin Interface . . . . . . . . . . . . . . . . . . Usage of the transactionID / subcount Parameters . . . . . . . . . . . . . . . . . . Usage of the routingInfo and accountType Parameters . . . . . . . . . . . . . . . Usage of the ClusterName Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . Confirmation Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters for the chargeAmount Operation . . . . . . . . . . . . . . . . . . . . . . . Parameters for the authorizeAmount Operation . . . . . . . . . . . . . . . . . . . . . Parameters for the authorizeAmount1 Operation . . . . . . . . . . . . . . . . . . . . Parameters for the captureAmount Operation . . . . . . . . . . . . . . . . . . . . . . Parameters for the transferAmount Operation . . . . . . . . . . . . . . . . . . . . . . Parameters for the adviceOfCharge Operation . . . . . . . . . . . . . . . . . . . . . Parameters for the adviceOfChargeConf Confirmation Operation . . . . . . . Parameters for the refundTA Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters for the rechargeAmount Operation . . . . . . . . . . . . . . . . . . . . . Parameters for the rechargeAmount1 Operation . . . . . . . . . . . . . . . . . . . . Parameters for the rechargeAmountConf1 Confirmation Operation. . . . . . Parameters for the refund Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameters for the Simple Confirmation Operations . . . . . . . . . . . . . . . . . Parameters for the getConsumerAccountList Operation . . . . . . . . . . . . . . Parameters for the getAccountListConf Confirmation Operation . . . . . . . . Parameters for the getTAState Operation . . . . . . . . . . . . . . . . . . . . . . . . . 16 17 18 19 19 20 26 27 28 28 29 31 33 35 37 39 40 41 42 44 46 48 49 57 59 62
Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Typical Usage Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 Example of a Property File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 J2EE Connector Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 J2EE Connector Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Usage Scenario for the J2EE Connector Interface . . . . . . . . . . . . . . . . . . . 72 Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 Timeout Handling at the Client Side Using getTAState . . . . . . . . . . . . . . . 74
A50020-A3245-K-2-76D6
Id:0900d80580208b4d
6.2 6.2.1 6.2.2 6.2.3 6.2.4 6.2.5 6.2.6 6.2.7
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Format of a Recharge Request Using GET Syntax . . . . . . . . . . . . . . . . . . . 78 Format of a Recharge Request Using POST Syntax. . . . . . . . . . . . . . . . . . 78 Example of a Recharge Request Using HTTP GET in Java . . . . . . . . . . . . 79 Example of a Recharge Request Using HTTP GET in C++. . . . . . . . . . . . . 81 Example of a Recharge Request Using the Java Library PaymentPlugin.jar . 84 Example of a GetTAState Request Using the Java Library PaymentPlugin.jar 86 Example of an EJB Using the J2EE Connector Interface . . . . . . . . . . . . . . 88 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Id:0900d80580208b4d
A50020-A3245-K-2-76D6
Change History
Change History
Issue 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 J-2 K-1 K-2 Issue Date 2006/06/11 2007/07/20 2008/06/04 Reason for Update Parameter productID in captureAmount operation deleted. New software version. VisiBroker variant deleted. Values for error list added. Error information in rechargeAmount confirmations and getTAState behaviour changed.
A50020-A3245-K-2-76D6
Id:0900d8058020fe8a
Change History
Id:0900d8058020fe8a
A50020-A3245-K-2-76D6
Introduction to the Manual
1 Introduction to the Manual

Introduction 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. This manual is aimed at all those who want to know about and work with the Payment Plugin interface or parts of it. 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
Target group Related documentation
A50020-A3245-K-2-76D6
Id:0900d805801577da
1.1
Contents
Structure of this Manual

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.
Id:0900d805801577da
A50020-A3245-K-2-76D6
1.2
Conventions and Symbols

Designations, symbols and font styles used in this manual: Designations, symbols, fonts Italics Description 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].
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. 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.
A50020-A3245-K-2-76D6
Id:0900d805801577da
Overview of the Payment Plugin Interface
2 Overview of the Payment Plugin Interface

Introduction 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
10
Id:0900d805801577d1
A50020-A3245-K-2-76D6
2.1
Introduction
Short Description
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 communication via SSL. In general, the Payment Plugin is a client to the online charging server (Charging@vantage or charge@once). It provides a synchronous HTTP-based interface for a webbased 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.
Interfaces
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.
A50020-A3245-K-2-76D6
Id:0900d805801577d1
11
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-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. 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) is the most widely used protocol for secure internet communication. 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 functionality for data encryption, server authentication, message integrity, and optional client authentication.
Non-web-based solution
Secure communication Secure Sockets Layer (SSL)
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. 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. 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.
Administration of the SSL infrastructure
Initalization of the keys
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.
Related documentation
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.
12
Id:0900d805801577d1
A50020-A3245-K-2-76D6
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 encryption of messages.
A50020-A3245-K-2-76D6
Id:0900d805801577d1
13
2.2
Introduction Internal interface
General Interface Behavior

This section describes the general message sequences of the internal and external Payment Plugin interfaces. 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 completion it sends a confirmation message to the client which includes the result of the transaction. 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
14
Id:0900d805801577d1
A50020-A3245-K-2-76D6
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.
A50020-A3245-K-2-76D6
Id:0900d805801577d1
15
HTTP Interface
3 HTTP Interface
Introduction 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. 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.
Request and response
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 projectspecific 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
16
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.1
Introduction
Payment Plugin Servlet

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. 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. 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.
Servlet engine
HTTP interface
A50020-A3245-K-2-76D6
Id:0900d8058021019d
17
HTTP Interface
3.2
Introduction Contents
Parameters for Payment Operations

This section describes the data types and parameters as well as the parameter mapping scheme which is used for various payment operations. 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
18
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.1
Introduction Contents
Parameter Description
This section briefly describes the parameters which are used in the mapping tables in the following sections. 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
Introduction Data types
Data Types
This section describes the data types which are used in the mapping tables of the following sections. The following simple data types are used for the Payment Plugin interface: Data Type String<n> Short Int Long Byte Boolean Array of <n> characters. 2 byte integer. 4 byte integer. 8 byte integer. - 128 ... 127 Binary value (true or false) Description
A50020-A3245-K-2-76D6
Id:0900d8058021019d
19
HTTP Interface
3.2.1.2
Introduction
Parameters Used for the Payment Plugin Interface

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 access FrontendID Description 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 projectspecifically. The source account ID as parameter of the operation, which caused the entry in the transaction store. The loyalty accounts where the merchant is owner, or money accounts of the consumer. Empty if none of these exist. The account type of an account (prepaid etc.). The defined account types are listed in section 3.2.16 Parameters for the getAccountListConf Confirmation Operation. 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. calculatedMoney 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. Amount: see money parameter Currency: see money parameter 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.
accountID accountList accountType
additional MoneyTo Authorize
20
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
IDL Parameter clearing Instrument
Description 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. deprecated: Values should be ignored. Defines the clearing period in days of the month. Values should be ignored.
clearingPeriod
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). deprecated: Values should be ignored. The clearing policy for the account.
clearingPolicy
currency current Authorized Amount
Contains the currency of the account as a string (exactly 3 letters long); fixed to the local currency, e.g. EUR. 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. Amount: see money parameter Currency: see money parameter dateOfLast Recharge The date of the previously performed recharge. Also see the description of the newExpiryDate.
A50020-A3245-K-2-76D6
Id:0900d8058021019d
21
HTTP Interface
IDL Parameter error
Description 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. 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. 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.
execution Status expiryDate
finalize Authorization
Values are true or false. If true is set, the authorization is finalized.
22
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
IDL Parameter firstRate
Description The first rate of the total sum of money in case of payment in parts. This parameter consists of the parts Amount and Currency. Amount: see money parameter Currency: see money parameter
lastBalance ModDate merchantID
The date and time when the account balance was last modified. 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. 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 Authorization TimeoutClass)
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. Amount: see money parameter Currency: see money parameter
A50020-A3245-K-2-76D6
Id:0900d8058021019d
23
HTTP Interface
IDL Parameter
Description
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 ChargeTime 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 calculate 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. 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. The user identification of an account owner (string, length 3 to 30). The ownerID is an MSISDN or a merchant login. String for additional consumer identification (length 0 to 20). Normally, for consumers this will be the PPS PIN, otherwise empty. 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-specifically. 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 projectspecifically. Sum and currency of money to be recharged. This parameter comprises amount and currency. Amount: see money parameter Currency: see money parameter
originalPrice
ownerID pin productID
recharged Money
24
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
IDL Parameter roleID
Description Describes the possible role of a charging user (unsigned short). Consumer = 1 PSP = 3 Merchant = 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. 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.
transactionID
transparent Data userID
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). 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). See description of mode (type ExpiryDateOrDays_t).
value(type ExpiryDateOr Days_t) value(type Authorization TimeoutClass)
See description of mode (type AuthorizationTimeoutClass).
A50020-A3245-K-2-76D6
Id:0900d8058021019d
25
HTTP Interface
3.2.1.3
Introduction
Usage of the transactionID / subcount Parameters

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 transactionID is a sequence of exactly either 18 or 20 digits. Depending on the transactionID format, the subcount is part of the transactionID. 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.
Conventions
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. Format of transactionID The trailing 2 digits are optional and represent the transaction subcount (0..99) which allows to enumerate sub-parts of a long term transaction.
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 of transactionID 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 generation scheme 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.
26
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
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 subcount pairs 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
Routing information
Usage of the routingInfo and accountType Parameters

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. 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. The possible values for accountType are described in the following table: Value 0 1 2 unknown consumer prepaid account consumer postpaid account Account type
Handling of operations
Values
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.
A50020-A3245-K-2-76D6
Id:0900d8058021019d
27
HTTP Interface
3.2.1.5
Cluster selection
Usage of the ClusterName Parameter

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
Possible parameters
Confirmation 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.
Mandatory parameters Optional parameters
The parameters TransactionID and ExecutionStatus are always part of a confirmation. 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.
28
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.2
Introduction Parameters
Parameters for the chargeAmount Operation

The chargeAmount operation is used if immediate payment without separate authorization and reservation is requested. The following table shows the parameter mapping scheme for the chargeAmount operation. For a description of the parameters, refer to section 3.2.1 Parameter Description. Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId Attribute Type String<4+14> Short String<30> String<20> String<80> Example for Value 300000110077355864 4 (merchant) merchant login merchant PIN AFI_011
IDL Parameter Type TransactionID_t UserCredentials_t
IDL Parameter Name transactionID roleID userID pin
Access FrontendID_t AccountHandle_t
access FrontendID userID accountID pin
ConsumerId ConsumerAccountId ConsumerPIN MerchantId
String<30> Long String<20> String<30>
consumer MSISDN 0 consumer PIN merchant login (has to be identical to ReqCred.User.Id)
UserID_t
merchantID
ProductID_t PurposeOf Transaction_t Money_t
productID purpose
ProductId Purpose
String<40> String<200>
PREMIUM MMS Order no. 123
money
Money.Currency Money.Amount
String<3> Long String<100> Short String String with fixed value
EUR 560000 3 1 (prepaid consumer) c1 chargeAmount
RoutingInfo_t AccountType_t not available not available
routingInfo accountType not available not available
RoutingInfo AccountType ClusterName RequestType
Confirmation CORBA operations mapping
The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations). Depending on the setting of the routingInfo and accountType parameters, the request is mapped to the following CORBA operations: chargeAmount if routingInfo and accountType are not part of the request parameters chargeAmount1 if routingInfo and / or accountType are part of the request parameters
A50020-A3245-K-2-76D6
Id:0900d8058021019d
29
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.
30
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.3
Introduction
Parameters for the authorizeAmount Operation

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 Description. Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN Attribute Type String<4+14> Short String<30> String<20> String<80> String<30> Long String<20> String<20> Example for Value 300000110077355864 4 (ext. merchant) merchant login merchant PIN AFI_011 consumer MSISDN 0 consumer PIN merchant login (has to be identical to ReqCred.User.Id)
AccessFrontendID _t AccountHandle_t
access Fronten- AccessFrontendId dID userID accountID pin ConsumerId ConsumerAccountId ConsumerPIN MerchantId
UserID_t
merchantID
productID purpose moneyTo Authorize firstRate
ProductId Purpose Autho.Currency Autho.Amount Rate.Currency Rate.Amount
String<40> String<200> String<3> Long String<3> Long Byte
PREMIUM MMS Order no.003 EUR 5600000 EUR 120000 1 = classified 2 = absolute
Money_t
Authorization TimoutClass Authorization TimoutClass
mode
Mode
value
Value
Byte
for classified: 1 = short range 2 = medium range 3 = long range for absolute:1 .. 99 days
not available not available
ClusterName RequestType
String String with fixed value
c1 authorizeAmount
A50020-A3245-K-2-76D6
Id:0900d8058021019d
31
HTTP Interface
Confirmation
The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
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.
32
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.4
Introduction
Parameters for the authorizeAmount1 Operation

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 to authorizeAmount Parameters
The authorizeAmount1 operation uses a parameter set other than the authorizeAmount operation. The authorization timeout is specified in minutes instead of days. 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 Description. Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN Attribute Type String<4+14> Short String<30> String<20> String<80> String<30> Long String<20> String<100> Short String<20> Example for Value 300000110077355864 4 (external merchant) merchant login merchant PIN AFI_011 consumer MSISDN 0 consumer PIN 3 1 (prepaid consumer) merchant login (has to be identical to ReqCred.User.Id)
AccessFrontendID _t AccountHandle1_t
access Fronten- AccessFrontendId dID userID accountID pin routingInfo accountType ConsumerId ConsumerAccountId ConsumerPIN RoutingInfo AccountType MerchantId
UserID_t
merchantID
productID purpose moneyTo Authorize firstRate
ProductId Purpose Autho.Currency Autho.Amount Rate.Currency Rate.Amount
String<40> String<200> String<3> Long String<3> Long Byte
PREMIUM MMS Order no.003 EUR 5600000 EUR 120000 1 = not used 2 = not used 3 = minutes classified 4 = minutes absolute
Money_t
Authorization TimoutClass
mode
Mode
A50020-A3245-K-2-76D6
Id:0900d8058021019d
33
HTTP Interface
IDL Parameter Type Authorization TimoutClass
IDL Parameter Name value
Request Attribute Name Value
Attribute Type Long
Example for Value for classified: 1 = short range 2 = medium range 3 = long range for absolute:1 ... 142,560 minutes or 1 .. 99 days
c1 authorizeAmount1
Confirmation
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 attributes are optional. Please refer to section 3.2.1.5 Usage of
the ClusterName Parameter for further information.
34
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.5
Introduction
Parameters for the captureAmount Operation

The captureAmount operation is used if payment with separate authorization and reservation 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 operation. For a description of the parameters, refer to section 3.2.1 Parameter Description. Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId Attribute Type String<4+14+2> Short String<30> String<20> String<80> Example for Value refer to section 3.2.1 Parameter Description 4 (external merchant) merchant login merchant PIN AFI_011
Access FrontendID_t AccountHandle1_t
access FrontendID userID accountID pin routingInfo accountType
ConsumerId ConsumerAccountId ConsumerPIN RoutingInfo AccountType Purpose
String<30> Long String<20> String <100> Short String<200>
consumer MSISDN 0 consumer PIN 3 1 (prepaid consumer Order no. 0456
PurposeOf Transaction_t Money_t
purpose
money
String<3> Long String<5>
EUR 660000 true or false
boolean
finalize Authorization
Final
Money_t
additional MoneyTo Authorize
Add.Currency Add.Amount
String<3> Long
EUR 16000
c1 captureAmount
Confirmation
A50020-A3245-K-2-76D6
Id:0900d8058021019d
35
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 ClusterName Parameter for further information.
36
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.6
Parameters for the transferAmount Operation

The transferAmount operation is used if a general transfer of money between internal accounts, without any restrictions regarding the type of accounts, is requested. The following table shows the parameter mapping scheme for the transferAmount operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId
Attribute Type String<4+14> Short String<30> String<20> String<80>
Example for Value 300000110077355864 1 (consumer) consumer login consumer PIN AFI_011
SourceId SourceAccountId SourcePIN SourceRoutingInfo SourceAccountType TargetId TargetAccountId TargetPIN TargetRoutingInfo TargetAccountType MerchantId
String<30> Long String<20> String<100> Short String<30> Long String<20> String<100> Short String<20>
consumer MSISDN 0 source PIN 3 1 (prepaid consumer) login or MSISDN 0 target PIN 3 1 (prepaid consumer) merchant login has to be identical to ReqCred.UserId PREMIUM MMS Order no. 123
RoutingInfo_t AccountType_t AccountHandle_t
routingInfo accountType userID accountID pin
RoutingInfo_t AccountType_t UserID_t
routingInfo accountType merchantID
productID purpose
ProductId Purpose
money
String<3> Long String String with fixed value
EUR 560000 c1 transferAmount
Confirmation
A50020-A3245-K-2-76D6
Id:0900d8058021019d
37
HTTP Interface
CORBA operations mapping
Depending on the setting of the routingInfo, accountType, merchantID and productID parameters, the request is mapped to the following CORBA operations:

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.
38
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.7
Parameters for the adviceOfCharge Operation

The adviceOfCharge operation is used for price inquiry before service delivery. 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 Description.
Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId
Attribute Type String<4+14> Short String<30> String<20> String<80>
Example for Value 300000110077355864 4 (ext. merchant) merchant login merchant PIN AFI_011
ConsumerId ConsumerAccountId ConsumerPIN RoutingInfo AccountType MerchantId
String<30> Long String<20> String<100> Short String<20>
consumer MSISDN 0 consumer PIN 3 1 (prepaid consumer) merchant login (has to be identical to ReqCred.User.Id)
UserID_t
merchantID
productID purpose
ProductId Purpose
money
String<3> Long String String with fixed value
EUR 560000 c1 adviceOfCharge
Confirmation
The execution result is returned using the adviceOfChargeConf operation (refer to section 3.2.8 Parameters for the adviceOfChargeConf Confirmation Operation).
A50020-A3245-K-2-76D6
Id:0900d8058021019d
39
HTTP Interface
3.2.8
Introduction
Parameters for the adviceOfChargeConf Confirmation Operation

The confirmation operation for the adviceOfCharge operation containes the transactionID, executionStatus, transparentData, error, timeStampForRating and CalculatedMoney 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 Description. Request Attribute Name TransactionId ExecutionStatus Attribute Type String<4+14> Short Example for Value 300000110077355864 1 = successful refer to section 3.2.14 Parameters for the Simple Confirmation Operations for permitted values TransparentData CalculatedMoney. Currency CalculatedMoney. Amount String<500> String<3> Long 51 EUR 160000 (same precision as in the request) true {(8,1859,"SCP error")} 1036136490713 UNIX system time in milliseconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
Parameters
IDL Parameter Type TransactionID_t ExecutionStatus_t
IDL Parameter Name transactionID execution Status
TransparentData_t Money_t
transparent Data Calculated Money
ErrorList_t
error
ErrorList. noMoneyFlow ErrorList.list
Boolean String Long
Date_t
timeStamp ForRating
TimeStamp ForRating
Result values to return success 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 confirmation operations (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
Response: TransactionID=123456789012345678 TransparentData="" CalculatedMoney.Currency=EUR CalculatedMoney.Amount=9893 ErrorList.noMoneyFlow=true ErrorList.list={} TimeStampForRating=1084956846481 ExecutionStatus=1
Example
40
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.9
Parameters for the refundTA Operation

The refundTA operation is used to refund a successful transaction. 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 TransactionID_t
IDL Parameter Name transactionID
Request Attribute Name TransactionId
Attribute Type String<4+14>
Example for Value 300000110077355864 The ID for the transaction which is to be refunded. Differing 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.
UserCredentials_t
roleID userID pin
ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId
Short String<30> String<20> String<80>
4 (ext. merchant) merchant login merchant PIN AFI_011
ConsumerId ConsumerAccountId ConsumerPIN RoutingInfo AccountType Purpose
consumer MSISDN 0 consumer PIN 3 1 (prepaid consumer) Order no. 123
PurposeOf Transaction_t not available not available
purpose
c1 refundTA
Confirmation
A50020-A3245-K-2-76D6
Id:0900d8058021019d
41
HTTP Interface
3.2.10
Introduction Virtual accounts
Parameters for the rechargeAmount Operation

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 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 Description. IDL Parameter Name transactionID roleID userID pin Access FrontendID_t AccountHandle_t access FrontendID userID accountID pin PurposeOf Transaction_t Money_t money Money.Currency Money.Amount Date_t not available not available newExpiryDate not available not available ExpiryDate ClusterName RequestType String<3> Long Long String String with fixed value EUR 560000 see Values for ExpiryDate c1 rechargeAmount purpose ConsumerId ConsumerAccountId ConsumerPIN Purpose String<30> Long String<20> String<200> consumer MSISDN 0 consumer PIN Order no. 123 Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId Attribute Type String<4+14> Short String<30> String<20> String<80> Example for Value 300000110077355864 3 (PSP) PSP login "" AFI_011
Confirmation
42
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
Values for ExpiryDate
The following values may be specified for ExpiryDate: Value -1 0 date > 0 && < 2 years (365 * 2 * 24 * 60 * 60 * 1000) date > (current time 24 h) Description The date is not specified. It is calculated by the SCP/SEP. The date is not set, i. e. the expiration date is not changed. Delta mode: the expiration date is a time span in milliseconds which is limited up to 2 years. 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).
A50020-A3245-K-2-76D6
Id:0900d8058021019d
43
HTTP Interface
3.2.11
Introduction Virtual accounts Expiry date Parameters
Parameters for the rechargeAmount1 Operation

The rechargeAmount1 operation triggers a recharging transaction on the clearing server. Virtual accounts are recharged by the sum defined by the money parameter. The handling of the expiry date is specified by the parameters mode and value. 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 Description. IDL Parameter Name Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId Attribute Type String<4+14> Short String<30> String<20> String<80> Example for Value 300000110077355864 3 (PSP) PSP login "" AFI_011
transactionID roleID userID pin
ConsumerId ConsumerAccountId ConsumerPIN MerchantId
String<30> Long String<20> String<20>
consumer MSISDN 0 consumer PIN merchant login has to be identical to ReqCred.UserId PREMIUM MMS Order no. 123
UserID_t
merchantID
productID purpose
ProductId Purpose
money
String<3> Long byte
EUR 560000 1 = absolute setting 2 = relative setting 3 = default setting 4 = no setting For a description, please refer to Values for Expiry.Mode
ExpiryDateOrDays _t:Mode_t
mode
Expiry.Mode
ExpiryDateOrDays _t:Value_t RoutingInfo_t AccountType_t
value routingInfo accountType
Expiry.Value RoutingInfo AccountType
Long String<100> Short
90 3 1 (prepaid consumer)
44
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
IDL Parameter Type not available not available
IDL Parameter Name not available not available
Request Attribute Name ClusterName RequestType
Attribute Type String String with fixed value c1
Example for Value
rechargeAmount1
Confirmation
The execution result is returned using the rechargeAmountConf1 operation. The confirmation 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: rechargeAmount1 if routingInfo and accountType are not specified rechargeAmount2 if routingInfo and accountType are specified, but merchantID and productID are not specified rechargeAmount3 if routingInfo, accountType, merchantID and productID are specified 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.
CORBA operations mapping
Values for Expiry.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: Expiry. Mode 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. Description
A50020-A3245-K-2-76D6
Id:0900d8058021019d
45
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

The rechargeAmount1Conf confirmation operation contains the following 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 Name Request Attribute Name TransactionId ExecutionStatus Attribute Type String<4+14> Short Example for Value 300000110077355864 1 = successful refer to section 3.2.14 Parameters for the Simple Confirmation Operations for permitted values
transactionID executionStatus
TransparentData_t ErrorList_t
transparentData TransparentData error ErrorList.noMoneyFlow ErrorList.list
String<500> Boolean String String<30> Long String<20> String<3> Long
51 true {(8,1859,"SCP error")} consumer MSISDN 0 consumer PIN EUR 160000 (same precision as in the request) EUR 560000 (same precision as in the request) 1036136490713 UNIX system time in milliseconds since 1970 = Monday, July 09, 14:53:30 CEST 2001 Currently not supported, contains only default values.
AccountHandle_t
userID accountID pin
ConsumerId ConsumerAccountId ConsumerPIN RechargedMoney. Currency RechargedMoney. Amount
Money_t
recharged Money
Money_t
ID
CurrentBalance. Currency CurrentBalance. Amount
String<3> Long
Date_t
dateOfLast Recharge
DateOfLastRecharge
Long
46
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
IDL Parameter Type Date_t
IDL Parameter Name oldExpiryDate
Request Attribute Name OldExpiryDate
Attribute Type Long
Example for Value 1034458556121 UNIX system time in milliseconds since 1970 = Monday, July 09, 14:53:30 CEST 2001 1033619588825 UNIX system time in milliseconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
Date_t
newExpiryDate
NewExpiryDate
Long
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).
Response: TransactionID=300000110077355864 ExecutionStatus=1 TransparentData="51" ErrorList.noMoneyFlow=false ErrorList.list={} ConsumerId=cons_xyz ConsumerAccountId=0 ConsumerPIN=**** RechargedMoney.Currency=EUR RechargedMoney.Amount=55500000 CurrentBalance.Currency=EUR CurrentBalance.Amount=55510000 DateOfLastRecharge=0 OldExpiryDate=1034458556121 NewExpiryDate=1033619588825
Example
g In the case of an error, the list of attributes contains only default values.
A50020-A3245-K-2-76D6
Id:0900d8058021019d
47
HTTP Interface
3.2.13
Parameters for the refund Operation

The refund operation triggers a refund in the clearing server in order to undo a previous charge operation. 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 Name Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId Attribute Type String<4+14> Short String<30> String<20> String<80> Example for Value 300000110077355864 3 (PSP) PSP login "" AFI_011
transactionID roleID userID pin
ConsumerId ConsumerAccountId ConsumerPIN RoutingInfo AccountType MerchantId
consumer MSISDN 0 consumer PIN 3 1 (prepaid consumer) merchant login (has to be identical to ReqCred.User.Id)
UserID_t
merchantID
ProductID_t PurposeOf Transaction_t long long Date_t
productID purpose
ProductId Purpose
errorCause originalCharge Time
ErrorCause OriginalChargingTime
Long Long
13 994683210000 UNIX system time in milliseconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
Money_t
originalPrice
OriginalPrice.Currency String<3> OriginalPrice.Amount Long String String with fixed value
EUR 560000 c1 refund
Confirmation
48
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.14
Parameters for the Simple Confirmation Operations

The previously mentioned confirmation operations contain the transactionID, executionStatus, transparentData, CalculatedMoney and error 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.
Response Attribute Name "TransactionId" "ExecutionStatus" AttributeType String<4+14+2> Short Example for Value 300000110077355864 1 = successful refer to the following table for possible values
IDL Parameter Name transactionID executionStatus
TransparentData_t Money_t
transparentData CalculatedMoney
"TransparentData" "CalculatedMoney.Currency" "CalculatedMoney.Amount"
String<500> String<3> Long
"51" "EUR" 160,000 (same precision as in request)
ErrorList_t
error
"ErrorList.noMoneyFlow" "ErrorList.list"
Boolean String
true {(8,1859,"SCP error")}
Result values to return success 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: Result classification A B Execution Status Successful Limits violated ErrorList.noMoneyFlow Description
The transaction was executed successfully. The transaction was not executed successfully. The account limits are exceeded.
Failure
true
The transaction was not executed successfully. The account is not changed.
A50020-A3245-K-2-76D6
Id:0900d8058021019d
49
HTTP Interface
Result classification D
Execution Status Failure
ErrorList.noMoneyFlow false
Description
The transaction was not executed successfully. The account is possibly changed.
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:
Status Description Requested action
Execution status 1 2
Result classification A C
Successful Invalid account
The transaction is executed successfully. The account is invalid or unknown for the requested operation.
None The reason why the online charging server sends this execution status has to be analysed. 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.
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.
Limits violated
The limits, e.g., threshold values, of an account or any limits set by the software (hard-coded limits) are violated. The currency data table is not available from the Payment broker.
No repetition of the payment request.
Data not available
The reason why the online charging server sends this execution status has to be analysed. 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.
6 7
C D
Invalid user ID Internal error
The user with this ID is unknown to the system. The transaction is not completed because of an internal error. 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. Use getTAState to check the status of the transaction or check the tickets at the online charging server. The reason why the online charging server sends this execution status has to be analysed. 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.
Invalid transaction
50
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
Execution status 9
Result classification C
Status
Description
Requested action
Transaction already open
The transaction to be opened is already open.
The reason why the application sent a transactionID already in use has to be analysed. The appropriate action has to be taken atapplication side. Then it must be decided if the request has to be repeated with a new transactionID. Wait a couple of seconds and repeat the request.
10
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. This status is returned if a capture is tried and the authorized money is not sufficient. Either an incorrect currency is used (currency string is unknown to the system) or the requested amount of money is higher than the maximum allowed value (accounting component configuration parameter).
11
Authorization not available Invalid money
Authorize/capture is not a use case for Ferma VoMS. The reason why the online charging server sends this execution status has to be analysed. 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.
12
13
Invalid parameter
Wrong parameters or parameter values are used by the client that issues the request. The application is temporarily in a status where it cannot accept the current request due to overload protection. This status is returned if a capture is executed and an additional authorization is tried which is not granted. This status is returned if a feature is not supported for a specific set of users. E.g., loyalty point management is not supported for postpaid consumers. The external user repository, e.g., LDPA server, does not response to a location request. The account is stored on and the backend server does not answer the request, but no timeout happens. The account is stored on and the backend server does not answer the request, due to a timeout. Up to this value: All execution status codes are reserved for further extensions. Do not use any values between 1-9999 for any project specific extensions. Wait a couple of seconds and repeat the request. Authorize/capture is not a use case for Ferma VoMS. 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.
14
No resources
15
Authorization not possible Feature not supported
16
17
External ARS error
18
External AMS error
19
External AMS timeout maximum reserved
9999
Error cases
The following error cases are possible: Default values In 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
A50020-A3245-K-2-76D6
Id:0900d8058021019d
51
HTTP Interface
satisfy formal interface criteria, but do not make sense. Be sure to check the execution status before using the supplied data. Disaster recovery In 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 caused by Payment Plugin

Execution status -100 Result classification C
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.
Status Description Requested action
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 analysed. 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
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.
-102
Duplicate transaction 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. The transaction is not completed because of an internal error. There is a critical problem in CORBA communication. No requests can be sent to online charging server. The Payment Plugin was not able to process the request due to an overload situation. The user with this ID is unknown to the system. Use getTAState to check the status of the transaction or check the tickets at the online charging server. It is recommended that the Payment Plugin log file is evaluated by Nokia Siemens Networks staff. Wait a couple of seconds and repeat the request. The reason why the online charging server sends this execution status has to be analysed. 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.
-103
Confirmation timeout
-104
CORBA communication error Overload detected
-105
-106
Invalid user ID
-107
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.
52
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
Execution status -108
Status
Description
Requested action
Limits exceeded
The limits, e.g., threshold values, of an account or any limits set by the software (hard-coded limits) are violated. A timeout occured while the Payment Plugin is waiting for the online charging server to acknowledge the reception of the request. A temporary overload situation has been reported by the online charging server.
No repetition of the payment request.
-109
Response timeout
Use getTAState to check the status of the transaction or check the tickets at 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 ServerOverloadTimeout. Wait a couple of seconds and repeat the request. There is no automatic repetition by the Payment Plugin.
-110
No server resources
Result values caused by 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. Error Code -1 -2 -3 -4 -5 -6 -7 -8 -9 -10 -11 -12 -13 -14 -15 -16 -17 -18 Description Exception from online charging server when sending chargeAmount request Exception from online charging server when sending authorizeAmount request Exception from online charging server when sending captureAmount request Exception from online charging server when sending getVersion request Naming service not available CorbaObjectPool initialization error No online charging server available No ChargingBroker available NamingContext creation error NamingContext resolve error NamingContext not found Exception during the ChargingBroker creation Exception during refresh online charging server objects StoreResponse not possible because OrderMapEntry does not exist Exception from online charging server when sending transferAmount request Exception from ClearingServer when sending rechargeAmount request No ClearingServer available Exception during refresh ClearingServerObjects
A50020-A3245-K-2-76D6
Id:0900d8058021019d
53
HTTP Interface
Error Code -19 -20 -21 -22 -23 -24 -25 -26 -27 -28 -29 -30 -31 -32 No ClearingBroker available
Description
Exception during ClearingBroker creation Exception from online charging server when sending getTAState request Exception from online charging server when sending forgetTAState request CORBA "bad parameter" exception is thrown Invalid order map entry state when trying to store response Exception from AccountManagementServer when sending getConsumerAccountList request Exception from AccountManagementServer when sending getVersion request No AccountManagementServer available No AccountManagementBroker available Exception during refreshAccountManagementObjects Exception during AccountManagementBroker creation Unexpected exception from ClearingServer when sending refund request Unexpected exception from online charging server when sending adviceOfCharge request
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 caused by parameter validation errors
Execution status -200 Result classification C Request Type not valid Parameter or attribute not found Number Format error Without the request type the appropriate request object cannot be created with the given parameters. A parameter or attribute needed for the operation is not found in the http request. 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. A class cast exception occurred due to an invalid parameter value. Indicates that the number of elements in the attribute lists specifying the account handles is inconsistent.
1Specify
The following values are results from validation of request parameters at the HTTP interface, e.g., due to missing parameters or illegal parameter values:
Status
Description
Requested action
a valid request type.
-201
1Specify
the missing parameter or attribute.
-202
1Correct
the wrong parameter.
-203
Class Cast error
This plugin return code does not exist any more. It is only mentioned for completeness.
1Correct
-204
Account Handle Specification error
the account type.
54
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
Execution status -205
Status
Description
Requested action
Multiple user IDs error Multiple PINs error
Indicates that multiple values have been specified for the user IDs in the list of account handles. Indicates that multiple values have been specified for the PINs in the list of account handles. Indicates that multiple values have been specified for the routing information in the list of account handles. Indicates that multiple values have been specified for the account types in the list of account handles. Indicates that the cluster name specified in the request has not been configured.
1Correct
the userIDs.
-206
1Correct
the PINs.
-207
Multiple routing info error Multiple account types error Cluster name not found
This plugin return code does not exist any more. It is only mentioned for completeness.
1Correct
-208
the account types.
-230
1The
1Correct
the cluster name.
error was detected by the Payment Plugin. The request was not sent to the online charging server.
HTTP response format
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 OK Date: Wed, 03 Mar 2004 14:34:25 GMT Server: Apache/2.0.48 (Unix) mod_jk2/2.0.2 Content-Type: text/plain;charset=ISO-8859-1 Connection: close Response: TransactionID=300000110077355864 TransparentData="" CalculatedMoney.Currency=EUR CalculatedMoney.Amount=7688 ErrorList.noMoneyFlow=true ErrorList.list={} ExecutionStatus=1
Response in case of success
If the response was sucsessful, the syntax of the response is as follows:

HTTP/1.1 200 OK Date: Wed, 03 Mar 2004 14:34:25 GMT Server: Apache/2.0.48 (Unix) mod_jk2/2.0.2 Content-Type: text/plain;charset=ISO-8859-1 Connection: close Response: TransactionID=300000110077355865 ExecutionStatus=-104 TransparentData="" CalculatedMoney.Currency=EUR CalculatedMoney.Amount=7688 ErrorList.noMoneyFlow=true ErrorList.list={(111,-31," org.omg.CORBA.OBJECT_NOT_EXIST: minor code: 0 completed: No")}
Response in case of error
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 representative 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 OK Date: Wed, 03 Mar 2004 14:34:25 GMT
A50020-A3245-K-2-76D6
Id:0900d8058021019d
55
HTTP Interface
Server: Apache/2.0.48 (Unix) mod_jk2/2.0.2 Content-Type: text/plain;charset=ISO-8859-1 Connection: 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.
56
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.15
Parameters for the getConsumerAccountList Operation

This asynchronous getConsumerAccountList operation retrieves information about a list of user accounts. The following table shows the parameter mapping scheme for the getConsumerAccountList operation. For a description of the parameters, refer to section 3.2.1 Parameter Description. IDL Parameter Name transactionID roleID userID pin Request Attribute Name TransactionId ReqCred.Role ReqCred.UserId ReqCred.PIN AccessFrontendId Attribute Type String<4+14> Short String<30> String<20> String<80> Example for Value 300000110077355864 1 (consumer) consumer MSISDN PIN AFI_011
IDL Parameter Type
TransactionID_t UserCredentials_t
Access FrontendID_t AccountHandleList_t AccountHandleList_t AccountHandleList_t RoutingInfo_t AccountType_t not available not available
access FrontendID userID accountID pin routingInfo accountType not available not available
UserIdList AccountIdList PINList RoutingInfo AccountType ClusterName RequestType
each UserId is String<30> Long (list) String<20> String<100> Short String
consumer MSISDN a list of account IDs separated by commas PIN 3 1 (prepaid consumer) c1
String with fixed getConsumerAccounvalue tList
Confirmation CORBA operations mapping
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: getConsumerAccountList if routingInfo and accountType are not specified getConsumerAccountList1 if routingInfo and accountType are specified 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.
AccountHandleList data type
The AccountHandleList data type depends on whether the Java API or the HTTP interface is used: Java API If the Java API is used, the AccountHandleList is a data structure of type Array. The structure is composed of UserId, AccountId and PIN.
A50020-A3245-K-2-76D6
Id:0900d8058021019d
57
HTTP Interface
HTTP interface If the HTTP interface is used, the AccountHandleList is represented by three name/value pairs where the values are separated by commas.
AccountIdList="1"
Example 1: One account for one user Example 2: Three accounts for one user
TransactionId= "300000110077355864" UserIdList="Miller" PINList ="pin_5678" 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.
58
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
3.2.16
Parameters for the getAccountListConf Confirmation Operation

The confirmation operation for getConsumerAccountList contains the transactionID, executionStatus, transparentData and accountList 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. IDL Parameter Name Response Attribute Name TransactionId ExecutionStatus Attribute Type String<4+14> Short Example for Value 300000110077355864 1 refer to section 3.2.15 Parameters for the getConsumerAccountList Operation for possible values
transactionID executionStatus
TransparentData_t transparentData AccountList_t accountList
TransparentData Special representation for each list element described below
String<500>
51
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. 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 Name accountID Response Attribute Name AccountId. AccountType. Long Short Attribute Type Example for Value 1234567890 0 unknown 1 consumer prepaid 2 consumer postpaid 3 merchant sales 4 merchant fees 5 psp sales 6 psp merchant paid fees 7 psp consumer paid fees 8 loyalty account MSISDN or merchant login EUR
Record structure for Account_t IDL Parameter Type
AccountID_t
AccountType_t::Value_t accountType
UserID_t::Value_t Currency_t::Value_t boolean
ownerID currency approved
OwnerId. Currency. deprecated
A50020-A3245-K-2-76D6
Id:0900d8058021019d
59
HTTP Interface
IDL Parameter Type
IDL Parameter Name currentBalance current Authorized Amount clearing Instrument clearingPolicy clearingPeriod clearing Threshold lastBalance ModDate
Response Attribute Name Balance. AuthoAmount. deprecated deprecated deprecated deprecated BalModDate.
Attribute Type Long Long 50000 60000
Example for Value
Amount_t::Value_t Amount_t::Value_t PaymentInstrument_t ClearingPolicy_t short Amount_t::Value_t Date_t
Long
994683210000 = UNIX system time in milliseconds since 1970 = Monday, July 09, 14:53:30 CEST 2001 994683210000 = UNIX system time in milliseconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
Date_t
expiryDate
ExpiryDate.
Long
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 API If the Java API is used, the AccountList is a data structure of type Array. HTTP interface If 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.
60
Id:0900d8058021019d
A50020-A3245-K-2-76D6
HTTP Interface
Example for N = 2
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: close TransactionID = 300000110077355864 ExecutionStatus = 1 TransparentData = "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
depracated depracated depracated depracated
depracated
depracated depracated depracated depracated
g In the case of an error, the list of attributes contains only default values.
A50020-A3245-K-2-76D6
Id:0900d8058021019d
61
HTTP Interface
3.2.17
Parameters for the getTAState Operation

This synchronous operation returns transaction information for the given TransactionId. The type of the return value is TransactionStatus_t (enumeration type). 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 resolution, if multiple charging servers are connected to the Payment Plugin. However, the address resolution functionality has to be implemented project-specifically.
IDL Parameter Type TransactionID_t UserID_t
IDL Parameter Name transactionID userID
Request Attribute Name TransactionId UserId
Attribute Type String<4+14> String<30>
Example for Value 300000110077355864 MSISDN (has to be identical to the parameter ConsumerId in the original transaction) c1 getTAState
ClusterName Parameter for further information. 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).
62
Id:0900d8058021019d
A50020-A3245-K-2-76D6
Java API
4 Java API
Introduction 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 connections 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 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
g HTML documentation for all interface classes is included in the Payment Plugin
A50020-A3245-K-2-76D6
Id:0900d80580208e80
63
Java API
4.1
Introduction Interface usage scenario
Typical Usage Scenario

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. Proceed as follows: Step 1 Action 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( PaymentPlugin.getReference() ) 3 Obtain a reference to the PaymentConnectionFactory: PaymentConnectionFactory pcf = PaymentConnectionFactory.getReference(); If multiple online charging system clusters have been configured in the PaymentPlugin.properties file, a factory to a specific cluster may be aquired by: PaymentConnectionFactory pcf = PaymentConnectionFactory.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 arguments 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.
64
Id:0900d80580208e80
A50020-A3245-K-2-76D6
Java API
Step 6
Action Use the connection to execute requests on the online charging server. The connection may be reused for subsequent requests. If the client is multithreaded, 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.
Check the status of execution. Error codes are documented in section 3.2.14 Parameters for the Simple Confirmation Operations. int status = conf.getExecutionStatus();
Finally, close the PaymentConnection: conn.close(); This frees all resources allocated for this connection.
A50020-A3245-K-2-76D6
Id:0900d80580208e80
65
Java API
4.2
Introduction
Example of a Property File

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. The following table comprises a sample property file: Value corbaloc::zahlnix:2061/Name Service Cluster.0=c1,corbaloc::testserv1: 2061/NameService Cluster.1=c2,corbaloc::testserv2: 2061/NameService Comment The URL of the CORBA Name Service.Syntax: corbaloc::<IP-Addr>: <Port>/NameService A list of online charging system clusters to be accessed. The syntax is as follows: <logical name>, <URL of cluster specific CORBA NameService> If the interface.version.major property has a value less than 2, confirmation messages are compatible with earlier versions, i.e. do not contain transparent data. If the interface version is not set, the version defaults to 2.1. Defines the logging configuration to be used. The property value consists of the specification of a logging level (FATAL, ERROR, WARN, INFO, DEBUG) and a list of appenders. Please see the log4j documentation available at: http://jakarta.apache. org/log4j/docs/index.html
Property file Property name NameServiceUrl
Cluster.<unique number>
interface.version.major interface.version.minor
2 1
log4j.rootLogger
log4j.rootLogger=WARN, logfile, console
log4j.appender.logfile.File TransactionHostId
/opt/jakarta-tomcat4.1.29/logs/PaymentPlugin.log 4444
Absolute path of PaymentPlugin log file. ${java.io.tmpdir}/ PaymentPlugin.log HostId of the sender used as a prefix for the TransactionId if the string is not empty (maximum 4 digits).
66
Id:0900d80580208e80
A50020-A3245-K-2-76D6
Java API
Property name log4j.renderer.[Lde.siemens. advantage.payment.payplugin. impl.processing.Account; log4j.renderer.de.siemens. advantage.payment.payplugin. impl.processing. RechargeAmountResponse
Value de.siemens.advantage.payment. payplugin.impl.logging.Account ListRenderer de.siemens.advantage.payment. payplugin.impl.logging.Recharge AmountResponseRenderer
Comment Registration of object renderers Note: Values do not need to be changed.
de.siemens.advantage.payment. log4j.renderer.de.siemens. payplugin.impl.logging. Paymentadvantage.payment.payplugin. impl.processing.Payment- ResponseRenderer Response log4j.renderer.[Lde.siemens. advantage.payment.payplugin. impl.corba. AccountManagementTypes. Account_t; log4j.renderer.[Lorg.omg. CORBA.Policy; log4j.appender.console log4j.appender.console.layout log4j.appender.console. Threshold log4j.appender.console. layout.ConversionPattern log4j.appender.logfile de.siemens.advantage.payment. payplugin.impl.logging. Account_tListRenderer de.siemens.advantage.payment. payplugin.impl.logging. PolicyListRenderer org.apache.log4j. ConsoleAppender org.apache.log4j.PatternLayout ERROR %d %5p [%t] %x (%F:%L) - %m%n Definition of the output pattern of: the file name of the caller org.apache.log4j. RollingFileAppender 10MB the line number Note: Values do not need to be changed. Definition of console appender Note: Values do not need to be changed. 5 false Definition of the output pattern for the %d %5p [%t] %x (%F:%L) - %m%n logfiles Note: Values do not need to be changed. 30 000 Interval (in milliseconds) for sending getVersion calls to the online charging server for alive tests. Note: Value does not need to be changed. org.apache.log4j.PatternLayout Definition of number of logfiles to be kept Note: Values do not need to be changed. Definition of console appender Note: Values do not need to be changed.
log4j.appender.logfile. MaxFileSize log4j.appender.logfile. MaxBackupIndex log4j.appender.logfile.Append log4j.appender.logfile.layout log4j.appender.logfile.layout. ConversionPattern AliveTestInterval
A50020-A3245-K-2-76D6
Id:0900d80580208e80
67
Java API
Property name AliveTestTimeout 20 000
Value
Comment 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. Note: Value does not need to be changed.
NameServiceTimeout
20 000
Timeout value (in milliseconds) for NameService responses using the locations specified in NameServiceUrl. Note: Value does not need to be changed.
ResponseTimeout
20 000
Timeout value (in milliseconds) for the response from online charging server to a payment request. Note: Value does not need to be changed.
ConfirmationTimeout
30 000
Timeout value (in milliseconds) for callback from the online charging server for a previously sent payment request. Note: Value does not need to be changed.
CorbaObjectPoolRefreshInter- 300 000 val
Time interval (in milliseconds) for refreshing the CorbaObjectPool. Note: Value does not need to be changed.
MaxNumParallelReq
100
Maximum number of parallel requests for overload protection. Also controls the maximum number of concurrent instances of PaymentConnection. Note: Value does not need to be changed.
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. Note: Value does not need to be changed.
ChargingServerNamingContext 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. Note: Value must not be changed.
68
Id:0900d80580208e80
A50020-A3245-K-2-76D6
Java API
Property name ChargingBrokerNaming ContextPath
Value PaymentInterface/Broker
Comment Naming Context Path under which the CORBA ChargingBroker server object(s) can be found. Note: Value must not be changed.
ChargingBrokerName
ChargingBroker
Name of the ChargingBroker server object. Note: Value must not be changed.
ClearingServerNaming ContextPath
Naming Context Path under which the CORBA ClearingServer server objects can be found. Note: Value must not be changed.
ClearingServerClusterName
ClearingServer
Name of the ClearingServer server cluster. Note: Value must not be changed.
ClearingBrokerNaming ContextPath
PaymentInterface/Broker
Naming Context Path under which the CORBA ClearingBroker server object(s) can be found. Note: Value must not be changed.
ClearingBrokerName
ClearingBroker
Name of the ClearingBroker server object. Note: Value must not be changed.
AccountManagementServer NamingContextPath
Naming Context Path under which the CORBA AccountManagementServer server objects can be found. Note: Value must not be changed.
AccountManagementServer ClusterName
AccountManagementServer
Name of the AccountManagementServer server cluster. Note: Value must not be changed.
AccountManagementBroker NamingContextPath
PaymentInterface/Broker
Naming Context Path under which the CORBA AccountManagementBroker server object(s) can be found. Note: Value must not be changed.
AccountManagementBroker Name
AccountManagementBroker
Name of the AccountManagementBroker server object. Note: Value must not be changed.
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.
A50020-A3245-K-2-76D6
Id:0900d80580208e80
69
J2EE Connector Interface
5 J2EE Connector Interface

Introduction This chapter describes the Java 2 Enterprise Edition (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. 5.1 J2EE Connector Architecture 5.2 Usage Scenario for the J2EE Connector Interface
Contents
70
Id:0900d80580208e6b
A50020-A3245-K-2-76D6
5.1
Introduction J2EE connector architecture
J2EE Connector Architecture

This section describes the J2EE connector architecture (JCA) and the restrictions with regard to the use of this interface. The JCA defines a standard architecture for enabling J2EE components such as enterprise 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. 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 parameters. 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 different classes for connection factories and connections. The request classes are identical.
JCA specification and restrictions
A50020-A3245-K-2-76D6
Id:0900d80580208e6b
71
5.2
Introduction
Usage Scenario for the J2EE Connector Interface

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 connection factory has been bound to the Java Naming and Directory Interface (JNDI) name eis/PayAdvConnector. This section shows how to use this interface to send a charging request to the online charging server.
// import required packages and classes 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; ... // create initial context Context initCtx = new InitialContext(); // perform JNDI lookup // the naming context is specific to the application server PayAdvConnectionFactory factory = (PayAdvConnectionFactory) initCtx.lookup( "java:comp/env/eis/PayAdvConnector" ); // get a connection to the payment server PayAdvConnection conn = factory.getConnection(); // instantiate a request ChargeAmountReq req = new ChargeAmountReq( ... ); // execute the request PaymentResponse resp = conn.execute( req ); // evaluate the response System.out.println( "executed request, executionstatus = " +resp.getExecutionStatus() ); // finally close the connection to put it back to the pool conn.close();
Precondition Example
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.
72
Id:0900d80580208e6b
A50020-A3245-K-2-76D6
Appendix
6 Appendix
Introduction Contents This chapter contains a hint on how to handle timeouts and examples showing how to use the recharge request. 6.1 Timeout Handling at the Client Side Using getTAState 6.2 Examples
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
73
Appendix
6.1
Introduction Network problems
Timeout Handling at the Client Side Using getTAState

This section gives a hint on how to handle timeouts. 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 temporarily to be transmitted later. In the worst case, the message is completely lost. 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. The following figure shows the typical message flow:
Client application
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 ConfirmationTimeout (-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 getAccountTransactionList 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
74
Id:0900d8058020b05e
A50020-A3245-K-2-76D6
Appendix
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. Nevertheless, 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 projectspecifically. 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 getTAState request to check the status of the transaction. Depending on the received information 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 application 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 administer, if it does not receive confirmations from the online charging server. Transaction status values The following table specifies and explains the possible transaction status values: Transaction status values 0 = requested Comment Depending on the operation, this internal status means: - chargeRequested - authorizationRequested - captureRequested - rechargeRequested. Note: This status is an intermediate internal status with a short lifetime.
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
75
Appendix
Transaction status values 1 = processed The final status, if - the chargeAmount or - the final captureAmount or - the rechargeAmount
Comment
has been processed successfully by the online charging server. 2 = timeout 3 = failed 4 = expired 5 = authorized Not used. The transaction status value 3 (failed) is used instead. The confirmation contains an ExecutionStatus > 1 due to problems; e.g. authorization check failed, consumer is unknown, ... Not used. The transaction status value 3 (failed) is used instead. The internal status after a successful authorizeAmount.Any number of captureAmount requests may be received via the CORBA interface. In this case, the transaction status is changed to captureRequested. The internal status after a captureAmount has been received. Note: This status is an intermediate internal status with a short lifetime. Not used. The transaction status value 5 (authorized) is used instead.
6 = capture Requested
7 = partly Captured
The following error codes are sent if the getTAState request was unsuccessful: -101 = Invalid transaction -104 = CORBA communication error -105 = Overload detected -109 = Response Timeout -110 = No server resources The getTAState request has failed, because the transaction is not known by the online charging server The getTAState request has failed, because there is a problem in the CORBA communication between the Payment Plugin and the online charging server. The getTAState request has failed due to a temporary overload situation in the online charging server. There was no response from the online charging server to the getTAState request. The getTAState request has failed due to a temporary overload situation reported by the online charging server.
76
Id:0900d8058020b05e
A50020-A3245-K-2-76D6
Appendix
6.2
Introduction
Examples
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 recommended 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: Status Code 200 204 400 401 403 404 500 501 503 The request has succeeded. The server has fulfilled the request, but there is no new information to send back. The request could not be understood by the server due to invalid syntax. The request requires user authentication. The server understood the request, but is refusing to fulfill it. The server has not found anything matching the request URL. The server encountered an unexpected condition which prevented it from fulfilling the request. The server does not support the functionality required to fulfill the request. The server is currently unable to handle the request due to temporary overloading or maintenance of the server. Description
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 URLencoded 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
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
77
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.6 Example of a GetTAState Request Using the Java Library PaymentPlugin.jar 6.2.7 Example of an EJB Using the J2EE Connector Interface
6.2.1
Introduction Syntax
Format of a Recharge Request Using GET Syntax

This section describes the format of a recharge request using the GET syntax.
GET/PaymentPlugin/servlet/PaymentPluginServlet?TransactionId=300000110077355864 &ReqCred.Role=3&ReqCred.UserId=PSPLogin&ReqCred.PIN=8888&AccessFrontendId=JSUNI COM&ConsumerId=8613072506800&ConsumerAccountId=0&ConsumerPIN=1234&Purpose=cashin+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

Introduction Syntax
Format of a Recharge Request Using POST Syntax

This section describes the format of a recharge request using the POST 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>
78
Id:0900d8058020b05e
A50020-A3245-K-2-76D6
Appendix
6.2.3
Introduction Example
Example of a Recharge Request Using HTTP GET in Java

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.
/* 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 {
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
79
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.
80
Id:0900d8058020b05e
A50020-A3245-K-2-76D6
Appendix
6.2.4
Introduction
Example of a Recharge Request Using HTTP GET in C++

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.
/* 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 #include #include #include #include #include #include #include #include #include #include <iostream.h> <strstream.h> <sys/types.h> <sys/socket.h> <arpa/inet.h> <netdb.h> <unistd.h> <errno.h> <string.h> <stdlib.h> <limits.h>
Example
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 */
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
81
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];
82
Id:0900d8058020b05e
A50020-A3245-K-2-76D6
Appendix
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; }
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
83
Appendix
6.2.5
Introduction
Example of a Recharge Request Using the Java Library PaymentPlugin.jar

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 client application
/* 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 import import import import de.siemens.advantage.payment.payplugin.impl.processing.*; de.siemens.advantage.payment.payplugin.impl.corba.Common.*; de.siemens.advantage.payment.payplugin.impl.PluginProperties; org.apache.log4j.Logger; 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();
84
Id:0900d8058020b05e
A50020-A3245-K-2-76D6
Appendix
// // // // // //
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 simple startup script
f In order to run the application make sure the CORBA runtime environment is set up
correctly.
#! /bin/bash JAVA_HOME=/usr/java1.4.2 JVM=${JAVA_HOME}/bin/java JACORB_HOME=/opt/INTPaqasp/lib JACORB_LIBS=${JACORB_HOME}/lib/jacorb.jar:${JACORB_HOME}/lib/logkit.jar:${JACORB_HOME}/lib/avalon-framework.jar LOG4J=/opt/INTPaqasp/lib/log4j-1.2.8.jar PLUGIN_JAR=/opt/INTPaqasp/lib/PaymentPlugin.jar LOCAL_CLASSPATH=".:${PLUGIN_JAR}:${LOG4J}" exec ${JVM} ${JVM_FLAGS} \ -classpath "${LOCAL_CLASSPATH}" \
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
85
Appendix
-Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB \ -Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton \ APIRecharge $1
6.2.6
Introduction Example
Example of a GetTAState Request Using the Java Library PaymentPlugin.jar

The example code in this section shows an implementation of a simple client executing a GetTAState request using the Java API.
/* 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 import import import import import
de.siemens.advantage.payment.payplugin.impl.processing.*; de.siemens.advantage.payment.payplugin.impl.corba.Common.*; de.siemens.advantage.payment.payplugin.impl.PluginProperties; de.siemens.advantage.payment.payplugin.impl.sim.servlet.RequestBuilder; org.apache.log4j.Category; 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
86
Id:0900d8058020b05e
A50020-A3245-K-2-76D6
Appendix
// // // //
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.
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
87
Appendix
6.2.7
Introduction
Example of an EJB Using the J2EE Connector Interface

This section gives an example of a simple EJB implementation that uses the J2EE connector interface of the Payment Plugin to send chargeAmount requests to the online charging server.
/* 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 import import import import import import import javax.ejb.SessionContext; javax.ejb.EJBException; java.rmi.RemoteException; javax.ejb.SessionBean; javax.naming.*; de.siemens.advantage.payment.payplugin.intf.connector.*; de.siemens.advantage.payment.payplugin.impl.processing.ChargeAmountReq; de.siemens.advantage.payment.payplugin.impl.processing.PaymentResponse;
Example
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()"); }
88
Id:0900d8058020b05e
A50020-A3245-K-2-76D6
Appendix
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 convenience.
A50020-A3245-K-2-76D6
Id:0900d8058020b05e
89
Index
A
absolute date 22, 24 accessFrontendID 20 accountID 20 accountList 20 accountType 20 additionalMoneyToAuthorize 20 adviceOfCharge operation 39 adviceOfChargeConf operation 40 approved 20 AuthorizationTimeoutClass 23, 25 authorizeAmount operation 31, 33
F
finalizeAuthorization 22 firstRate 23
G
getConsumerAccountList confirmation operation 59 operation 57
H
HTTP request 77 HTTP response 77
I
interface external 14 internal 14 internal timer 14
C
calculatedMoney 20 captureAmount operation 35 certificate 12 chargeAmount operation 29 clearingInstrument 21 clearingPeriod 21 clearingPolicy 21 clearingThreshold 21 confirmation 14 confirmation message 14 confirmation timeout 15 currency 21 currentAuthorizedAmount 21 currentBalance 21
J
J2EE 70 J2EE connector architecture 71 Java 2 Enterprise Edition 70 Java Secure Socket Extension (JSSE) 12 JCA 71
L
lastBalanceModDate 23
M
manual conventions 9 purpose 7 structure 8 target group 7 mapping table authorizeAmount 31, 33 captureAmount 35 chargeAmount 29 getAccountListConf 59 getConsumerAccountList 57, 62 rechargeAmount 42, 44 refund 48 simple confirmation 49 transferAmount 37, 39, 40, 41 merchantID 23 message sequence 14
D
data types 19 date 22 dateOfLastRecharge 21
E
EIS 71 enterprise information system 71 error 22 executionStatus 22 expiry date 44 expiryDate 22 values 43 ExpiryDateOrDays 23, 25 ExpiryMode 45
90
Id:0900d80580208b4d
A50020-A3245-K-2-76D6
mode of AuthorizationTimeoutClass 23 of ExpiryDateOrDays 23 money 23 moneyToAuthorize 23
N
newExpiryDate 24, 43, 45
timeout 14 timer internal 14 transactionID 25, 26 transferAmount operation 37 transparentData 25
U
userID 25
O
oldExpiryDate 24 online charging server 7, 11 originalChargeTime 24 originalPrice 24 ownerID 24
V
value of AuthorizationTimeoutClass 25 of ExpiryDateOrDays 25 virtual account 44
P
payment operation 16 pin 24 productID 24 purpose 24 purpose of the manual 7
R
rechargeAmount operation 42, 44 rechargedMoney 24 refund operation 48 refundTA operation 41 request 14 response timeout 14 RoleID 25 routingInfo 25
S
sample property file 66 Secure Sockets Layer (SSL) 12 sequence of messages 14 servlet application 17 simple confirmation operation 49 SSL 12 structure of manual 8 styles used in manual 9 symbols 9
T
target group manual 7 time span 22, 24
A50020-A3245-K-2-76D6
Id:0900d80580208b4d
91

NSN in CORBA Payment Plugin - Interface - New

Încărcat de

Informații document

Descriere originală:

Titlu original

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

NSN in CORBA Payment Plugin - Interface - New

Încărcat de

Drepturi de autor:

Formate disponibile

Development

DMN:Payment Plugin Interface

DMN:Payment Plugin Interface

Important Notice on Product Safety

DMN:Payment Plugin Interface

DMN:Payment Plugin Interface

6.2 6.2.1 6.2.2 6.2.3 6.2.4 6.2.5 6.2.6 6.2.7

DMN:Payment Plugin Interface

DMN:Payment Plugin Interface

DMN:Payment Plugin Interface

Introduction to the Manual

1 Introduction to the Manual

Target group Related documentation

Introduction to the Manual

DMN:Payment Plugin Interface

Structure of this Manual

DMN:Payment Plugin Interface

Introduction to the Manual

Conventions and Symbols

Overview of the Payment Plugin Interface

DMN:Payment Plugin Interface

2 Overview of the Payment Plugin Interface

DMN:Payment Plugin Interface

Overview of the Payment Plugin Interface

Overview of the Payment Plugin Interface

DMN:Payment Plugin Interface

Secure communication Secure Sockets Layer (SSL)

Public key certificates

Administration of the SSL infrastructure

Initalization of the keys

DMN:Payment Plugin Interface

Overview of the Payment Plugin Interface

g Using secure communication reduces the communication throughput, because

Overview of the Payment Plugin Interface

DMN:Payment Plugin Interface

General Interface Behavior

DMN:Payment Plugin Interface

Overview of the Payment Plugin Interface

DMN:Payment Plugin Interface

Request and response

DMN:Payment Plugin Interface

Payment Plugin Servlet

DMN:Payment Plugin Interface

Parameters for Payment Operations

DMN:Payment Plugin Interface

DMN:Payment Plugin Interface

Parameters Used for the Payment Plugin Interface

accountID accountList accountType

additional MoneyTo Authorize

DMN:Payment Plugin Interface

IDL Parameter clearing Instrument

currency current Authorized Amount

DMN:Payment Plugin Interface

IDL Parameter error

execution Status expiryDate

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

DMN:Payment Plugin Interface

IDL Parameter firstRate

lastBalance ModDate merchantID

mode(type Authorization TimeoutClass)

mode(type ExpiryDateOr Days_t)

DMN:Payment Plugin Interface