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


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


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



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



iv

Contents

15

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



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.



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



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



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.



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.



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


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 << “AuthFactory::_Narrow() failed !” << endl; Return 1; } 328 329 330 331

Appendix J shows a simple java client using the same mechanism. On line 32, in the SimpleClient.java file, we see the specification of the ‘corbaloc’ string in the usage section of this class.

332 333

As can be seen from this example, the steps involved in connecting to the AuthFactory are much simplified, with the knowledge of the hostname and port number of the AuthServer. 3.1.2. Using AuthServer IOR File

334 335

Upon startup, the authServer will deposit its IOR according to the Server Config setting

336

(corbaIORdir). The default location is:

337 338

/mountp/var/ior/authServer.ior

339 Note:

If the IOR is not in the default location please contact the Tecnomen Project Engineer for assistance.

340 341 342 343 344

To connect to the authServer, the client must first be able to access this IOR file, load it, and then use it in combination with the CORBA::string_to_object(iorString) method to get a handle on the authServer itself. Appendix F details this step on line 43, of the AuthFactory_impl.java code.

345 346

The AuthFactory_impl constructor, takes as it’s second argument the file name in which the authServer IOR is located.

347

Appendix F, line 23, a helper function is used to read in the contents of this file.

348 349 350 351

Appendix F, line 53, a CORBA helper class is used to narrow the object reference obtained using the orb.string_to_object(iorString) call to the correct type of object. In our case, we are testing that it narrows to an instance of an AuthFactory, as defined in the AuthFactory IDL definition in Appendix A. Copyright © Tecnomen Corporation 2008


8 33

3.2.

352

Authenticate

353 354

Once a valid handle on the authServer is obtained, it is used to authenticate the client session.

355 356

The available ‘AuthFactory::login()’operation, as shown on line 140 Appendix F, is used in the AuthServer_impl::login() function.

357 358

The AuthServer_impl::login() function takes as args a user and password, and a sequence holder to the ‘to be returned’ ServiceKeySeq sequence.

359 360 361 362

The AuthFactory::login operation returns both a sequence of available services, in the sSeq parameter sequence, as shown on line 140 (Appendix F), and also returns information about the internal authenticated user, which must later be used in subsequent paymentEngine operations.

3.3.

363

Get the PaymentEngine Factory’s IOR

364 365

Appendix H: RechargeClient.java source code illustrates the glue that ties together all the other components.

366

Appendix H line 43, shows the setting of the default location of the authServer’s IOR file.

367 368

Appendix H line 74, shows the client constructing the AuthFactory_impl class, described above, and subsequently on line 78 calling the factories login() method.

369 370

On lines 95 through 110, shows the client parsing the returned serviceKeySeq from the authServer.

371 372

On line 99, the ‘service’ part of the returned structure must be validated against the required service. A match to the PAYMENT2 service is required..

373 374

We see on line 102 the required factory key is extracted, and on line 104 the required PaymentEngine Factory’s IOR string is extracted.

375 Where necessary, it is possible to have Payment Engine processes running in parallel. This would only be required currently in the event that the customers existing client architecture precludes the possibility of running multiple physical client processes. To cater for a multi-threaded client, it is possible to configure each client thread to attach to it’s individual PaymentEngine process, as a workaround. Contact Tecnomen to avail of this configuration.

Note:

3.4.

376 377 378

Connect to the PaymentEngine Factory On line 116 of Appendix H, the PaymentEngine Factory’s IOR string is used to get a CORBA handle on the remote Payment Engine Factory.

34 35 36

2

PAYMENT service refers to an integer key value of 100 – the AuthServer’s service key for the PaymentEngine.



9 38

379 380 381

Appendix H, line 125, a CORBA standard helper class is used to narrow the paymentFactoryObj variable to a CORBA object of the required type –in this case a PaymentEngine_Factory object, as described in Appendix E.

3.5.

382

Get a PaymentEngine Instance

383 384 385 386 387

On line 135 of Appendix H, an actual PaymentEngine instance is got with the obtained PaymentEngine Factory CORBA handle. The previously obtained factoryKey, as given by the authServer must be used. Failure to provide a valid key, i.e. one obtained directly from the authServer will result in a failure to get a PaymentEngine instance. An exception will be thrown by the server, and the CORBA reference will be NULL.

388 389 390

On line 147, the ‘engineId()’ operation on the PaymentEngine instance is called. This returns the instance id of the actual payment engine that is currently being used. We will need this value later, when we disconnect from the server.

391 392

Finally, on line 150, a PaymentEngine_impl helper class is constructed, which will wrap all interaction with the PaymentEngine operations, as defined in Appendix E.

3.6.

393

Call directFundTransfer

394 395

On line 216 of Appendix H, the declaration of the function used to carry out the actual functions of interest is illustrated.

396

This is a simple client application that loops on 3 options.

397



To carry out a directFundTransfer operation on line 226.

398



To carry out a directDebitTransfer operation on line 231,

399



To exit on line 235.

400

On line 267, is the directFundTransfer helper function.

3.7.

401

Extract Results

402 403

Line 277 of Appendix H, declares a PE_AccountDetails struct, which serves as a holder for the returned data from the actual directFundTransfer call.

404

Line 296 shows the call to the clients directFundTransfer helper operation.

405 406

The required input parameters, i.e. Subscriber Id, Amount and Transaction Type to the helper class, are supplied, as described in Appendix G.

407 408 409

Line 43 of Appendix G, shows the actual call to the remote PaymentEngine object, passing it all the necessary parameters, including the ‘operatorId’ value obtained way back from the authServer’s returned UserInfo structure.

410 411 412

Lines 316 to 335 of Appendix H, shows the extraction of the resultant data, including the result code (major and minor), and all of the subscriber data, such as the accountBalance, serviceStatus, accountStatus, Expiry, etc.



10 40

3.8.

413

Disconnecting from the PaymentEngine

414

Line 180 of Appendix H, shows the declaration of the releasePaymentEngine operation.

415 416 417

Line 191, shows the client calling the correct release operation on the PaymentEngine Factory, using the factoryKey and engineId instance obtained in the initialisation sequence earlier.



11 42

4. Payment Interface Operations

418

4.1.

419 420 421

Account Details Return Result Structure Some Payment Engine operations use a common return struct as the result of each operation. This struct is detailed in Appendix E and reproduced below:

422 Type

Field

Description

CORBA::Short

result

Major Return Code

CORBA::Short

transferResult

Minor Return Code

CORBA::Long

accountBalance

Account Balance (100,000 == 1)

CORBA::Short

serviceStatus

Service Status 0: 1: 2: 3: 4: 5: 6: 7: 8:

CORBA::Short

accountStatus

Inactive Active SuspendedManually Stolen SuspendedFraud SuspendedErrors SuspendedMaxBalance SuspendedInvalidPin Frozen (Blocked)

Account Status 1: 2: 3: 4: 5:

FirstTime Normal RechargeExpired Disconnected Shutdown

TDateTime

expiryDate

Date of expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Short

profileID

Profile ID

CORBA::Long

subOptions

Bit Mask of Subscriber options

TDateTime

ivrQueryExpiryDate

IVR Query Expiry Date. By default TINC:: name space is inferred before the TDateTime type

CORBA::Short

ivrQueryCounter

IVR Query Counter

CORBA::Long

amountBalance

Unapplied amount (100,000 == 1) This is for DirectDebitTransfer operation.

CORBA::Long

periodicBalance

Periodic Account Balance (100,000 == 1)

TDateTime

periodicExpiry

Periodic Account expiry date

CORBA::Long

bonusBalance

Bonus Account Balance (100,000 == 1)

TDateTime

bonusExpiry

Bonus Account expiry date

CORBA::Long

smBalance

Short Message Account Balance (100,000 == 1)



12 44

Type

Field

Description

TDateTime

smExpiry

Short Message Account expiry date

CORBA::Long

dataBalance

Data Account Balance (100,000 == 1)

TDateTime

dataExpiry

Data Account expiry date

TDateTime

LastRechargeDate

423

4.2.

424

Account Details Return Result Sequence

425 426

Other Payment Engine operations use a common return sequence as the result of each operation.

427

The parameter labels are enums defined in the TINC::GEOPEAccountDetails interface. PARAMETER

TYPE

Max. Size

DESCRIPTION

Result

CORBA::Short

Major Return Code

TransferResult

CORBA::Short

Minor Return Code

AccountBalance

CORBA::Long


ServiceStatus

CORBA::Short

Service Status 0: 1: 2: 3: 4: 5: 6: 7: 8:

AccountStatus

CORBA::Short




ExpiryDate

TDateTime


ProfileID

CORBA::Short

Profile ID

SubOptions

CORBA::Long


IvrQueryExpiryDa te

TDateTime


IvrQueryCounter

CORBA::Short

IVR Query Counter

AmountBalance

CORBA::Long

Unapplied amount (100,000 == 1) This is for DirectDebitTransfer operation.

PARAMETER

TYPE

PeriodicBalance

CORBA::Long


Max. Size

DESCRIPTION Periodic Account Balance (100,000 == 1)


13 46

PeriodicExpiry

TDateTime


BonusBalance

CORBA::Long


BonusExpiry

TDateTime

Bonus Account expiry date

SmBalance

CORBA::Long

Short Message Account Balance (100,000 == 1)

SmExpiry

TDateTime

Short Message Account expiry date

DataBalance

CORBA::Long

Data Account Balance (100,000 == 1)

DataExpiry

TDateTime

Data Account expiry date

LastRechargeDat e

TDateTime

428 4.2.1. Major Return Codes

429

Value

e-Numerator

Description

0

e_OK

Successful

1

e_SubscriberDoesNot Exist

Incorrect Account Number

2

e_InvalidAccountState

Account in an invalid state

3

e_InvalidAmount

Incorrect Amount

4

e_TemporaryError

Fatal Error

5

e_VoucherQueueError

Voucher Queue Full

6

e_InvalidServiceState

Service Status Inactive

7

e_QualityOfService

Service Outage

8

e_InvalidVoucher

Invalid voucher

9

e_VoucherNotFound

Voucher not found

10

e_CDRError

Error sending a CDR or Mediation File

11

e_UnChargedAmount

Successful, amountBalance is non-zero (directDebitTransfer)

12

e_Reserved012

Future Use

13

e_Reserved013

Future Use

14

e_Reserved014

Future Use

15

e_Reserved015

Future Use

16

e_Reserved016

Future Use

17

e_Reserved017

Future Use

18

e_Reserved018

Future Use

19

e_Reserved019

Future Use

Value

e-Numerator

Description

20

e_InvalidParamType

Invalid Param Type. For FundTransfer operation

21

e_InvalidParamCount

Invalid Param Count. For FundTransfer operation



14 48

22

e_InvalidOperation

Invalid Operation. For FundTransfer operation

23

e_InvalidSubscriberId

Invalid Subscriber ID. For FundTransfer operation

24

e_InvalidOperatorId

Future Use

25

e_-InvalidTransactionType

Future Use

26

e_InvalidRechargeDiscount

Future Use

27

e_InvalidMainBalanceDelta

Future Use

28

e_InvalidMainExpiryDate

Future Use

29

e_InvalidMainExpiryDelta

Future Use

30

e_InvalidPeriodicBalanceDelta

Future Use

31

e_InvalidPeriodicExpiryDate

Future Use

32

e_InvalidPeriodicExpiryDelta

Future Use

33

e_InvalidPeriodicPlanId

Future Use

34

e_InvalidBonusBalanceDelta

Future Use

35

e_InvalidBonusExpiryDate

Future Use

36

e_InvalidBonusExpiryDelta

Future Use

37

e_InvalidBonusPlanId

Future Use

38

e_InvalidSmBalanceDelta

Future Use

39

e_InvalidSmExpiryDate

Future Use

40

e_InvalidSmExpiryDelta

Future Use

41

e_InvalidSmPlanId

Future Use

42

e_InvalidDataBalanceDelta

Future Use

43

e_InvalidDataExpiryDate

Future Use

44

e_InvalidDataExpiryDelta

Future Use

45

e_InvalidDataPlanId

Future Use

46

e_FeatureNotAvailable

Future Use

430



15 50

4.3.

431

PaymentEngine::directFundTransfer Operation

432 433

The directFundTransfer operation used to transfer funds from a subscriber’s account without modifying their current account status. Warning:

 rechargeDiscountRate parameter should be set to zero (0) if not required.  expiryDate parameter should be set to 1/1/1970 0:0:0 if not required. Parameter is ignored if set to this “null” value.

434 Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x 435 The following rules apply to the directFundTransfer (dFT) operation:

Note:

       

dFT does not modify the Subscribers account status dFT operations are not allowed for accounts with a status of “Shutdown” dFT operations are only allowed for a Service Status of “Active” dFT may perform positive or negative account balance adjustments, including “First Time” and “Disconnected” Subscribers without modifying the account status Inputs are the value to be recharged and / or the expiry date for the account dFT enforces the minumum and maximum credit balances as defined in the MaxDefines table. dFT may perform positive or negative acount balance adjustements for a Subscriber with Voucher Type Tariffing activated. Voucher Queues are adjusted for charges only. If the Multiple Account feature is activated for the Subscriber, the following applies:  Modifying a Multiple Account balance expiry date via the fundTransfer 3 operation to a date that exceeds the current Main Account balance expiry , will result in the Main Account expiry date being adjusted to meet the latest date, as long as the Main Account expiry is not also provided.  If only the Main Account expiry date is set, then Multiple Account expiry dates are adjusted accordingly if required.

436 TINC:: is inferred PE_AccountDetails directFundTransfer( in string subid, in long amount, in short rechargeDiscountRate, in TDateTime expiryDate, in short transactionType, in long operatorId ) raises (Pi_exception);

437 438

