PP 4.3.7 Payment Interface

Payment Interface

Payment Interface

Bookmarks: Version: 9 ;status: Issued ; author: Donncha Daly ; editor: Louise Naimi ; acceptor: Louise Naimi ; issued: 26/05/2008 ; template: 1

Payment Interface

Prepaid 4.3.8

Technical Description

5035581/9

Copyright

Copyright Tecnomen Corporation 2008. All rights reserved. No part of this document may be reproduced, distributed, stored in a retrieval system or translated into any language, in any form or by any means, electronic, mechanical, magnetic, optical, photocopying, manual or otherwise, without the prior written permission of Tecnomen. For additional copies of the document, please contact Tecnomen by e-mail: feedback@tecnomen.com.

Disclaimer

Tecnomen makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Tecnomen reserves the right to revise this publication and to make changes from time to time in the contents hereof without obligation to notify any person of such revision or changes.

Feedback

Tecnomen endeavours to provide accurate and useful documentation for all Tecnomen products. To achieve this goal, the documentation group welcomes your comments and suggestions regarding any aspect of Tecnomen user documentation. Send your comments by e-mail to: feedback@tecnomen.com.

Trademarks and Registered Trademarks

Products and product names mentioned in this document may be trademarks or registered trademarks of their respective owners.

Revision History

VersionIssuedDescription

112.07.2006Supports Prepaid 4.3.8.

2.14.07.2006Input Parameters added to accountQuery Operation section. Input Parameters added to accountUpdate Operation section. Input Parameters added to periodFundTransfer Operation section. Added the following new sections: onlineFundTransferSeq Operation; PeriodFundTransferSeq Operation; directDebitTransferSeq Operation; directFundTransferSeq Operation; accountUpdateSeq Operation and accountQuerySeq Operation.

328.08.2006Sections 2.1 and 4.1 was updated and the following new sections were added: 4.2, 4.16, 4.17, 4.18, 4.19, 4.20, 4.21 and 4.22. PaymentEngine:: was added to the name of the operation in sections 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 4.9, 4.10, 4.11, 4.12, 4.13, 4.14 and 4.15.

431.08.2006Added Section 4.16.4.

520.09.2006Supports Prepaid 4.3.8. Added Section 4.12 FundAccountTransfer. Updated Section 4.17 PackageRecharge Operation.

628.11.2006Updated Output Seq parameters in fundAccountTransfer operation.

720.09.2007Updated packageRecharge Minor Result Code 11.

815.05.2008updated the fundTransfer minor result codes.

926.05.2008Added PaymentEngine::voucherRecharge operation

Preface

About This Document

This document describes Tecnomens Payment Interface as a centralised payment related service.

Audience

This document is intended for Tecnomen personnel and customer use.

This document assumes familiarity with Tecnomens Prepaid 4.3.8 Release.

Notational Conventions

The following margin symbols may be used throughout this document.

Margin Symbols

Notes, cautions and warnings appear to highlight important or critical procedures and tips.

Note:Used to highlight important procedures or tips.

Caution:Used to highlight procedures you must follow exactly.

Warning:Used to highlight critical procedures you must follow exactly. Otherwise, you may experience data loss or application failure.

Contents

11.Introduction

