Payment Interface - Technical Description

1

Payment Interface

Prepaid 4.3.8

Technical Description

5035581/9 2

2

Payment Interface 3

3Copyright 4 5 6 7 8

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: [email protected].

9Disclaimer 10 11 12 13 14

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.

15Feedback 16 17 18 19

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: [email protected].

20Trademarks and Registered Trademarks 21 22

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

23Revision History Version Issued 1

12.07.2006

Supports Prepaid 4.3.8.

2.

14.07.2006

‘Input 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.

3

28.08.2006

Sections 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.

4

31.08.2006

Added Section 4.16.4.

5

20.09.2006

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

6

28.11.2006

Updated Output Seq parameters in fundAccountTransfer operation.

7

20.09.2007

Updated packageRecharge Minor Result Code 11.

5035581/9 4

Description

Copyright © Tecnomen Corporation 2008

Payment Interface 5

Version Issued

Description

8

15.05.2008

updated the fundTransfer minor result codes.

9

26.05.2008

Added PaymentEngine::voucherRecharge operation

Document Status Issue date

5035581/9 Issued 26.05.2008

Author Editor Acceptor

Louise Naimi Louise Naimi Louise Naimi

Payment Interface 7

Preface

24

25About 26 27

This Document This document describes Tecnomen’s Payment Interface as a centralised payment related service.

28Audience 29

This document is intended for Tecnomen personnel and customer use.

30

This document assumes familiarity with Tecnomen’s Prepaid 4.3.8 Release.

31Notational 32

Conventions

The following margin symbols may be used throughout this document.

33Margin Symbols 34

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

35 Note:

Used to highlight important procedures or tips.

36 Caution: Used to highlight procedures you must follow exactly. 37 Warning:

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

38 39

5035581/9 8

Copyright © Tecnomen Corporation 2008

Contents

i

9

Contents

40

411. 42 43 44 45 46 47 48

INTRODUCTION..............................................................................................................................1 1.1. Tecnomen’s Prepaid Architecture.............................................................................................1 1.1.1. SDP/PSP.......................................................................................................................1 1.2. What is the PaymentEngine ?...................................................................................................1 1.3. Multiple Client Support............................................................................................................2 1.4. Authentication Server Process..................................................................................................3 1.4.1. Authserver.....................................................................................................................3 1.5. Mediation Device Router (MDR) Support...............................................................................4

492. 50

PAYMENTINTERFACE TUTORIAL...............................................................................................5 2.1. High-Level Logical Flow.........................................................................................................5

513. 52 53 54 55 56 57 58 59 60 61

DETAILED CALL SEQUENCE.......................................................................................................7 3.1. Connect to the AuthServer........................................................................................................7 3.1.1. Using resolve_initial_references(“AuthFactory”).......................................................7 3.1.2. Using AuthServer IOR File...........................................................................................8 3.2. Authenticate..............................................................................................................................9 3.3. Get the PaymentEngine Factory’s IOR.....................................................................................9 3.4. Connect to the PaymentEngine Factory.................................................................................10 3.5. Get a PaymentEngine Instance...............................................................................................10 3.6. Call directFundTransfer..........................................................................................................10 3.7. Extract Results........................................................................................................................10 3.8. Disconnecting from the PaymentEngine................................................................................11

624. 63 64 65 66 67 68 69 70 71 72 73 74 75 76

PAYMENT INTERFACE OPERATIONS.......................................................................................12 4.1. Account Details Return Result Structure................................................................................12 4.2. Account Details Return Result Sequence...............................................................................13 4.2.1. Major Return Codes....................................................................................................14 4.3. PaymentEngine::directFundTransfer Operation.....................................................................16 4.3.1. Input Parameters.........................................................................................................17 4.3.2. CDRs Generated by directFundTransfer.....................................................................17 4.3.3. directFundTransfer Minor Result Codes.....................................................................17 4.4. PaymentEngine::directFundTransferSeq Operation...............................................................18 4.4.1. Input Parameters.........................................................................................................19 4.4.2. CDRs generated by directFundTransferSeq...............................................................20 4.4.3. directFundTransferSEQ Minor Result Codes.............................................................20 4.5. PaymentEngine::directDebitTransfer Operation....................................................................21 4.5.1. Input Parameters.........................................................................................................21 4.5.2. CDRs Generated by directDebitTransfer....................................................................22

Copyright © Tecnomen Corporation 2008

Payment Interface 5035581/9

ii

Contents

11

77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117

4.6.

4.7.

4.8.

4.9.

4.10.

4.11.

4.12. 4.13.

4.14.

4.15.

4.16.

4.17.