Figure 4-2 Direct Fund Transfer

51

3

See Section 4.6 fundTransfer for more information.



16 53

4.3.1. Input Parameters

439

Parameter

Type

Max. Size

subId

CORBA::String

amount

30

Default

Req

Description

None

key

Prepaid unique subscriber number

CORBA::Long

None

mandatory

100000 units = 1 whole amount, positive or negative

expiryDate

eFieldType::dtim e

None

mandatory

Date the subscribers account expires. Default “null” value of 1/1/1970 0:0:0 is required in order for date not to be adjusted.

transactionType

CORBA::Short

None

mandatory

User defined

rechargeDiscount

CORBA::Short

None

mandatory

Sets the Subscriber.Recharge_discount field.

operatorId

CORBA::Long

None

mandatory

Validated internal ID issued by the authServer upon successful login. Appears in CDR.

440 4.3.2. CDRs Generated by directFundTransfer

441

Transaction Tag Type 47

Description

DIRECT_FUND_TRANSFER_CC Customer Care direct fund transfer

4.3.3. directFundTransfer Minor Result Codes

442


Value

Description

0

OK

100

Subscriber Does Not Exist

101

Value out of range. For example 120%

110

Invalid Account State Error

111

Invalid Service State Error

120

Max Recharge Value Error

121

Max Charge Value Error

122

Max Balance Error

123

Min Balance Error

130

Max Recharge Frauds Error

131

Max Total Recharge Error

200

Temporary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error


17 55

4.4.

443

PaymentEngine::directFundTransferSeq Operation

444 445

The directFundTransferSeq operation is used to transfer funds from a subscriber’s account without modifying their current account status.

446 447 448

The directFundTransferSeq operation is identical to directFundTransfer, except that it uses a Sequence data structure to pass parameters. This makes it easier to add new parameters in the future.

449 Warning:

 rechargeDiscountRate parameter should be set to zero (0) if not required.  expiryDate parameter should be set to 1/1/1970 0:0:0 if not required. Parameter is ignored if set to this “null” value.

450 451 Caution:



Only values associated with Currency_code 0 and Voucher_type 0 in the TPECreditAmountMap table can be used with non-voucher related recharges, with the exception of directFundTransfer.



The TINC package name space is inferred automatically in order to comply with Java 1.4.x

452



18 57

453 The following rules apply to the directFundTransferSeq (dFT) operation:

Note:

       

dFT does not modify the Subscribers account status dFT operations are not allowed for accounts with a status of “Shutdown” dFT operations are only allowed for a Service Status of “Active” dFT may perform positive or negative account balance adjustments, including “First Time” and “Disconnected” Subscribers without modifying the account status Inputs are the value to be recharged and / or the expiry date for the account dFT enforces the minumum and maximum credit balances as defined in the MaxDefines table. dFT may perform positive or negative acount balance adjustements for a Subscriber with Voucher Type Tariffing activated. Voucher Queues are adjusted for charges only. If the Multiple Account feature is activated for the Subscriber, the following applies:  Modifying a Multiple Account balance expiry date via the fundTransfer 4 operation to a date that exceeds the current Main Account balance expiry , will result in the Main Account expiry date being adjusted to meet the latest date, as long as the Main Account expiry is not also provided.  If only the Main Account expiry date is set, then Multiple Account expiry dates are adjusted accordingly if required.

454 455

Figure 4-3 Direct Fund Transfer 4.4.1. Input Parameters

456 457 458

The parameter labels are enums defined in the TINC::GEOdirectFundTransferSeq interface. PARAMETER

TYPE

Max. Size

DEFAULT

REQ.

DESCRIPTION

30

None

key


subId

CORBA::String

Amount

CORBA::Long

None

mandatory


transactionType

CORBA::Short

None

mandatory

User defined

rechargeDiscount

CORBA::Short

None

mandatory

expiryDate

eFieldType::dti me

None

mandatory

Sets the Subscriber.Recharge_discount field. Date the subscribers account expires. Default “null” value of 1/1/1970 0:0:0 is required in order for date not to be adjusted.

58

4

See Section 4.6 fundTransfer for more information.



19 60

459 PARAMETER

TYPE

Max. Size

DEFAULT

REQ.

DESCRIPTION

operatorId

CORBA::Long

None

mandatory


isFinalCall

CORBA::Boole an

None

mandatory

If the SRR has been queried to verify if the subscriber exists locally, then the flag is set to TRUE. If the SRR has not been queried, the flag is set to FALSE. TRUE = It is the final call. FALSE = It is not the final call.

460 4.4.2. CDRs generated by directFundTransferSeq

461 462


Description

DIRECT_FUND_TRANSFER_CC Customer Care direct fund transfer

463 4.4.3. directFundTransferSEQ Minor Result Codes

464 465

Value

Description

0

OK

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


200

Temporary Error

201

Quality of Service

202

Service Outage

210

Fatal Error



20 62

Value

Description

400

Programming Error

466

4.5.

467

PaymentEngine::directDebitTransfer Operation

468 469 470 471

The directDebitTransfer used specifically to debit an account. The operation decrements the account balance to zero (not below) and sets amountNotCharged to the remainder. The amount is always treated as a charge whether a positive or negative amount is entered.

472

This operation does not change the Subscribers account status.

473 Caution:



Only values associated with Currency_code 0 and Voucher_type 0 in the TPECreditAmountMap table can be used with non-voucher related recharges, with the exception of directFundTransfer.



The TINC package name space is inferred automatically in order to comply with Java 1.4.x

474 TINC:: is inferred

PE_AccountDetails directDebitTransfer( in in in ) raises (Pi_exception);

in string subid, long amount, short transactionType, long operatorId

475 476

Figure 4-4 Direct Debit Transfer 4.5.1. Input Parameters

477

Parameter

Type

subId

CORBA::String

Amount

Max. Size

Req.

Description

None

Key


CORBA::Long

None

mandatory


transactionType

CORBA::Short

None

mandatory

User defined

operatorId

CORBA::Long

None

mandatory



30

Default


21 64

4.5.2. CDRs Generated by directDebitTransfer

478


Description

DIRECT_DEBIT_TRANSFER_CC Customer Care direct debit transfer

479 4.5.3. directDebitTransfer Minor Result Codes

480

Value

Description

0

OK

1

UnCharged Amount

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

481

4.6.

482

PaymentEngine::directDebitTransferSeq Operation

483 484 485

The directDebitTransferSeq operation is identical to directDebitTransfer, except that it uses a Sequence data structure to pass parameters. This makes it easier to add new parameters in the future.

486 487 488 489

The directDebitTransferSeq operation is used specifically to debit an account. The operation decrements the account balance to zero (not below) and sets amountNotCharged to the remainder. The amount is always treated as a charge whether a positive or negative amount is entered.

490

This operation does not change the subscriber’s account status.

491



22 66

Caution:  The TINC package name space is inferred automatically in order to comply with Java 1.4.x

492 short directDebitTransferSeq(inout tincSeq pSeq, inout recordSeq rSeq) raises (Pi_exception);

493 494

Figure 4-5 Direct Debit Transfer 4.6.1. Input Parameters

495 496 497

The parameter labels are enums defined in the TINC::GEOdirectDebitTransferSeq interface. PARAMETER

TYPE

Max. Size

DEFAULT

REQ.

DESCRIPTION

30

None

key


subId

CORBA::String

Amount

CORBA::Long

None

mandatory


transactionType

CORBA::Short

None

mandatory

User defined

operatorId

CORBA::Long

None

mandatory


isFinalCall

CORBA::Boole an

None

mandatory


498 499 4.6.2. CDRs generated by directDebitTransferSeq

500


Description

DIRECT_DEBIT_TRANSFER_CC Customer Care direct debit transfer

501 4.6.3. directDebitTransferSeq Minor Result Codes

502


Value

Description

0

OK

1

UnCharged Amount

100



23 68

4.7.

503 504 505 506

Value

Description

101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

PaymentEngine::onlineFundTransfer Operation This is the onlineFundTransfer operation used to transfer funds to the subscriber’s account and is treated in a similar manner as a voucher recharge, therefore a Subscribers account status is set to Normal.

Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x 507 Note:

onlineFundTransfer enforces the minumum and maximum credit balances as defined in the MaxDefines table.

508 TINC:: is inferred

PE_AccountDetails onlineFundTransfer( in string subid, in long amount, in short expiryTimer, in short transactionType, in long operatorId ) raises (Pi_exception);

509 510

Figure 4-6 Online Fund Transfer



24 70

4.7.1. Input Parameters

511

Parameter

Type

subId

CORBA::String

Amount

Max. Size 30

Default

Req.

Description

None

key


CORBA::Long

None

mandatory


expiryTimer

CORBA:Short

None

mandatory

Number of days to increment Main Account expiry.

transactionType

CORBA::Short

None

mandatory

User defined

operatorId

CORBA::Long

None

mandatory


512 4.7.2. CDRs Generated by onlineFundTransfer

513

Transaction Tag Type

Description

BANK_RECHARGE

15

Bank recharge

514 4.7.3. onlineFundTransfer Minor Result Codes

515


Value

Description

0

OK

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


150

Voucher Type Error

151

Voucher Queue Error

200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error


25 72

Value

Description

400

Programming Error

516

4.8.

517

PaymentEngine::onlineFundTransferSeq Operation

518 519 520

The onlineFundTransferSeq operation is identical to onlineFundTransfer, except that it uses a Sequence data structure to pass parameters. This makes it easier to add new parameters in the future.

521 522 523

The onlineFundTransferSeq operation is used to transfer funds to the subscriber’s account and is treated in a similar manner as a voucher recharge, therefore a subscriber’s account status is set to Normal. Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x

525  onlineFundTransferSeq enforces the minumum and maximum credit balances as defined in the MaxDefines table.

Note: 526

short onlineFundTransferSeq(inout tincSeq pSeq, inout recordSeq rSeq) raises (Pi_exception);

528 529

Figure 4-7 Online Fund Transfer 4.8.1. Input Parameters

530 531 532

The parameter labels are enums defined in the TINC::GEOonlineFundTransferSeq interface. PARAMETER

TYPE

Max. Size

DEFAULT

REQ.

DESCRIPTION

30

None

key


subId

CORBA::String

Amount

CORBA::Long

None

mandatory


expiryTimer

CORBA:Short

None

mandatory

Number of days to increment Main Account expiry.

transactionType

CORBA::Short

None

mandatory

User defined

operatorId

CORBA::Long

None

mandatory


isFinalCall

CORBA::Boole an

None

mandatory

If the SRR has been queried to verify if the subscriber exists locally, then the flag is set to TRUE. If the SRR has not been queried,



26 74

the flag is set to FALSE. TRUE = It is the final call. FALSE = It is not the final call.

533 4.8.2. CDRs generated by onlineFundTransferSeq

534


Description

BANK_RECHARGE

15

Bank recharge

535 4.8.3. onlineFundTransferSeq Minor Result Codes

536

Value

Description

0

OK

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


150

Voucher Type Error

151

Voucher Queue Error

200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

537

4.9.

538 539 540

PaymentEngine::periodFundTransfer Operation This is the periodFundTransfer operation used to implement the Autocontrol and Periodic Account features.



27 76

541 542 543

This operation must be configured via the system-wide ServerConfig entry pftVersion to determine the functionality to support. There are 4 available options, each of which is detailed in Ref. /3/ Periodic Account Feature Description manual.

544 545

The periodFundTransfer operation takes the value specified in the amount parameter and applies it to the Periodic_Balance field based on the transactionType parameter that is set5.

546 Additional rules governing functionality can apply depending on the system-wide pftVersion selected and TransactionType parameters supplied via the periodFundTransfer operation, Refer to Ref. /3/, Appendix B for a table describing the functionality of the pftVersion and TransactionType parameters.

Note:

547 Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x 548 TINC:: is inferred PE_AccountDetails periodFundTransfer( in string subid, in long amount, in TDateTime expiryDate, in short tariffPlanId, in long accountBalanceDelta, in short transactionType, in long operatorId ) raises (Pi_exception);

549 550

Figure 4-8 Period Fund Transfer 4.9.1. Input Parameters

551

Parameter

Type

Subid

Required

Description

CORBA::String

Key

Subscriber number

Amount

CORBA::Long

Mandatory

Monthly credit amount. Maps directly to the Periodic Balance field. 4

expiryDate

eFfieldType::dtim e

Mandatory

Expiry Date. Maps directly to the Periodic Expiry field.

tariffPlanId

CORBA::Short

Mandatory

Tariff Plan ID allows the credited amount to be used at a specific Tariff Plan. If the Tariff Plan is set to 0 (zero), then the Subscriber associated Tariff Plan is used to charge for the call. Maps directly to the Periodic_tariff_plan_id field.

accountBalanceDelta CORBA::Long

Mandatory

Used to adjust the Main Account Balance.

transactionType

CORBA::Short

Mandatory

Transaction Type Flag (0 1) 4

operatorId

CORBA::Long

Mandatory

Validated internal ID issued by the authServer upon successful login. Appears in CDR

77 78 79 80

5

Default

: 0: Periodic Account value is replaced by the specified amount and the Account Status is set to Normal if the value specified in positive. 1: Periodic Account value is incremented by the specified amount and the Account Status is set to Normal if the value specified is positve.



28 82

4.9.2. CDRs Generated by periodFundTransfer

552


Description

PP_PERIOD_FUND_TRANSFER_ Fund transfer by CC CC

62

553 4.9.3. periodFundTransfer Minor Result Codes

554

5554.10.

Value

Description

0

OK

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

PaymentEngine::periodFundTransferSeq Operation

556 557 558

The periodFundTransferSeq operation is identical to periodFundTransfer, except that it uses a Sequence data structure to pass parameters. This makes it easier to add new parameters in the future.