1.1.Tecnomens Prepaid Architecture11.1.1.SDP/PSP11.2.What is the PaymentEngine ?11.3.Multiple Client Support21.4.Authentication Server Process31.4.1.Authserver31.5.Mediation Device Router (MDR) Support42.PaymentInterface Tutorial52.1.High-Level Logical Flow53.Detailed Call Sequence73.1.Connect to the AuthServer73.1.1.Using resolve_initial_references(AuthFactory)73.1.2.Using AuthServer IOR File83.2.Authenticate93.3.Get the PaymentEngine Factorys IOR93.4.Connect to the PaymentEngine Factory103.5.Get a PaymentEngine Instance103.6.Call directFundTransfer103.7.Extract Results103.8.Disconnecting from the PaymentEngine114.Payment Interface Operations124.1.Account Details Return Result Structure124.2.Account Details Return Result Sequence134.2.1.Major Return Codes144.3.PaymentEngine::directFundTransfer Operation164.3.1.Input Parameters174.3.2.CDRs Generated by directFundTransfer174.3.3.directFundTransfer Minor Result Codes174.4.PaymentEngine::directFundTransferSeq Operation184.4.1.Input Parameters194.4.2.CDRs generated by directFundTransferSeq204.4.3.directFundTransferSEQ Minor Result Codes204.5.PaymentEngine::directDebitTransfer Operation214.5.1.Input Parameters214.5.2.CDRs Generated by directDebitTransfer224.5.3.directDebitTransfer Minor Result Codes224.6.PaymentEngine::directDebitTransferSeq Operation224.6.1.Input Parameters234.6.2.CDRs generated by directDebitTransferSeq234.6.3.directDebitTransferSeq Minor Result Codes234.7.PaymentEngine::onlineFundTransfer Operation244.7.1.Input Parameters254.7.2.CDRs Generated by onlineFundTransfer254.7.3.onlineFundTransfer Minor Result Codes254.8.PaymentEngine::onlineFundTransferSeq Operation264.8.1.Input Parameters274.8.2.CDRs generated by onlineFundTransferSeq274.8.3.onlineFundTransferSeq Minor Result Codes274.9.PaymentEngine::periodFundTransfer Operation284.9.1.Input Parameters294.9.2.CDRs Generated by periodFundTransfer294.9.3.periodFundTransfer Minor Result Codes294.10.PaymentEngine::periodFundTransferSeq Operation304.10.1.Input Parameters314.10.2.CDRs generated by periodFundTransferSeq324.10.3.periodFundTransferSeq Minor Result Codes324.11.PaymentEngine::fundTransfer324.11.1.Input pSeq (Parameter Sequence)354.11.2.Output dSeq (Data Sequence)384.11.3.fundTransfer Minor Result Codes394.12.PaymentEngine::FundAccountTransfer394.13.PaymentEngine::accountUpdate424.13.1.Input Parameters434.13.2.CDRs Generated by accountUpdate434.13.3.account Update Minor Result Codes444.14.PaymentEngine::accountUpdateSeq Operation444.14.1.Input Parameters454.14.2.CDRs generated by accountUpdateSeq454.14.3.accountUpdateSeq Minor Result Codes464.15.PaymentEngine::accountQuery464.15.1.Input Parameters474.15.2.Account Query Minor Return Codes474.16.PaymentEngine::accountQuerySeq Operation484.16.1.Input Parameters484.16.2.accountQuerySeq Minor Return Codes484.17.paymentEngine::packageRecharge Operation494.17.1.Input Sequence (pSeq Contents)494.17.2.CDRs Generated by packageRecharge504.17.3.packageRecharge Minor Result Codes504.17.4.Package Refund524.18.PaymentEngine::voucherRecharge Operation534.18.1.Input Parameters534.18.2.CDRs generated by voucher recharge534.18.3.Return Code534.19.ASyncEngine::voucherRecharge Operation554.19.1.Input Parameters554.19.2.CDRs Generated by voucherRecharge564.19.3.Return Code564.20.ASyncEngine::voucherRechargeSeq Operation564.20.1.Input Parameters564.20.2.CDRs Generated by voucherRecharge574.20.3.Return Code574.21.VoucherJobMgr::getJobDetails Operation574.21.1.Input Parameters584.22.VoucherJobDetails Return Result Structure584.23.VoucherJobMgr::getJobDetailsSeqOperation624.23.1.Input Parameters624.24.VoucherJob Details Return Result Sequence634.25.PI Exceptions664.25.1.General Error Codes664.25.2.IDL GW Specific Error Codes664.25.3.User/Subscriber Error Codes664.25.4.Voucher Error Codes674.25.5.Job Control Error Codes684.25.6.Payment Engine Error Codes69Appendix A: AuthFactory.idl70Appendix B: Exceptions.idl71Appendix C: TINCdefs.idl72Appendix D: Types.idl73Appendix E: PaymentEngine.idl74Appendix F: AuthFactory_impl.java75Appendix G: PaymentEngine.java80Appendix H: RechargeClient.java84Appendix I: RechargeClient.sh97Appendix J: Trace.java98Appendix K: SimpleClient.java99Appendix L: TPEDefs.idl100Definitions and References101

1. Introduction

Tecnomens PaymentEngine provides access to a well defined set of payment related functionality for both internal and external use.

Note:PaymentInterface is a product name for the PaymentEngine and supports external operations.

1.1. Tecnomens Prepaid Architecture

With the introduction of Tecnomen Prepaid 4.3 a new Prepaid system architecture is implemented. The new architecture consists of four basic functional layers:

Database Layer consisting:

Service Data Point (SDP)

Prepaid Support Point (PSP)

Service Layer

Signalling Layer

Network Layer

1.1.1. SDP/PSP

The Service Data Point (SDP) provides the Service Control Function (SCF) with access to the data required by service logic programs (e.g. subscriber data). Therefore, the SDP contains the Service Data Function (SDF).