4.5.3. directDebitTransfer Minor Result Codes....................................................................22 PaymentEngine::directDebitTransferSeq Operation..............................................................22 4.6.1. Input Parameters.........................................................................................................23 4.6.2. CDRs generated by directDebitTransferSeq...............................................................23 4.6.3. directDebitTransferSeq Minor Result Codes..............................................................23 PaymentEngine::onlineFundTransfer Operation....................................................................24 4.7.1. Input Parameters.........................................................................................................25 4.7.2. CDRs Generated by onlineFundTransfer....................................................................25 4.7.3. onlineFundTransfer Minor Result Codes....................................................................25 PaymentEngine::onlineFundTransferSeq Operation..............................................................26 4.8.1. Input Parameters.........................................................................................................27 4.8.2. CDRs generated by onlineFundTransferSeq...............................................................27 4.8.3. onlineFundTransferSeq Minor Result Codes..............................................................27 PaymentEngine::periodFundTransfer Operation....................................................................28 4.9.1. Input Parameters.........................................................................................................29 4.9.2. CDRs Generated by periodFundTransfer...................................................................29 4.9.3. periodFundTransfer Minor Result Codes...................................................................29 PaymentEngine::periodFundTransferSeq Operation..............................................................30 4.10.1. Input Parameters.........................................................................................................31 4.10.2. CDRs generated by periodFundTransferSeq..............................................................32 4.10.3. periodFundTransferSeq Minor Result Codes.............................................................32 PaymentEngine::fundTransfer................................................................................................32 4.11.1. Input pSeq (Parameter Sequence)...............................................................................35 4.11.2. Output dSeq (Data Sequence).....................................................................................38 4.11.3. fundTransfer Minor Result Codes...............................................................................39 PaymentEngine::FundAccountTransfer..................................................................................39 PaymentEngine::accountUpdate.............................................................................................42 4.13.1. Input Parameters.........................................................................................................43 4.13.2. CDRs Generated by accountUpdate...........................................................................43 4.13.3. account Update Minor Result Codes..........................................................................44 PaymentEngine::accountUpdateSeq Operation......................................................................44 4.14.1. Input Parameters.........................................................................................................45 4.14.2. CDRs generated by accountUpdateSeq......................................................................45 4.14.3. accountUpdateSeq Minor Result Codes.....................................................................46 PaymentEngine::accountQuery..............................................................................................46 4.15.1. Input Parameters.........................................................................................................47 4.15.2. Account Query Minor Return Codes..........................................................................47 PaymentEngine::accountQuerySeq Operation.......................................................................48 4.16.1. Input Parameters.........................................................................................................48 4.16.2. accountQuerySeq Minor Return Codes......................................................................48 paymentEngine::packageRecharge Operation........................................................................49

Payment Interface 5035581/9

Copyright © Tecnomen Corporation 2008

Contents 13

118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146

4.18.

4.19.

4.20.

4.21. 4.22. 4.23. 4.24. 4.25.

iii

4.17.1. Input Sequence (pSeq Contents).................................................................................49 4.17.2. CDRs Generated by packageRecharge.......................................................................50 4.17.3. packageRecharge Minor Result Codes.......................................................................50 4.17.4. Package Refund..........................................................................................................52 PaymentEngine::voucherRecharge Operation........................................................................53 4.18.1. Input Parameters.........................................................................................................53 4.18.2. CDRs generated by voucher recharge.........................................................................53 4.18.3. Return Code................................................................................................................53 ASyncEngine::voucherRecharge Operation...........................................................................55 4.19.1. Input Parameters.........................................................................................................55 4.19.2. CDRs Generated by voucherRecharge.......................................................................56 4.19.3. Return Code................................................................................................................56 ASyncEngine::voucherRechargeSeq Operation.....................................................................56 4.20.1. Input Parameters.........................................................................................................56 4.20.2. CDRs Generated by voucherRecharge.......................................................................57 4.20.3. Return Code................................................................................................................57 VoucherJobMgr::getJobDetails Operation..............................................................................57 4.21.1. Input Parameters.........................................................................................................58 VoucherJobDetails Return Result Structure...........................................................................58 VoucherJobMgr::getJobDetailsSeqOperation.........................................................................62 4.23.1. Input Parameters.........................................................................................................62 VoucherJob Details Return Result Sequence..........................................................................63 PI Exceptions..........................................................................................................................66 4.25.1. General Error Codes...................................................................................................66 4.25.2. IDL GW Specific Error Codes....................................................................................66 4.25.3. User/Subscriber Error Codes......................................................................................66 4.25.4. Voucher Error Codes...................................................................................................67 4.25.5. Job Control Error Codes.............................................................................................68 4.25.6. Payment Engine Error Codes......................................................................................69