559 560

The periodFundTransferSeq operation is used to implement the Autocontrol and Periodic Account features.

561 562 563 564

This operation must be configured via the ServerConfig entry pftVersion to determine whether Autocontrol (pftVersion option 1) or Periodic Account, also known as “standard” version (pftVersion option 0) is set. Refer to Ref. /2/, Customer Care Administrator Manual for details on the Server Configuration options.



29 84

565 566 567

The periodFundTransferSeq operation takes the value specified in the amount parameter and applies it to the Periodic_Balance field based on the transactionType parameter that is set6. 

Note:

If the pftVersion is set to 0  The accountBalanceDelta can be used to increment or decrement the Main Account Balance If the pftVersion is set to 1 the following rules apply:



 

If the Main Account Balance is greater than the accountBalanceDelta (UsedAmount) value, then the Main Account Balance is replaced with the accountBalanceDelta (UsedAmount) value. If the Main Account Balance is less than or equal to the accountBalanceDelta (UsedAmount) value, then the Main Account Balance is untouched.

568 Caution:  The TINC package name space is inferred automatically in order to comply with Java 1.4.x 569 short periodFundTransferSeq(inout tincSeq pSeq, inout recordSeq rSeq) raises (Pi_exception);

570 571

Figure 4-9 Period Fund Tranfer 4.10.1.

572 573 574

Input Parameters

The parameter labels are enums defined in the TINC::GEOperiodFundTransferSeq interface.

Parameter

Type

Subid

Required

Description

CORBA::String

Key


Amount

CORBA::Long

Mandatory

Monthly credit amount. Maps directly to the Periodic Balance field. 4

expiryDate

eFieldType::dtime

Mandatory

Expiry Date. Maps directly to the Periodic Expiry field.

tariffPlanId

CORBA::Short

Mandatory

Tariff Plan ID allows the credited amount to be used at a specific Tariff Plan. If the Tariff Plan is set to 0 (zero), then the Subscriber associated Tariff Plan is used to charge for the call. Maps directly to the Periodic_tariff_plan_id field.

accountBalanceDelta CORBA::Long

Mandatory

Used to adjust the Main Account Balance.

transactionType

CORBA::Short

Mandatory

Transaction Type Flag (0 1)4

operatorId

CORBA::Long

Mandatory


85 86 87 88

6

Default

: 0: Periodic Account value is replaced by the specified amount and the Account Status is set to Normal if the value specified in positive. 1: Periodic Account value is incremented by the specified amount and the Account Status is set to Normal if the value specified is positve.



30 90

Parameter

Type

Default

isFinalCall

CORBA::Boolean None

Required

Description

Mandatory


575 4.10.2.

576

CDRs generated by periodFundTransferSeq


Description

62

PP_PERIOD_FUND_TRANSFER_ Fund transfer by CC CC

4.10.3.

periodFundTransferSeq Minor Result Codes

577 578

Value

Description

0

OK

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

579

4.11.

580 581 582

PaymentEngine::fundTransfer Prior to Prepaid 4.3.6, Subscribers had one associated prepaid account balance, known as the Main Account.



31 92

An exception to this rule are customer sites that have the Periodic Account feature installed. This feature is now standard with Prepaid Release 4.3.6 and higher. Refer to the Periodic Account Feature Description for more information on this feature.

Note:

583 584 585 586

The existing payment Engine legacy operations: PeriodicFundTransfer ; directFundTransfer and onlineFundTransfer continue to update the Main Account balance and associated expiry date only.

587 588 589

To support the modification of the new account balances: Bonus Account, SM Account, Data Account, and the existing Main Account, as well as their associated expiry date details, a new Payment Engine operation called fundTransfer has been developed. The directFundTransfer operation also supports the updating of the existing Recharge Discount Rate as as well as Periodic Account balance and expiry details.

Note: 591 592 593 594 595

The fundTransfer operation uses a new parameter called p_OperationType to determine the type of operation to perform. For Prepaid, the directFundTransfer and onlineFundTransfer operations are the only valid selection, but future releases will see all backend paymentEngine operations7 supported by fundTransfer.

596 597

The fundTransfer operation provides a “Sequence of ANY” API to the various underlying operations available via the CORBA Payment Interface.

598 eFundTransferResult fundTransfer( in tincSeq pSeq, out tincSeq dSeq) raises (Pi_exception);

599 600

Figure 4-10.paymentEngine::fundTransfer Operation

601 602

op_DirectFundTransfer

603 604 605

The directFundTransfer operation Type called by op_DirectFundTransfer implements an enhanced version of the existing directFundTransfer operation. The following transactions are supported:

606



Set the Recharge Discount Rate

607



Adjust the Main Account Balance and associated expiry date

608



Adjust the Periodic Account Balance8

609



Adjust the Bonus Account Balance and associated expiry date

610



Adjust the SM Account Balance and associated expiry date

611



Adjust the Data Account Balance and associated expiry date.

93 94

7 8

periodicFundTransfer and directDebitFundTransfer Associated expiry date parameter is for future use



32 96

612 The following rules apply to the directFundTransfer (dFT) operation:

Note:

       

dFT does not modify the Subscribers account status dFT operations are not allowed for accounts with a status of “Shutdown” dFT operations are only allowed for a Service Status of “Active” dFT performs positive or negative account balance adjustments, including “First Time” and “Disconnected” Subscribers without modifying the account status Inputs are the value to be recharged and / or the expiry date for each account dFT enforces the minumum and maximum credit balances as defined in the MaxDefines table. dFT may perform positive or negative acount balance adjustments for a Subscriber with Voucher Type Tariffing activated. Voucher Queues are adjusted for charges only. If the Multiple Account feature is activated for the Subscriber, the following applies:  Modifying a Multiple Account balance expiry date via the fundTransfer operation to a date that exceeds the current Main Account balance expiry , will result in the Main Account expiry date being adjusted to meet the latest date, as long as the Main Account expiry date is not also provided.  If the Main Account9 expiry is provided and set to a date that is less than some or all of the Multiple Account expiry dates, even in the same transaction, then the Multiple Account expiry dates are capped to equal the Main Account expiry date. To ensure that Multiple Accounts dates are not adjusted based on the Main Account date, leave the p_MainExpiryDate parameter either as the “null” date of 1/1/1970 0:0:0, or simply do not include it in the input sequence.

 If only the Main Account10 expiry date is set, then Multiple Account expiry dates are adjusted accordingly if required.

613 615

op_OnlineFundTransfer

616 617 618 619 620

The OnlineFundTransfer operation Type called by op_OnlineFundTransfer implements an enhanced version of the existing OnlineFundTransfer operation used to transfer funds to / from a Subscribers accounts. The OnlineFundTransfer operation is treated similar to that of a voucher recharge, and will modify a Subscribers account status to Normal. The following transactions are supported:

621



Adjust the Main Account Balance and associated expiry date

622



Adjust the Bonus Account Balance and associated expiry date

623



Adjust the SM Account Balance and associated expiry date

624



Adjust the Data Account Balance and associated expiry date.

97 98 99

9

PE legacy directFundTransfer operation via Payment Interface or IDL Gateway can also set Main Account expiry date. 10 See Footnote 7



33 101

625 The following rules apply to the OnlineFundTransfer (oFT) operation:

Note:

    

oFT does modify the Subscribers account status inputs are always the value to be recharged and the expiry delta 11 for each account oFT enforces the minumum and maximum credit balances as defined in the MaxDefines table. If the Multiple Account feature is activated for the Subscriber, the following applies: The Main Account expiry date is always greater than or equal to the Bonus, Data and or Short Message account expiry dates.  Recharging any of the Multiple Accounts will set the account status to Normal

626 4.11.1.

627 628

4.11.1.1.

Place Holder12

Input pSeq (Parameter Sequence) op_DirectFundTransfer

Parameter

p_OperationTy OperationType pe

Type

Max Size Default

eFundTransfer Op

None

Required

Description

Key

Type of payment operation: op_DirectFundTransfer

p_SubID

subId

CORBA::String

30

p_OperatorId

OperatorId

CORBA::Long

None

Key

Unique Prepaid Subscriber number

Mandatory


0

Optional

User Defined

p_RechargeDis rechargeDiscou CORBA::Short count nt

0%

Optional

p_MainBalance amount Delta

CORBA::Long

0

Optional

Delta aount to be applied to Main account. 100000 units = 1 whole unit, positive or negative

p_MainExpiryD ate

eFieldType::TD ateTime

Null

Optional

Date Subscribers Main Account expires. Default value of 1/1/1970 0:0:0 is entered if left blank. This is date is a “null” value and is ignored by the operation, therefore date(s) is/are not adjusted.

p_TransactionT TransactionTyp ype e

CORBA::Short

None None

directFundTransfer

102 103 104

11 12

expiryDate

Same functionality as the expiryTimer parameter in the PE legacy onlineFundTransfer operation Place Holder is a CORBA::Short that is used to identify each field. These are defined in the directFundTransferOp in the TPEDefs.idl



34 106

Place Holder

Parameter

Type

p_PeriodicBala nceDelta

periodicAmount CORBA::Long

Max Size Default

Required

Description

0

Optional

Delta amount to be applied to Periodic Account. 100000 units = 1 whole amount, positive or negative

p_PeriodicExpir periodicExpiry yDate


Null

Optional

Date Subscribers Periodic Account expires.Default value of 1/1/1970 0:0:0 is entered if left blank. This is date is a “null” value and is ignored by the operation, therefore date(s) is/are not adjusted.

p_BonusBalanc bonusAmount eDelta

CORBA::Long

0

Optiional

Delta amount to be applied to Bonus Account. 100000 units = 1 whole amount, positive or negative

p_BonusExpiry Date


Null

Optional

Date Subscribers Bonus Account expires. Default value of 1/1/1970 0:0:0 is entered if left blank. This is date is a “null” value and is ignored by the operation, therefore date(s) is/are not adjusted.

p_SmBalanceD smAmount elta

CORBA::Long

0

Optional

Delta amount to be applied to SM Account. 100000 units = 1 whole amount, positive or negative

p_SmExpiryDat smExpiry e


Null

Optional

Date Subscribers SM Account expires. Default value of 1/1/1970 0:0:0 is entered if left blank. This is date is a “null” value and is ignored by the operation, therefore date(s) is/are not adjusted.

p_DataBalance Delta

dataAmount

CORBA::Long

0

Optional

Delta amount to be applied to Data Account. 100000 units = 1 whole amount, positive or negative

p_DataExpiryD ate

dataExpiry


Null

Optional

Date Subscribers Data Account expires. Default value of 1/1/1970 0:0:0 is entered if left blank. This is date is a “null” value and is ignored by the operation, therefore date(s) is/are not adjusted.

bonusExpiry



35 108

629

4.11.1.2.

Place Holder13

op_OnlineFundTransfer

Parameter

p_OperationTy OperationType pe

Type

Max Size Default

eFundTransfer Op

None

Required

Description

Key

Type of payment operation: op_OnlineFundTransfer

p_SubID

subId

CORBA::String

30

p_OperatorId

OperatorId

CORBA::Long

None

p_TransactionT TransactionTyp ype e

None None

Key

Unique Prepaid Subscriber number

Mandatory


CORBA::Short

0

Optional

User Defined

p_MainBalance MainBalanceDe CORBA::Long Delta lta

0

Optional

Delta aount to be applied to Main account. 100000 units = 1 whole unit, positive or negative

p_MainExpiryD elta

Null

Optional

Days to extend the Subscribers Main Account expiry

p_BonusBalanc BonusBalanceD CORBA::Long eDelta elta

0

Optional

Delta amount to be applied to Bonus Account. 100000 units = 1 whole amount, positive or negative

p_BonusExpiry Delta

Null

Optional

Days to extend the Subscribers Bonus Account expiry

p_SmBalanceD SmBalanceDelt CORBA::LONG elta a

0

Optional

Delta amount to be applied to Short Message Account. 100000 units = 1 whole amount, positive or negative

p_SmExpiryDelt SmExpiryDelta a

Null

Optional

Days to extend the Subscribers Short Message Account expiry

onlineFundTransfer

MainExpiryDelt a

CORBA::Short

BonusExpiryDel CORBA::Short ta

CORBA::Short

p_DataBalance Delta

DataBalanceDel CORBA::Long ta

0

Optional

Delta amount to be applied to Data Account. 100000 units = 1 whole amount, positive or negative

p_DataExpiryD elta

DataExpiryDelta CORBA::Short

Null

Optional

Days to extend the Subscribers Data Account expiry

Reserved

Reserved

For Future Use

p_Reserved024 Reserved

109 110

13

Reserved

Reserved

Place Holder is a CORBA::Short that is used to identify each field. These are defined in the directFundTransferOp in the TPEDefs.idl



36 112

630

4.11.2.

Output dSeq (Data Sequence)

Place Holder14

Parameter

Type

Max Size Description

MajorCode

result

CORBA::Short

Result of operation

r_MinorCode

transferResult

CORBA::Short

Detailed result code

r_ServiceStatus serviceStatus

CORBA::Short

A valid Service status i.e. 0 - Inactive 1 - Active 2 - Suspended 3 - Stolen 4 - Suspended by Fraud

5 - Suspended by Errors 6 - Suspended by Max Bal 7 - Suspended by PIN 8 – Suspended Frozen

r_AccountStatu s

accountStatus

CORBA::Short

A valid Account status i.e. 1 - First Time User 2 - Normal User

3 - Recharge Expired 4 - Disconnected 5 - Shutdown

r_ProfileId

profileId

CORBA::Short

Subscriber profile ID used to associate the subscriber with access to Prepaid service features

r_SubOptions

subOptions

CORBA::Long

Bit field for Subscriber Level options.