The Prepaid Support Point (PSP) provides additional support functionality for Tecnomens Prepaid Service e.g. Short Message Notification, PaymentEngine, Agenda Manager etc.

1.1.1.1. HA Failover / Failback Support

Refer to the Tecnomen Customer Care Technical Description for details on HA Failover support.

1.2. What is the PaymentEngine ?

The existing IDL Gateway, which supports a generic interface to the Tecnomen Prepaid Service will co-exist with the PaymentEngine. The various payment related operations use the PaymentEngine to carry out the work. The difference between the existing IDL Gateway and the PaymentEngine is the IDL Gateway is optimised for generality, whilst the PaymentEngine is optimised for speed.

Tecnomens PaymentEngine is a centralised payment related service carrying out all ancillary payment operations, other than general Prepaid Service Call Handling logic, in a secure environment. The secure aspect, is enforced via the authServer Authentication Service, as described later.

Based on a CORBA TAO http://www.ociweb.com and SQLAPI++ http://www.sqlapi.com implementation, the PaymentEngine is a multi-threaded process executing all charging and recharging functionality, such as voucher and credit recharges in addition to onlineFundTransfer (renamed bankRecharge / genericRecharge), directFundTransfer, PeriodFundTransfer, AccountQuery and AccoundUpdate operations in a secure environment. The paymentEngine generates all MDR (Mediation Device Router) files, as well as any CDR relating to account recharges.

The diagram below (Fig 1-1) depicts the high-level architecture of the PaymentEngine and AuthServer being hosted on the PSP, in relation to the SDP.

The various permitted PaymentEngine operations are detailed, as being called via one or more either internal or external clients.

1.3. Multiple Client Support

Each PaymentEngine instance will support a certain Transaction Per Second (TPS) call rate, governed by the platform its running on, restrictions imposed by the PSP and SDP platforms and finally a Licenced TPS limit, per engine.

To achieve higher TPS rates it may be necessary, to use multiple clients to achieve the overall call rate required.

Figure 11 Overview of Tecnomens Payment Engine

It is necessary to properly disconnect from the PaymentEngine using the PaymentEngine Factorys releasePaymenEngine() operation. Failure to do this will stop further getPaymentEngine() requests from being honoured for a period of time, until the PaymentEngine Factorys scheduled eviction procedure is activated.

1.4. Authentication Server Process

The authServer acts as a secure Naming Service for all CORBA based processes, including the rechargeGateway. All CORBA processes register with the authServer at startup time. Any clients that wish to access any of the available services must first authenticate via the authServer using a valid login / password combination. The authServer will then hand out the necessary connection information, as appropriate, to the client.

1.4.1. Authserver

The job of the authServer is to hand out connection information (amongst other things) to clients that request them, after a login/password authentication dialogue has taken place.

The authServer has additionally an element of fault tolerance built in. Upon startup, or whenever requested, the authServer will read and cache the current user login/password information thats persistently stored in the CC_DB. Caching reduces the dependency on CC_DB (and hence the Customer Care host) requirement of being available.

An additional aspect of the authServer is that it enables central control of transaction rate settings for any and all processes that use it.

Upon startup, the PaymentEngine, for instance, registers its IOR (CORBA Interoperable Object Reference) with authServer and is subsequently given both a unique key, for use in authorising subsequent getPaymentEngine() requests from clients, and one or more parameters to control the number of engines (threads) allowed, and the max TPS allowed per engine.

1.5. Mediation Device Router (MDR) Support

Note:MDR file generation is configurable On / Off system wide.

Mediation Device Router file generation is supported. For further information on the Mediation Device Router (MDR), see ref. /1/.

2. PaymentInterface Tutorial

The following sections describe, in detail, the steps necessary to successfully interface to the PaymentInterface.

The necessary CORBA IDL definitions of the required interfaces are in the appendix. The supplied sample code, in the appendix, is written in java. We also supply, with the delivery, the C++ source code for a simple load test tool that is more realistic, in terms of what a typical C++ client will need to do.

This tutorial, whilst concentrating on the java sample code, is applicable at a high level to the C++ code. All the same logical steps are required, no matter what language is used.

The full IDL definitions of all necessary components are listed in the appendices, including all necessary return codes (in Appendix E: PaymentEngine.idl) and error codes (in Appendix C: TINCdefs.idl)

2.1. High-Level Logical Flow

The essential steps that need to be covered are the following :-

1. Get a handle on the authServer

2. Authenticate with the authServer using its login() method