147APPENDIX A: AUTHFACTORY.IDL...................................................................................................70 148APPENDIX B: EXCEPTIONS.IDL.......................................................................................................71 149APPENDIX C: TINCDEFS.IDL.............................................................................................................72 150APPENDIX D: TYPES.IDL...................................................................................................................73 151APPENDIX E: PAYMENTENGINE.IDL..............................................................................................74 152APPENDIX F: AUTHFACTORY_IMPL.JAVA.....................................................................................75 153APPENDIX G: PAYMENTENGINE.JAVA...........................................................................................80 154APPENDIX H: RECHARGECLIENT.JAVA.........................................................................................84 155APPENDIX I: RECHARGECLIENT.SH...............................................................................................97

Copyright © Tecnomen Corporation 2008

Payment Interface 5035581/9

iv

Contents

15

156APPENDIX J: TRACE.JAVA.................................................................................................................98 157APPENDIX K: SIMPLECLIENT.JAVA.................................................................................................99 158APPENDIX L: TPEDEFS.IDL.............................................................................................................100 159DEFINITIONS AND REFERENCES..................................................................................................101 160 161

Payment Interface 5035581/9

Copyright © Tecnomen Corporation 2008

1 17

1. Introduction

162 163 164

Tecnomen’s PaymentEngine provides access to a well defined set of payment related functionality for both internal and external use. PaymentInterface is a product name for the PaymentEngine and supports external operations.

Note: 1651.1.

Tecnomen’s Prepaid Architecture

166 167

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

168 169 170 171 172 173



  

Database Layer consisting:  Service Data Point (SDP)  Prepaid Support Point (PSP) Service Layer Signalling Layer Network Layer

1.1.1. SDP/PSP

174 175 176 177

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).

178 179

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

180

1.1.1.1.

181 182

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

1.2.

183

HA Failover / Failback Support

What is the PaymentEngine ?

184 185 186 187 188

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.

189 190 191 192

Tecnomen’s 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.

Copyright © Tecnomen Corporation 2008

Payment Interface 5035581/9

2 19

193 194 195 196 197 198 199

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.

200 201

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.

202 203

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

1.3.

204

Multiple Client Support

205 206 207

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

208 209

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

IDL Operations* Login

Return IOR

Login

PSP

authServer

Return IOR

PaymentEngine PaymentEngine [PaymentInterface PaymentEngine PaymentEngine PaymentEngine 1-50]

IDL Operations*

IDL Operations * directFundTransfer directDebitTransfer onlineFundTransfer periodFundTransfer fundTransfer

Return IOR Login

IDL Operations*

SDP

210 211

Figure 1-1 Overview of Tecnomen’s Payment Engine

Payment Interface 5035581/9

Copyright © Tecnomen Corporation 2008

3 21

212 213 214 215

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

1.4.

216 217 218 219 220 221

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

222 223 224

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.

225 226 227 228

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 that’s persistently stored in the CC_DB. Caching reduces the dependency on CC_DB (and hence the Customer Care host) requirement of being available.

229 230

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

231 232 233 234 235

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.

236

Note: 237 238

Mediation Device Router (MDR) Support 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/.

Copyright © Tecnomen Corporation 2008

Payment Interface 5035581/9

4 23

2. PaymentInterface Tutorial

239 240 241

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

242 243 244 245

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.

246 247

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.

248 249 250

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.

251 252

High-Level Logical Flow The essential steps that need to be covered are the following :-

253

1. Get a handle on the authServer

254

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

255 256 257

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).

258 259

4. Use the PaymentEngine Factory’s IOR to get a handle to the PaymentEngine Factory.

260 261

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

262 263

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

264 265

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

266 267 268

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.

269 270 271

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.

272 273 274

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.

Payment Interface 5035581/9

Copyright © Tecnomen Corporation 2008

5 25

275 276 277

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.

278 279 280

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.

281 282 283 284

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 Factory’s releasePaymentEngine(), releaseAsyncEngine operations.

285 286

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

287 288 289 290

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.

291 292 293

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

294 295 296 297

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.

298 299 300 301

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 time1.

26 27

1

The PaymentEngine Factory will eventually notice that there exists a ‘stale’ paymentEngine, however this might take some considerable time, typically about 60 minutes.

Copyright © Tecnomen Corporation 2008

Payment Interface 5035581/9

6 29

3. Detailed Call Sequence

302

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.

303

Connect to the AuthServer

304 305

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

306 307 308

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.

309 310 311

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”)

312 313 314 315

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.

316

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

317 authServer -ORBEndpoint iiop://PSP:1500 318 319 320

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.

321 322

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

323 clientProcess -ORBInitRef AuthFactory=corbaloc:iiop:PSP:1500/AuthServer 324 325 326

A typical C++ client then uses the following commands to bind to the server :Payment Interface 5035581/9

Copyright © Tecnomen Corporation 2008

7 31

327 // 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