r_IvrQueryExpir IvrQueryWxpiry eFieldType::TD yDate Date ateTime

IVR_query_charging_expiry value

r_ivrCounter

IVR_query_counter value

ivrCounter

CORBA::Short

r_AmountBalan amountBalance CORBA::Long ce

Balance un-applied

r_Account Balance

accountBalance CORBA::Long

Balance of Main Account. 100000 units = 1 whole amount, positive or negative

r_ExpiryDate

expiryDate

Expiry date of Main Account


r_PeriodicBalan periodicBalance CORBA::Long ce

Balance of Periodic Account. 100000 units = 1 whole amount, positive or negative

r_PeriodicExpir y

PeriodicExpiry

eFieldType::TDa teTime

Periodic Account expiry date.

r_BonusBalanc e

bonusBalance

CORBA::Long

r_BonusExpiry

bonusExpiry

eFieldType::TDa teTime

r_SmBalance

smBalance

CORBA::Long

r_SmExpiry

smExpiry

r_DataBalance

dataBalance

r_DataExpiry

dataExpiry

eFieldType::TDa teTime CORBA::Long eFieldType::TDa teTime

Balance of Bonus Account. 100000 units = 1 whole amount, positive or negative Bonus Account expiry date. Balance of SM Account. 100000 units = 1 whole amount, positive or negative SM Account expiry date. Balance of Data Account. 100000 units = 1 whole amount, positive or negative Data Account expiry date.

631

113 114

14

Place Holder is a CORBA::Short used to identify each field. These are defined in the fundTransferOp in the TPEDefs.idl



37 116

632

4.11.3.

fundTransfer Minor Result Codes Value

Description

0

Success

1


2

Invalid Account Status

3

Invalid Amount

4

Temporary Error

5

Voucher Queue Error

6

Invalid Service Status

7

Quality of Service Error

8

Invalid Voucher

9

Voucher Not Found

10

CDR Error

633

4.12.

634

PaymentEngine::FundAccountTransfer

635 636 637 638 639 640

This Operation allows the transfer of funds into/from any balance of any account. This operation accepts tincSeq and recordSeq in inout parameters and supports DFT and OFT operations. Several accounts may be recharged at once using this operation by inputing a separate tincSeq within the recordSeq, for each account. A separate TOCS recharge-format CDR is generated for each account that is affected. Voice format CDRs will not be sent. As defined in PaymentEngine.idl.

641

FundTransferOp::eFundTransferResult

642

fundAccountTransfer(inout tincSeq _pSeq,

643

inout recordSeq _rSeq)

644

raises (Pi_exception);

645 6464.12.1.1.

Input Sequence Parameters

647_pSeq Parameters 648 649

Parameter labels are enums defined in the TINC::FundAccountTransferOp interface, which is in TPEDefs.idl.

650 PARAMETER

p_SubId

TYPE

CORBA::String


REQ.

Required

DESCRIPTION

The Subscriber’s Id


38 118

p_OperatorId

CORBA::Long

Required

The ID of the operator carrying out the operation.

p_OperationType

CORBA::Short

Required

The type of the sub-operation (op_DirectFundTransfer, op_OnlineFundTransfer)

p_TransactionType

CORBA::Short

Optional

TransactionType

p_RechargeDiscount

CORBA::Short

Optional

RechargeDiscount

651

652_rSeq Parameters 653 654

Each tincSeq within the recordSeq (_rSeq) will contain information on an account to be recharged and will contain the following parameters.

655 656

Parameter labels are enums defined in the TINC::FundAccountTransferOp interface, which is in TPEDefs.idl. PARAMETER

TYPE

DESCRIPTION

p_AccountType

CORBA::Short

The account to be credited/debited.

p_BalanceId

CORBA::Short

The balance to be credited/debited.

p_BalanceDelta

CORBA::Long

The amount to credit/debit by.

p_ExpiryDate

EfieldType::dtime

The expiry to be applied.

p_ExpiryDelta

CORBA::Short

The number of days to increase the expiry by.

p_PlanId

CORBA::Short

p_PackageId

CORBA::Short

The id of the package to be added to the account.

p_VoucherType

CORBA::Short

The voucher type (only for short voucher systems).

657 6584.12.1.2.

Output Sequence Parameters

659 660

Each tincSeq within the recordSeq (_rSeq) will contain information on the account that was recharged.

661 662

Parameter labels are enums defined in the TINC::FundAccountTransferOp interface, which is in TPEDefs.idl. PARAMETER

TYPE

DESCRIPTION

r_MajorCode

CORBA::Short

Result of operation.

r_MinorCode

CORBA::Short

Detailed result code.

r_SubId

CORBA::String

Subscriber Id

r_AccountType

CORBA::Short

0 == Voice(Future Use) 1 == Event



39 120

PARAMETER

TYPE

DESCRIPTION 2 == Data 3 == MMS

r_BalanceId

CORBA::Short

The balance that was affected.

r_TariffPlanId

CORBA::Short

Default plan associated with account

r_BalanceAmount

CORBA::Long

Balance after transfer was completed

r_BalanceUnits

CORBA::Short

Balance currency of monetary unit

r_BalanceExpiry

EfieldType::dtime

Expiry date of affected balance after transfer.

663



40 122

6644.12.1.3.

Minor Result Codes Value

Description

0

OK

100


101


110


111


112

Invalid Account Error

120


121


122

Max Balance Error

123

Min Balance Error

130


131


150

VTT Voucher Type Error

151

Voucher Queue Error

152

Voucher Denomination Error

200

Temporary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

665

4.13.

666 667 668 669

PaymentEngine::accountUpdate Used to update the subscribers accountStatus and expiryDate. If the accountStatus is being updated from Normal (2) to RechargeExpired (3), then the subscribers accountBalance will be reset to 0 balance.

Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x 670



41 124

TINC:: is inferred

PE_AccountDetails accountUpdate( in string subid, in short accountStatus, in TDateTime expiryDate, in short transactionType, in long operatorId ) raises (Pi_exception);

671 672

Figure 4-11. Account Update

673 4.13.1.

674

Input Parameters

675 PARAMETER

TYPE

Max. Size

DEFAULT

REQ.

DESCRIPTION

30

None

key


subId

CORBA::String

accountStatus

CORBA::Short

None

mandatory

Sets the Subscriber Account_status field.

expiryDate

eFieldType::dti me

None

mandatory

Date the subscriber’s account expires. Default “null” value of 1/1/1970 0:0:0 is required in order for the date not to be adjusted.

transactionType

CORBA::Short

None

mandatory

User defined

operatorId

CORBA::Long

None

mandatory


676 4.13.2.

677

CDRs Generated by accountUpdate


20

ACC_STATUS_EXPIRED_TO_DI SC ACC_STATUS_DISC_TO_SHUTD OWN EXPIRED_BALANCE_ZEROED

24

SUSPENDED_FRAUD

25

SUSPENDED_ERRORS

26

SUSPENDED_BALANCE

78

ACCOUNT_UPDATE_CC

13 14

Description Account status change: recharge expired  disconnected Account status change: disconnected  shutdown Account balance set to zero when expiry date reached. Suspended due to exceeding maximum for recharge fraud counter Suspended due to exceeding maximum for recharge error counter Suspended due to exceeding maximum balance Account_status transition other than normal lifecycle.

678



42 126

4.13.3.

679

account Update Minor Result Codes

Value

Description

0

OK

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


150

Voucher Type Error

151

Voucher Queue Error

200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

680

4.14.

681

PaymentEngine::accountUpdateSeq Operation

682 683 684

The accountUpdateSeq operation is identical to accountUpdate, except that it uses a Sequence data structure to pass parameters. This makes it easier to add new parameters in the future.

685 686 687

The accountUpdateSeq operation is used to update the subscriber’s accountStatus and expiryDate. If the accountStatus is being updated from Normal (2) to RechargeExpired (3), then the subscriber’s accountBalance will be reset to 0 balance.

688 Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x 689 short accountUpdateSeq(inout tincSeq pSeq, inout recordSeq rSeq) raises (Pi_exception);

690 691

Figure 4-12 Account Update



43 128

4.14.1.

692 693

Input Parameters

The parameter labels are enums defined in the TINC::GEOaccountUpdateSeq interface. PARAMETER

TYPE

Max. Size

DEFAULT

REQ.

DESCRIPTION

30

None

key


subId

CORBA::String

accountStatus

CORBA::Short

None

mandatory

Sets the Subscriber Account_status field.

expiryDate

eFieldType::dti me

None

mandatory

Date the subscriber’s account expires. Default “null” value of 1/1/1970 0:0:0 is required in order for the date not to be adjusted.

transactionType

CORBA::Short

None

mandatory

User defined

operatorId

CORBA::Long

None

mandatory


isFinalCall

CORBA::Boole an

None

mandatory


694 4.14.2.

695

CDRs generated by accountUpdateSeq


Description

ACC_STATUS_EXPIRED_TO_DI Account status change: recharge expired  SC disconnected ACC_STATUS_DISC_TO_SHUTD Account status change: disconnected  shutdown OWN Account balance set to zero when expiry date EXPIRED_BALANCE_ZEROED reached.

13 14 20 24

SUSPENDED_FRAUD

Suspended due to exceeding maximum for recharge fraud counter

25

SUSPENDED_ERRORS

Suspended due to exceeding maximum for recharge error counter

26

SUSPENDED_BALANCE

Suspended due to exceeding maximum balance

78

ACCOUNT_UPDATE_CC

Account_status transition other than normal lifecycle.

696 4.14.3.

697

accountUpdateSeq Minor Result Codes Value

Description

0

OK



44 130

Value

Description

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


150

Voucher Type Error

151

Voucher Queue Error

200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

699

4.15.

700 701

PaymentEngine::accountQuery This operation is used to query a Subscribers account.

Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x 702



45 132

TINC:: is inferred

PE_AccountDetails accountQuery( in string subid, in long operatorId ) raises (Pi_exception);

703 704

Figure 4-13. Account Query

705 4.15.1.

706

PARAMETER

Input Parameters TYPE

subId

CORBA::String

operatorId

CORBA::Long

Max. Size

DEFAULT

REQ.

DESCRIPTION

30

None

Key


None

Mandatory


707 4.15.2.

708

Account Query Minor Return Codes Value

Description

0

OK

100


101


110


111


120


121


122

Max Balance Error

123

Min Balance Error

130


131


150

Voucher Type Error

151

Voucher Queue Error

200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error



46 134

709

4.16.

710

PaymentEngine::accountQuerySeq Operation

711 712 713

The accountQuerySeq operation is identical to accountQuery, except that it uses a Sequence data structure to pass parameters. This makes it easier to add new parameters in the future.

714

This operation is used to query a subscriber’s account. Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x

715 short accountQuerySeq(inout tincSeq pSeq, inout recordSeq rSeq) raises (Pi_exception);

716 717

Figure 4-14 Account Query

718 4.16.1.

719 720

Input Parameters

The parameter labels are enums defined in the TINC::GEOaccountQuerySeq interface. PARAMETER

TYPE

Max. Size

DEFAULT

REQ.

DESCRIPTION

30

None

Key


subId

CORBA::String

operatorId

CORBA::Long

None

Mandatory


isFinalCall

CORBA::Boole an

None

Mandatory


721 4.16.2.

722


accountQuerySeq Minor Return Codes Value

Description

0

OK

100


101


110


111



47 136

Value

Description

120


121


122

Max Balance Error

123

Min Balance Error

130


131


150

Voucher Type Error

151

Voucher Queue Error

200

Temporoary Error

201

Quality of Service

202

Service Outage

210

Fatal Error

400

Programming Error

723

4.17.

724 725 726 727 728

paymentEngine::packageRecharge Operation The packageRecharge synchronous operation is used to recharge a subscriber’s Commercial, Tailored Commercial, Promotional and Refund packages. The account type and the id of the package to be used is received as input. The account type determines which account (Event [SM], Session [Data], etc.) the recharge should be applied to. packageRechargeOp::ePackageRechargeResult packageRecharge (in tincSeq pSeq) raises (Pi_exception);

730 731

Figure 4-15 Package Recharge 4.17.1.

732 733 734 735

Input Sequence (pSeq Contents)

The TINC::PackageRechargeOp::ePackageRechargeInputAtt enumerated type is used to assign Parameter Ids to elements of this sequence. This enumeration is defined in TPEDefs.idl.

736 PARAMETER

ID

TYPE

REQ.

DESCRIPTION

SubId

PackageRechargeOp::SubId

String

Required

Subscriber ID

OperatorId

PackageRechargeOp::OperatorId

Long

Required

Operator ID

AccountType

PackageRechargeOp::AccountType

Short

Required

Account the recharge is to be applied to.



48 138

TINAccountType::eTINA ccountTypeAtt (defined in TINTocsDefs.idl) should be used to define this. PackageId

PackageRechargeOp::PackageId

Long

Required

ID of the package.

RechargePolicy

PackageRechargeOp::RechargePolicy

Short

Optional

Cumulative or overwrite recharge policy. PackageRechargeOp::e PackageRechargePolicy Att (defined in TPEDefs.idl) should be used to define this.

Amount

PackageRechargeOp::Amount

Long

Optional

If received, will override the package’s Quantity_amount value in PackageDefinition table.

Cost

PackageRechargeOp::Cost

Long

Optional

If received, will override the package’s Cost_amount value. If provided, must be >= 0.

Expiry

PackageRechargeOp::Expiry

TDate Time

Optional

If received, will override the package’s Period or Expiry value, as appropriate.

737 4.17.2.

738

CDRs Generated by packageRecharge

ID 219

DESCRIPTION Package Recharge.

739 4.17.3.

740 741 742 743

packageRecharge Minor Result Codes

The following result codes are defined in the TINC::PackageRechargeOp::ePackageRechargeResult enumerated type, which can be found in TPEDefs.idl.