3. Get a PaymentEngineFactory IOR. Parse the returned sequence of data from the authServer looking for an instance of a PaymentEngine Factory, and extract the required IOR (CORBA Interroperable Object Reference).

4. Use the PaymentEngine Factorys IOR to get a handle to the PaymentEngine Factory.

5. Use the PaymentEngine Factorys getPaymentEngine() method to create a PaymentEngine instance for this client.

6. Use the PaymentEngine Factorys getAsyncEngine() method to create a ASyncEngine instance for this client.

7. Use the PaymentEngine Factorys getVoucherJobMgr() method to create a VoucherJobMgr instance for this client.

8. Use the paymentEngine thus obtained, to call available operations, such as directFundTransfer, directDebitTransfer, etc., as per the provided CORBA IDL specification of the PaymentEngine. See appendix E.

9. Use the AsyncEngine thus obtained, to call available operations, such as voucherRecharge, voucherRechargeSeq, etc., as per the provided CORBA IDL specification of the PaymentEngine. See appendix E.

Note: The voucherRecharge and voucherRechargeSeq will return a job number which must be used in the getJobDetails and getJobDetailsSeq to determine if the voucherRecharge request completed.

10. Use the VoucherJobMgr thus obtained, to call available operations, such as getJobDetails, getJobDetailsSeq, etc., as per the provided CORBA IDL specification of the PaymentEngine. See appendix E.

11. Repeat step 8, 9 and 10 repeatedly, until there is a need, at some point, to disconnect; the concept being that the clients will have a long lived connection to the paymentEngine.

12. Upon exit of the client, the client MUST remember to properly disconnect from the PaymentEngine and AsyncEngine that it currently has. This is achieved by using the PaymentEngine Factorys releasePaymentEngine(), releaseAsyncEngine operations.

Note: There is no need to release the VoucherJobMgr as it is static and is shared amoung all clients.

It is important to realise that there is an overhead in asking the PaymentEngine Factory for a paymentEngine, especially if you consider the process of first authenticating with the authServer, and in general carrying out steps 1 to 5 above.

The client should do all of its authentication once, at the beginning, and from then on just use the provided PaymentEngine CORBA handle to execute the required payload operations.

The only other circumstance under which a client is required to request for a new paymentEngine, is in the event that something goes wrong, i.e. some error condition at the process or CORBA level, at which time the client must assume that it must re-authenticate, and thus get a new PaymentEngine handle, as per the above sequence.

Finally, it is vital that the client, is a well-behaved client, in so much as the client MUST follow the proper disconnection sequence, as detailed later. Essentially, this means using the factories releasePaymentEngine() operation, before the client exits. Failure to do this will cause the clients to be blocked from subsequent access for a period of time.

3. Detailed Call Sequence

Caution:In order to comply with Java 1.4.x requirements, all code must be scoped into modules, i.e must be packaged. All code relevant to the CORBA Payment Interface and this manaul has been placed in the TINC (Tecnomen Intelligent Network Customer Care) name space.

3.1. Connect to the AuthServer

The authServer is a central authentication service. All client processes, whether internal or external must use it to authenticate the client.

Upon successful authentication, the authServer will hand back to the calling client the necessary data required to attach to one or more permitted services within the Tecnomen system.

There is no other way to connect to any Tecnomen process, without first having to go to the authServer, since it acts as both a Secure Naming Service and an authentication Service.

3.1.1. Using resolve_initial_references(AuthFactory)

The authServer uses a Persistant Lifespan Policy. Clients can use the CORBA::ORB::resolve_initial_references() mechanism to bind to the service, just like they would to bind to the NamingService.

The authServer is started with an ORBEndpoint specification, as follows:-

authServer -ORBEndpoint iiop://PSP:1500

From the above command we see that the server is using an IIOP (Internet Inter-Operable Protocol) transport. The process is registered to listen on port 1500 on the PSP host.

To connect to the authServer, the client is started by specifying a corbaloc object reference that looks somewhat similar to the command below:-

clientProcess -ORBInitRef AuthFactory=corbaloc:iiop:PSP:1500/AuthServer

A typical C++ client then uses the following commands to bind to the server :-

// First we initialise the ORB

CORBA::ORB_var orb = CORBA::ORB_init(argc, argv);

// Finally, we get a reference using resolve_initial_references()

CORBA::Object_var obj = orb->resolve_initial_references(AuthFactory);

AuthFactory_var factory = AuthFactory::_narrow(obj.in());

If (CORBA::is_nil(factory.in())) {

Cerr