Date post: | 02-Oct-2014 |
Category: |
Documents |
Upload: | roaringarrow |
View: | 164 times |
Download: | 1 times |
DevelopmentApplication Interface
DMN:Payment Plugin Interface
A50020-A3245-K-2-76D6
2 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d80580208b4d
The information in this document is subject to change without notice and describes only the product defined in the introduction of this documentation. This documentation is intended for the use of Nokia Siemens Networks customers only for the purposes of the agreement under which the document is submitted, and no part of it may be used, reproduced, modified or transmitted in any form or means without the prior written permission of Nokia Siemens Networks. The documentation has been prepared to be used by professional and properly trained personnel, and the customer assumes full responsibility when using it. Nokia Siemens Networks welcomes customer comments as part of the process of continuous development and improvement of the documentation.
The information or statements given in this documentation concerning the suitability, capacity, or performance of the mentioned hardware or software products are given "as is" and all liability arising in connection with such hardware or software products shall be defined conclusively and finally in a separate agreement between Nokia Siemens Networks and the customer. However, Nokia Siemens Networks has made all reasonable efforts to ensure that the instructions contained in the document are adequate and free of material errors and omissions. Nokia Siemens Networks will, if deemed necessary by Nokia Siemens Networks, explain issues which may not be covered by the document.
Nokia Siemens Networks will correct errors in this documentation as soon as possible. IN NO EVENT WILL Nokia Siemens Networks BE LIABLE FOR ERRORS IN THIS DOCUMENTA-TION OR FOR ANY DAMAGES, INCLUDING BUT NOT LIMITED TO SPECIAL, DIRECT, INDI-RECT, INCIDENTAL OR CONSEQUENTIAL OR ANY LOSSES, SUCH AS BUT NOT LIMITED TO LOSS OF PROFIT, REVENUE, BUSINESS INTERRUPTION, BUSINESS OPPORTUNITY OR DATA,THAT MAY ARISE FROM THE USE OF THIS DOCUMENT OR THE INFORMATION IN IT.
This documentation and the product it describes are considered protected by copyrights and other intellectual property rights according to the applicable laws.
The wave logo is a trademark of Nokia Siemens Networks Oy. Nokia is a registered trademark of Nokia Corporation. Siemens is a registered trademark of Siemens AG.
Other product names mentioned in this document may be trademarks of their respective owners, and they are mentioned for identification purposes only.
Copyright © Nokia Siemens Networks 2008. All rights reserved
f Important Notice on Product Safety Elevated voltages are inevitably present at specific points in this electrical equipment. Some of the parts may also have elevated operating temperatures.
Non-observance of these conditions and the safety instructions can result in personal injury or in property damage.
Therefore, only trained and qualified personnel may install and maintain the system.
The system complies with the standard EN 60950 / IEC 60950. All equipment connected has to comply with the applicable safety standards.
The same text in German:
Wichtiger Hinweis zur Produktsicherheit
In elektrischen Anlagen stehen zwangsläufig bestimmte Teile der Geräte unter Span-nung. Einige Teile können auch eine hohe Betriebstemperatur aufweisen.
Eine Nichtbeachtung dieser Situation und der Warnungshinweise kann zu Körperverlet-zungen und Sachschäden führen.
Deshalb wird vorausgesetzt, dass nur geschultes und qualifiziertes Personal die Anlagen installiert und wartet.
Das System entspricht den Anforderungen der EN 60950 / IEC 60950. Angeschlossene Geräte müssen die zutreffenden Sicherheitsbestimmungen erfüllen.
A50020-A3245-K-2-76D6
3
DMN:Payment Plugin Interface
Id:0900d80580208b4d
Table of ContentsThis document has 91 pages.
Change History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1 Introduction to the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.1 Structure of this Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.2 Conventions and Symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2 Overview of the Payment Plugin Interface . . . . . . . . . . . . . . . . . . . . . . . . . 102.1 Short Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2 General Interface Behavior . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
3 HTTP Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.1 Payment Plugin Servlet. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.2 Parameters for Payment Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183.2.1 Parameter Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.2.1.1 Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.2.1.2 Parameters Used for the Payment Plugin Interface . . . . . . . . . . . . . . . . . . 203.2.1.3 Usage of the transactionID / subcount Parameters . . . . . . . . . . . . . . . . . . 263.2.1.4 Usage of the routingInfo and accountType Parameters . . . . . . . . . . . . . . . 273.2.1.5 Usage of the ClusterName Parameter . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.1.6 Confirmation Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283.2.2 Parameters for the chargeAmount Operation . . . . . . . . . . . . . . . . . . . . . . . 293.2.3 Parameters for the authorizeAmount Operation . . . . . . . . . . . . . . . . . . . . . 313.2.4 Parameters for the authorizeAmount1 Operation . . . . . . . . . . . . . . . . . . . . 333.2.5 Parameters for the captureAmount Operation . . . . . . . . . . . . . . . . . . . . . . 353.2.6 Parameters for the transferAmount Operation . . . . . . . . . . . . . . . . . . . . . . 373.2.7 Parameters for the adviceOfCharge Operation . . . . . . . . . . . . . . . . . . . . . 393.2.8 Parameters for the adviceOfChargeConf Confirmation Operation . . . . . . . 403.2.9 Parameters for the refundTA Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.2.10 Parameters for the rechargeAmount Operation . . . . . . . . . . . . . . . . . . . . . 423.2.11 Parameters for the rechargeAmount1 Operation . . . . . . . . . . . . . . . . . . . . 443.2.12 Parameters for the rechargeAmountConf1 Confirmation Operation. . . . . . 463.2.13 Parameters for the refund Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.2.14 Parameters for the Simple Confirmation Operations . . . . . . . . . . . . . . . . . 493.2.15 Parameters for the getConsumerAccountList Operation . . . . . . . . . . . . . . 573.2.16 Parameters for the getAccountListConf Confirmation Operation . . . . . . . . 593.2.17 Parameters for the getTAState Operation . . . . . . . . . . . . . . . . . . . . . . . . . 62
4 Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634.1 Typical Usage Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644.2 Example of a Property File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5 J2EE Connector Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 705.1 J2EE Connector Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715.2 Usage Scenario for the J2EE Connector Interface . . . . . . . . . . . . . . . . . . . 72
6 Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736.1 Timeout Handling at the Client Side Using getTAState . . . . . . . . . . . . . . . 74
4 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d80580208b4d
6.2 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776.2.1 Format of a Recharge Request Using GET Syntax . . . . . . . . . . . . . . . . . . . 786.2.2 Format of a Recharge Request Using POST Syntax. . . . . . . . . . . . . . . . . . 786.2.3 Example of a Recharge Request Using HTTP GET in Java . . . . . . . . . . . . 796.2.4 Example of a Recharge Request Using HTTP GET in C++. . . . . . . . . . . . . 816.2.5 Example of a Recharge Request Using the Java Library PaymentPlugin.jar .
846.2.6 Example of a GetTAState Request Using the Java Library PaymentPlugin.jar
866.2.7 Example of an EJB Using the J2EE Connector Interface . . . . . . . . . . . . . . 88
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
A50020-A3245-K-2-76D6
5
DMN:Payment Plugin Interface Change History
Id:0900d8058020fe8a
Change HistoryIssue K-2
The following listing details the modifications to this manual as compared to the previous edition.
Parameters for the adviceOfChargeConf Confirmation Operation (3.2.8)
– Parameter ErrorList_t changed, examples for the parameter added.
Parameters for the rechargeAmountConf1 Confirmation Operation (3.2.12)
– Parameter ErrorList_t changed, examples for the parameter added. Parameter DateOfLastRecharge default- no longer supported.
Parameters for the getConsumerAccountList Operation (3.2.15)
– For a parameter UserCredentials_t value loginname changed into MSISDN.
Issue History
Issue Number
Issue Date Reason for Update
J-2 2006/06/11 Parameter productID in captureAmount operation deleted.
K-1 2007/07/20 New software version. VisiBroker variant deleted. Values for error list added.
K-2 2008/06/04 Error information in rechargeAmount confirmations and getTAState behaviour changed.
6 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020fe8a
Change History
A50020-A3245-K-2-76D6
7
DMN:Payment Plugin Interface Introduction to the Manual
Id:0900d805801577da
1 Introduction to the ManualIntroduction This manual describes the syntax of the Payment Plugin interfaces of Nokia Siemens
Networks charge@once V1.1 / Nokia Siemens Networks Charging@vantage V2.2.
The application server can use three methods to pass CORBA calls via the payment communication layer to the online charging server (Charging@vantage or charge@once):
• For J2EE servers, the J2EE connector interface may be used. • For web-based applications (HTTP), the Payment Plugin servlet may be used. • For non-web-based applications, the Payment Plugin library has to be loaded to the
application.
All these interfaces are functionally equivalent. To enable secure communication for the Payment Plugin interfaces it is possible to use the Secure Sockets Layer (SSL) protocol.
The behaviour of the CORBA charging service triggered by the Payment Plugin is project-specific.
Purpose Presents the information required in addition to general Charging@vantage / charge@once knowledge in order to understand and administrate the Payment Plugin interface.
Target group This manual is aimed at all those who want to know about and work with the Payment Plugin interface or parts of it.
Relateddocumentation
Please refer to the “Documentation Overview” for more detailed information on the operating documentation of the product.
The installation and configuration of the Payment Plugin are described in the manual “ADMN:Payment Plugin Installation and Configuration”.
Contents 1.1 Structure of this Manual
1.2 Conventions and Symbols
8 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d805801577da
Introduction to the Manual
1.1 Structure of this Manual
Contents This manual contains the following chapters:
1 Introduction to the Manual
This chapter describes some basics for working with this manual.
2 Overview of the Payment Plugin Interface
This chapter provides a brief introduction to the Payment Plugin interface and depicts its structure. It describes the behavior of internal and external interfaces.
3 HTTP Interface
This chapter describes the Payment Plugin interface for web-based applications. The main request/response methods of the Payment Plugin servlet are described in brief. The following chapters comprise parameter mapping tables to be used for various payment operations.
4 Java API
This chapter describes the Payment Plugin interface for non-web-based applications.
5 J2EE Connector Interface
This chapter describes the J2EE connector interface as a standard architecture for enabling J2EE components to interact with enterprise information systems (EIS). An example is used to describe how to use this interface.
6 Appendix
This chapter provides hints about the handling of timeouts and it describes the format of a recharge request using the GET and the POST syntax, and shows some examples of recharge requests.
7 "Index"
This chapter contains a list of keywords.
A50020-A3245-K-2-76D6
9
DMN:Payment Plugin Interface Introduction to the Manual
Id:0900d805801577da
1.2 Conventions and SymbolsDesignations, symbols and font styles used in this manual:
Designations, symbols, fonts
Description
Italics Used for – emphasis– software and hardware items– filenames, pathnames– interface items, such as names of windows, menus and
menu items, dialog boxes, field names, etc.
Example: Enter the value in the Parameter field.
Courier Used for – commands and characters to be typed into a user interface– scripts and system output.
Example: Type annoC017 in the Parameter field.
Boldface Used to mark keywords within the text.
Example: This is especially important!
Square brackets [ ] Used for keyboard shortcuts and command buttons.
Examples: Close the application with [Alt] + [F4].Acknowledge this message by clicking on [OK].
g Indicates supplementary information on the current topic. This supplementary information may be useful tips on operation, explanations, the description of master conditions or similar information.
f Indicates a warning. If the instructions given are not observed, errors or data loss can occur. To avoid errors, always observe all the instructions following a warning.
10 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d805801577d1
Overview of the Payment Plugin Interface
2 Overview of the Payment Plugin InterfaceIntroduction This chapter describes the Payment Plugin interface. The Payment Plugin consists of
different external interfaces and an internal interface. Only the external interfaces are described in this document.
Furthermore, it describes the general interface behavior and the possibility to enable secure communication for the Payment Plugin interfaces using the SSL (Secure Sockets Layer) protocol.
Contents 2.1 Short Description
2.2 General Interface Behavior
A50020-A3245-K-2-76D6
11
DMN:Payment Plugin Interface Overview of the Payment Plugin Interface
Id:0900d805801577d1
2.1 Short Description
Introduction This section describes the available external interfaces of the Payment Plugin and three possibilities of using the Payment Plugin. It also describes the possibility of secure com-munication via SSL.
Interfaces In general, the Payment Plugin is a client to the online charging server (Charging@van-tage or charge@once). It provides a synchronous HTTP-based interface for a web-based application and allows this application to send requests to the online charging server. The plugin handles the CORBA communication with the online charging server.
In addition, the Payment Plugin provides a Java-based API. This makes it possible to connect a non-web-based client to the online charging server in an easy manner.
The Java 2 Enterprise Edition (J2EE) connector interface allows for the deployment of the Payment Plugin to J2EE compliant servers.
Structure The following figure shows how the Payment Plugin can be used in order to connect different kinds of applications to the online charging server.
J2EE solution A Java 2 Enterprise Edition (J2EE) connector interface supports a standard architecture for connecting the J2EE platform to the online charging server, e.g. Charging@vantage. This interface is described in chapter 5 J2EE Connector Interface.
12 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d805801577d1
Overview of the Payment Plugin Interface
Web-based solution The HTTP client has to provide all the parameter values which are required in the IDL interface specification as name/value pairs. These name/value pairs (GET or POST requests) from web-based applications are mapped to CORBA parameters for the call at the Payment Plugin interface. Result values are also coded in this way. The parameter names are described in chapter 3 HTTP Interface.
Non-web-basedsolution
Non-web-based applications have to use the PaymentRequest classes of the Payment Plugin Java library to pass the parameters of the request to the CORBA calls. The usage of PaymentResponse classes enables the access to response parameters. Further information is given in chapter 4 Java API.
Securecommunication
It is possible to enable secure communication for the Payment Plugin interfaces using the SSL protocol. The Payment Plugin supports SSL for the IIOP communication to the online charging server and at the external HTTP interface.
Secure Sockets Layer(SSL)
Secure Sockets Layer (SSL) is the most widely used protocol for secure internet com-munication. SSL provides a secure enhancement to the standard Transport Control Protocol (TCP) running as a layer between TCP and application layer protocols, such as IIOP and HTTP.
The SSL implementation is provided by the Java Secure Socket Extension (JSSE), which has been integrated into the J2SDK version 1.4.2. It provides a framework and an implementation for a Java version of the SSL and TLS protocols and includes function-ality for data encryption, server authentication, message integrity, and optional client authentication.
Public key certificates SSL relies on public key certificates in the standard X.509 format. These certificates are presented in the authentication phase of the SSL handshake and used to compute and exchange session keys.
Administration of theSSL infrastructure
The Payment Plugin does not provide any tools or interfaces to administer the infrastructure (keystores and truststores) necessary for SSL, e.g. generate key pairs, import/export of certificates, define trusted certificate authorities or ensure availability of valid certificates. This has to be done by the network operator with the help of external commands provided by the SSL implementation, e.g the keytool command of the J2SDK.
Initalization of the keys The keystores are only read once on startup. As a result switching from unsecure to secure communication and vice versa requires a restart of the Payment Plugin. Likewise the Payment Plugin has to be restarted when new certificates are to be used.
Thus, using SSL is a matter of Payment Plugin configuration, which has to be extended to take additional properties into account.
Global properties SSL properties are global, i.e they take effect for all online charging servers to be connected and include the following parameters:
• An indicator whether SSL communication is optional or mandatory. • The location of the keystore. • The password to open the keystore and access its keys.
Relateddocumentation
For additional information on the maintenance of the SSL infrastructure refer to the “ADMN:Payment Plugin Installation and Configuration” manual.
Installation and configuration of SSL support on Tomcat is described in the Tomcat documentation.
A50020-A3245-K-2-76D6
13
DMN:Payment Plugin Interface Overview of the Payment Plugin Interface
Id:0900d805801577d1
Enabling SSL at the HTTP interface is only a matter of Tomcat configuration and is therefore completely transparent to the Payment Plugin.
g Using secure communication reduces the communication throughput, because connection setup takes a bit longer due to additional messages exchanged in the SSL handshake and because of the computing overhead for decryption and encryp-tion of messages.
14 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d805801577d1
Overview of the Payment Plugin Interface
2.2 General Interface Behavior
Introduction This section describes the general message sequences of the internal and external Payment Plugin interfaces.
Internal interface The internal interface between the PaymentPlugin and the online charging server is an asynchronous message-based CORBA interface.
When the online charging server receives a request, it immediately sends back an acknowledgement for the reception and starts processing the transaction. After comple-tion it sends a confirmation message to the client which includes the result of the trans-action. The client in turn acknowledges that it has received this message.The sequence of these messages for a chargeAmount() request is shown in the following figure:
External interfaces The external interfaces of the Payment Plugin provide synchronous method calls for these operations.
To prevent infinite blocking of the interface method calls two timeouts are implemented:
After sending a request the Payment Plugin starts an internal timer and waits for the acknowledgement from the online charging server. If the timer expires before the acknowledgement is received, an error of type Response Timed Out is reported to the client and the request context is released. Otherwise a second timer is started while the Payment Plugin is waiting for the confirmation. Again, if no confirmation is received
A50020-A3245-K-2-76D6
15
DMN:Payment Plugin Interface Overview of the Payment Plugin Interface
Id:0900d805801577d1
within the specified time, a Confirmation Timed Out error is returned and the request is terminated.
Since the confirmation timeout is started no sooner than the response has been received, the maximum response time of the Payment Plugin to its clients is the sum of the parameters ResponseTimeout and ConfirmationTimout.
16 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3 HTTP InterfaceIntroduction This chapter describes the Payment Plugin interface for web-based (servlet)
applications. The main request/response methods of the Payment Plugin servlet are described briefly. The following sections comprise parameter mapping tables to be used for various payment operations.
Request and response The web-server-based application provides a parameter list of name/value pairs (HttpServletRequest from javax.servlet.http) for the payment request. Each pair is mapped to a parameter belonging to the online charging server. The response is returned as plain text.
g Values and ranges of parameters are not checked by the Payment Plugin interface. Constraints concerning values and ranges are described in section 3.2.1 Parameter Description. Additional parameter constraints may be imposed by the project-specific IP charging service.
The Payment Plugin interface provides synchronous request / response behaviour. The asynchronous behaviour of the CORBA layer is hidden.
Contents 3.1 Payment Plugin Servlet
3.2 Parameters for Payment Operations
A50020-A3245-K-2-76D6
17
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.1 Payment Plugin Servlet
Introduction This section describes the Payment Plugin servlet. Servlets are designed to work within a request/response processing model. The plugin servlet is a Java component plugged into a Java-enabled web server to enhance its functionality.
Servlet engine The servlet runs on the web server platform as part of the servlet engine. The servlet engine on the web server is responsible for initializing, invoking and destroying each servlet instance.
HTTP interface The plugin servlet provides a synchronous HTTP interface for payment requests. POST requests are mapped to CORBA calls at the online charging server Payment Execution Point (PEP) interface. The client of the plugin servlet, e.g. the HTTP client, has to provide all the parameter values which are required in the IDL interface specification as name-value pairs. Result values are also coded in this way, but in a free format not encoded as in a standard application/x-form-urlencoded manner. For an example see HTTP response in section 3.2.14 Parameters for the Simple Confirmation Operations.
18 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2 Parameters for Payment Operations
Introduction This section describes the data types and parameters as well as the parameter mapping scheme which is used for various payment operations.
Contents 3.2.1 Parameter Description
3.2.2 Parameters for the chargeAmount Operation
3.2.3 Parameters for the authorizeAmount Operation
3.2.4 Parameters for the authorizeAmount1 Operation
3.2.5 Parameters for the captureAmount Operation
3.2.6 Parameters for the transferAmount Operation
3.2.7 Parameters for the adviceOfCharge Operation
3.2.8 Parameters for the adviceOfChargeConf Confirmation Operation
3.2.9 Parameters for the refundTA Operation
3.2.10 Parameters for the rechargeAmount Operation
3.2.11 Parameters for the rechargeAmount1 Operation
3.2.12 Parameters for the rechargeAmountConf1 Confirmation Operation
3.2.13 Parameters for the refund Operation
3.2.14 Parameters for the Simple Confirmation Operations
3.2.15 Parameters for the getConsumerAccountList Operation
3.2.16 Parameters for the getAccountListConf Confirmation Operation
3.2.17 Parameters for the getTAState Operation
A50020-A3245-K-2-76D6
19
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.1 Parameter Description
Introduction This section briefly describes the parameters which are used in the mapping tables in the following sections.
Contents 3.2.1.1 Data Types
3.2.1.2 Parameters Used for the Payment Plugin Interface
3.2.1.3 Usage of the transactionID / subcount Parameters
3.2.1.4 Usage of the routingInfo and accountType Parameters
3.2.1.5 Usage of the ClusterName Parameter
3.2.1.6 Confirmation Parameters
3.2.1.1 Data Types
Introduction This section describes the data types which are used in the mapping tables of the following sections.
Data types The following simple data types are used for the Payment Plugin interface:
Data Type Description
String<n> Array of <n> characters.
Short 2 byte integer.
Int 4 byte integer.
Long 8 byte integer.
Byte - 128 ... 127
Boolean Binary value (true or false)
20 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2.1.2 Parameters Used for the Payment Plugin Interface
Introduction This section describes the parameters used for the Payment Plugin interface. These parameters are used in the mapping tables of the following sections:
IDL Parameter Description
access Fron-tendID
Values of this type describe the access frontend, which was used in a specific transaction (free form, length 0..80). Together with the UserID this is a valuable source of information for customer care and statistics. The value store of this parameter has to be defined project-specifically.
accountID The source account ID as parameter of the operation, which caused the entry in the transaction store.
accountList The loyalty accounts where the merchant is owner, or money accounts of the consumer. Empty if none of these exist.
accountType The account type of an account (prepaid etc.). The defined account types are listed in section 3.2.16 Parameters for the getAccountList-Conf Confirmation Operation.
additional MoneyTo Authorize
If finalizeAuthorization is false, the currently authorized sum of money can be increased by this value. The currencies of money and moneytoAuthorize must be the same. If finalizeAuthorization is true, the value of this parameter is ignored.
The additionalMoneyToAuthorize parameter comprises amount and currency.
Amount: see money parameter
Currency: see money parameter
approved deprecated: Values should be ignored.
When the account is not approved the user has a specific lower account balance limit which may not be passed. The parameter is only relevant for merchant and postpaid consumer accounts.
Values can be true or false.
calculated-Money
Sum and currency of money contained in the confirmation message (e.g. charged money). This amount is either calculated by means of the parameters received with the server request (if rating is performed) or is just the same value as the money parameter provided with the charging request.
In case an authorization takes place (authorizeAmount or captureAmount), this will be the authorized amount (not the captured amount).
This parameter comprises Amount and Currency.
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.
A50020-A3245-K-2-76D6
21
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
clearing Instru-ment
deprecated: Values should be ignored.
The identification of the associated clearing instrument of the account. This is one of the clearing instruments contained in the user profile.
clearingPeriod deprecated: Values should be ignored.
Defines the clearing period in days of the month. Values should be ignored.
clearing Threshold
deprecated: Values should be ignored.
The threshold for clearing an account. If the threshold is passed, the clearing is triggered. This parameter is only relevant if the clearingPolicy is set to 3 (= threshold).
clearingPolicy deprecated: Values should be ignored.
The clearing policy for the account.
currency Contains the currency of the account as a string (exactly 3 letters long); fixed to the local currency, e.g. EUR.
current Autho-rized Amount
The currently reserved sum in the account. The parameter is only relevant for consumer accounts.
currentBalance Current balance of the account. This parameter consists of the parts Amount and Currency.
Amount: see money parameter
Currency: see money parameter
dateOfLast Recharge
The date of the previously performed recharge.
Also see the description of the newExpiryDate.
IDL Parameter Description
22 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
error Indicates whether or not any account balance has been changed and lists any error occured during processing on the online charging server.
This parameter consists of the parts noMoneyFlow and list.
noMoneyFlow: Indicates whether money has definitively not been moved, i.e. no money was added or deducted from an account. If this parameter is set to false, money is transfered from/to any account and a manual recover (e.g. by means of tickets) may be necessary. In case of timeout situations the value of this flag is undefined.
list: An entry in the error list contains the ID of the unit/component which reports the error, the internal error ID from this unit/component and an additional description. If the error list is empty, the request is successfully executed.
For reported errors the following IDs are possible:
1 = Account management component (ACM)2 = Address resolution component (ADR)3 = CORBA charging service (CCS)4 = CORBA interface component (ECI)5 = User session managment component (PUS)6 = Transaction management component (TAM)7 = Request routing component (SRR)8 = Account accessing component (AAC)9 = SCP online interface (ONL)111 = Payment Plugin
For the IDs 1 to 9 the error location is the online charging server.
errorCause This parameter contains the error code the client associates with the refund. It is provided by the merchant application for statistical or bookkeeping purposes and to allow a (clearing server external) rating engine to calculate the amount to be granted in case no money is given.
execution Status
Confirmation parameter, which contains the result of the requested operation. The possible return codes are listed in section 3.2.14 Parameters for the Simple Confirmation Operations.
expiryDate Expiration date of the account. Only relevant for consumer accounts.
An absolute date is specified by the number of elapsed milliseconds since midnight, January 1, 1970 UTC.A time span is specified as the number of milliseconds to be added to the current time. The maximum time span is limited to 2 years.The possible values are described in section 3.2.10 Parameters for the rechargeAmount Operation.
finalize Autho-rization
Values are true or false. If true is set, the authorization is finalized.
IDL Parameter Description
A50020-A3245-K-2-76D6
23
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
firstRate The first rate of the total sum of money in case of payment in parts. This parameter consists of the parts Amount and Currency.
Amount: see money parameter
Currency: see money parameter
lastBalance ModDate
The date and time when the account balance was last modified.
merchantID The login name of the merchant for this operation (string, length 1 to 20). The merchantID may only contain printable ASCII characters and must contain at least one non-digit character. It is used for identification of the target account.
mode(type Authorization TimeoutClass)
Describes the timeout for authorization of money. There are two ways of specifying the timeout:
Classified: One of three (timeout) classes can be chosen. System constants preset the timeout in days for each of the classes.
Absolute: The timeout can be specified in days (1 to 99) or minutes (1..142560). Stepping is 1 day/minute.
The possible values are described in section 3.2.3 Parameters for the authorizeAmount Operation.
mode(type ExpiryDateOr Days_t)
Describes the absolute expiration date or the relative number of days until an expiration date which are added to an existing expiration date. There are four ways of specifying this parameter which are described in section 3.2.11 Parameters for the rechargeAmount1 Operation.
The minimum value is 1, the maximum value is 5 * 365.
money Sum and currency of money to be transferred. The currency of money must be the same as the currency in which the authorization was made. The money parameter comprises Amount and Currency.
Amount: the sum of money (-10E18+1 ... +10E18-1). The maximum number of digits is 18 (without decimal point). The default number of fractional digits is 5.
Currency: currency of the money to be transferred (string, exactly 3 letters long); fixed to the local currency, e.g. EUR.
Example: Money.Currency = EUR and Money.Amount = 560000 means EUR 5,60
moneyTo Authorize
Sum and currency of money to be transferred. Any subsequent parameter of this request or follow-on request within this transaction context has to have the same currency. This parameter comprises Amount and Currency.
Amount: see money parameter
Currency: see money parameter
IDL Parameter Description
24 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
newExpiryDate The expiration date after the recharge operation to which the rechargeAmountConf confirmation belongs.
An absolute date is specified by the number of elapsed milliseconds since midnight, January 1, 1970 UTC.A time span is specified as the number of milliseconds to be added to the current time. The maximum time span is limited to 2 years.The possible values are described in section 3.2.10 Parameters for the rechargeAmount Operation.
oldExpiryDate The expiration date before the recharge operation to which the rechargeAmountConf confirmation belongs.
Also see the description of the newExpiryDate.
original Char-geTime
The time at which the operation that caused this refund took place. It is provided by the merchant application for statistical or stockkeeping purposes. It allows a (clearing server external) rating engine to cal-culate the amount to be granted in the case no money is given. This parameter is optional. If the parameter is not to be used, a zero value must be passed.
originalPrice The money that was originally charged with the operation that causes this refund. It is provided by the merchant application for statistical or stockkeeping purposes. It allows a (clearing server external) rating engine to calculate the amount to be granted in case no money is given.
ownerID The user identification of an account owner (string, length 3 to 30). The ownerID is an MSISDN or a merchant login.
pin String for additional consumer identification (length 0 to 20). Normally, for consumers this will be the PPS PIN, otherwise empty.
productID The class of the product (good, service, etc.) a merchant offers. A productID could be, e.g. CD AUDIO JAZZ or CD SW OFFICE. It could also be a part number for ordering the product or similar.
productID is a free format string (length 40) defined by the merchant application and is used for statistical evaluation.The value store of this parameter has to be defined project-specifi-cally.
purpose Describes the purpose of a specific charging transaction. It is a free format string (length 0 .. 200), which has to be interpreted by the client applications.The value store of this parameter has to be defined project-specifically.
recharged Money
Sum and currency of money to be recharged. This parameter comprises amount and currency.
Amount: see money parameter
Currency: see money parameter
IDL Parameter Description
A50020-A3245-K-2-76D6
25
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
roleID Describes the possible role of a charging user (unsigned short).
Consumer = 1PSP = 3Merchant = 4
routingInfo This parameter (length 0 ... 100) is used by the server to route requests to a specific account handling system. If the value of parameter routingInfo is an empty string and the parameter accountType is set to 0, the online charging server does not reject the request, but automatically tries to resolve the location of the account.
transactionID Represents the unique ID to identify a transaction context over the interface. It is defined by the initiator of a transaction.
For details refer to section 3.2.1.3 Usage of the transactionID / subcount Parameters.
transparent Data
Confirmation parameter which is used to send project-specific defined information back to the client. The default value is an empty free-format string (length 0..80).
userID The identification of a user. For a merchant, this is a string (length 1..20, one must be a nondigit). For consumers, this is the MSISDN (length 3 to 20, all digits).
value(type ExpiryDateOr Days_t)
See description of mode (type ExpiryDateOrDays_t).
value(type Authorization TimeoutClass)
See description of mode (type AuthorizationTimeoutClass).
IDL Parameter Description
26 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2.1.3 Usage of the transactionID / subcount Parameters
Introduction The transactionID is a unique ID generated by the client system and used to identify each specific charging operation performed by the online charging system. A transac-tionID is a sequence of exactly either 18 or 20 digits. Depending on the transactionID format, the subcount is part of the transactionID.
Conventions The uniqueness of transactionIDs in a distributed installation of brokers and servers is achieved by the following conventions: • The 4 leading digits are the hostid, which is a uniquely administered ID of the brokers
or servers in the scope of the installation. These digits may be used for load control and default transactionID mapping. The value 1000 is reservedf or internal use and should not be selected.
• The 14 following digits are a continuously growing integer (i.e. one by one) starting (at least) with 0, which has to be generated and administered by the client.
g This restriction has been lifted. The leading 18 characters need not be digits but may be arbitrary ASCII characters. It is still strongly recommended to use the scheme described, since uniqueness among all transaction IDs must still be provided for by the clients.
• The trailing 2 digits are optional and represent the transaction subcount (0..99) which allows to enumerate sub-parts of a long term transaction.
Format oftransactionID
The online charging system supports two formats of the transactionID parameter:
• The original 18 digit format:– Is used for all calls which trigger simple transactions (chargeAmount,
transferAmount, rechargeAmount) and for authorizeAmount.– Is used optionally for captureAmount.– All 18 digits are significant for checking the uniqueness of a transaction.
The HostId can be defined in the property file of the Payment Plugin.In that case, the Payment Plugin automatically prefixes all transactionIDs created by the client with that HostId. If the HostId is not defined, the total 18 digits are filled with this counter.
• The 20 digit format, which extends the original transactionID by a subcount:– Is used optionally for captureAmount.– All 20 bytes are used for checking uniqueness of a transaction.– The first 18 digits are used for selecting the transaction context. The structure is
the same as described for the 18 digit format of the transactionID.– The last 2 digits (subcount) will be checked on constantly growing with wrap
around (see details later).
In case of captureAmount, the two formats are available simultaneously.
Uniqueness check oftransactionID
If a client uses the 18 digit format, the uniqueness check is performed as described for the original format of the transactionID.
If the client wants to use the subcount, it can use the 20 digit format and use the uniqueness check as described for the new format of the transactionID.
Subcount generationscheme and check
The following generation scheme will be applied to generate a subcount and to check the validity of a subcount during an authorize/capture transaction:
• The subcount (SUBC) runs from 00..99. • The first value of an SUBC must be out of 0..2.
A50020-A3245-K-2-76D6
27
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
• If the SUBC reaches the value 99, the SUBC wraps around and starts from 0 again. • The maximum gap between SUBC values for captureN and captureN+1 must not
exceed two: 0 < (SUBCN+1 - SUBCN) <= 2 or 0 < (SUBCN+1 + 100 - SUBCN) <= 2
The gap is greater than zero to allow losing of single requests in a routed network due to timeouts.
The server checks the subcount according to this generation scheme. If this scheme is violated, an InvalidTransaction exception is thrown by the server. This InvalidTransaction exception does not terminate the authorisation. A subsequent capture using the same TransactionID and a valid subcount will be successful.
Examples of subcountpairs
Examples of pairs of consequent subcounts are: • Valid: { 0, 1 }, { 0, 2 }, { 97, 99 }, { 99, 0 }, { 99, 1 } • Invalid: { 0, 4 }, { 47, 62 }, { 47, 46 }, { 97, 1 }, { 99, 3 }
3.2.1.4 Usage of the routingInfo and accountType Parameters
Routing information routingInfo and accountType are parameters. If the location and type of the subscriber's account are known to the client application, it is possible to bypass the address resolution function in the online charging server. This is done by providing the necessary routing information in the request.
Handling of operations The CORBA interface of the online charging server offers separate versions of operations, with and without routing and account type information. At the HTTP interface the Payment Plugin transparently calls the correct operation depending on the setting of these parameters. At the J2EE Connector interface and the Java API the user of the Payment Plugin has to select the operation with the appropriate set of arguments.
Values The possible values for accountType are described in the following table:
g If the value of routingInfo is an empty string and if the value of accountType is 0, the online charging system automatically tries to resolve the location/type of the target account. In a standard online charging system configuration setting routingInfo should always be set to ““ and accountType should be set to 0.
Value Account type
0 unknown
1 consumer prepaid account
2 consumer postpaid account
28 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2.1.5 Usage of the ClusterName Parameter
Cluster selection ClusterName is an optional parameter. As described in section 2.1 Short Description, it is possible to connect the Payment Plugin to more than one online charging system cluster. When using the HTTP interface the cluster name may be specified in the list of request parameters. For all other interfaces the cluster name has to be provided before sending requests to the online charging server.
For all other interfaces the cluster selection has to be done in the application code, see 4 Java API.
3.2.1.6 Confirmation Parameters
Possible parameters Execution of requests will be reported by confirmations which contain the following parameters: • TransactionID • ExecutionStatus • TransparentData • CalculatedMoney • ErrorList
These parameters are described in section 3.2.1.2 Parameters Used for the Payment Plugin Interface. A complete list of values for ExecutionStatus is presented in section 3.2.14 Parameters for the Simple Confirmation Operations.
Mandatoryparameters
The parameters TransactionID and ExecutionStatus are always part of a confirmation.
Optional parameters The presence of the remaining parameters depends on the interface version defined in the Payment Plugin configuration file:
– If the interface version is greater or equal to 2.0 confirmations aditionally contain the TransparentData parameter.
– If the interface version is greater than or equal to 2.1 there will also be the parameters CalculatedMoney and ErrorList in addition to all the parameters mentioned before.
A50020-A3245-K-2-76D6
29
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.2 Parameters for the chargeAmount Operation
Introduction The chargeAmount operation is used if immediate payment without separate authoriza-tion and reservation is requested.
Parameters The following table shows the parameter mapping scheme for the chargeAmount oper-ation. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Confirmation The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
CORBA operationsmapping
Depending on the setting of the routingInfo and accountType parameters, the request is mapped to the following CORBA operations:
• chargeAmountif routingInfo and accountType are not part of the request parameters
• chargeAmount1if routingInfo and / or accountType are part of the request parameters
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
4 (merchant)
merchant login
merchant PIN
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandle_t userID
accountID
pin
ConsumerId
ConsumerAccountId
ConsumerPIN
String<30>
Long
String<20>
consumer MSISDN
0
consumer PIN
UserID_t merchantID MerchantId String<30> merchant login
(has to be identical to ReqCred.User.Id)
ProductID_t productID ProductId String<40> PREMIUM MMS
PurposeOf
Transaction_t
purpose Purpose String<200> Order no. 123
Money_t money Money.Currency
Money.Amount
String<3>
Long
EUR
560000
RoutingInfo_t routingInfo RoutingInfo String<100> 3
AccountType_t accountType AccountType Short 1 (prepaid consumer)
not available not available ClusterName String c1
not available not available RequestType String with fixed value
chargeAmount
30 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
g The RoutingInfo, AccountType and ClusterName attributes are optional. Please refer to sections 3.2.1.4 Usage of the routingInfo and accountType Parameters and 3.2.1.5 Usage of the ClusterName Parameter for further information.
g If the account type and the account location are not known, RoutingInfo is left empty and AccountType is set to 0. Using chargeAmount without RoutingInfo and AccountType is deprecated.
A50020-A3245-K-2-76D6
31
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.3 Parameters for the authorizeAmount Operation
Introduction The authorizeAmount operation is used if deferred payment or payment in parts is requested. This operation comprises following transactions:
• Authorizing and reserving a sum of money. • Executing the first rate for payment in parts.
Parameters The following table shows the parameter mapping scheme for the authorizeAmount operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
4 (ext. merchant)
merchant login
merchant PIN
AccessFrontendID_t
access Fronten-dID
AccessFrontendId String<80> AFI_011
AccountHandle_t userID
accountID
pin
ConsumerId
ConsumerAccountId
ConsumerPIN
String<30>
Long
String<20>
consumer MSISDN
0
consumer PIN
UserID_t merchantID MerchantId String<20> merchant login
(has to be identical to ReqCred.User.Id)
ProductID_t productID ProductId String<40> PREMIUM MMS
PurposeOf Transaction_t
purpose Purpose String<200> Order no.003
Money_t moneyTo Authorize
Autho.Currency
Autho.Amount
String<3>
Long
EUR
5600000
Money_t firstRate Rate.Currency
Rate.Amount
String<3>
Long
EUR
120000
Authorization TimoutClass
mode Mode Byte 1 = classified
2 = absolute
Authorization TimoutClass
value Value Byte for classified:
1 = short range
2 = medium range
3 = long range
for absolute:1 .. 99 days
not available not available ClusterName String c1
not available not available RequestType String with fixed value
authorizeAmount
32 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
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.
A50020-A3245-K-2-76D6
33
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.4 Parameters for the authorizeAmount1 Operation
Introduction The authorizeAmount1 operation is used if deferred payment or payment in parts is requested. This operation comprises the following transactions:
• Authorizing and reserving a sum of money. • Executing the first rate for payment in parts.
Differences toauthorizeAmount
The authorizeAmount1 operation uses a parameter set other than the authorizeAmount operation. The authorization timeout is specified in minutes instead of days.
Parameters The following table shows the parameter mapping scheme for the authorizeAmount operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
4 (external merchant)
merchant login
merchant PIN
AccessFrontendID_t
access Fronten-dID
AccessFrontendId String<80> AFI_011
AccountHandle1_t userID
accountID
pin
routingInfo
accountType
ConsumerId
ConsumerAccountId
ConsumerPIN
RoutingInfo
AccountType
String<30>
Long
String<20>
String<100>
Short
consumer MSISDN
0
consumer PIN
3
1 (prepaid consumer)
UserID_t merchantID MerchantId String<20> merchant login
(has to be identical to ReqCred.User.Id)
ProductID_t productID ProductId String<40> PREMIUM MMS
PurposeOf Transaction_t
purpose Purpose String<200> Order no.003
Money_t moneyTo Authorize
Autho.Currency
Autho.Amount
String<3>
Long
EUR
5600000
Money_t firstRate Rate.Currency
Rate.Amount
String<3>
Long
EUR
120000
Authorization TimoutClass
mode Mode Byte 1 = not used
2 = not used
3 = minutes classified
4 = minutes absolute
34 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
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 Authori-zationTimoutClass refers to 3 parameters described in the Technical Project Data (ChargeTransactionLifetime for short, medium and long).
g The ClusterName attributes are optional. Please refer to section 3.2.1.5 Usage of the ClusterName Parameter for further information.
Authorization TimoutClass
value Value Long for classified:
1 = short range
2 = medium range
3 = long range
for absolute:1 ... 142,560 minutes or 1 .. 99 days
not available not available ClusterName String c1
not available not available RequestType String with fixed value
authorizeAmount1
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
A50020-A3245-K-2-76D6
35
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.5 Parameters for the captureAmount Operation
Introduction The captureAmount operation is used if payment with separate authorization and reser-vation is requested. This operation comprises the following transactions:
• Transferring the required sum of money from the source to the target virtual account. • Reducing the sum of currently authorized money within its transaction context. • An additional sum of money can be authorized or the authorization can be finalized.
Each captureAmount operation within a transaction context can have a subcounter as a postfix of the transaction_ID. The range of the subcounter is 0 ... 99.
Parameters The following table shows the parameter mapping scheme for the capture Amount oper-ation. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Confirmation The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14+2> refer to section 3.2.1 Parameter Description
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
4 (external merchant)
merchant login
merchant PIN
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandle1_t userID
accountID
pin
routingInfo
accountType
ConsumerId
ConsumerAccountId
ConsumerPIN
RoutingInfo
AccountType
String<30>
Long
String<20>
String <100>
Short
consumer MSISDN
0
consumer PIN
3
1 (prepaid consumer
PurposeOf
Transaction_t
purpose Purpose String<200> Order no. 0456
Money_t money Money.Currency
Money.Amount
String<3>
Long
EUR
660000
boolean finalize
Authorization
Final String<5> true or false
Money_t additional
MoneyTo
Authorize
Add.Currency
Add.Amount
String<3>
Long
EUR
16000
not available not available ClusterName String c1
not available not available RequestType String with fixed value
captureAmount
36 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
g The parameters ConsumerId, ConsumerAccountId, ConsumerPIN, RoutingInfo and AccountType are optional. They may be specified all together or not at all. The ClusterName attribute is optional. Please refer to section 3.2.1.5 Usage of the Clus-terName Parameter for further information.
A50020-A3245-K-2-76D6
37
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.6 Parameters for the transferAmount Operation
Introduction The transferAmount operation is used if a general transfer of money between internal accounts, without any restrictions regarding the type of accounts, is requested.
Parameters The following table shows the parameter mapping scheme for the transferAmount oper-ation. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Confirmation The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
1 (consumer)
consumer login
consumer PIN
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandle_t userID
accountID
pin
SourceId
SourceAccountId
SourcePIN
String<30>
Long
String<20>
consumer MSISDN
0
source PIN
RoutingInfo_t routingInfo SourceRoutingInfo String<100> 3
AccountType_t accountType SourceAccountType Short 1 (prepaid consumer)
AccountHandle_t userID
accountID
pin
TargetId
TargetAccountId
TargetPIN
String<30>
Long
String<20>
login or MSISDN
0
target PIN
RoutingInfo_t routingInfo TargetRoutingInfo String<100> 3
AccountType_t accountType TargetAccountType Short 1 (prepaid consumer)
UserID_t merchantID MerchantId String<20> merchant login has to be identical to ReqCred.UserId
ProductID_t productID ProductId String<40> PREMIUM MMS
PurposeOf
Transaction_t
purpose Purpose String<200> Order no. 123
Money_t money Money.Currency
Money.Amount
String<3>
Long
EUR
560000
not available not available ClusterName String c1
not available not available RequestType String with fixed value
transferAmount
38 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
CORBA operationsmapping
Depending on the setting of the routingInfo, accountType, merchantID and productID parameters, the request is mapped to the following CORBA operations:
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.
A50020-A3245-K-2-76D6
39
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.7 Parameters for the adviceOfCharge Operation
Introduction The adviceOfCharge operation is used for price inquiry before service delivery.
Parameters The following table shows the parameter mapping scheme for the adviceOfCharge operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.
Confirmation The execution result is returned using the adviceOfChargeConf operation (refer to section 3.2.8 Parameters for the adviceOfChargeConf Confirmation Operation).
g The ClusterName attribute is optional. Please refer to section 3.2.1.5 Usage of the ClusterName Parameter for further information.
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
4 (ext. merchant)
merchant login
merchant PIN
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandle1_t userID
accountID
pin
routingInfo
accountType
ConsumerId
ConsumerAccountId
ConsumerPIN
RoutingInfo
AccountType
String<30>
Long
String<20>
String<100>
Short
consumer MSISDN
0
consumer PIN
3
1 (prepaid consumer)
UserID_t merchantID MerchantId String<20> merchant login
(has to be identical to ReqCred.User.Id)
ProductID_t productID ProductId String<40> PREMIUM MMS
PurposeOf
Transaction_t
purpose Purpose String<200> Order no. 123
Money_t money Money.Currency
Money.Amount
String<3>
Long
EUR
560000
not available not available ClusterName String c1
not available not available RequestType String with fixed value
adviceOfCharge
40 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2.8 Parameters for the adviceOfChargeConf Confirmation Operation
Introduction The confirmation operation for the adviceOfCharge operation containes the transac-tionID, executionStatus, transparentData, error, timeStampForRating and Calculated-Money parameters.
Parameters The following table shows the parameter mapping scheme for the adviceOfChargeConf operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.
Result values to returnsuccess or error
The result value of the ExecutionStatus_t type is used to asynchronously confirm the execution of the request in the online charging system and to return the success or error code to the Payment Plugin. The values are the same as described for the simple con-firmation operations (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
Example Response: TransactionID=123456789012345678 ExecutionStatus=1TransparentData=""CalculatedMoney.Currency=EURCalculatedMoney.Amount=9893ErrorList.noMoneyFlow=trueErrorList.list={}TimeStampForRating=1084956846481
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
ExecutionStatus_t executionStatus
ExecutionStatus Short 1 = successful
refer to section 3.2.14 Parameters for the Simple Confirmation Opera-tions for permitted values
TransparentData_t transparentData
TransparentData String<500> 51
Money_t Calculated Money
CalculatedMoney. Currency
CalculatedMoney. Amount
String<3>
Long
EUR
160000 (same precision as in the request)
ErrorList_t error ErrorList.noMoneyFlow
ErrorList.list
Boolean
String
true
{(8,1859,"SCP error")}
Date_t timeStampForRating
TimeStampForRating
Long 1036136490713 UNIX system time in millisec-onds since 1970 = Monday, July 09, 14:53:30 CEST 2001
A50020-A3245-K-2-76D6
41
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.9 Parameters for the refundTA Operation
Introduction The refundTA operation is used to refund a successful transaction.
Parameters The following table shows the parameter mapping scheme for the refundTA operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Confirmation The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
The ID for the transaction which is to be refunded. Dif-fering from most other requests, this ID is not created but must be an existing ID coming from either a previous charge request or authorize request.
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
4 (ext. merchant)
merchant login
merchant PIN
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandle1_t userID
accountID
pin
routingInfo
accountType
ConsumerId
ConsumerAccountId
ConsumerPIN
RoutingInfo
AccountType
String<30>
Long
String<20>
String<100>
Short
consumer MSISDN
0
consumer PIN
3
1 (prepaid consumer)
PurposeOf
Transaction_t
purpose Purpose String<200> Order no. 123
not available not available ClusterName String c1
not available not available RequestType String with fixed value
refundTA
42 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2.10 Parameters for the rechargeAmount Operation
Introduction The rechargeAmount operation triggers a recharging transaction on the clearing server. The expiry date is passed as an absolute date or as a number of days.
Virtual accounts Virtual accounts are recharged by the sum defined by the money parameter.
g This operation is deprecated, but has been kept due to compatibility reasons. Clients should use operation rechargeAmount1 with parameters RoutingInfo = "" and AccountType = 0 instead.
Parameters The following table shows the parameter mapping scheme for the rechargeAmount operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.
Confirmation The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
g The ClusterName attribute is optional. Please refer to section 3.2.1.5 Usage of the ClusterName Parameter for further information.
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
3 (PSP)
PSP login
" "
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandle_t userID
accountID
pin
ConsumerId
ConsumerAccountId
ConsumerPIN
String<30>
Long
String<20>
consumer MSISDN
0
consumer PIN
PurposeOf
Transaction_t
purpose Purpose String<200> Order no. 123
Money_t money Money.Currency
Money.Amount
String<3>
Long
EUR
560000
Date_t newExpiryDate ExpiryDate Long see Values for ExpiryDate
not available not available ClusterName String c1
not available not available RequestType String with fixed value
rechargeAmount
A50020-A3245-K-2-76D6
43
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
Values for ExpiryDate The following values may be specified for ExpiryDate:
Value Description
-1 The date is not specified. It is calculated by the SCP/SEP.
0 The date is not set, i. e. the expiration date is not changed.
date > 0 && < 2 years (365 * 2 * 24 * 60 * 60 * 1000)
Delta mode: the expiration date is a time span in milliseconds which is limited up to 2 years.
date > (current time - 24 h)
Absolute mode: the expiration date is an absolute date (UTC)
(e.g. Monday, July 09, 2001, 14:53:30 Central European Summer Time (CEST) = 994683210000 UNIX system time in milliseconds since 1970).
44 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2.11 Parameters for the rechargeAmount1 Operation
Introduction The rechargeAmount1 operation triggers a recharging transaction on the clearing server.
Virtual accounts Virtual accounts are recharged by the sum defined by the money parameter.
Expiry date The handling of the expiry date is specified by the parameters mode and value.
Parameters The following table shows the parameter mapping scheme for the recharge Amount operation. For a description of the parameters, refer to section 3.2.1 Parameter Descrip-tion.
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
3 (PSP)
PSP login
" "
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandle_t userID
accountID
pin
ConsumerId
ConsumerAccountId
ConsumerPIN
String<30>
Long
String<20>
consumer MSISDN
0
consumer PIN
UserID_t merchantID MerchantId String<20> merchant login has to be identical to ReqCred.UserId
ProductID_t productID ProductId String<40> PREMIUM MMS
PurposeOf
Transaction_t
purpose Purpose String<200> Order no. 123
Money_t money Money.Currency
Money.Amount
String<3>
Long
EUR
560000
ExpiryDateOrDays_t:Mode_t
mode Expiry.Mode byte 1 = absolute setting
2 = relative setting
3 = default setting
4 = no setting
For a description, please refer to Values for Expiry.Mode
ExpiryDateOrDays_t:Value_t
value Expiry.Value Long 90
RoutingInfo_t routingInfo RoutingInfo String<100> 3
AccountType_t accountType AccountType Short 1 (prepaid consumer)
A50020-A3245-K-2-76D6
45
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
Confirmation The execution result is returned using the rechargeAmountConf1 operation. The confir-mation also contains the new expiration date and the new balance of the account which has been recharged.
CORBA operationsmapping
Depending on the setting of the routingInfo, accountType, merchantID and productID parameters, the request is mapped to the following CORBA operations:
• rechargeAmount1if routingInfo and accountType are not specified
• rechargeAmount2if routingInfo and accountType are specified, but merchantID and productID are not specified
• rechargeAmount3if routingInfo, accountType, merchantID and productID are specified
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.
Values forExpiry.Mode
The handling of the expiration date is specified by the mode and value parameters. The confirmation contains the new expiration date and the new balance of the account that has been recharged.
The following values may be specified for Expiry.Mode:
not available not available ClusterName String c1
not available not available RequestType String with fixed value
rechargeAmount1
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
Expiry.Mode
Description
1 Absolute setting:
The Expiry.Value parameter specifies the new expiration date as the number of milliseconds since midnight , January 1, 1970 UTC.
2 Relative setting:
The Expiry.Value parameter specifies the number of days to be used as input for the calculation of the new current expiration date. This calculation is project-specific and may be based on either the current date or the current expiry date stored in the subscriber data.
3 Default setting:
The new expiration date is calculated by the online charging server. The Expiry.Value parameter has to be set to -1.
4 No setting:
The expiration date is not changed. The Expiry.Value parameter has to be set to 0.
46 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
g If the account does not have an expiration date property the parameters mode and value are ignored by the online charging server.
3.2.12 Parameters for the rechargeAmountConf1 Confirmation Operation
Introduction The rechargeAmount1Conf confirmation operation contains the following parameters.
Parameters The following table shows how these parameters, which occur within the confirmation operation, are mapped. For a description of the parameters, refer to section 3.2.1 Parameter Description.
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
ExecutionStatus_t executionStatus ExecutionStatus Short 1 = successful
refer to section 3.2.14 Parameters for the Simple Confirmation Oper-ations for permitted values
TransparentData_t transparentData TransparentData String<500> 51
ErrorList_t error ErrorList.noMoney-Flow
ErrorList.list
Boolean
String
true
{(8,1859,"SCP error")}
AccountHandle_t userID
accountID
pin
ConsumerId
ConsumerAccountId
ConsumerPIN
String<30>
Long
String<20>
consumer MSISDN
0
consumer PIN
Money_t recharged Money
RechargedMoney. Currency
RechargedMoney. Amount
String<3>
Long
EUR
160000 (same precision as in the request)
Money_t ID CurrentBalance. Currency
CurrentBalance. Amount
String<3>
Long
EUR
560000 (same precision as in the request)
Date_t dateOfLast Recharge
DateOfLastRecharge Long 1036136490713 UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
Currently not supported, contains only default values.
A50020-A3245-K-2-76D6
47
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
Result value The value of the ExecutionStatus_t parameter contains the result of the transaction. The values are the same as described for the simple confirmation operations (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
Example Response: TransactionID=300000110077355864 ExecutionStatus=1TransparentData="51"ErrorList.noMoneyFlow=falseErrorList.list={}ConsumerId=cons_xyzConsumerAccountId=0ConsumerPIN=****RechargedMoney.Currency=EURRechargedMoney.Amount=55500000CurrentBalance.Currency=EURCurrentBalance.Amount=55510000DateOfLastRecharge=0OldExpiryDate=1034458556121NewExpiryDate=1033619588825
g In the case of an error, the list of attributes contains only default values.
Date_t oldExpiryDate OldExpiryDate Long 1034458556121 UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
Date_t newExpiryDate NewExpiryDate Long 1033619588825 UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
48 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2.13 Parameters for the refund Operation
Introduction The refund operation triggers a refund in the clearing server in order to undo a previous charge operation.
Parameters The following table shows the parameter mapping scheme for the refund operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Confirmation The execution result is returned in a simple confirmation (refer to section 3.2.14 Parameters for the Simple Confirmation Operations).
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
3 (PSP)
PSP login
" "
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandle1_t userID
accountID
pin
routingInfo
accountType
ConsumerId
ConsumerAccountId
ConsumerPIN
RoutingInfo
AccountType
String<30>
Long
String<20>
String<100>
Short
consumer MSISDN
0
consumer PIN
3
1 (prepaid consumer)
UserID_t merchantID MerchantId String<30> merchant login
(has to be identical to ReqCred.User.Id)
ProductID_t productID ProductId String<40> PREMIUM MMS
PurposeOf
Transaction_t
purpose Purpose String<200> Order no. 123
long long errorCause ErrorCause Long 13
Date_t originalCharge Time
OriginalChargingTime Long 994683210000
UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
Money_t originalPrice OriginalPrice.Currency
OriginalPrice.Amount
String<3>
Long
EUR
560000
not available not available ClusterName String c1
not available not available RequestType String with fixed value
refund
A50020-A3245-K-2-76D6
49
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
g The ClusterName attribute is optional. Please refer to section 3.2.1.5 Usage of the ClusterName Parameter for further information.
3.2.14 Parameters for the Simple Confirmation Operations
Introduction The previously mentioned confirmation operations contain the transactionID, execution-Status, transparentData, CalculatedMoney and error parameters.
Parameters The following table shows how these parameters, which occur within the confirmation operations, are mapped. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Result values to returnsuccess or error
The result values of ExecutionStatus_t type are used to confirm the execution of the request in the online charging system and to return the success or error code to the Payment Plugin.
g Values > 0 are sent from the online charging server.
Values < 0 are errors detected by the Payment Plugin.
Every value except "1" indicates an error.
Result classification The following table describes the result classification of the execution status which occurs in the next table:
IDL Parameter Type IDL Parameter Name Response Attribute Name AttributeType Example for Value
TransactionID_t transactionID "TransactionId" String<4+14+2> 300000110077355864
ExecutionStatus_t executionStatus "ExecutionStatus" Short 1 = successful
refer to the following table for possible values
TransparentData_t transparentData "TransparentData" String<500> "51"
Money_t CalculatedMoney "CalculatedMoney.Currency"
"CalculatedMoney.Amount"
String<3>
Long
"EUR"
160,000
(same precision as in request)
ErrorList_t error "ErrorList.noMoneyFlow"
"ErrorList.list"
Boolean
String
true
{(8,1859,"SCP error")}
Result
classification
Execution
Status
ErrorL-ist.noMoney-
Flow
Description
A Successful The transaction was executed suc-cessfully.
B Limits violated The transaction was not executed successfully.
The account limits are exceeded.
C Failure true The transaction was not executed successfully.
The account is not changed.
50 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
Execution status The execution status is transported as part of asynchronous responses (confirmation) after the execution of a transaction has been processed by the online charging server. The following table describes the values of execution status:
D Failure false The transaction was not executed successfully.
The account is possibly changed.
Result
classification
Execution
Status
ErrorL-ist.noMoney-
Flow
Description
Execu-tion
status
Result
classification
Status Description Requested action
1 A Successful The transaction is executed successfully. None
2 C Invalid account The account is invalid or unknown for the requested operation.
The reason why the online charging server sends this execution status has to be analy-sed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).
No automatic repetition of the request is rec-ommended.
3 C Invalid access rights
The insufficient access rights which are based on the roles
- password or PIN or
- the subscriber is locked or
- the first call is not set.
4 B Limits violated The limits, e.g., threshold values, of an account or any limits set by the software (hard-coded limits) are violated.
No repetition of the payment request.
5 C Data not available The currency data table is not available from the Payment broker.
The reason why the online charging server sends this execution status has to be analy-sed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).
No automatic repetition of the request is rec-ommended.
6 C Invalid user ID The user with this ID is unknown to the system.
7 D Internal error The transaction is not completed because of an internal error.
Use getTAState to check the status of the transaction or check the tickets at the online charging server.
8 C Invalid transaction The transaction is unknown, because either an error occurred or because the transaction has timed out at either at the online charging server side or at the Payment broker side.
The reason why the online charging server sends this execution status has to be analy-sed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).
No automatic repetition of the request is rec-ommended.
A50020-A3245-K-2-76D6
51
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
Error cases The following error cases are possible:
• Default valuesIn error cases, the return values are supplied with dummies by operations which carry more return values than an execution status. I.e., constant values that only
9 C Transaction already open
The transaction to be opened is already open.
The reason why the application sent a trans-actionID already in use has to be analysed. The appropriate action has to be taken atap-plication side. Then it must be decided if the request has to be repeated with a new trans-actionID.
10 C Transaction busy This status is returned if the transaction is in a status that does not allow to handle the current request. E.g., a capture is tried for a transaction and another capture is already in progress.
Wait a couple of seconds and repeat the request.
11 C Authorization not available
This status is returned if a capture is tried and the authorized money is not suffi-cient.
Authorize/capture is not a use case for Ferma VoMS.
12 C Invalid money Either an incorrect currency is used (cur-rency string is unknown to the system) or the requested amount of money is higher than the maximum allowed value (accounting component configuration parameter).
The reason why the online charging server sends this execution status has to be analy-sed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).
No automatic repetition of the request is rec-ommended.
13 C Invalid parameter Wrong parameters or parameter values are used by the client that issues the request.
14 C No resources The application is temporarily in a status where it cannot accept the current request due to overload protection.
Wait a couple of seconds and repeat the request.
15 C Authorization not possible
This status is returned if a capture is executed and an additional authorization is tried which is not granted.
Authorize/capture is not a use case for Ferma VoMS.
16 C Feature not sup-ported
This status is returned if a feature is not supported for a specific set of users. E.g., loyalty point management is not sup-ported for postpaid consumers.
The reason why the application sends a request with an unsupported feature has to be analysed. The appropriate action has to be taken at application side.
17 C External ARS error The external user repository, e.g., LDPA server, does not response to a location request.
18 C External AMS error The account is stored on and the backend server does not answer the request, but no timeout happens.
19 D External AMS timeout
The account is stored on and the backend server does not answer the request, due to a timeout.
9999 maximum reserved Up to this value: All execution status codes are reserved for further exten-sions.
Do not use any values between 1-9999 for any project specific extensions.
Execu-tion
status
Result
classification
Status Description Requested action
52 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
satisfy formal interface criteria, but do not make sense. Be sure to check the execu-tion status before using the supplied data.
• Disaster recoveryIn the case, the whole system fails, the client connects to a stand-by system which is available. This includes any resolving of names in a newly available naming service.
Result values causedby Payment Plugin
The following values are detected by the Payment Plugin. These return codes are caused by exceptions which occur immediately after the call of the CORBA operation.
Execution status
Result
classification
Status Description Requested action
-100 C Transaction already open
The transaction to be opened is already open.
The reason why the application sends a transactionID already in use has to be anal-ysed. The appropriate action has to be taken on application side.
Then it must be decided if the request has to be repeated with a new transactionID.
-101 C Invalid transaction The transaction is not known, because either an error occurred or because the transaction has timed out at either at the online charging server side or at the Payment Broker side.
The reason why the online charging server sends this execution status has to be anal-ysed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).
No automatic repetition of the request is recommended.
-102 C Duplicate transac-tion ID
The reason why the application sends a transactionID already contained in the internal administration table of the Payment Plugin has to be analysed. The appropriate action has to be taken on application side.
-103 D Confirmation timeout The transaction is not completed because of an internal error.
Use getTAState to check the status of the transaction or check the tickets at the online charging server.
-104 C CORBA communi-cation error
There is a critical problem in CORBA communication. No requests can be sent to online charging server.
It is recommended that the Payment Plugin log file is evaluated by Nokia Siemens Networks staff.
-105 C Overload detected The Payment Plugin was not able to process the request due to an overload situation.
Wait a couple of seconds and repeat the request.
-106 C Invalid user ID The user with this ID is unknown to the system.
The reason why the online charging server sends this execution status has to be anal-ysed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).
No automatic repetition of the request is recommended.
-107 C Invalid access rights The insufficient access rights which are based on the roles
- password or PIN or
- the subscriber is locked or
- the first call is not set.
The reason why the online charging server sends this execution status has to be anal-ysed. The appropriate action has to be taken either at the application or at the online charging server side (probably software bug).
No automatic repetition of the request is recommended.
A50020-A3245-K-2-76D6
53
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
Result values causedby CORBA layer
exceptions
The following values are subcodes of -104 CORBA communication error execution status . The values are created by the Payment Plugin. These return codes are caused by exceptions which occur immediately after the call of the CORBA operation.
-108 C Limits exceeded The limits, e.g., threshold values, of an account or any limits set by the software (hard-coded limits) are violated.
No repetition of the payment request.
-109 D Response timeout A timeout occured while the Payment Plugin is waiting for the online charging server to acknowledge the reception of the request.
Use getTAState to check the status of the transaction or check the tickets at the online charging server.
-110 C No server resources A temporary overload situation has been reported by the online charging server.
The server was not able to process the request due to an overload situation. The payment Plugin rejects rejects further requests with execution status -110 until an internal timer has expired and the overload situation is cleared. The timeout is specified by configuration property ServerOverload-Timeout.
Wait a couple of seconds and repeat the request. There is no automatic repetition by the Payment Plugin.
Execution status
Result
classification
Status Description Requested action
Error Code
Description
-1 Exception from online charging server when sending chargeAmount request
-2 Exception from online charging server when sending authorizeAmount request
-3 Exception from online charging server when sending captureAmount request
-4 Exception from online charging server when sending getVersion request
-5 Naming service not available
-6 CorbaObjectPool initialization error
-7 No online charging server available
-8 No ChargingBroker available
-9 NamingContext creation error
-10 NamingContext resolve error
-11 NamingContext not found
-12 Exception during the ChargingBroker creation
-13 Exception during refresh online charging server objects
-14 StoreResponse not possible because OrderMapEntry does not exist
-15 Exception from online charging server when sending transferAmount request
-16 Exception from ClearingServer when sending rechargeAmount request
-17 No ClearingServer available
-18 Exception during refresh ClearingServerObjects
54 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
g The value of FunctionalUnitID is always set to 111. The value of error text is set to the error message dynamically generated by the CORBA runtime environment.
Result values causedby parameter
validation errors
The following values are results from validation of request parameters at the HTTP interface, e.g., due to missing parameters or illegal parameter values:
-19 No ClearingBroker available
-20 Exception during ClearingBroker creation
-21 Exception from online charging server when sending getTAState request
-22 Exception from online charging server when sending forgetTAState request
-23 CORBA "bad parameter" exception is thrown
-24 Invalid order map entry state when trying to store response
-25 Exception from AccountManagementServer when sending getConsumerAc-countList request
-26 Exception from AccountManagementServer when sending getVersion request
-27 No AccountManagementServer available
-28 No AccountManagementBroker available
-29 Exception during refreshAccountManagementObjects
-30 Exception during AccountManagementBroker creation
-31 Unexpected exception from ClearingServer when sending refund request
-32 Unexpected exception from online charging server when sending adviceOf-Charge request
Error Code
Description
Execu-tion
status
Result
classification
Status Description Requested action
-200 C Request Type not valid
Without the request type the appropriate request object cannot be created with the given parameters.
1Specify a valid request type.
-201 C Parameter or attribute not found
A parameter or attribute needed for the operation is not found in the http request.
1Specify the missing parameter or attribute.
-202 C Number Format error
A request attribute of type Integer, Long, Short or Double cannot be parsed from the attribute or parameter value of the http request, e.g. "mike55" cannot be parsed to Long.
1Correct the wrong parameter.
-203 C Class Cast error A class cast exception occurred due to an invalid parameter value.
This plugin return code does not exist any more. It is only mentioned for complete-ness.
-204 C Account Handle Specification error
Indicates that the number of elements in the attribute lists specifying the account handles is inconsistent.
1Correct the account type.
A50020-A3245-K-2-76D6
55
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
HTTP responseformat
The response for users of the HTTP interface is sent as plain text.
If the request is syntactically correct, the format is:HTTP/1.1 200 OKDate: Wed, 03 Mar 2004 14:34:25 GMTServer: Apache/2.0.48 (Unix) mod_jk2/2.0.2Content-Type: text/plain;charset=ISO-8859-1Connection: close
Response: TransactionID=300000110077355864 ExecutionStatus=1TransparentData=""CalculatedMoney.Currency=EURCalculatedMoney.Amount=7688ErrorList.noMoneyFlow=trueErrorList.list={}
Response in case ofsuccess
If the response was sucsessful, the syntax of the response is as follows:HTTP/1.1 200 OKDate: Wed, 03 Mar 2004 14:34:25 GMTServer: Apache/2.0.48 (Unix) mod_jk2/2.0.2Content-Type: text/plain;charset=ISO-8859-1Connection: close
Response: TransactionID=300000110077355865 ExecutionStatus=-104TransparentData=""CalculatedMoney.Currency=EURCalculatedMoney.Amount=7688ErrorList.noMoneyFlow=trueErrorList.list={(111,-31," org.omg.CORBA.OBJECT_NOT_EXIST: minor code: 0 completed: No")}
Response in case oferror
In case of success the ErrorList attributes noMoneyFlow and list are undefined and therefore must not be evaluated.
According to the specification of the HTTP Protocol (RFC 2068) the following is valid:HTTP applications MUST accept CRLF, bare CR, and bare LF as being represen-tative of a line break in text media received via HTTP.
If the request is invalid, e.g., because of missing attributes, the syntax of the response is as follows:HTTP/1.1 200 OKDate: Wed, 03 Mar 2004 14:34:25 GMT
-205 C Multiple user IDs error
Indicates that multiple values have been specified for the user IDs in the list of account handles.
1Correct the userIDs.
-206 C Multiple PINs error Indicates that multiple values have been specified for the PINs in the list of account handles.
1Correct the PINs.
-207 C Multiple routing info error
Indicates that multiple values have been specified for the routing information in the list of account handles.
This plugin return code does not exist any more. It is only mentioned for complete-ness.
-208 C Multiple account types error
Indicates that multiple values have been specified for the account types in the list of account handles.
1Correct the account types.
-230 C Cluster name not found
Indicates that the cluster name specified in the request has not been configured.
1Correct the cluster name.
1The error was detected by the Payment Plugin. The request was not sent to the online charging server.
Execu-tion
status
Result
classification
Status Description Requested action
56 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
Server: Apache/2.0.48 (Unix) mod_jk2/2.0.2Content-Type: text/plain;charset=ISO-8859-1Connection: close"
*** ERROR ExecutionStatus=<status> *** StatusMessage=<msg>"
g The evaluation of the response is only necessary if the HTTP result code is 200 OK. Otherwise, the HTTP request has caused a protocol error. In this case, the exact format of the response depends on the web server in use.
A50020-A3245-K-2-76D6
57
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.15 Parameters for the getConsumerAccountList Operation
Introduction This asynchronous getConsumerAccountList operation retrieves information about a list of user accounts.
Parameters The following table shows the parameter mapping scheme for the getConsumerAccoun-tList operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Confirmation The execution result is returned using the getConsumerAccountListConf operation and contains information including the balance and currently authorized amount.
CORBA operationsmapping
Depending on the setting of the routingInfo and accountType parameters, the request is mapped to the following CORBA operations:
• getConsumerAccountListif routingInfo and accountType are not specified
• getConsumerAccountList1if routingInfo and accountType are specified
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.
AccountHandleListdata type
The AccountHandleList data type depends on whether the Java API or the HTTP inter-face is used:
• Java APIIf the Java API is used, the AccountHandleList is a data structure of type Array. The structure is composed of UserId, AccountId and PIN.
IDL Parameter Type IDL Parame-ter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserCredentials_t roleID
userID
pin
ReqCred.Role
ReqCred.UserId
ReqCred.PIN
Short
String<30>
String<20>
1 (consumer)
consumer MSISDN
PIN
Access
FrontendID_t
access
FrontendID
AccessFrontendId String<80> AFI_011
AccountHandleList_t userID UserIdList each UserId is String<30>
consumer MSISDN
AccountHandleList_t accountID AccountIdList Long (list) a list of account IDs sepa-rated by commas
AccountHandleList_t pin PINList String<20> PIN
RoutingInfo_t routingInfo RoutingInfo String<100> 3
AccountType_t accountType AccountType Short 1 (prepaid consumer)
not available not available ClusterName String c1
not available not available RequestType String with fixed value
getConsumerAccoun-tList
58 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
• HTTP interfaceIf the HTTP interface is used, the AccountHandleList is represented by three name/value pairs where the values are separated by commas.
Example 1: Oneaccount for one user
TransactionId= "300000110077355864" … UserIdList="Miller" AccountIdList="1" PINList ="pin_5678"
Example 2: Threeaccounts for one user
TransactionId= "300000110077355864" … UserIdList="Miller" AccountIdList="1,4,6" PINList="pin_5678"
An empty string for PINList is possible (PINList=" ").
g A user can have up to seven subaccounts.
A50020-A3245-K-2-76D6
59
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
3.2.16 Parameters for the getAccountListConf Confirmation Operation
Introduction The confirmation operation for getConsumerAccountList contains the transactionID, executionStatus, transparentData and accountList parameters.
Parameters The following table shows how these parameters, which occur within the confirmation operations, are mapped. For a description of the parameters, refer to section 3.2.1 Parameter Description.
Result values The result value of ExecutionStatus_t type is used to confirm the execution of the request in the online charging system asynchronously and to return the success or error code to the Payment Plugin. The values are the same as described in section 3.2.14 Parameters for the Simple Confirmation Operations.
Record structure forAccount_t
The accountList IDL parameter type is a sequence of records of Account_t type. The account-specific information has the following record structure (Account_t):
IDL Parameter Type
IDL Parameter Name
Response Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
ExecutionStatus_t executionStatus ExecutionStatus Short 1
refer to section 3.2.15 Parameters for the getConsumerAccountList Operation for possible values
TransparentData_t transparentData TransparentData String<500> 51
AccountList_t accountList Special representation for each list element described below
IDL Parameter Type IDL Parameter Name
Response
Attribute Name
Attribute
Type
Example
for Value
AccountID_t accountID AccountId.<i> Long 1234567890
AccountType_t::Value_t accountType AccountType.<i> Short 0 unknown1 consumer prepaid2 consumer postpaid3 merchant sales4 merchant fees5 psp sales6 psp merchant paid fees7 psp consumer paid fees8 loyalty account
UserID_t::Value_t ownerID OwnerId.<i> String<30> MSISDN or merchant login
Currency_t::Value_t currency Currency.<i> String<3> EUR
boolean approved deprecated
60 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
The appendix string .<i> denotes the i-th element of the list, with a range for i from "1" to "N" with "N" being the number of elements in the list.
AccountList data type The AccountList data type depends on whether the Java API or the HTTP interface is used:
• Java APIIf the Java API is used, the AccountList is a data structure of type Array.
• HTTP interfaceIf the HTTP interface is used, the AccountList is represented by a string containing all parameters as name / value pairs where the values are separated by commas.
Amount_t::Value_t currentBalance Balance.<i> Long 50000
Amount_t::Value_t current Autho-rized Amount
AuthoAmount.<i> Long 60000
PaymentInstrument_t clearing Instru-ment
deprecated
ClearingPolicy_t clearingPolicy deprecated
short clearingPeriod deprecated
Amount_t::Value_t clearing Thresh-old
deprecated
Date_t lastBalance ModDate
BalModDate.<i> Long 994683210000 = UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
Date_t expiryDate ExpiryDate.<i> Long 994683210000 = UNIX system time in milli-seconds since 1970 = Monday, July 09, 14:53:30 CEST 2001
IDL Parameter Type IDL Parameter Name
Response
Attribute Name
Attribute
Type
Example
for Value
A50020-A3245-K-2-76D6
61
DMN:Payment Plugin Interface HTTP Interface
Id:0900d8058021019d
Example for N = 2
g In the case of an error, the list of attributes contains only default values.
HTTP/1.1 200 OKDate: Wed, 16 Feb 2005 14:34:45 GMTServer: Apache/2.0.48 (Unix) mod_jk2/2.0.2Content-Type: text/plain;charset=ISO-8859-1Connection: closeTransactionID = 300000110077355864 ExecutionStatus = 1TransparentData = "100"AccountId.1 = 987654, AccountType.1 = 1, OwnerId.1 = 'Miller', Currency.1 = 'EUR', Approved.1 = true, Balance.1 = 23200, AuthoAmount.1 = 0, ClearInstr.1 = 2, ClearPolicy.1 = 1 ClearPeriod.1 = 17, ClearThresh.1 = 0, BalModDate.1 = 0,ExpiryDate.1 = 0,…, …,AccountId.2 = 987654, AccountType.2 = 1, OwnerId.2 = 'Miller', Currency.2 = 'EUR', Approved.2 = true, Balance.2 = 23200, AuthoAmount.2 = 0, ClearInstr.2 = 2, ClearPolicy.2 = 1 ClearPeriod.2 = 17, ClearThresh.2 = 0, BalModDate.2 = 0,ExpiryDate.2 = 0
depracated depracateddepracateddepracateddepracated depracated depracateddepracateddepracateddepracated
62 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058021019d
HTTP Interface
3.2.17 Parameters for the getTAState Operation
Introduction This synchronous operation returns transaction information for the given TransactionId. The type of the return value is TransactionStatus_t (enumeration type).
Parameters The following table shows the parameter mapping scheme for the getTAState operation. For a description of the parameters, refer to section 3.2.1 Parameter Description.
With this operation the value of the parameter UserId may be used for address resolu-tion, if multiple charging servers are connected to the Payment Plugin. However, the address resolution functionality has to be implemented project-specifically.
g The ClusterName attribute is optional. Please refer to section 3.2.1.5 Usage of the 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).
IDL Parameter Type
IDL Parameter Name
Request Attribute
Name
Attribute
Type
Example
for Value
TransactionID_t transactionID TransactionId String<4+14> 300000110077355864
UserID_t userID UserId String<30> MSISDN (has to be identical to the parameter Consum-erId in the original transac-tion)
not available not available ClusterName String c1
not available not available RequestType String with fixed value
getTAState
A50020-A3245-K-2-76D6
63
DMN:Payment Plugin Interface Java API
Id:0900d80580208e80
4 Java APIIntroduction This chapter describes the Payment Plugin interface for non-web-based applications.
Applications written in Java may load the Payment Plugin as a library and use the Java API to send requests to the online charging server.The design of the Java API is similar to the J2EE Connector API. A PaymentConnectionFactory manages a set of logical con-nections to the charging server which in turn may be used to send requests to the online charging server.
Requests to the charging server are represented by instances of subclasses of PaymentRequest.
Interface classes Thus, the Application Programming Interface (API) consists of the following interface classes:
• PluginProperties • PaymentConnectionFactory • PaymentConnection • subclasses of PaymentRequest and PaymentResponse
g HTML documentation for all interface classes is included in the Payment Plugin package.
The binaries of the above mentioned classes and of all generated CORBA classes are stored in the PaymentPlugin.jar file, which needs to be installed on the client machine. Additionally, a CORBA runtime environment has to be installed. Currently there are two separate Payment Plugin variants for the VisiBroker or the JacORB.
Contents 4.1 Typical Usage Scenario
4.2 Example of a Property File
64 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d80580208e80
Java API
4.1 Typical Usage Scenario
Introduction This section describes a typical usage scenario of the Payment Plugin interface. Examples for the usage of the API classes can be found in chapter 6 Appendix.
Interface usagescenario
Proceed as follows:
Step Action
1 Initialize the Payment Plugin properties:
PluginProperties.getReference().load( new FileInput Stream( <name of property file> ) );
The PluginProperties class implements the singleton pattern.
2 Initialize the logging framework from the properties:
org.apache.log4j.PropertyConfigurator.configure( Payment-Plugin.getReference() )
3 Obtain a reference to the PaymentConnectionFactory:
PaymentConnectionFactory pcf = PaymentConnectionFac-tory.getReference();
If multiple online charging system clusters have been configured in the Pay-mentPlugin.properties file, a factory to a specific cluster may be aquired by:
PaymentConnectionFactory pcf = PaymentConnectionFac-tory.getReference(alias);
Provided that alias has been configured as an alias name for that cluster, i.e. there is an entry like the following in the PaymentPlugin.properties file.
Cluster.<n>=<alias>,<NameServiceURL of the cluster>
4 Get a new connection from the factory:
PaymentConnection conn = pcf.getConnection();
5 Instantiate a payment request.
A payment request can be instantiated by calling the default constructor and subsequent set methods or by calling the overloaded constructor with argu-ments for all request parameters.
PaymentRequest req = new ChargeAmountReq( tid, role, ... );
or
PaymentRequest req = new ChargeAmountReq();
req.setTransactionID( tid );
req.setRoleID( role );
... // Same for the rest of the attributes.
If using the second approach, PaymentRequest objects may be instantiated once and reused for subsequent requests. However, the caller has to make sure that all attributes are set and reset correctly.
The attributes of these requests are described in the API documentation which is part of the Payment Plugin package.
A50020-A3245-K-2-76D6
65
DMN:Payment Plugin Interface Java API
Id:0900d80580208e80
6 Use the connection to execute requests on the online charging server.
The connection may be reused for subsequent requests. If the client is multi-threaded, separate connections should be used for each thread.
PaymentResponse conf = conn.execute( req );
The execute() call returns if either a response has been received from the charging server or a timeout has expired.
7 Check the status of execution. Error codes are documented in section 3.2.14 Parameters for the Simple Confirmation Operations.
int status = conf.getExecutionStatus();
8 Finally, close the PaymentConnection:
conn.close();
This frees all resources allocated for this connection.
Step Action
66 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d80580208e80
Java API
4.2 Example of a Property File
Introduction This section describes an example of a property file which contains the configuration parameters of the Payment Plugin. During start up, the Payment Plugin reads this file and sets the appropriate internal control variables.
Property file The following table comprises a sample property file:
Property name Value Comment
NameServiceUrl corbaloc::zahlnix:2061/NameService
The URL of the CORBA Name Ser-vice.Syntax: corbaloc::<IP-Addr>: <Port>/NameService
Cluster.<unique number> Cluster.0=c1,corbaloc::testserv1: 2061/NameService
Cluster.1=c2,corbaloc::testserv2: 2061/NameService
A list of online charging system clusters to be accessed. The syntax is as follows:
<logical name>, <URL of cluster specific CORBA NameService>
interface.version.major 2 If the interface.version.major property has a value less than 2, confirmation messages are compatible with earlier ver-sions, i.e. do not contain transparent data. If the interface version is not set, the version defaults to 2.1.
interface.version.minor 1
log4j.rootLogger log4j.rootLogger=WARN, logfile, console
Defines the logging configuration to be used.
The property value consists of the specifi-cation of a logging level (FATAL, ERROR, WARN, INFO, DEBUG) and a list of appenders.
Please see the log4j documentation avail-able at: http://jakarta.apache. org/log4j/docs/index.html
log4j.appender.logfile.File /opt/jakarta-tomcat-4.1.29/logs/PaymentPlugin.log
Absolute path of PaymentPlugin log file.${java.io.tmpdir}/ PaymentPlugin.log
TransactionHostId 4444 HostId of the sender used as a prefix for the TransactionId if the string is not empty (maximum 4 digits).
A50020-A3245-K-2-76D6
67
DMN:Payment Plugin Interface Java API
Id:0900d80580208e80
log4j.renderer.[Lde.siemens. advantage.payment.payplu-gin. impl.processing.Account;
de.siemens.advantage.payment. payplugin.impl.logging.AccountListRenderer
Registration of object renderers
Note: Values do not need to be changed.
log4j.renderer.de.siemens. advantage.payment.payplu-gin. impl.processing. RechargeAmountResponse
de.siemens.advantage.payment. payplugin.impl.logging.Recharge AmountResponseRenderer
log4j.renderer.de.siemens. advantage.payment.payplu-gin. impl.processing.Payment-Response
de.siemens.advantage.payment. payplugin.impl.logging. Payment-ResponseRenderer
log4j.renderer.[Lde.siemens. advantage.payment.payplu-gin. impl.corba. AccountMan-agementTypes. Account_t;
de.siemens.advantage.payment. payplugin.impl.logging. Account_tListRenderer
log4j.renderer.[Lorg.omg. CORBA.Policy;
de.siemens.advantage.payment. payplugin.impl.logging. PolicyLis-tRenderer
log4j.appender.console org.apache.log4j. ConsoleAp-pender
Definition of console appender
Note: Values do not need to be changed.log4j.appender.console.layout org.apache.log4j.PatternLayout
log4j.appender.console. Threshold
ERROR
log4j.appender.console. lay-out.ConversionPattern
%d %5p [%t] %x (%F:%L) - %m%n Definition of the output pattern of:
• the file name of the caller
• the line number
Note: Values do not need to be changed.
log4j.appender.logfile org.apache.log4j. RollingFileAp-pender
log4j.appender.logfile. Max-FileSize
10MB Definition of console appender
Note: Values do not need to be changed.
log4j.appender.logfile. Max-BackupIndex
5 Definition of number of logfiles to be kept
Note: Values do not need to be changed.log4j.appender.logfile.Append false
log4j.appender.logfile.layout org.apache.log4j.PatternLayout Definition of the output pattern for the logfiles
Note: Values do not need to be changed.log4j.appender.logfile.layout. ConversionPattern
%d %5p [%t] %x (%F:%L) - %m%n
AliveTestInterval 30 000 Interval (in milliseconds) for sending get-Version calls to the online charging server for alive tests.
Note: Value does not need to be changed.
Property name Value Comment
68 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d80580208e80
Java API
AliveTestTimeout 20 000 Timeout value (in milliseconds) for getVersion calls to the online charging server for alive tests. A warning is written to the log file if the timeout has expired.
Note: Value does not need to be changed.
NameServiceTimeout 20 000 Timeout value (in milliseconds) for NameService responses using the loca-tions 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-val
300 000 Time interval (in milliseconds) for refresh-ing 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.
ChargingServerNamingCon-text Path
PaymentInterface/Server Naming Context Path under which the CORBA ChargingServer server objects can be found.
Note: Value must not be changed.
ChargingServerClusterName ChargingServer Name of the ChargingServer server cluster.
Note: Value must not be changed.
Property name Value Comment
A50020-A3245-K-2-76D6
69
DMN:Payment Plugin Interface Java API
Id:0900d80580208e80
ChargingBrokerNaming Con-textPath
PaymentInterface/Broker 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 Con-textPath
PaymentInterface/Server 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 Con-textPath
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
PaymentInterface/Server 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.
Property name Value Comment
70 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d80580208e6b
J2EE Connector Interface
5 J2EE Connector InterfaceIntroduction This chapter describes the Java 2 Enterprise Edition (J2EE) connector interface as a
standard architecture for enabling J2EE components to interact with enterprise informa-tion systems (EIS). An example is used to describe how to use this interface.
Contents 5.1 J2EE Connector Architecture
5.2 Usage Scenario for the J2EE Connector Interface
A50020-A3245-K-2-76D6
71
DMN:Payment Plugin Interface J2EE Connector Interface
Id:0900d80580208e6b
5.1 J2EE Connector Architecture
Introduction This section describes the J2EE connector architecture (JCA) and the restrictions with regard to the use of this interface.
J2EE connectorarchitecture
The JCA defines a standard architecture for enabling J2EE components such as enter-prise beans, servlets or Java Server Pages (JSP) to interact with enterprise information systems (EISs). J2EE components use connections to access services provided by the EIS. Connection objects are pooled by the application server. This provides a scalable application environment that can support a large number of clients requiring access to an EIS. Using connection factories, connection is obtained between the application and the EIS through the application server. On receiving a client request, connections from the pool are given to the client. After use, these connections are released by the client and are put back in the connection pool.
JCA specification andrestrictions
The JCA is specified in the respective Java Connector Architecture Specification (e.g. version 1.0, final release August 22, 2001).
Restrictions with respect to the JCA specification: • The optional common client interface (CCI) is not supported. • All connections are non-transactional. • The security management interface is not supported. Requester credentials are not
required when establishing connections, but have to be provided as request param-eters.
• Since the Payment Plugin uses the log4j logging framework internally, it is not possible to change the destination of the logging output by calling the setLogWriter() method.
The J2EE connector interface is very similar to the Java API. Both interfaces use differ-ent classes for connection factories and connections. The request classes are identical.
72 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d80580208e6b
J2EE Connector Interface
5.2 Usage Scenario for the J2EE Connector Interface
Introduction This section described in an example how to use this interface. It is assumed that the connector has been configured and deployed to the application server and that the con-nection factory has been bound to the Java Naming and Directory Interface (JNDI) name eis/PayAdvConnector.
Precondition This section shows how to use this interface to send a charging request to the online charging server.
Example // import required packages and classesimport javax.naming.*;import de.siemens.advantage.payment.payplugin.intf.connector.*;import de.siemens.advantage.payment.payplugin.impl.processing.ChargeAmountReq;import de.siemens.advantage.payment.payplugin.impl.processing.PaymentResponse; ...// create initial contextContext initCtx = new InitialContext();
// perform JNDI lookup// the naming context is specific to the application serverPayAdvConnectionFactory factory =(PayAdvConnectionFactory) initCtx.lookup( "java:comp/env/eis/PayAdvConnector" );// get a connection to the payment serverPayAdvConnection conn = factory.getConnection();
// instantiate a requestChargeAmountReq req = new ChargeAmountReq( ... );
// execute the requestPaymentResponse resp = conn.execute( req );
// evaluate the responseSystem.out.println( "executed request, executionstatus = " +resp.getExecutionStatus() );
// finally close the connection to put it back to the poolconn.close();
g The error handling code has been omitted for clarity.
Additional information HTML documentation for all interface classes is included in the Payment Plugin software package.
The source code for the usage of the connector in a sample EJB is shown in section 6.2.7 Example of an EJB Using the J2EE Connector Interface.
A50020-A3245-K-2-76D6
73
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
6 AppendixIntroduction This chapter contains a hint on how to handle timeouts and examples showing how to
use the recharge request.
Contents 6.1 Timeout Handling at the Client Side Using getTAState
6.2 Examples
74 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020b05e
Appendix
6.1 Timeout Handling at the Client Side Using getTAState
Introduction This section gives a hint on how to handle timeouts.
Network problems In a network it is always possible that the link between client and server is interrupted. It depends on the configuration of the network elements (e.g. routers) how long messages survive in these situations. In the best case, a message may be stored tem-porarily to be transmitted later. In the worst case, the message is completely lost.
Client application This situation of delayed or lost messages cannot be controlled by the Payment Plugin or the online charging server. In fact, it is the client who is responsible for the correct completion of the transactions.
Message flow The following figure shows the typical message flow:
Timeout If the online charging server does not acknowledge in time that it has received the request, the Payment Plugin reports a ResponseTimeout error. A ConfirmationTimeout error is reported, if no confirmation indicating the result of the transaction is received during a specified period of time.After a ResponseTimeout (-109) or a ConfirmationTim-eout (-103) there are two possible situations:
• The request may have been received and processed by the online charging server and the confirmation may have been lost.
• The request was not received by the online charging server at all.
In general, transactions, which result in any account changes, are still stored for a short time at the online charging server, so that their states could be queried by getTAState afterwards. However, transactions which do not change any accounts like the getAc-countTransactionList and getTAState transactions are not stored and usually should not be queried by getTaState. There may be internal reasons, for which even some of these
A50020-A3245-K-2-76D6
75
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
transactions are stored. There are also several reasons, due to which failed transactions are not stored, for example if the transaction cannot be processed at all because of any parameter errors or because of rejection due to traffic limitation or overload. Neverthe-less, again there might be internal reasons, for which even some of such transactions are stored.
In older systems it was possible to query transactions only, which had been processed in the PaymentCore and not the ones, which had been processed in the CCS. So the getTAState request had been available in a Charging@vantage configuration only. In charge@once configurations the getTaState implementation had to be ordered project-specifically. In CPOCS the getTaState transaction works for CCS transactions too - with slightly changed behaviour due to the different internal implementation.
The timeframe the transaction status is available varies with the used online charging system:
Using the PaymentCore the transaction status is available for at least 15 minutes after the processing. With CPOCS and direct Service access the timeframe depends also on success. For successful transaction the timeframe can be administered on Tarifftool. In a product configuration it is 10 minutes. Most non successful transactions need not to be stored by the CCS.
getTAState request After recognizing a ResponseTimeout or a ConfirmationTimeout, the client sends a get-TAState request to check the status of the transaction. Depending on the received infor-mation the client reacts as described in the table below.
g After the Payment Plugin has declared timeout for a transaction, any response from the online charging server concerning this transaction is ignored. The client applica-tion must not base any decisions on these 'late' responses which might have been buffered somewhere in the network. Decisions must be based solely on the result of the getTAState request.
g If a confirmation to the client at the Payment Plugin cannot be transferred, the online charging server will not execute rollbacks. The client application using the Payment Plugin has to decide whether to initiate actions to rollback or rollforward or admin-ister, if it does not receive confirmations from the online charging server.
Transaction statusvalues
The following table specifies and explains the possible transaction status values:
Transaction status values
Comment
0 = requested Depending on the operation, this internal status means:
- chargeRequested- authorizationRequested- captureRequested- rechargeRequested.
Note: This status is an intermediate internal status with a short life-time.
76 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020b05e
Appendix
1 = processed The final status, if
- the chargeAmount or
- the final captureAmount or
- the rechargeAmount
has been processed successfully by the online charging server.
2 = timeout Not used. The transaction status value 3 (failed) is used instead.
3 = failed The confirmation contains an ExecutionStatus > 1 due to problems; e.g. authorization check failed, consumer is unknown, ...
4 = expired Not used. The transaction status value 3 (failed) is used instead.
5 = authorized The internal status after a successful authorizeAmount.Any number of captureAmount requests may be received via the CORBA inter-face. In this case, the transaction status is changed to captureRe-quested.
6 = capture Requested
The internal status after a captureAmount has been received.
Note: This status is an intermediate internal status with a short life-time.
7 = partly Captured
Not used. The transaction status value 5 (authorized) is used instead.
The following error codes are sent if the getTAState request was unsuccessful:
-101 = Invalid transaction
The getTAState request has failed, because the transaction is not known by the online charging server
-104 = CORBA communica-tion error
The getTAState request has failed, because there is a problem in the CORBA communication between the Payment Plugin and the online charging server.
-105 = Overload detected
The getTAState request has failed due to a temporary overload sit-uation in the online charging server.
-109 = Response Timeout
There was no response from the online charging server to the getT-AState request.
-110 = No server resources
The getTAState request has failed due to a temporary overload sit-uation reported by the online charging server.
Transaction status values
Comment
A50020-A3245-K-2-76D6
77
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
6.2 Examples
Introduction This section provides some basic information about the HTTP protocol and shows examples of recharge requests.
For further information on this protocol, refer to RFC 1945 (HTTP/1.0) and RFC 2616 (HTTP/1.1) which can be downloaded from http://www.rfc-editor.org.
HTTP request An HTTP request consists of a request method, a request URL, header fields and a body. HTTP defines the following request methods: • GET: retrieves the resource identified by the request URL • HEAD: returns the headers identified by the requested URL • POST: sends data of unlimited length to the web server
The Payment Plugin servlet handles both GET and POST. The POST request is recom-mended because there is no length limitation.
HTTP response An HTTP response contains a result code, header fields and a body. The HTTP protocol expects the result code and all header fields to be returned before any body content.
A GET request does not have a body (i.e. the body is empty). The response contains a body with the response data and header fields which describe the body (especially Content-Type and Content-Encoding). With a GET request, the parameters are encoded in the URL, whereas with a POST request they are transmitted in the body.
Status codes Some commonly used status codes include the following:
The following sections show simple examples of a rechargeAmount request using GET and POST syntax.
All request parameters are specified as tag-value pairs separated by the "&" character. Tags and values are separated by the "=" character. The list has to be provided in URL-encoded format. Please see RFC 1738 for details.
Contents 6.2.1 Format of a Recharge Request Using GET Syntax
6.2.2 Format of a Recharge Request Using POST Syntax
Status Code
Description
200 The request has succeeded.
204 The server has fulfilled the request, but there is no new information to send back.
400 The request could not be understood by the server due to invalid syntax.
401 The request requires user authentication.
403 The server understood the request, but is refusing to fulfill it.
404 The server has not found anything matching the request URL.
500 The server encountered an unexpected condition which prevented it from ful-filling the request.
501 The server does not support the functionality required to fulfill the request.
503 The server is currently unable to handle the request due to temporary over-loading or maintenance of the server.
78 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020b05e
Appendix
6.2.3 Example of a Recharge Request Using HTTP GET in Java
6.2.4 Example of a Recharge Request Using HTTP GET in C++
6.2.5 Example of a Recharge Request Using the Java Library PaymentPlugin.jar
6.2.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 Format of a Recharge Request Using GET Syntax
Introduction This section describes the format of a recharge request using the GET syntax.
Syntax GET/PaymentPlugin/servlet/PaymentPluginServlet?TransactionId=300000110077355864 &ReqCred.Role=3&ReqCred.UserId=PSPLogin&ReqCred.PIN=8888&AccessFrontendId=JSUNICOM&ConsumerId=8613072506800&ConsumerAccountId=0&ConsumerPIN=1234&Purpose=cash-in+Recharge&Money.Currency=RMB&Money.Amount=20000&ExpiryDate=1043977423&Request Type=rechargeAmount HTTP/1.0<NEWLINE>
g The entire request is in one line.
6.2.2 Format of a Recharge Request Using POST Syntax
Introduction This section describes the format of a recharge request using the POST syntax.
Syntax POST /PaymentPlugin/servlet/PaymentPluginServlet HTTP/1.0<NEWLINE>User-Agent: None<NEWLINE>Content-Type: application/x-www-form-urlencoded<NEWLINE>Content-Length: 285<NEWLINE><NEWLINE>TransactionId=300000110077355864&ReqCred.Role=3&ReqCred.UserId=PSPLogin&ReqCred.PIN=&AccessFrontendId=%2F%2Fhttp%3A&ConsumerId=8613001114206&ConsumerAccountId=0&ConsumerPIN=&Purpose=Online+Recharging&Money.Currency=RMB&Money.Amount=10000&ExpiryDate =1014937200000&RequestType=rechargeAmount<NEWLINE><NEWLINE>
A50020-A3245-K-2-76D6
79
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
6.2.3 Example of a Recharge Request Using HTTP GET in Java
Introduction The sample code below shows a Java implementation of a simple client using the HTTP interface to send a recharge request and print the response to the standard output.
Example /* Copyright (c) Siemens AG 2000,2001 All Rights Reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/
import java.io.*;import java.net.*;import java.util.*;
// example for a HTTP GET recharge amount request for the Payment Plugin // Servlet residing on a Web Server public class HTTPGetRecharge { public static final String classVersion = "@(#) HTTPGetRecharge.java : /main/5 : ";
public static void main(String[] args) throws Exception {
// define the servlet String servletURL =
"http://localhost:8080/PaymentPlugin/servlet/PaymentPluginServlet?";
// define the name value pairs used for one recharge amount request String par1 = "RequestType=rechargeAmount";
String par2 = "TransactionId=300000110077355864"; String par3 = "ReqCred.Role=3";
// The class URLEncoder contains a utility method for converting a // String into a MIME format called "x-www-form-urlencoded" format. // The conversion is necessary to transfer the space character ' ' // as a plus sign '+'. String par4 = "ReqCred.UserId=" + URLEncoder.encode("Jimmy Smith"); String par5 = "ReqCred.PIN=8888"; String par6 = "AccessFrontendId=HTTP_Tester"; String par7 = "ConsumerAccountId=0815"; String par8 = "ConsumerId=Miller"; String par9 = "ConsumerPIN=1234"; String par10 = "Purpose=test_of_rechargeAmount"; String par11 = "Money.Currency=EUR"; String par12 = "Money.Amount=500000";
// the expiration date is today plus 30 days Date today = new Date(); long expiryDate = today.getTime() + 30 * 24 * 60 * 60 *1000L; String par13 = "ExpiryDate=" + expiryDate;
// build a string containing the servlet url and the params String spec = servletURL + par1 + "&" + par2 + "&" + par3 + "&" + par4 + "&" + par5 + "&" + par6 + "&" + par7 + "&" + par8 +
"&" + par9 + "&" + par10 + "&" + par11 + "&" + par12 + "&" + par13;
System.out.println("The spec of the URL: " + spec);
try {
80 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020b05e
Appendix
// Class URL represents a Uniform Resource Locator, a pointer to // a "resource" on the World Wide Web. URL url = new URL(spec);
// build a connection to this URL and send the request URLConnection urlConn = url.openConnection();
// If it is an HTTP connection, display some additional// information. if (urlConn instanceof HttpURLConnection) { HttpURLConnection h = (HttpURLConnection) urlConn; System.out.println(" Request Method: " + h.getRequestMethod()); System.out.println(" Response Message: " + h.getResponseMessage()); System.out.println(" Response Code: " + h.getResponseCode());
}
// get an input stream InputStream urlconninstr = urlConn.getInputStream(); // get an InputStreamReader InputStreamReader isr = new InputStreamReader( urlconninstr ); // use a BufferedReader BufferedReader br = new BufferedReader( isr ); // read the response from the Payment Plugin Servlet line by line
System.out.println("The result of the RechargeAmount is ..."); String line = br.readLine(); while (line != null) { System.out.println(line); line = br.readLine();
} // close the BufferedReader br.close(); } catch (MalformedURLException mue) { System.out.println(mue.getMessage());
} // catch MalformedURLException catch (IOException ioe) { System.out.print("general IO exception "); System.out.println(ioe.getMessage()); } // catch IOException } // end main}
As the standard Java library provides convenience classes to handle URL connections, the implementation is quite simple.
A50020-A3245-K-2-76D6
81
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
6.2.4 Example of a Recharge Request Using HTTP GET in C++
Introduction The sample code in this section shows an implementation of a simple client in C++, which sends a recharge request using the HTTP interface and prints the response to the standard output. Unlike the Java example in section 6.2.3 Example of a Recharge Request Using HTTP GET in Java, this implementation requires somewhat more code, as the socket connection to the web server has to be established explicitly by the client.
Example /* Copyright (c) Siemens AG 2000,2002 All Rights Reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/
#include <iostream.h>#include <strstream.h>#include <sys/types.h>#include <sys/socket.h>#include <arpa/inet.h>#include <netdb.h>#include <unistd.h>#include <errno.h>#include <string.h>#include <stdlib.h>#include <limits.h>
const char * SERVLET_NAME = "/PaymentPlugin/servlet/PaymentPluginServlet";
/* * generate header for a HTTP GET request */
void fillInHeader( ostrstream& ostr ) { ostr << "GET "; ostr << SERVLET_NAME;/* *encode parameters for a dummy Recharge request */
void fillInParams( ostrstream& ostr ) { const char DELIM = '&'; ostr << "RequestType=rechargeAmount"<< DELIM << "TransactionId=300000110077355864"<< DELIM << "ReqCred.Role=3"<< DELIM << "ReqCred.UserId=Jimmy+Smith"<< DELIM << "ReqCred.PIN=8888"<< DELIM << "AccessFrontendId=HTTP_Tester"<< DELIM << "ConsumerAccountId=0815"<< DELIM << "ConsumerId=Miller"<< DELIM << "ConsumerPIN=1234"<< DELIM << "Purpose=test_of_rechargeAmount"<< DELIM << "Money.Currency=EUR"<< DELIM << "Money.Amount=500000"<< DELIM << "ExpiryDate=99999";}
/* * generate the request */
82 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020b05e
Appendix
void fillInRequest( ostrstream& ostr ) { fillInHeader( ostr ); ostr << "?"; fillInParams( ostr ); ostr << " HTTP/1.0"; ostr << "\r\n\r\n"; ostr << ends;
}
/* * open an internet socket to the web server * the web server is specified by an IP address and a port number */
int openConnection( const char *hostName, const short port ) { int sd = socket( AF_INET, SOCK_STREAM, 0 ); if ( sd < 0 ) { cerr << strerror( errno ) << endl; } else { hostent *entry = gethostbyname( hostName ); if ( entry == NULL ) { cerr << "ERROR: host \"" << hostName << "\" not found." << endl; sd = -2; } else { in_addr in; memcpy( &in.s_addr, entry->h_addr_list[0], sizeof in.s_addr );
sockaddr_in addr; memset( &addr, 0, sizeof addr ); addr.sin_family = AF_INET; addr.sin_port = htons( port ); addr.sin_addr.s_addr = in.s_addr; cout << "Connecting to \"" << hostName << "\" (" << inet_ntoa( in ) << "), "
<< port << endl; int rc = connect( sd, (sockaddr *) &addr, sizeof addr ); if ( rc < 0 ) { cerr << "ERROR: " << strerror( errno ) << endl; sd = rc; } } }
return sd;}
/* * close the socket connection */
void closeConnection( int sd ) { shutdown( sd, 2 ); close( sd );
}
/* * main routine */
int main( int argc, char *argv[] ) {
const int RESULT_LEN = 2048; char resultBuffer[RESULT_LEN];
A50020-A3245-K-2-76D6
83
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
int rc;
/* * 0. process command line */ if ( argc < 3 ) { cerr << "Usage: HTTPRecharge <hostname of the web server running the PaymentPlugin> <port>" << endl; return 1;
}
char * hostName = argv[1]; int port = atoi( argv[2] ); if ( port == 0 || port <= SHRT_MIN || port >= SHRT_MAX ) { cerr << "invalid port number" << endl; return 2; }
/* * 1. establish a connection to the web server */ int sd = openConnection( hostName, port ); if ( sd < 0 ) { cerr << "Connection to \"" << hostName << "\", port " << port << "
failed." << endl;
return 3; }
/* * 2. generate a Recharge request */ ostrstream requestBuffer; fillInRequest( requestBuffer ); char * request = requestBuffer.str(); cout << "sending GET request:\n" << request << endl;
/* * 3. send the request */ rc = write( sd, request, strlen( request ) );// error handling omitted !!! cout << "request sent, waiting for response" << endl;
/* * 4. wait for the response * keep on reading until the response is complete */ int bytesRead = rc; int msgLen = 0; while ( bytesRead > 0 ) { bytesRead = read( sd, resultBuffer + msgLen, RESULT_LEN - msgLen ); msgLen += bytesRead; } cout << "result is:\n" << resultBuffer << endl;
/* * 5. close the connection to the web server */ closeConnection( sd );
return 0;}
84 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020b05e
Appendix
6.2.5 Example of a Recharge Request Using the Java Library PaymentPlugin.jar
Introduction The sample code in this section shows an implementation of a simple client using the classes of the processing layer.
The following recharge request examples are shown below:
• Client application
• Startup script for JacORB
Example of a clientapplication
/* Copyright (c) Siemens AG 2000,2002 All Rights Reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/
import de.siemens.advantage.payment.payplugin.impl.processing.*;import de.siemens.advantage.payment.payplugin.impl.corba.Common.*;import de.siemens.advantage.payment.payplugin.impl.PluginProperties;import org.apache.log4j.Logger;import org.apache.log4j.PropertyConfigurator;
import java.util.*;import java.io.*;
// example for usage of the Payment Plugin API
public class APIRecharge {
// Retrieve a Logger for class APIRecharge. // Logger is the central class in the log4j package. public static Logger logger = Logger.getInstance( APIRecharge.class.getName() );
public static void main(String[] args) {
try { if ( args.length > 0 ) {
// read the Payment Plugin property file and // initialize the PluginProperties class PluginProperties.getReference().load( new FileInputStream( args[0] ) ); }
// extends class BasicConfigurator from log4j // to provide configuration from an external file PropertyConfigurator.configure( PluginProperties.getReference() );
// verify the properties specified by the user PluginProperties.getReference().verify();
// obtain a reference to the PaymentConnectionFactory// for the charge@once cluster "SEP01" // NOTE: there must be a configuration entry // Cluster.0=SEP01,corbaloc::<hostname_or_ip>:2061/NameService // in the PaymentPlugin.properties file PaymentConnectionFactory factory = PaymentConnectionFactory.getReference( "SEP01" );
// if only one cluster is used the method call above may be reduced to // PaymentConnectionFactory factory = // PaymentConnectionFactory.getReference();
A50020-A3245-K-2-76D6
85
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
// get a new connection from the factory// .PaymentConnection conn = factory.getConnection();// Instantiate a payment request// either calling the default constructor and subsequent set// methods or the overloaded constructor with arguments for all// request parameters
RechargeAmountReq req = new RechargeAmountReq(); req.setTransactionID("300000110077355864"); req.setRoleID( (short)3 ); req.setUserID("Jimmy Smith"); req.setPin("8888"); req.setAccessFrontendID("API_Tester"); req.setConsumerAccountID( Long.parseLong("0815")); req.setConsumerID("Miller"); req.setConsumerPIN("1234"); req.setPurpose("test_of_rechargeAmount"); req.setCurrency("EUR"); req.setAmount(500000);
// the expiration date is today plus 30 days Date today = new Date(); long expiryDate = today.getTime() + 30 * 24 * 60 * 60 *1000L; req.setExpiryDate(expiryDate); System.out.println(req);
// Use the connection to execute requests on the Charging@vantage// server. PaymentResponse conf = conn.execute( req );// Check the status of the execution.// Error codes are documented in the // Charging@vantage Interface Specification.// Additional error codes are generated by the PaymentPlugin. int status = conf.getExecutionStatus(); System.out.println("ExecutionStatus=" + status + " for TransactionID " + conf.getTransactionID());
// Finally close the PaymentConnection.// This will free all the resources allocated for this connection. conn.close();
} catch ( Exception ex ) { System.out.println( "Uncaught exception: " + ex.getLocalizedMessage() );
} System.exit( 0 ); }}
Example of a simplestartup script
f In order to run the application make sure the CORBA runtime environment is set up correctly.
#! /bin/bashJAVA_HOME=/usr/java1.4.2JVM=${JAVA_HOME}/bin/java
JACORB_HOME=/opt/INTPaqasp/libJACORB_LIBS=${JACORB_HOME}/lib/jacorb.jar:${JACORB_HOME}/lib/logkit-.jar:${JACORB_HOME}/lib/avalon-framework.jarLOG4J=/opt/INTPaqasp/lib/log4j-1.2.8.jarPLUGIN_JAR=/opt/INTPaqasp/lib/PaymentPlugin.jar
LOCAL_CLASSPATH=".:${PLUGIN_JAR}:${LOG4J}"
exec ${JVM} ${JVM_FLAGS} \ -classpath "${LOCAL_CLASSPATH}" \
86 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020b05e
Appendix
-Dorg.omg.CORBA.ORBClass=org.jacorb.orb.ORB \ -Dorg.omg.CORBA.ORBSingletonClass=org.jacorb.orb.ORBSingleton \ APIRecharge $1
6.2.6 Example of a GetTAState Request Using the Java Library PaymentPlugin.jar
Introduction The example code in this section shows an implementation of a simple client executing a GetTAState request using the Java API.
Example /* Copyright (c) Siemens AG 2000,2001 All Rights Reserved
The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/
import de.siemens.advantage.payment.payplugin.impl.processing.*;import de.siemens.advantage.payment.payplugin.impl.corba.Common.*;import de.siemens.advantage.payment.payplugin.impl.PluginProperties;import de.siemens.advantage.payment.payplugin.impl.sim.servlet.RequestBuilder;import org.apache.log4j.Category;import org.apache.log4j.PropertyConfigurator;
import java.util.*;import java.io.*;
// example for usage of the Payment Plugin API
public class APIGetTAState { public static final String classVersion = "@(#) APIGetTAState.java : /main/1 :";
// Retrieve a category for class APIGetTAState. Category is the central // class in the log4j package. public static Category cat = Category.getInstance( APIGetTAState.class.getName() );
public static void main(String[] args) {
try { if ( args.length > 0 ) { // read the Payment Plugin property file and initialize the // PluginProperties class PluginProperties.getReference().load( new FileInputStream( args[0] ) );
}
// extends class BasicConfigurator from log4j to provide // configuration from an external file PropertyConfigurator.configure( PluginProperties.getReference() );
// verify the properties specified by the user // PluginProperties.getReference().verify();
// obtain a reference to the PaymentConnectionFactory // PaymentConnectionFactory factory = PaymentConnectionFactory.getReference();
// get a new connection from the factory
A50020-A3245-K-2-76D6
87
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
PaymentConnection conn = factory.getConnection(); // Instantiate a payment request // either calling the default constructor and subsequent set // methods or the overloaded constructor with arguments for all // request parameters TAStateReq req = new TAStateReq(); req.setTransactionID("100000000001");
// Use the connection to execute requests on the payment@vantage // server. PaymentResponse conf = conn.execute( req ); // Check the status of the execution. // Error codes are documented in the Payment@vantage Interface // Specification. // Additional error codes are generated by the PaymentPlugin. int status = conf.getExecutionStatus(); System.out.println( "Status for TransactionID " + conf.getTransactionID() + " = " + status );
// Finally close the PaymentConnection. // This will free all the resources allocated for this connection. conn.close(); } catch ( Exception ex ) { System.out.println( "Uncaught exception: " + ex.getLocalizedMessage() ); } System.exit( 0 ); }
g The start script is similar to that used in section 6.2.5 Example of a Recharge Request Using the Java Library PaymentPlugin.jar.
88 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d8058020b05e
Appendix
6.2.7 Example of an EJB Using the J2EE Connector Interface
Introduction This section gives an example of a simple EJB implementation that uses the J2EE con-nector interface of the Payment Plugin to send chargeAmount requests to the online charging server.
Example /* Copyright (c) Siemens AG 2000,2001,2002 All Rights Reserved The reproduction, transmission or use of this document or its contents is not permitted without express written authority. Offenders will be liable for damages. All rights, including rights created by patent grant or registration of a utility model or design, are reserved. Technical modifications possible. Technical specifications and features are binding only insofar as they are specifically and expressly agreed upon in a written contract.*/
import javax.ejb.SessionContext;import javax.ejb.EJBException;import java.rmi.RemoteException;import javax.ejb.SessionBean;import javax.naming.*;import de.siemens.advantage.payment.payplugin.intf.connector.*;import de.siemens.advantage.payment.payplugin.impl.processing.ChargeAmountReq;import de.siemens.advantage.payment.payplugin.impl.processing.PaymentResponse;
public class ChargingBean implements SessionBean {
public ChargingBean() { System.out.println( "ChargingBean()" ); }
public void setSessionContext( SessionContext sc ) throws javax.ejb.EJBException, java.rmi.RemoteException { ctx = sc; }
public void ejbCreate() throws javax.ejb.EJBException, java.rmi.RemoteException { System.out.println("ChargingBean.ejbCreate()"); try { Context initCtx = new InitialContext(); Object obj = initCtx.lookup( "java:comp/env/eis/PaymentConnector"); factory = (PayAdvConnectionFactory) obj; }
catch ( Exception ex ) { System.err.println( ex ); throw new RemoteException( ex.getMessage() );
} }
public void ejbRemove() throws javax.ejb.EJBException, java.rmi.RemoteException { System.out.println("ChargingBean.ejbRemove()"); factory = null;
}
public void ejbActivate() throws javax.ejb.EJBException, java.rmi.RemoteException { System.out.println("ChargingBean.ejbActivate()");
}
public void ejbPassivate() throws javax.ejb.EJBException, java.rmi.RemoteException { System.out.println("ChargingBean.ejbPassivate()");
}
A50020-A3245-K-2-76D6
89
DMN:Payment Plugin Interface Appendix
Id:0900d8058020b05e
public int charge( String tid, String userId, long accountId, String pin, String productId, String purpose, long amount ) throws java.rmi.RemoteException { // System.out.println("ChargingBean.charge()"); PayAdvConnection conn = null; ChargeAmountReq req = new ChargeAmountReq( tid, (short) 0, "Mr. Bean", "0815", "www.dummy.org", purpose, userId, accountId, pin, "merchant name", productId, "EUR", amount ); PaymentResponse resp = null; try { conn = factory.getConnection(); resp = conn.execute( req ); return resp.getExecutionStatus(); } catch ( Exception ex ) { System.err.println( "exception in charge: " + ex );
ex.printStackTrace(); throw new RemoteException( ex.getMessage() );
} finally { if ( conn != null ) { try { conn.close(); } catch (Exception ex) { System.err.println( "charge: Error while closing connection: " + ex ); ex.printStackTrace(); }
} } }
private SessionContext ctx; private PayAdvConnectionFactory factory;}
g Some of the attributes of the ChargeAmountReq instance are hardcoded for conve-nience.
90 A50020-A3245-K-2-76D6
DMN:Payment Plugin Interface
Id:0900d80580208b4d
Index
Aabsolute date 22, 24accessFrontendID 20accountID 20accountList 20accountType 20additionalMoneyToAuthorize 20adviceOfCharge
operation 39adviceOfChargeConf
operation 40approved 20AuthorizationTimeoutClass 23, 25authorizeAmount
operation 31, 33
CcalculatedMoney 20captureAmount
operation 35certificate 12chargeAmount
operation 29clearingInstrument 21clearingPeriod 21clearingPolicy 21clearingThreshold 21confirmation 14confirmation message 14confirmation timeout 15currency 21currentAuthorizedAmount 21currentBalance 21
Ddata types 19date 22dateOfLastRecharge 21
EEIS 71enterprise information system 71error 22executionStatus 22expiry date 44expiryDate 22
values 43ExpiryDateOrDays 23, 25ExpiryMode 45
FfinalizeAuthorization 22firstRate 23
GgetConsumerAccountList
confirmation operation 59operation 57
HHTTP request 77HTTP response 77
Iinterface
external 14internal 14
internal timer 14
JJ2EE 70J2EE connector architecture 71Java 2 Enterprise Edition 70Java Secure Socket Extension (JSSE) 12JCA 71
LlastBalanceModDate 23
Mmanual
conventions 9purpose 7structure 8target group 7
mapping tableauthorizeAmount 31, 33captureAmount 35chargeAmount 29getAccountListConf 59getConsumerAccountList 57, 62rechargeAmount 42, 44refund 48simple confirmation 49transferAmount 37, 39, 40, 41
merchantID 23message sequence 14
A50020-A3245-K-2-76D6
91
DMN:Payment Plugin Interface
Id:0900d80580208b4d
modeof AuthorizationTimeoutClass 23of ExpiryDateOrDays 23
money 23moneyToAuthorize 23
NnewExpiryDate 24, 43, 45
OoldExpiryDate 24online charging server 7, 11originalChargeTime 24originalPrice 24ownerID 24
Ppayment operation 16pin 24productID 24purpose 24purpose of the manual 7
RrechargeAmount
operation 42, 44rechargedMoney 24refund
operation 48refundTA
operation 41request 14response timeout 14RoleID 25routingInfo 25
Ssample property file 66Secure Sockets Layer (SSL) 12sequence of messages 14servlet application 17simple confirmation
operation 49SSL 12structure of manual 8styles used in manual 9symbols 9
Ttarget group
manual 7time span 22, 24
timeout 14timer
internal 14transactionID 25, 26transferAmount
operation 37transparentData 25
UuserID 25
Vvalue
of AuthorizationTimeoutClass 25of ExpiryDateOrDays 25
virtual account 44