744 Result Code Enum

Value

Description

PackageRechargeOp::OK

0

Success.

PackageRechargeOp::InvalidSu bscriberId

1

The SubId supplied is not valid.

PackageRechargeOp::Subscrib erDoesNotExist

2

The supplied SubId is not that of a valid subscriber.



49 140

Result Code Enum

Value

Description

PackageRechargeOp::InvalidOp eratorId

3

The supplied OperatorId is not valid.

PackageRechargeOp::InvalidAc countType

4

The AccountType supplied is invalid.

PackageRechargeOp::AccountN otEnabled

5

The subscriber does not have the supplied AccountType enabled.

PackageRechargeOp::InvalidRe chargePolicy

6

The supplied RechargePolicy is invalid.

PackageRechargeOp::InvalidPa ckageId

7

The supplied Package ID is invalid

PackageRechargeOp::Package NotFound

8

No entry was found in PP_DB..PackageDefinition for the given PackageId.

PackageRechargeOp::Package NotUseable

9

The Event_type of the supplied PackageId is not compatible with the given AccountType.

PackageRechargeOp::PackageI dMismatch

10

A cumulative recharge policy was selected and the supplied package id did not match the id of the currently resident package.

PackageRechargeOp::InvalidSe rviceState

11

The subscriber’s service state or Account Status is such that a recharge is not possible at this time.

PackageRechargeOp::Operation NotAvailable

12

Operation is unavailable as TOCS is not active on this system.

PackageRechargeOp::InvalidPa ramType

13

An input parameter is of incorrect type.

PackageRechargeOp::InvalidPa ramCount

14

All required parameters were not provided.

PackageRechargeOp::Insufficie ntFunds

15

The subscriber does not have enough money in his/her account to pay for this package.

PackagerechargeOp::InvalidCos t

16

Temporary Error.

PackagerechargeOp::InvalidAm ount

17

Environmental Error.

PackagerechargeOp::InvalidExp iryDate

18

Fatal Error.

PackagerechargeOp::PackageP oolFull

19

No free slot could be found in the package pool.

PackageRechargeOp::Temporar yError

20

PackageRechargeOp::Environm entError

21

PackageRechargeOp::FatalErro r

22



50 142

4.17.4.

745

Package Refund

746 747

The Package Recharge functionality can be used in conjunction with dailyRun and ccRun to refund packages.

748 749

If a file is placed in the ServerConfig.updateSubs directory with a prefix of in, it will be processed by dailyRun. The file should have the following format: packageRecharge,TrandId,SubId,AccountType,PackageId,RechargePolicy

750 751

Figure 4-16 Package Recharge File

752

4.17.4.1.

753 754

The following table describes the parameters included in the file, which is processed by either ccRun or dailyRun to refund packages.

Package Refund Parameters

755 Parameter

Description

packageRecharge

Operation

TranId

Number to track each entry in a file. (Can be any number or type short.)

SubId

SubId

AccountType

Event – 1, or Data – 2

PackageId

Id of the Package, 1 is usually a refund package.

Recharge Policy

0 – Overwrite, 1 – Cumulative

756 757

4.17.4.2.

758

A sample refund entry for subscriber 0612313 of the Event account is as follows:

Package Refund Sample Entry

759

packageRecharge,0,0612313,1,1,1

760

Figure 4-17 Sample Package Refund Entry



51 144

4.18.

761 762

PaymentEngine::voucherRecharge Operation This is the synchronous version of the voucher recharge method.

PE_AccountDetails voucherRecharge(in string subid, in string voucher, in long operatorId) raises (Pi_exception);

763 764

Figure 4-18 Voucher Recharge 4.18.1.

765

Input Parameters

PARAMETER

TYPE

DEFAULT

REQ.

DESCRIPTION

Subid

CORBA::String

Key

Voucher

CORBA::String

Mandatory Voucher Number.

operatorId

CORBA::Long

Mandatory Validated internal ID issued by the authServer upon successful login. Appears in CDR

4.18.2.

766

CDRs generated by voucher recharge

Transaction Type

Tag CC VOUCHER_RECHARGE

34

Subscriber number

Description CC Voucher Recharge

767 4.18.3.

768

Return Code

769

This operation is synchronous and returns the PE_AccountDetails structure defined in the

770

PaymentEngine interface. PARAMETER

Result

TYPE CORBA::short

DEFAULT None

REQ. Numeric

DESCRIPTION Defined result values are as follows: 0 – Successful 1 – Incorrect account number 2 – Account in an invalid state 3 – Incorrect amount 4 – Fatal Error 5 – Voucher Queue Full 6 – Service Status inactive 7 – Service Outage 8 – Invalid Voucher 9 – Voucher not found



52 146

PARAMETER

TYPE

DEFAULT

REQ.

DESCRIPTION 10 – Error sending a CDR or Mediation File 11 – Successful, amountBalance is nonzero (directDebitTransfer)

transferResult

CORBA::short

None

Numeric

Transfer Result

accountBalance

CORBA::long

None

Numeric

In units of 100000 = 1 whole unit

serviceStatus

CORBA::short

None

Numeric

0 - Inactive 1 - Active 2 – Suspended 3 - Stolen 4 - Suspended by Fraud 5 - Suspended by Errors 6 – Suspended by Max Bal 7 – Suspended by Pin 8 – Suspended by Frozen

accountStatus

CORBA::short

None

Numeric

1 – First Time User 2 – Normal User 3 – Recharge Expired 4 – Disconnected 5 – Shutdown

expiryDate

EFieldType::dtime

None

Valid Date Time

Expiry date

profileId

CORBA::short

None

Numeric

Profile Id

subOptions

CORBA::long

None

Numeric

Sub Options

ivrQueryExpiryDate

EFieldType::dtime

None

Valid Date Time

IVR Query Expiry

ivrQueryCounter

CORBA::short

None

Numeric

IVR Query Counter

amountBalance

CORBA::long

None

Numeric

Balance un-applied

lastRechargeDate

EFieldType::dtime

None

Valid Date Time

Last Recharge Date

perioidcBalance

CORBA::long

None

Numeric

Periodic Balance

periodicExpiry

EFieldType::dtime

None

Valid Date Time

Periodic Expiry

periodicStatus

CORBA::short

None

Numeric

Control Plan Users 1 – First Time User 2 – Normal 3 – Partial Blocking 4 – Blocked

bonusBalance

CORBA::long

None

Numeric

Bonus Balance

bonusExpiry

EFieldType::dtime

None

Valid Date

Bonus Expiry



53 148

PARAMETER

TYPE

DEFAULT

REQ.

DESCRIPTION

Time smBalance

CORBA::long

None

Numeric

SM Balance

smExpiry

EFieldType::dtime

None

Valid Date Time

SM Expiry

dataBalance

CORBA::long

None

Numeric

Data Balance

dataExpiry

EFieldType::dtime

None

Valid Date Time

Date Expiry

overdraftBalance

CORBA::long

None

Numeric

Overdraft Balance

771

4.19.

772

ASyncEngine::voucherRecharge Operation

Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x 773 TINC:: is inferred

774

CORBA::Long voucherRecharge( in string subid, in string callingPartyNumber, in string voucher, in string locationId, in short thisVoucherErrors, in short transactionType, in TDateTime transactionDate, in short correlationSource, in short correlationId, in long operatorId ) raises (Pi_exception);

775

Figure 4-19 Voucher Recharge 4.19.1.

776

Input Parameters

Parameter

Type

Subid

Required

Description

CORBA::String

Key

Subscriber number

CallingPartyNumber

CORBA::String

Mandatory

International and Area Code

Voucher

CORBA::String

Mandatory

Voucher Number.

LocationId

CORBA::String

Mandatory

Current Location of the Subscriber.

ThisVoucherErrors

CORBA::Short

Mandatory

Number of errors made by the subscriber when entering this voucher number.

TransactionType

CORBA::Short

Mandatory

External transaction type to be placed in the CDR


Default


54 150

Parameter

Type

transactionDate

Required

Description

eFfieldType::dtim e

Mandatory

Date and Time of Voucher Recharge to be placed in the CDR

corrleationSource

CORBA::Short

Mandatory

Placed in the CDR for corrleation purposes.

corrleationId

CORBA::Short

Mandatory


operatorId

CORBA::Long

Mandatory


4.19.2.

777

Default

CDRs Generated by voucherRecharge


Description

3

IVR_VOUCHER_RECHARGE

IVR voucher Recharge

34

CC VOUCHER_RECHARGE

CC Voucher Recgarge

778 4.19.3.

779 780 781

Return Code

The voucher recharge operating is asynchronus and returns a job number. This number must be used with the VoucherJobMgr::getJobDetails to get return codes.

7824.20.

ASyncEngine::voucherRechargeSeq Operation

Caution:  The TINC package name space is inferred automatically in order to comply with Java 1.4.x 783 CORBA::Long voucherRechargeSeq(inout tincSeq pSeq, inout recordSeq rSeq) raises (Pi_exception);

784 785


786 787

Input Parameters

The parameter labels are enums defined in the TINC::GEOvoucherRechargeSeq interface.

Parameter

Type

Subid

Required

Description

CORBA::String

Key

Subscriber number

CallingPartyNumber

CORBA::String

Mandatory

International and Area Code

Voucher

CORBA::String

Mandatory

Voucher Number.

LocationId

CORBA::String

Mandatory

Current Location of the Subscriber.

ThisVoucherErrors

CORBA::Short

Mandatory

Number of errors made by the subscriber when entering this voucher number.

TransactionType

CORBA::Short

Mandatory

External transaction type to be placed in the CDR


Default


55 152

Parameter

Type

Default

Required

Description

transactionDate

eFfieldType::dtim e

Mandatory

Date and Time of Voucher Recharge to be placed in the CDR

corrleationSource

CORBA::Short

Mandatory


corrleationId

CORBA::Short

Mandatory


operatorId

CORBA::Long

Mandatory


None

788

4.20.2.

789

CDRs Generated by voucherRecharge


Description

3

IVR_VOUCHER_RECHARGE

IVR voucher Recharge

34

CC VOUCHER_RECHARGE

CC Voucher Recgarge

790 4.20.3.

791 792 793

Return Code

The voucher recharge operating is asynchronus and returns a job number. This number must be used with the VoucherJobMgr::getJobDetails to get return codes.

794

4.21.

795

VoucherJobMgr::getJobDetails Operation

Caution: The TINC package name space is inferred automatically in order to comply with Java 1.4.x 796 TINC:: is inferred

CORBA::Boolean getJobDetails( in long jobNo, inout VoucherJobDetails vjd, ) raises (Pi_exception);

797 798

Figure 4-21 Voucher Recharge

799



56 154

4.21.1.

800

Input Parameters

Parameter

Type

jobNo vjd

4.22.

801

Default

Required

Description

CORBA::Long

Key

The Job number returned from the voucherRecharge operation.

VoucherJobDetail s

Mandatory

Holder for the output parameters.

VoucherJobDetails Return Result Structure

802 Type

Field

Description

CORBA::Short

opState

The Result of the Voucher Recharge. See Result table below.

CORBA::String

subId

Subscriber Number

CORBA::Short

serviceStatus

Service Status 0: 1: 2: 3: 4: 5: 6: 7: 8:

CORBA::Short

accountStatus




CORBA::Long

accountBalance


TDateTime

expiryDate


CORBA::Long

periodicBalance

Periodic Balance (100,000 == 1)

TDateTime

periodicExpiry

Date of periodic expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Long

bonusBalance

Bonus Balance (100,000 == 1)

TDateTime

bonusExpiry

Date of bonus expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Long

smBalance

SM Balance (100,000 == 1)

TDateTime

smExpiry

Date of sm expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Long

dataBalance

Data Balance (100,000 == 1)



57 156

Type

Field

Description

TDateTime

dataExpiry

Date of data expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Long

smBonusBalance

SM Bonus Balance (100,000 == 1)

CORBA::Long

dataBonusBalance

Data Bonus Balance (100,000 == 1)

TDateTime

suspendDate

Suspended. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Short

rechargeFraudCounter

Recharge Fraud Counter

CORBA::Short

totalRechargeErrorCounter

Total Recharge Error Counter

CORBA::Short

balanceNotificationStatus

Balance Notification Status

CORBA::Short

expiryNotificationStatus

Expiry Notification Status

CORBA::Short

smBalanceNotificationStatus

Sm Balance Notification Status

CORBA::Short

smExpiryNotificationStatus

Sm Expiry Notification Status

CORBA::Short

profileID

Profile ID

CORBA::Long

subOptions


TDateTime

ivrQueryExpiryDate


CORBA::Short

ivrQueryCounter

IVR Query Counter

CORBA::Short

discountPercentage

Discount Percentage

CORBA::Long

overdraftBalance

Over Draft Balance (100,000 == 1) Future Use

CORBA::Long

overdraftActualValue

Overdraft Actual Value (100,000 == 1) Future Use

CORBA::Long

periodicBalance

Periodic Account Balance (100,000 == 1) Future Use

TDateTime

periodicExpiry


CORBA::Long

bonusBalance


The following Parameter releate to the voucher that has been recharged CORBA::Short

voucherType

Voucher Type

CORBA::Short

currencyCode

Currency Code

CORBA::Short

tariffPlanId

Tariff Plan Id

CORBA::String

voucherNo

Voucher No

CORBA::Long

faceValue

Face Value of the main part of the voucher.

CORBA::Long

actualValue

Actual Value of the main part of the voucher. (100,000 == 1)



58 158

Type

Field

Description

CORBA::Long

bonusFaceValue

Face Value of the Bonus part of the voucher.

CORBA::Long

bonusActualValue

Actual Value of the Bonus part of the voucher. (100,000 == 1)

