1
Payment Interface
Prepaid 4.3.8
Technical Description
5035581/9 2
2
Payment Interface 3
3Copyright 4 5 6 7 8
Copyright © Tecnomen Corporation 2008. All rights reserved. No part of this document may be reproduced, distributed, stored in a retrieval system or translated into any language, in any form or by any means, electronic, mechanical, magnetic, optical, photocopying, manual or otherwise, without the prior written permission of Tecnomen. For additional copies of the document, please contact Tecnomen by e-mail:
[email protected].
9Disclaimer 10 11 12 13 14
Tecnomen makes no representations or warranties with respect to the contents hereof and specifically disclaims any implied warranties of merchantability or fitness for any particular purpose. Further, Tecnomen reserves the right to revise this publication and to make changes from time to time in the contents hereof without obligation to notify any person of such revision or changes.
15Feedback 16 17 18 19
Tecnomen endeavours to provide accurate and useful documentation for all Tecnomen products. To achieve this goal, the documentation group welcomes your comments and suggestions regarding any aspect of Tecnomen user documentation. Send your comments by e-mail to:
[email protected].
20Trademarks and Registered Trademarks 21 22
Products and product names mentioned in this document may be trademarks or registered trademarks of their respective owners.
23Revision History Version Issued 1
12.07.2006
Supports Prepaid 4.3.8.
2.
14.07.2006
‘Input Parameters’ added to accountQuery Operation section. ‘Input Parameters’ added to accountUpdate Operation section. ‘Input Parameters’ added to periodFundTransfer Operation section. Added the following new sections: onlineFundTransferSeq Operation; PeriodFundTransferSeq Operation; directDebitTransferSeq Operation; directFundTransferSeq Operation; accountUpdateSeq Operation and accountQuerySeq Operation.
3
28.08.2006
Sections 2.1 and 4.1 was updated and the following new sections were added: 4.2, 4.16, 4.17, 4.18, 4.19, 4.20, 4.21 and 4.22. PaymentEngine:: was added to the name of the operation in sections 4.3, 4.4, 4.5, 4.6, 4.7, 4.8, 4.9, 4.10, 4.11, 4.12, 4.13, 4.14 and 4.15.
4
31.08.2006
Added Section 4.16.4.
5
20.09.2006
Supports Prepaid 4.3.8. Added Section 4.12 FundAccountTransfer. Updated Section 4.17 PackageRecharge Operation.
6
28.11.2006
Updated Output Seq parameters in fundAccountTransfer operation.
7
20.09.2007
Updated packageRecharge Minor Result Code 11.
5035581/9 4
Description
Copyright © Tecnomen Corporation 2008
Payment Interface 5
Version Issued
Description
8
15.05.2008
updated the fundTransfer minor result codes.
9
26.05.2008
Added PaymentEngine::voucherRecharge operation
Document Status Issue date
5035581/9 Issued 26.05.2008
Author Editor Acceptor
Louise Naimi Louise Naimi Louise Naimi
Payment Interface 7
Preface
24
25About 26 27
This Document This document describes Tecnomen’s Payment Interface as a centralised payment related service.
28Audience 29
This document is intended for Tecnomen personnel and customer use.
30
This document assumes familiarity with Tecnomen’s Prepaid 4.3.8 Release.
31Notational 32
Conventions
The following margin symbols may be used throughout this document.
33Margin Symbols 34
Notes, cautions and warnings appear to highlight important or critical procedures and tips.
35 Note:
Used to highlight important procedures or tips.
36 Caution: Used to highlight procedures you must follow exactly. 37 Warning:
Used to highlight critical procedures you must follow exactly. Otherwise, you may experience data loss or application failure.
38 39
5035581/9 8
Copyright © Tecnomen Corporation 2008
Contents
i
9
Contents
40
411. 42 43 44 45 46 47 48
INTRODUCTION..............................................................................................................................1 1.1. Tecnomen’s Prepaid Architecture.............................................................................................1 1.1.1. SDP/PSP.......................................................................................................................1 1.2. What is the PaymentEngine ?...................................................................................................1 1.3. Multiple Client Support............................................................................................................2 1.4. Authentication Server Process..................................................................................................3 1.4.1. Authserver.....................................................................................................................3 1.5. Mediation Device Router (MDR) Support...............................................................................4
492. 50
PAYMENTINTERFACE TUTORIAL...............................................................................................5 2.1. High-Level Logical Flow.........................................................................................................5
513. 52 53 54 55 56 57 58 59 60 61
DETAILED CALL SEQUENCE.......................................................................................................7 3.1. Connect to the AuthServer........................................................................................................7 3.1.1. Using resolve_initial_references(“AuthFactory”).......................................................7 3.1.2. Using AuthServer IOR File...........................................................................................8 3.2. Authenticate..............................................................................................................................9 3.3. Get the PaymentEngine Factory’s IOR.....................................................................................9 3.4. Connect to the PaymentEngine Factory.................................................................................10 3.5. Get a PaymentEngine Instance...............................................................................................10 3.6. Call directFundTransfer..........................................................................................................10 3.7. Extract Results........................................................................................................................10 3.8. Disconnecting from the PaymentEngine................................................................................11
624. 63 64 65 66 67 68 69 70 71 72 73 74 75 76
PAYMENT INTERFACE OPERATIONS.......................................................................................12 4.1. Account Details Return Result Structure................................................................................12 4.2. Account Details Return Result Sequence...............................................................................13 4.2.1. Major Return Codes....................................................................................................14 4.3. PaymentEngine::directFundTransfer Operation.....................................................................16 4.3.1. Input Parameters.........................................................................................................17 4.3.2. CDRs Generated by directFundTransfer.....................................................................17 4.3.3. directFundTransfer Minor Result Codes.....................................................................17 4.4. PaymentEngine::directFundTransferSeq Operation...............................................................18 4.4.1. Input Parameters.........................................................................................................19 4.4.2. CDRs generated by directFundTransferSeq...............................................................20 4.4.3. directFundTransferSEQ Minor Result Codes.............................................................20 4.5. PaymentEngine::directDebitTransfer Operation....................................................................21 4.5.1. Input Parameters.........................................................................................................21 4.5.2. CDRs Generated by directDebitTransfer....................................................................22
Copyright © Tecnomen Corporation 2008
Payment Interface 5035581/9
ii
Contents
11
77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
4.6.
4.7.
4.8.
4.9.
4.10.
4.11.
4.12. 4.13.
4.14.
4.15.
4.16.
4.17.
4.5.3. directDebitTransfer Minor Result Codes....................................................................22 PaymentEngine::directDebitTransferSeq Operation..............................................................22 4.6.1. Input Parameters.........................................................................................................23 4.6.2. CDRs generated by directDebitTransferSeq...............................................................23 4.6.3. directDebitTransferSeq Minor Result Codes..............................................................23 PaymentEngine::onlineFundTransfer Operation....................................................................24 4.7.1. Input Parameters.........................................................................................................25 4.7.2. CDRs Generated by onlineFundTransfer....................................................................25 4.7.3. onlineFundTransfer Minor Result Codes....................................................................25 PaymentEngine::onlineFundTransferSeq Operation..............................................................26 4.8.1. Input Parameters.........................................................................................................27 4.8.2. CDRs generated by onlineFundTransferSeq...............................................................27 4.8.3. onlineFundTransferSeq Minor Result Codes..............................................................27 PaymentEngine::periodFundTransfer Operation....................................................................28 4.9.1. Input Parameters.........................................................................................................29 4.9.2. CDRs Generated by periodFundTransfer...................................................................29 4.9.3. periodFundTransfer Minor Result Codes...................................................................29 PaymentEngine::periodFundTransferSeq Operation..............................................................30 4.10.1. Input Parameters.........................................................................................................31 4.10.2. CDRs generated by periodFundTransferSeq..............................................................32 4.10.3. periodFundTransferSeq Minor Result Codes.............................................................32 PaymentEngine::fundTransfer................................................................................................32 4.11.1. Input pSeq (Parameter Sequence)...............................................................................35 4.11.2. Output dSeq (Data Sequence).....................................................................................38 4.11.3. fundTransfer Minor Result Codes...............................................................................39 PaymentEngine::FundAccountTransfer..................................................................................39 PaymentEngine::accountUpdate.............................................................................................42 4.13.1. Input Parameters.........................................................................................................43 4.13.2. CDRs Generated by accountUpdate...........................................................................43 4.13.3. account Update Minor Result Codes..........................................................................44 PaymentEngine::accountUpdateSeq Operation......................................................................44 4.14.1. Input Parameters.........................................................................................................45 4.14.2. CDRs generated by accountUpdateSeq......................................................................45 4.14.3. accountUpdateSeq Minor Result Codes.....................................................................46 PaymentEngine::accountQuery..............................................................................................46 4.15.1. Input Parameters.........................................................................................................47 4.15.2. Account Query Minor Return Codes..........................................................................47 PaymentEngine::accountQuerySeq Operation.......................................................................48 4.16.1. Input Parameters.........................................................................................................48 4.16.2. accountQuerySeq Minor Return Codes......................................................................48 paymentEngine::packageRecharge Operation........................................................................49
Payment Interface 5035581/9
Copyright © Tecnomen Corporation 2008
Contents 13
118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146
4.18.
4.19.
4.20.
4.21. 4.22. 4.23. 4.24. 4.25.
iii
4.17.1. Input Sequence (pSeq Contents).................................................................................49 4.17.2. CDRs Generated by packageRecharge.......................................................................50 4.17.3. packageRecharge Minor Result Codes.......................................................................50 4.17.4. Package Refund..........................................................................................................52 PaymentEngine::voucherRecharge Operation........................................................................53 4.18.1. Input Parameters.........................................................................................................53 4.18.2. CDRs generated by voucher recharge.........................................................................53 4.18.3. Return Code................................................................................................................53 ASyncEngine::voucherRecharge Operation...........................................................................55 4.19.1. Input Parameters.........................................................................................................55 4.19.2. CDRs Generated by voucherRecharge.......................................................................56 4.19.3. Return Code................................................................................................................56 ASyncEngine::voucherRechargeSeq Operation.....................................................................56 4.20.1. Input Parameters.........................................................................................................56 4.20.2. CDRs Generated by voucherRecharge.......................................................................57 4.20.3. Return Code................................................................................................................57 VoucherJobMgr::getJobDetails Operation..............................................................................57 4.21.1. Input Parameters.........................................................................................................58 VoucherJobDetails Return Result Structure...........................................................................58 VoucherJobMgr::getJobDetailsSeqOperation.........................................................................62 4.23.1. Input Parameters.........................................................................................................62 VoucherJob Details Return Result Sequence..........................................................................63 PI Exceptions..........................................................................................................................66 4.25.1. General Error Codes...................................................................................................66 4.25.2. IDL GW Specific Error Codes....................................................................................66 4.25.3. User/Subscriber Error Codes......................................................................................66 4.25.4. Voucher Error Codes...................................................................................................67 4.25.5. Job Control Error Codes.............................................................................................68 4.25.6. Payment Engine Error Codes......................................................................................69
147APPENDIX A: AUTHFACTORY.IDL...................................................................................................70 148APPENDIX B: EXCEPTIONS.IDL.......................................................................................................71 149APPENDIX C: TINCDEFS.IDL.............................................................................................................72 150APPENDIX D: TYPES.IDL...................................................................................................................73 151APPENDIX E: PAYMENTENGINE.IDL..............................................................................................74 152APPENDIX F: AUTHFACTORY_IMPL.JAVA.....................................................................................75 153APPENDIX G: PAYMENTENGINE.JAVA...........................................................................................80 154APPENDIX H: RECHARGECLIENT.JAVA.........................................................................................84 155APPENDIX I: RECHARGECLIENT.SH...............................................................................................97
Copyright © Tecnomen Corporation 2008
Payment Interface 5035581/9
iv
Contents
15
156APPENDIX J: TRACE.JAVA.................................................................................................................98 157APPENDIX K: SIMPLECLIENT.JAVA.................................................................................................99 158APPENDIX L: TPEDEFS.IDL.............................................................................................................100 159DEFINITIONS AND REFERENCES..................................................................................................101 160 161
Payment Interface 5035581/9
Copyright © Tecnomen Corporation 2008
1 17
1. Introduction
162 163 164
Tecnomen’s PaymentEngine provides access to a well defined set of payment related functionality for both internal and external use. PaymentInterface is a product name for the PaymentEngine and supports external operations.
Note: 1651.1.
Tecnomen’s Prepaid Architecture
166 167
With the introduction of Tecnomen Prepaid 4.3 a new Prepaid system architecture is implemented. The new architecture consists of four basic functional layers:
168 169 170 171 172 173
Database Layer consisting: Service Data Point (SDP) Prepaid Support Point (PSP) Service Layer Signalling Layer Network Layer
1.1.1. SDP/PSP
174 175 176 177
The Service Data Point (SDP) provides the Service Control Function (SCF) with access to the data required by service logic programs (e.g. subscriber data). Therefore, the SDP contains the Service Data Function (SDF).
178 179
The Prepaid Support Point (PSP) provides additional support functionality for Tecnomen’s Prepaid Service e.g. Short Message Notification, PaymentEngine, Agenda Manager etc.
180
1.1.1.1.
181 182
Refer to the Tecnomen Customer Care Technical Description for details on HA Failover support.
1.2.
183
HA Failover / Failback Support
What is the PaymentEngine ?
184 185 186 187 188
The existing IDL Gateway, which supports a generic interface to the Tecnomen Prepaid Service will co-exist with the PaymentEngine. The various payment related operations use the PaymentEngine to carry out the work. The difference between the existing IDL Gateway and the PaymentEngine is the IDL Gateway is optimised for generality, whilst the PaymentEngine is optimised for speed.
189 190 191 192
Tecnomen’s PaymentEngine is a centralised payment related service carrying out all ancillary payment operations, other than general Prepaid Service Call Handling logic, in a secure environment. The secure aspect, is enforced via the authServer “Authentication Service”, as described later.
Copyright © Tecnomen Corporation 2008
Payment Interface 5035581/9
2 19
193 194 195 196 197 198 199
Based on a CORBA TAO http://www.ociweb.com and SQLAPI++ http://www.sqlapi.com implementation, the PaymentEngine is a multi-threaded process executing all charging and recharging functionality, such as voucher and credit recharges in addition to onlineFundTransfer (renamed bankRecharge / genericRecharge), directFundTransfer, PeriodFundTransfer, AccountQuery and AccoundUpdate operations in a secure environment. The paymentEngine generates all MDR (Mediation Device Router) files, as well as any CDR relating to account recharges.
200 201
The diagram below (Fig 1-1) depicts the high-level architecture of the PaymentEngine and AuthServer being hosted on the PSP, in relation to the SDP.
202 203
The various permitted PaymentEngine operations are detailed, as being called via one or more either internal or external clients.
1.3.
204
Multiple Client Support
205 206 207
Each PaymentEngine instance will support a certain Transaction Per Second (TPS) call rate, governed by the platform it’s running on, restrictions imposed by the PSP and SDP platforms and finally a ‘Licenced’ TPS limit, per engine.
208 209
To achieve higher TPS rates it may be necessary, to use multiple clients to achieve the overall call rate required.
IDL Operations* Login
Return IOR
Login
PSP
authServer
Return IOR
PaymentEngine PaymentEngine [PaymentInterface PaymentEngine PaymentEngine PaymentEngine 1-50]
IDL Operations*
IDL Operations * directFundTransfer directDebitTransfer onlineFundTransfer periodFundTransfer fundTransfer
Return IOR Login
IDL Operations*
SDP
210 211
Figure 1-1 Overview of Tecnomen’s Payment Engine
Payment Interface 5035581/9
Copyright © Tecnomen Corporation 2008
3 21
212 213 214 215
It is necessary to properly disconnect from the PaymentEngine using the PaymentEngine Factory’s releasePaymenEngine() operation. Failure to do this will stop further getPaymentEngine() requests from being honoured for a period of time, until the PaymentEngine Factory’s scheduled eviction procedure is activated.
1.4.
216 217 218 219 220 221
Authentication Server Process The authServer acts as a secure Naming Service for all CORBA based processes, including the rechargeGateway. All CORBA processes register with the authServer at startup time. Any clients that wish to access any of the available services must first authenticate via the authServer using a valid login / password combination. The authServer will then hand out the necessary connection information, as appropriate, to the client.
1.4.1. Authserver
222 223 224
The job of the authServer is to hand out connection information (amongst other things) to clients that request them, after a login/password authentication dialogue has taken place.
225 226 227 228
The authServer has additionally an element of fault tolerance built in. Upon startup, or whenever requested, the authServer will read and cache the current user login/password information that’s persistently stored in the CC_DB. Caching reduces the dependency on CC_DB (and hence the Customer Care host) requirement of being available.
229 230
An additional aspect of the authServer is that it enables central control of transaction rate settings for any and all processes that use it.
231 232 233 234 235
Upon startup, the PaymentEngine, for instance, registers its IOR (CORBA Interoperable Object Reference) with authServer and is subsequently given both a unique ‘key’, for use in authorising subsequent getPaymentEngine() requests from clients, and one or more parameters to control the number of ‘engines’ (threads) allowed, and the max TPS allowed per engine.
1.5.
236
Note: 237 238
Mediation Device Router (MDR) Support MDR file generation is configurable On / Off system wide.
Mediation Device Router file generation is supported. For further information on the Mediation Device Router (MDR), see ref. /1/.
Copyright © Tecnomen Corporation 2008
Payment Interface 5035581/9
4 23
2. PaymentInterface Tutorial
239 240 241
The following sections describe, in detail, the steps necessary to successfully interface to the PaymentInterface.
242 243 244 245
The necessary CORBA IDL definitions of the required interfaces are in the appendix. The supplied sample code, in the appendix, is written in java. We also supply, with the delivery, the C++ source code for a simple load test tool that is more realistic, in terms of what a typical C++ client will need to do.
246 247
This tutorial, whilst concentrating on the java sample code, is applicable at a high level to the C++ code. All the same logical steps are required, no matter what language is used.
248 249 250
The full IDL definitions of all necessary components are listed in the appendices, including all necessary return codes (in Appendix E: PaymentEngine.idl) and error codes (in Appendix C: TINCdefs.idl)
2.1.
251 252
High-Level Logical Flow The essential steps that need to be covered are the following :-
253
1. Get a handle on the authServer
254
2. Authenticate with the authServer using its login() method
255 256 257
3. Get a PaymentEngineFactory IOR. Parse the returned sequence of data from the authServer looking for an instance of a PaymentEngine Factory, and extract the required IOR (CORBA Interroperable Object Reference).
258 259
4. Use the PaymentEngine Factory’s IOR to get a handle to the PaymentEngine Factory.
260 261
5. Use the PaymentEngine Factory’s getPaymentEngine() method to create a PaymentEngine instance for this client.
262 263
6. Use the PaymentEngine Factory’s getAsyncEngine() method to create a ASyncEngine instance for this client.
264 265
7. Use the PaymentEngine Factory’s getVoucherJobMgr() method to create a VoucherJobMgr instance for this client.
266 267 268
8. Use the paymentEngine thus obtained, to call available operations, such as directFundTransfer, directDebitTransfer, etc., as per the provided CORBA IDL specification of the PaymentEngine. See appendix E.
269 270 271
9. Use the AsyncEngine thus obtained, to call available operations, such as voucherRecharge, voucherRechargeSeq, etc., as per the provided CORBA IDL specification of the PaymentEngine. See appendix E.
272 273 274
Note: The voucherRecharge and voucherRechargeSeq will return a job number which must be used in the getJobDetails and getJobDetailsSeq to determine if the voucherRecharge request completed.
Payment Interface 5035581/9
Copyright © Tecnomen Corporation 2008
5 25
275 276 277
10. Use the VoucherJobMgr thus obtained, to call available operations, such as getJobDetails, getJobDetailsSeq, etc., as per the provided CORBA IDL specification of the PaymentEngine. See appendix E.
278 279 280
11. Repeat step 8, 9 and 10 repeatedly, until there is a need, at some point, to disconnect; the concept being that the clients will have a long lived connection to the paymentEngine.
281 282 283 284
12. Upon exit of the client, the client MUST remember to properly disconnect from the PaymentEngine and AsyncEngine that it currently has. This is achieved by using the PaymentEngine Factory’s releasePaymentEngine(), releaseAsyncEngine operations.
285 286
Note: There is no need to release the VoucherJobMgr as it is static and is shared amoung all clients.
287 288 289 290
It is important to realise that there is an overhead in asking the PaymentEngine Factory for a paymentEngine, especially if you consider the process of first authenticating with the authServer, and in general carrying out steps 1 to 5 above.
291 292 293
The client should do all of it’s authentication once, at the beginning, and from then on just use the provided PaymentEngine CORBA handle to execute the required ‘payload’ operations.
294 295 296 297
The only other circumstance under which a client is required to request for a new paymentEngine, is in the event that something goes wrong, i.e. some error condition at the process or CORBA level, at which time the client must assume that it must re-authenticate, and thus get a new PaymentEngine handle, as per the above sequence.
298 299 300 301
Finally, it is vital that the client, is a ‘well-behaved’ client, in so much as the client MUST follow the proper disconnection sequence, as detailed later. Essentially, this means using the factories releasePaymentEngine() operation, before the client exits. Failure to do this will cause the clients to be blocked from subsequent access for a period of time1.
26 27
1
The PaymentEngine Factory will eventually notice that there exists a ‘stale’ paymentEngine, however this might take some considerable time, typically about 60 minutes.
Copyright © Tecnomen Corporation 2008
Payment Interface 5035581/9
6 29
3. Detailed Call Sequence
302
Caution: In order to comply with Java 1.4.x requirements, all code must be scoped into modules, i.e must
be packaged. All code relevant to the CORBA Payment Interface and this manaul has been placed in the TINC (Tecnomen Intelligent Network Customer Care) name space.
3.1.
303
Connect to the AuthServer
304 305
The authServer is a central authentication service. All client processes, whether internal or external must use it to authenticate the client.
306 307 308
Upon successful authentication, the authServer will hand back to the calling client the necessary data required to attach to one or more ‘permitted’ services within the Tecnomen system.
309 310 311
There is no other way to connect to any Tecnomen process, without first having to go to the authServer, since it acts as both a Secure Naming Service and an authentication Service. 3.1.1. Using resolve_initial_references(“AuthFactory”)
312 313 314 315
The authServer uses a Persistant Lifespan Policy. Clients can use the CORBA::ORB::resolve_initial_references() mechanism to bind to the service, just like they would to bind to the NamingService.
316
The authServer is started with an ORBEndpoint specification, as follows:-
317 authServer -ORBEndpoint iiop://PSP:1500 318 319 320
From the above command we see that the server is using an IIOP (Internet Inter-Operable Protocol) transport. The process is registered to listen on port 1500 on the PSP host.
321 322
To connect to the authServer, the client is started by specifying a ‘corbaloc’ object reference that looks somewhat similar to the command below:-
323 clientProcess -ORBInitRef AuthFactory=corbaloc:iiop:PSP:1500/AuthServer 324 325 326
A typical C++ client then uses the following commands to bind to the server :Payment Interface 5035581/9
Copyright © Tecnomen Corporation 2008
7 31
327 // First we initialise the ORB CORBA::ORB_var orb = CORBA::ORB_init(argc, argv); // Finally, we get a reference using resolve_initial_references() CORBA::Object_var obj = orb->resolve_initial_references(“AuthFactory”); AuthFactory_var factory = AuthFactory::_narrow(obj.in()); If (CORBA::is_nil(factory.in())) { Cerr