CORBA::Long

smFaceValue

Face Value of the SM part of the voucher.

CORBA::Long

smActualValue

Actual Value of the SM part of the voucher. (100,000 == 1)

CORBA::Long

dataFaceValue

Face Value of the Data part of the voucher.

CORBA::Long

dataActualValue

Actual Value of the Data part of the voucher. (100,000 == 1)

CORBA::Long

extBonusAmount

Bonus Amount applied by an extranal VoMs

TDateTime

transactionDate

Data and time of the recahrge.

CORBA::Short

voucherSubType

Voucher Sub type, used for short voucher.

TDateTime

voucherExpiry

Date when the voucher credit will expire, used for short voucher.

CORBA::Long

smBonusFaceValue

Face Value of the SM Bonus part of the voucher.

CORBA::Long

smBonusActualValue

Actual Value of the SM Bonus part of the voucher. (100,000 == 1)

CORBA::Long

dataBonusFaceValue

Face Value of the Data Bonus part of the voucher.

CORBA::Long

dataBonusActualValue

Actual Value of the Data Bonus part of the voucher. (100,000 == 1)

CORBA::Long

packageId

The Id of the package that was recharge to the voice account. Future Use.

CORBA::Long

smPackageId

The Id of the package that was recharge to the SM account.

CORBA::Long

dataPackageId

The Id of the package that was recharge to the Data account.

803 804 805

Voucher Recharge Results


Result

Description

0

Success

1

Job is still in progress

2


3



59 160

Result

Description

100


101

ValueOutOfRange

103

InvalidParamType

104

InvalidParamCount

105

InvalidSubscriberId

106

InvalidVoucherNumber

107

VoucherNotPermitted

110

InvalidAccountStateError

111

InvalidServiceStateError

112

InvalidAccountError

120

MaxRechargeValueError

121

MaxChargeValueError

123

MinBalanceError

130

MaxRechargeFraudsError

131

MaxTotalRechargeError

150

VTTVoucherTypeError

151

VoucherQueueError

152

VoucherDenominationError

153

InvalidExpiryTypeError

160

InvalidVoucherError

161

VoucherNotFound

162

ExpiredVoucherError

163

DuplicateVoucherError

164

InvalidSecurityCodeError

165

VoucherAlreadyUsedBySub

170

MediationControlEnableTError (Success)

171

MediationControlEnableOErro r (Success)

172

MediationControlOtherError (Success)

180

CDRErrorRechargeSuccessInt (Success)

181

CDRErrorRechargeSuccessE xt (Success)

182

CDRErrorQualityOfServiceRe charge

183

CDRErrorQualityOfServiceRoll back

184

CDRErrorServiceOutage



60 162

8064.23.

Result

Description

185

CDRErrorRollbackFailureInt

186

CDRErrorRollbackFailureExt

187

CDRErrorCommitFailureExt

188

NoVoucherTypesForPrepaidS ervice

189

VoucherTypeNotPermitted

190

TVMVoucherTypeError

191

CreditAmountLookupError

192

ExternalEngineUnavailable

193

ExternalJob

194

EnvironmentError

200

TemporaryError

201

QualityOfService

202

ServiceOutage

203

CommsError

210

FatalError

220

ProgrammingError

VoucherJobMgr::getJobDetailsSeqOperation

Caution:  The TINC package name space is inferred automatically in order to comply with Java 1.4.x 807 CORBA::Long voucherRechargeSeq(inout tincSeq pSeq, inout recordSeq rSeq) raises (Pi_exception);

808 809


810 811

Input Parameters

The parameter labels are enums defined in the TINC::GEOvoucherRechargeSeq interface.

Parameter

Type

jobNo vjd

4.24.

812 813

Default

Required

Description

CORBA::Long

Key

The Job number returned from the voucherRecharge operation.

VoucherJobDetail s

Mandatory

Holder for the output parameters.

VoucherJob Details Return Result Sequence The parameter labels are enums defined in the TINC::GEOVoucherJobDetails interface.



61 164

814 Type

Field

Description

CORBA::Short

opState

The Result of the Voucher Recharge

CORBA::String

subId

Subscriber Number

CORBA::Short

serviceStatus

Service Status 0: 1: 2: 3: 4: 5: 6: 7: 8:

CORBA::Short

accountStatus




CORBA::Long

accountBalance


TDateTime

expiryDate


CORBA::Long

periodicBalance

Periodic Balance (100,000 == 1)

TDateTime

periodicExpiry

Date of periodic expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Long

bonusBalance

Bonus Balance (100,000 == 1)

TDateTime

bonusExpiry

Date of bonus expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Long

smBalance

SM Balance (100,000 == 1)

TDateTime

smExpiry

Date of sm expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Long

dataBalance

Data Balance (100,000 == 1)

TDateTime

dataExpiry

Date of data expiry. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Long

smBonusBalance

SM Bonus Balance (100,000 == 1)

CORBA::Long

dataBonusBalance

Data Bonus Balance (100,000 == 1)

TDateTime

suspendDate

Suspended. By default TINC:: name space is inferred before the TDateTime type.

CORBA::Short

rechargeFraudCounter

Recharge Fraud Counter

CORBA::Short

totalRechargeErrorCounter

Total Recharge Error Counter

CORBA::Short

balanceNotificationStatus

Balance Notification Status



62 166

Type

Field

Description

CORBA::Short

expiryNotificationStatus

Expiry Notification Status

CORBA::Short

smBalanceNotificationStatus

Sm Balance Notification Status

CORBA::Short

smExpiryNotificationStatus

Sm Expiry Notification Status

CORBA::Short

profileID

Profile ID

CORBA::Long

subOptions


TDateTime

ivrQueryExpiryDate


CORBA::Short

ivrQueryCounter

IVR Query Counter

CORBA::Short

discountPercentage

Discount Percentage

CORBA::Long

overdraftBalance

Over Draft Balance (100,000 == 1) Future Use

CORBA::Long

overdraftActualValue

Overdraft Actual Value (100,000 == 1) Future Use

CORBA::Long

periodicBalance

Periodic Account Balance (100,000 == 1) Future Use

TDateTime

periodicExpiry


CORBA::Long

bonusBalance


The following Parameter releate to the voucher that has been recharged CORBA::Short

voucherType

Voucher Type

CORBA::Short

currencyCode

Currency Code

CORBA::Short

tariffPlanId

Tariff Plan Id

CORBA::String

voucherNo

Voucher No

CORBA::Long

faceValue

Face Value of the main part of the voucher.

CORBA::Long

actualValue

Actual Value of the main part of the voucher. (100,000 == 1)

CORBA::Long

bonusFaceValue

Face Value of the Bonus part of the voucher.

CORBA::Long

bonusActualValue

Actual Value of the Bonus part of the voucher. (100,000 == 1)

CORBA::Long

smFaceValue

Face Value of the SM part of the voucher.

CORBA::Long

smActualValue

Actual Value of the SM part of the voucher. (100,000 == 1)

CORBA::Long

dataFaceValue

Face Value of the Data part of the voucher.

CORBA::Long

dataActualValue

Actual Value of the Data part of the voucher. (100,000 == 1)



63 168

Type

Field

Description

CORBA::Long

extBonusAmount

Bonus Amount applied by an extranal VoMs

TDateTime

transactionDate

Data and time of the recahrge.

CORBA::Short

voucherSubType

Voucher Sub type, used for short voucher.

TDateTime

voucherExpiry

Date when the voucher credit will expire, used for short voucher.

CORBA::Long

smBonusFaceValue

Face Value of the SM Bonus part of the voucher.

CORBA::Long

smBonusActualValue

Actual Value of the SM Bonus part of the voucher. (100,000 == 1)

CORBA::Long

dataBonusFaceValue

Face Value of the Data Bonus part of the voucher.

CORBA::Long

dataBonusActualValue

Actual Value of the Data Bonus part of the voucher. (100,000 == 1)

CORBA::Long

packageId

The Id of the package that was recharge to the voice account. Future Use.

CORBA::Long

smPackageId

The Id of the package that was recharge to the SM account.

CORBA::Long

dataPackageId

The Id of the package that was recharge to the Data account.

815

4.25.

816

PI Exceptions

4.25.1.

817

General Error Codes

General Error Code

Description

1

GENERAL_ERROR. General Server Error

2

DATABASE_ERROR. General database problem

3

OP_NOT_IMPLEMENTED. Operation not yet implemented

4

INIT_ERROR. Initialisation Error

5

INVALID_KEY. The Key that was given is incorrect

6

FILE_CREATE_ERROR. Cannot create file on server

7

FILE_ERROR. Server file error - examine log

8

DEFAULTS_FILE_ERROR. Cannot read file on server

9

INCOMPLETE_STRUCT. IDL struct recieved was not fully populated by the client



64 170

General Error Code

Description

10

OFFSET_EXCEEDED. Offset requested exceeds number of records available

11

TIMESTAMP_INVALID. Timestamps from the loadme to update were not equal

12

INVALID_LENGTH. Invalid Length

4.25.2.

818

IDL GW Specific Error Codes

IDL GW Specific Error Codes

Description

100

MAX_TRANSACTIONS_EXCEEDED

101

MISSING_KEY. Required key data not given

102

UNEXPECTED_ID. Usage error

103

UNEXPECTED_TYPE. Usage error

104

USER_TYPE. not available for this user type

105

INVALID_USER_TYPE. Invalid User Type

819 4.25.3.

820

User/Subscriber Error Codes

User / Subscriber Description Error Codes 201

MAXIMUM_USER_LIMIT. Max number of users logged in

202

INVALID_USER_ID. Invalid user id number

203

INVALID_PASSWORD. Incorrect password supplied

204

INVALID_LOGIN_DETAILS. Invalid user name or password

205

INVALID_LOGIN_NAME. Invalid user login id supplied

206

INVALID_VALUE. Cannot recharge by this amount

207

LOGIN_IN_USE. This Login name is already being used

208

NO_CDRS_AVAILABLE. No CDRs stored for this subscriber

209

INCOMPLETE_LOGIN. Missing login or user name

210

AGENT_DENIED. Agent does'nt have permission for this operation

211

SUBSCRIBER_DENIED. Subscriber does'nt have permission for this operation

212

MISSING_ESN. No ESN number supplied

213

ESN_IN_USE. ESN number already in use by other subscriber

214

ESN_IN_USE_BY. ESN number already in use by Subscriber

215

RANGE_EXCEEDED. Cannot allocate range this size with the MIN supplied - range is too big

216

NO_MIN_AVAILABLE. No MIN matching prefix given



65 172

User / Subscriber Description Error Codes 217

SUB_NUMB_TOO_SHORT. Subscriber Number too short for CDR file

218

SUB_EXISTS_IN_CACHE. Subscriber currently in cache

219

SMID_IN_USE. SM number already in use

220

VOUCHER_TRACK_NO. Voucher Tracking not allowed

221

INVALID_SMID. SM number not valid

222

UPDATE_MIN_FAILURE. updateMIN Failed

223

INVALID_FF_PHONE_NUMBERS_LENGTH. Invalid length of F&F Phone Numbers String

224

INVALID_FF_PHONE_NUMBER_CHARACTERS. Invalid F&F Characters

821 4.25.4.

822

Voucher Error Codes

Voucher Error Codes

Description

501

ORDER_NOT_FOUND. No such Print Order

502

ORDER_ITEM_NOT_PRINTED. Order item must be in a 'printed' state for regeneration

503

ORDER_NOT_PRINTED. Order must be in a 'printed' state for regeneration

504

NOT_IN_STOCK. Can only issue from available stock

505

BOX_ROLLBACK_ERROR. Could not rollback box issue

506

BATCH_ROLLBACK_ERROR. Could not rollback batch issue

507

BOX_ISSUE_ERROR. Could not commit issue of vouchers

508

BATCH_ISSUE_ERROR. Could not commit issue of vouchers

509

BATCH_ACTIVATE_ERROR. Could not commit activation of vouchers

510

VOUCHER_ACTIVATE_ERROR. Could not commit activation of vouchers

511

BATCH_NOT_ISSUED. Can only activate batches issued to you

512

BOX_PENDING_TRAN. Transaction already pending on this box

513

BATCH_PENDING_TRAN. Transaction already pending on this batch

514

INVALID_BOX. No Such Box

515

INVALID_BATCH. No Such Batch

516

INVALID_VOUCHER. No Such Voucher

517

VOUCHER_LENGTH_ERROR. Invalid Voucher length

518

INCORRECT_VOUCHER_STATE. INCORRECT_VOUCHER_STATE

519

VOUCHER_ALREADY_USED. Cannot re-use a voucher

520

short VOUCHER_ALREADY_USED_BY. Voucher already used by Subscriber

521

VOUCHER_ISSUE_ERROR. Could not commit issue of vouchers



66 174

Voucher Error Codes

Description

522

VOUCHER_CANCEL_ERROR. Could not rollback issue of vouchers

523

CANCEL_BATCH_ACTIVATE. Could not rollback batch activation

524

VOUCHER_ACTIVATE_CANCEL. Could not rollback batch activation

525

VOUCHER_NOT_FOUND. Invalid Voucher not found

526

INVALID_VOUCHER_LENGTH. Invalid Voucher not found

527

NO_SUCH_BATCH. Voucher batch does not exist

528

NON_ISSUED_ACTIVATE. Can only activate an issued batch

529

NO_SUCH_BOX. Voucher Box does not exist

530

INVALID_BATCH_NO. No Such Batch

531

INVALID_BOX_NO. No Such Batch

532

VOUCHER_DOES_NOT_EXIST. Voucher does not exist

533

INCORRECT_VOUCHER_STATE. Voucher is not in an Activated State

823 4.25.5.

824

Job Control Error Codes

Job Control Error Description Codes 901

JOB_ERROR. A job Operation failed

902

JOB_WARNING. A job Check Job via Job Management GUI failed

903

PROV_UNEXPECTED_PARAM. Unexpected parameter when creating a Sub

904

PROV_UNEXPECTED_TYPE. Unexpected parameter type when creating a Sub

905

COMMIC_FAILURE. Unexpected exception when trying to communicate with the Comic server

906

JOB_WIP. Job still in progress

825 4.25.6.

826

Payment Engine Error Codes

PayementEngine Error Codes

Description

1001

MAX_RECHARGE_EXCEEDED. Max recharge value exceeded

1002

INVALID_CREDIT. Incomplete or invalid credit card details

1003

CARD_EXPIRED. Credit card has expired

1004

CREDIT_LIMIT_EXCEEDED. This recharge would exceed the max allowed credit

1005

BLOCK_RECHARGE. Recharge Blocked to many Vouchers in Queue

1006

NO_SHUTDOWN_RECHARGE. Cannot Recharge a Subscriber in a state of Shutdown

1007

AMOUNT_LE_SURCHARGE. Recharge Failed, Ammount less than Surcharge



67 176

PayementEngine Error Codes

Description

1008

ACCOUNT_BLOCKED. Subscriber Account Blocked

1009

INVALID_ACCOUNT_STATUS. Invalid account Status

1010

INVALID_SERVICE_STATUS. Invalid service Status

1011

VOUCHER_QUEUE_ERROR. Voucher Queue Error

827



68 178

Appendix A: AuthFactory.idl

828 829

Sample code is available in the following directories on the PSP:

830

/opt/TINCpsp/4.38/examples/cpp

831

/opt/TINCpsp/4.38/examples/java

832 833



69 180

Appendix B: Exceptions.idl

834 835


836


837


838 839 840



70 182

Appendix C: TINCdefs.idl

841 842


843


844


845 846 847



71 184

Appendix D: Types.idl

848 849 850


851


852


853 854



72 186

Appendix E: PaymentEngine.idl

855 856 857


858


859


860 861



4. Payment Interface Operations

73

188

Appendix F: AuthFactory_impl.java

862 863


864


865


866 867



74

.

190 868

import java.io.*;

869

import java.util.*;

870

import org.omg.CORBA.*;

871

import tinc.*;

872

class AuthFactory_impl

873

{

874

//////////////////////////////////////////

875

// Local variable definitions

876

//////////////////////////////////////////

877 878

private String iorFileName = new String();

879

private String iorString

880

private AuthFactory authFactory;

881

private String[] program_args;

882

private long Key;

883

private boolean connected = false;

884 885

public AuthFactory_impl (String[] args, String _iorFileName)

886

{

= new String();

887

Trace.trace(4,"PaymentClient :> AuthFactory_impl::AuthFactory_impl() -> Constructor");

888

iorFileName = _iorFileName;

889

program_args = args;

890

readAuthIORFile();

891 892

if(initFactory())

893

{

894

Trace.trace(4,"PaymentClient :> Connected to AuthFactory");

895

connected = true;

896

}

897

else

898

{

899

Trace.trace(4,"PaymentClient :> Failed to Connect to AuthFactory");

900

connected = false; }

901 902

}

903 904

public boolean initFactory()

905

{

906

Trace.trace(4,"PaymentClient :> AuthFactory_impl::initFactory()");

907 908

ORB orb = ORB.init(program_args,null);

909

Trace.trace(4,"PaymentClient :> Connecting to Server "+iorString);

910

org.omg.CORBA.Object factoryObj = orb.string_to_object(iorString) ;

911 912

if(factoryObj == null)

913

{



75 192 914

Trace.trace(1,"PaymentClient :> factory Object is not valid");

915

return false;

916

}

917 918

try

919

{

920

authFactory = AuthFactoryHelper.narrow(factoryObj);

921 922

if(authFactory == null)

923

{

924

Trace.trace(1,"PaymentClient :> authFactory Object is not a factory");

925

return false; }

926 927

}

928

catch (COMM_FAILURE e)

929

{ Trace.traceException(1,e);

930

return false;

931 932

}

933

catch (SystemException e)

934


935

return false;

936 937

}

938

catch (Exception e)

939


940

return false;

941 942

}

943 944

return (factoryObj != null);

945

}

946 947

public void readAuthIORFile()

948

{

949

Trace.trace(4,"PaymentClient :> AuthFactory_impl::readAuthIORFile()");

950 951

File fileToParse = new File (iorFileName);

952

FileInputStream parseFileInputStrm = null;

953 954

try

955

{

956

if (!fileToParse.canRead())

957

{

958

Trace.trace(1,"PaymentClient :> Failed to read the file");

959

System.out.println("PaymentClient :> Failed to open file:"+iorFileName);



76

.

194 960

Trace.trace(1,"PaymentClient :> Bad Config File Name");

961

System.exit(-1); }

962 963

}

964

catch (Exception e)

965

{

966

Trace.traceException(1,e);

967

System.out.println("PaymentClient :> Failed to open ior file:");

968

System.exit(-1);

969

}

970 971

try

972

{

973

parseFileInputStrm = new FileInputStream(fileToParse);

974

java.io.DataInputStream dis = new java.io.DataInputStream(parseFileInputStrm);

975

iorString = dis.readLine() ; }

976

catch (IOException ex){}

977 978

}

979 980

//

981

// This method will validate the user with the AuthServer and give back a

982

// List of IOR's to servers and keys which that user can connect to

983

// NOTE: Administrator and Operator users should be able to talk to all servers

984

// NOTE: If the server itself did not register with the AuthServer it's IOR

985

//

986

//

987

public UserInfo login (String User, String Password, ServiceKeySeqHolder sSeq)

988

{

will not be known, make sure the server you wish to connect to is running

Trace.trace(4,"PaymentClient :> AuthFactory_impl::login()");

989 990 991

// Will hold the id and type of a validated user

992

UserInfo uf = new UserInfo(-1,(short)-1);

993 994

if(!connected) return uf;

995 996 997

if(authFactory == null)

998

{ Trace.trace(1,"PaymentClient :> authFactory Object is not a factory");

999

return uf;

1000 1001

}

1002 1003

try

1004

{ // Talk with the AuthServer

1005



77 196 1006

Trace.trace(4,"PaymentClient :> Before: authFactory.login()");

1007

uf = authFactory.login(User,Password,sSeq);

1008

}

1009

catch (Pi_exception pix)

1010

{

1011

Trace.trace(1,"PaymentClient :> AuthFactory_impl::login() -> Exception: "+pix);

1012

return uf;

1013

}

1014

catch(NullPointerException e)

1015

{

1016

Trace.trace(1,"PaymentClient :> AuthFactory_impl::login() -> Exception: "+e);

1017

return uf;

1018

}

1019

catch (COMM_FAILURE e)

1020

{

1021

Trace.trace(1,"PaymentClient :> AuthFactory_impl::login() -> org.omg.CORBA.COMM_FAILURE");

1022

return uf;

1023

}

1024

catch (SystemException e)

1025

{

1026


1027

return uf;

1028

}

1029

catch (Exception e)

1030

{

1031


1032

return uf; }

1033 1034

return uf;

1035

}

1036

}

1037



78

.

198

Appendix G: PaymentEngine.java

1038 1039


1040


1041


1042 1043 1044



79 200 1045

import java.io.*;

1046

import java.util.*;

1047


1048

import java.net.*;

1049

import tinc.*;

1050

public class PaymentEngine_impl

1051

{

1052

private PaymentEngine paymentEngine = null;

1053

private int operatorId = -1;

1054 1055

public PaymentEngine_impl(PaymentEngine _paymentEngine, int _operatorId)

1056

{

1057

Trace.trace(4,"PaymentClient :> PaymentEngine_impl::PaymentEngine_impl()");

1058

paymentEngine = _paymentEngine;

1059

operatorId = _operatorId;

1060

}

1061 1062

//

1063

// Once a connection to a paymentEngine is estabilished requests can be sent to it

1064

// The paymentEngine will return details of the request and the subscriber.

1065

// Note: These details will only be valid on a succesfull request, as defined by the result.

1066

//

1067

public PE_AccountDetails directFundTransfer(String _subid,int _amount, short _transactionType)

1068

{

1069

Trace.trace(4,"PaymentClient :> directFundTransfer("+_subid+","+_amount+","+_transactionType+")");

1070 1071

PE_AccountDetails ad;

1072 1073

try

1074

{ // Talk withe the paymentEngine

1075 1076

// declare some dummy params to satisfy the IDL int _rechargeDiscountrate = 0;

1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087

TDateTime _expiryDate; expiryDate.day = 1; expiryDate.month = 1; expiryDate.year = 1970; expiryDate.hour = 0; expiryDate.minute = 0; expiryDate.second = 0; ad = paymentEngine.directFundTransfer(_subid,_amount,_rechargeDiscountRate,_expiryDate_transactionType, operatorId);

1088 1089 1090

}

1091

catch (org.omg.CORBA.COMM_FAILURE corbEx)

1092

{ Trace.trace(1,"PaymentClient :> Exception:COMM_FAILURE");

1093



80

.

202 1094

Trace.traceException(1, corbEx);

1095

}

1096

catch (org.omg.CORBA.SystemException systemEx)

1097

{

1098

Trace.trace(1,"PaymentClient :> Exception:SystemException");

1099

Trace.traceException(1, systemEx);

1100

}

1101

catch(Exception ex)

1102

{

1103

Trace.trace(1,"PaymentClient :> Exception");

1104

Trace.traceException(1, ex); }

1105

return ad;

1106

}

1107 1108 1109

public PE_AccountDetails directDebitTransfer(String _subid,int _amount, short _transactionType)

1110

{

1111

Trace.trace(4,"PaymentClient :> directDebitTransfer("+_subid+","+_amount+","+_transactionType+")");

1112 1113


1114 1115

try

1116

{

1117

// Talk withe the paymentEngine

1118

ad = paymentEngine.directDebitTransfer(_subid,_amount,_transactionType,operatorId);

1119

}

1120


1121

{

1122

Trace.trace(1,"PaymentClient :> Exception:COMM_FAILURE");

1123


1124

}

1125


1126

{

1127


1128


1129

}

1130

catch(Exception ex)

1131

{

1132


1133

Trace.traceException(1, ex);

1134

}

1135

return ad; }

1136 1137

}

1138



81 204

1139

Appendix H: RechargeClient.java

1140


1141


1142


1143 1144 1145



82

.

206 1146

////////////////////////////////////////////////////////////////////////////////

1147

// Copyright Tecnomen Corp. 2003. All rights reserved.

1148

//

1149

// $Workfile: rechargeClient.java $

1150

// Declan Lynch - Oct 2003

1151

//

1152

// Description:

1153

// Main - Connects to a paymentEngine a send requests to the paymentEngine

1154

//////////////////////////////////////////////////////////////////////////////////

1155 1156

import java.io.*;

1157

import java.util.*;

1158


1159

import java.net.*;

1160

import tinc.*;

1161

public class rechargeClient

1162

{

1163

private static final int PAYMENT = 100;

1164

private static final String VERSION_ID = "$Revision: 1.5 $";

1165

private static final String PRODUCT_NAME = "Customer Care";

1166

private static String processName = "rechargeClient";

1167 1168

// The key that will be used to get and release engines from the server

1169

private static int factoryKey = -1;

1170

// The engineId id used in releaseing the Engine

1171

private static int engineId = -1;

1172 1173

// The operator id that the rquests will carried out under

1174

// Note: This will be the operator that can be seen on the CDR

1175

private static int operatorId = -1;

1176 1177

// The handle to the Factory

1178

private static PaymentEngine_Factory paymentFactory = null;

1179 1180

// The wrapper class the talk to the Engine

1181

private static PaymentEngine_impl paymentEngine_impl = null;

1182 1183

private static String User = "";

1184

private static String Password = "";

1185 1186

// The default location of the Auth IOR file

1187

// this can be changed using the -I comand line paramater

1188

private static String AuthIorPath = "/mountp/var/ior/authServer.ior";

1189 1190

// Method that will get a handle on a external paymentEngine.

1191

// Step 1. validate the user with the AuthServer and get a IOR List



83 208 1192

// Step 2. search the list for a paymentEngine Factory Ior

1193

// Step 3. using the IOR get a handle on the paymentEngine Factory

1194

// Step 4. using the paymentEngine Factory get a handle on the paymentEngine

1195

//

1196

//

1197

// Note : If the key is not the one that was returned from the AuthServer

1198

//

1199 1200

private static boolean getPaymentEngine(String[] args)

1201

{

using the key to login with the Factory.

the factory will reject the request.

Trace.trace(4,"PaymentClient :> Path to Auth Server IOR:"+AuthIorPath);

1202 1203 1204

boolean Continue = false;

1205 1206

try

1207

{

1208

//

1209

// Step 1. validate the user with the AuthServer and get an IOR List

1210

//

1211

String ior = new String();

1212 1213

// construct a holder for the inout sequence

1214

ServiceKeyRec[] emptyServiceKeyRec = new ServiceKeyRec[]{};

1215

ServiceKeySeqHolder serviceKeySeq = new ServiceKeySeqHolder(emptyServiceKeyRec);

1216

// create an AuthFactory handle

1217 1218

Trace.trace(4,"PaymentClient :> Creating AuthFactory_impl");

1219

AuthFactory_impl factory = new AuthFactory_impl(args,AuthIorPath);

1220 1221

// Talk with the AuthServer via the wrapper class

1222

Trace.trace(4,"PaymentClient :> Validating User/Password");

1223

UserInfo uf = factory.login(User,Password,serviceKeySeq);

1224 1225

if(uf.id == -1 || uf.type == -1) { Trace.trace(4,"PaymentClient :> Failed to Login ");

1226

Continue = false;

1227

} else {

1228 1229

// The operatorId will be used in the CDR of the recharge

1230

operatorId = uf.id;

1231

Trace.trace(4,"PaymentClient :> Logged in User " +User

1232

+" Id " +uf.id

1233

+" Type " +uf.type); Continue = true;

1234

}

1235 1236

// Step 2. search the serviceKeySeq list for a paymentEngine Factory record

1237



84

.

210 1238

if (Continue)

1239

{

1240

int elements = serviceKeySeq.value.length;

1241

Trace.trace(4,"PaymentClient :> No of elements in serviceKeySeq " + elements);

1242

for (int i=0;i
1243

{

1244

if(serviceKeySeq.value[i].service == PAYMENT)

1245

{ // extract the key that's later used to login to the paymentEngine Factory

1246

factoryKey = serviceKeySeq.value[i].key;

1247

// extract the CORBA IOR to allow use to connect to the paymentEngine Factory

1248 1249

ior = serviceKeySeq.value[i].ior;

1250

Trace.trace(4,"PaymentClient :> Found PAYMENT with a key " + factoryKey);

1251

Continue = true;

1252

break; }

1253

}

1254

}

1255 1256 1257

if(Continue)

1258

{

1259

// Step 3. using the IOR get a handle on the paymentEngine Factory

1260

ORB orb = ORB.init(args,null);

1261

org.omg.CORBA.Object paymentFactoryObj = orb.string_to_object(ior) ;

1262 1263

if(paymentFactoryObj == null)

1264

{

1265

Trace.trace(1,"PaymentClient :> paymentFactoryObj Object is not valid");

1266

Continue = false; }

1267 1268 1269

// narrow the CORBA object to a PaymentEngine_Factory

1270

paymentFactory = PaymentEngine_FactoryHelper.narrow(paymentFactoryObj);

1271 1272

if(paymentFactory == null)

1273

{ Trace.trace(1,"PaymentClient :> paymentFactory Object is not a factory");

1274

Continue = false;

1275

}

1276 1277 1278

// Step 4. using the paymentEngine Factory get a handle on the paymentEngine

1279

//

using the key to login to the Factory.

PaymentEngine paymentEngine = paymentFactory.getPaymentEngine(factoryKey);

1280 1281 1282

if (paymentEngine == null)

1283

{



85 212 1284

Trace.trace(1,"PaymentClient :> paymentEngine Object is not a factory"); Continue = false;

1285 1286

}

1287

else

1288

{

1289

Trace.trace(1,"PaymentClient :> Connected to paymentEngine");

1290 1291

// The engineId is used for releasing the paymentEngine later

1292

engineId = paymentEngine.engineId();

1293 1294

// Setup a wrapper class with the paymentEngine and the operId

1295

paymentEngine_impl = new PaymentEngine_impl(paymentEngine,operatorId); Continue = true;

1296

}

1297

}

1298 1299

}

1300


1301

{

1302

Trace.trace(1,"PaymentClient :> Exception:COMM_FAILURE");

1303


1304

Continue = false;

1305

}

1306


1307

{

1308


1309


1310

Continue = false;

1311

}

1312

catch(Exception ex)

1313

{

1314


1315

Trace.traceException(1, ex); Continue = false;

1316 1317

}

1318

Trace.trace(1,"DLY Returning " + Continue);

1319

return Continue; }

1320 1321 1322

//

1323

// Every paymentEngine that is bound, must be released !!!

1324

//

1325

private static boolean releasePaymentEngine()

1326

{

1327

Trace.trace(4,"PaymentClient :> Path to Auth Server IOR:"+AuthIorPath);

1328 1329




86

.

214 1330 1331

try

1332

{

1333

if(factoryKey >= 0)

1334

{

1335

Trace.trace(4,"PaymentClient :> Release PaymentEngine["+engineId+"]");

1336

Continue = paymentFactory.releasePaymentEngine(factoryKey, engineId); }

1337 1338

}

1339


1340

{ Trace.trace(1,"PaymentClient :> Exception:COMM_FAILURE");

1341 1342


1343

Continue = false;

1344

}

1345


1346

{

1347


1348


1349

Continue = false;

1350

}

1351

catch(Exception ex)

1352

{

1353


1354

Trace.traceException(1, ex);

1355

Continue = false;

1356

}

1357 1358

return Continue;

1359

}

1360 1361

private static void process()

1362

{

1363

Trace.trace(4,"PaymentClient :> process()");

1364

boolean Continue = true;

1365

while(Continue)

1366

{

1367

String option = options();

1368

if(option.equals("F"))

1369

{

1370

System.out.println("directFundTransfer");

1371

directFundTransfer();

1372

}

1373

else if(option.equals("D"))

1374

{ System.out.println("directDebitTransfer");

1375



87 216 1376

directDebitTransfer();

1377

}

1378

else if(option.equals("Q"))

1379

{ Continue = false;

1380 1381

}

1382

else

1383

{ System.out.println("Invalid Option : " +option);

1384

}

1385

}

1386 1387

}

1388 1389

private static String options()

1390

{

1391

Trace.trace(4,"PaymentClient :> options()");

1392

String option = new String();

1393 1394

System.out.println("Options:");

1395

System.out.println("(F)irectFundTransfer:");

1396

System.out.println("(D)irectDebitTransfer:");

1397

System.out.println("(Q)uit:");

1398

System.out.println(": ");

1399 1400

BufferedReader br = new BufferedReader(new InputStreamReader(System.in));

1401 1402

try {

1403

option = br.readLine();

1404

} catch (IOException ioe) {

1405

System.out.println("IO error trying to read option!");

1406

System.exit(1);

1407

}

1408 1409

return option;

1410

}

1411 1412

private static void directFundTransfer()

1413

{

1414


1415 1416


1417

String subIdStr = new String();

1418

String amountStr = new String();

1419

String tranTypeStr = new String();

1420 1421

// declare a holder for the returned data struct



88

.

218 1422


1423

ad.result = -1;

1424 1425


1426 1427

try {

1428 1429

System.out.println("Sub Id:");

1430

subIdStr = br.readLine();

1431 1432

System.out.println("Amount :");

1433

amountStr = br.readLine();

1434 1435

System.out.println("Tranasation Type :");

1436

tranTypeStr = br.readLine();

1437 1438

Continue = true;

1439 1440

// Send the request to the paymentEngine for processing

1441

ad = paymentEngine_impl.directFundTransfer(subIdStr,

1442

Integer.parseInt(amountStr),

1443

Short.parseShort(tranTypeStr));

1444

}

1445

catch (IOException ioe)

1446

{

1447

System.out.println("IO error trying to read input!");

1448

Continue = false;

1449

}

1450

catch (NumberFormatException nfe)

1451

{

1452

System.out.println("Invalid Number");

1453

Continue = false;

1454

}

1455 1456

// The Account Details are only valid when the operation was a success

1457

System.out.println("****************************");

1458

System.out.println("");

1459

System.out.println("Result : "+ad.result);

1460

System.out.println("TransferResult : "+ad.transferResult);

1461

if(Continue && (ad.result != -1))

1462

{

1463

System.out.println("Account Balance : "+ad.accountBalance);

1464

System.out.println("Service Status : "+ad.serviceStatus);

1465

System.out.println("Account Status : "+ad.accountStatus);

1466

System.out.println("ExpiryDate : "+ad.expiryDate.day +"/" + ad.expiryDate.month + "/"

1467



89 220 1468

+ ad.expiryDate.year + " "

1469

+ ad.expiryDate.hour + ":"

1470

+ ad.expiryDate.minute + ":"

1471

+ ad.expiryDate.second);

1472

System.out.println("Profile Date : "+ad.profileId);

1473

System.out.println("SubOptions : "+ad.subOptions);

1474

System.out.println("IVR Query Expiry Date : "+ad.ivrQueryExpiryDate.day + "/"

1475

+ ad.ivrQueryExpiryDate.month + "/"

1476

+ ad.ivrQueryExpiryDate.year + " "

1477

+ ad.ivrQueryExpiryDate.hour + ":"

1478

+ ad.ivrQueryExpiryDate.minute + ":"

1479

+ ad.ivrQueryExpiryDate.second); System.out.println("IVR Query Counter "+ad.ivrQueryCounter);

1480 1481

}

1482


1483


1484

}

1485 1486

private static void directDebitTransfer()

1487

{

1488


1489 1490


1491

String subIdStr = new String();

1492

String amountStr = new String();

1493

String tranTypeStr = new String();

1494 1495

// declare a holder for the returned data struct

1496


1497

ad.result = -1;

1498 1499


1500 1501

try {

1502 1503

System.out.println("Sub Id:");

1504

subIdStr = br.readLine();

1505 1506

System.out.println("Amount :");

1507

amountStr = br.readLine();

1508 1509

System.out.println("Tranasation Type :");

1510

tranTypeStr = br.readLine();

1511 1512

Continue = true;

1513



90

.

222 1514

// Send the request to the paymentEngine for processing

1515

ad = paymentEngine_impl.directDebitTransfer(subIdStr,

1516

Integer.parseInt(amountStr),

1517

Short.parseShort(tranTypeStr));

1518

}

1519

catch (IOException ioe)

1520

{

1521

System.out.println("IO error trying to read input!");

1522

Continue = false;

1523

}

1524

catch (NumberFormatException nfe)

1525

{

1526

System.out.println("Invalid Number");

1527

Continue = false;

1528

}

1529 1530

// The Acount Details are only valid when the operation was a success

1531


1532


1533

System.out.println("Result : "+ad.result);

1534

System.out.println("TransferResult : "+ad.transferResult);

1535

if(Continue && (ad.result != -1))

1536

{

1537

System.out.println("Account Balance : "+ad.accountBalance);

1538

System.out.println("UnCharged Balance : "+ad.amountBalance);

1539

System.out.println("Service Status : "+ad.serviceStatus);

1540

System.out.println("Account Status : "+ad.accountStatus);

1541

System.out.println("ExpiryDate : "+ad.expiryDate.day +"/"

1542

+ ad.expiryDate.month + "/"

1543

+ ad.expiryDate.year + " "

1544

+ ad.expiryDate.hour + ":"

1545

+ ad.expiryDate.minute + ":" + ad.expiryDate.second);

1546 1547

System.out.println("Profile Date : "+ad.profileId);

1548

System.out.println("SubOptions : "+ad.subOptions);

1549

System.out.println("IVR Query Expiry Date : "+ad.ivrQueryExpiryDate.day + "/"

1550

+ ad.ivrQueryExpiryDate.month + "/"

1551

+ ad.ivrQueryExpiryDate.year + " "

1552

+ ad.ivrQueryExpiryDate.hour + ":"

1553

+ ad.ivrQueryExpiryDate.minute + ":"

1554

+ ad.ivrQueryExpiryDate.second); System.out.println("IVR Query Counter "+ad.ivrQueryCounter);

1555 1556

}

1557


1558

System.out.println("****************************"); }

1559



91 224 1560 1561

private static void usage( String processName_ )

1562

{

1563

System.out.println("usage:");

1564

System.out.println(processName_);

1565

System.out.println("

-U ");

1566


-P ");

1567


-T ");

1568


-I ");

}

1569 1570 1571

public static void main(String[] args)

1572

{

1573

int i = 0;

1574

String arg;

1575 1576

//////////////////////////////////////////

1577

// Process command line parameters

1578

//////////////////////////////////////////

1579

while (i < args.length && args[i].startsWith("-"))

1580

{ arg = args[i++];

1581 1582 1583

if (arg.equals("-v"))

1584

{ System.out.println("\nVersion:"+ VERSION_ID+"\n");

1585 1586

}

1587

else if (arg.equals("-U"))

1588

{

1589

if (i < args.length)

1590

{ User = (args[i++]);

1591 1592

}

1593

else

1594

{ System.err.println("[-U] option requires User Name ");

1595

}

1596 1597

}

1598

else if (arg.equals("-P"))

1599

{

1600


1601

{ Password = (args[i++]);

1602 1603

}

1604

else

1605

{



92

.

226 1606

System.err.println("[-P] option requires Password "); }

1607 1608

}

1609

else if (arg.equals("-I"))

1610

{

1611


1612

{ AuthIorPath = (args[i++]);

1613 1614

}

1615

else

1616

{ System.err.println("[-I] option requires Password ");

1617

}

1618 1619

}

1620

else if (arg.equals("-T"))

1621

{

1622


1623

{ Trace.setTraceLevel(5,(args[i++]));

1624 1625

}

1626

else

1627

{ System.err.println("[-I] option requires Password ");

1628

}

1629 1630

}

1631

else usage(processName);

1632 1633

}

1634 1635

if(getPaymentEngine(args))

1636

{

1637

process();

1638

// Alway release after a Engine is finished with

1639

releasePaymentEngine(); }

1640

}

1641

}

1642 1643 1644



93 228

Appendix I: RechargeClient.sh

1645 1646


1647


1648


1649 1650 1651



94

.

230

Appendix J: Trace.java

1652 1653


1654


1655


1656 1657 1658



95 232

Appendix K: SimpleClient.java

1659 1660 1661


1662


1663


1664 1665



96

.

234

Appendix L: TPEDefs.idl

1666 1667


1668


1669


1670 1671

1672



Definitions and References

97

236

Definitions and References

1673

1674Definitions 1675 1676 1677 1678

IOR CORBA

Interoperable Object Reference Common Object Reference Broker Architecture

1679References 1680

/1/

Mediation Device Router, Operation Manual

1681

/2/

Customer Care Administrator Manual

1682

/3/

Periodic Account, Feature Description


Payment Interface 5035581/9+

Payment Interface - Technical Description

Recommend Documents