Mandatory (minimum) requirements for Online Vending Clients
Contents
1. Eskom Prepaid Online Vending System Mandatory Requirements for Online Vending Clients and Gateways Version 1 5 Page 1 TABLE OF CONTENTS 1 Table Of Contents enie Shri e cin a ected ee a a dee 2 2 ReterencoS iniscan a es ee eee ea ee a ee i ie ie 5 3 EXOCumIvie SUMIMANY enn ih thos Soper oa ae Ah hte ie ead a Seat hh cet Mites Ge 6 4 SCOPE essere eee eee ee et 7 5 Mandatory Requirements sossenneeeeeseeeenttrttrestrrtrtnnrrtrserrtrtnnnnnreerrtrnnnnnnneeeee eneen 8 BAe Ensuring unique XMLVend Message IDS ccceeeeeeeeeeeeeneeeeeeeeeeeeeeenaeees 8 5 2 Correct implementation of Advice Last Response ccceeeeeeeetereeeeeeeeeeeeee 8 5 3 Handling Track2data field in XMLVend 0 eeeeeeeeeeeeeeeeeeeeeeeeeeneeeeeeeeeeeeeeees 10 5 4 Client Error Messages and user MANUAI cccceeeeeeeeeeeeeeeeeeeeeeeeeeeetneeeeeeeees 11 5 5 Channel Strategy ais tne ie eae an ee ee A ee ee oe 11 BiG SBoketccnts ce eee ate ieee Sica te ee ove atte aie 12 5 7 Business Rule Validations cceeeecsccccceeeeeeeeeeeeeeeeeeeeeeeeeesesaaeaeeeeeeeeneneaea 12 5 8 Magnetic Card Reader ss nctee weve aoe ehieiiel e eee ee eee 12 5 9 Magnetic Card Writer ssnnsnneneeeeeoeeeeenrnteeeeerenrrrnrreorrrrtnnnntneeerrrennnnnneeereeee nn 12 5 10 Minimum Requirements for Acceptance ccccceeeeeeeeeeeteeeeeeeeeeeeeeetneeeeeeeees 12 6 Mandatory SC MariosS ccccceee2. XMLVend Client Server Qm Purchase credit ra Client timeout CreditVendReq gt jem AdviceReg LastResponse gt X fmm AdviceReq LaStRESPONSC Dy q o AdviceResp LastResponse j lt not exist Transaction does not exist erro O ew purchase credit token gt Handling Track2data field in XMLVend XMLVend provides the ability in a vend message to provide the meter information in either the disparate xml fields or in the track2data field It is required that client devices only use the Track2data field when the customer s data is captured from an Eskom Page 10 5 4 5 5 meter card Track2data shall not be extracted and submitted as separate fields in the XMLVend request In the event that the customer has no meter card and the data must be entered manually into the system the disparate xml fields should be completed These individual fields entered shall not be assembled into a Track2data field It is Eskom s intention to use the different ways of populating the xml fields to determine if the customer has used a magnetic card or not Should this information not be used Eskom s customer may be faced with repeated visits to the vending station until the problem has been resolved Client Error Messages and user manual Each client device operates in a unique environment Eskom has no wish to capitalise on supplier s intellectual property by asking for a list of
3. allow cancellation or reversal of tokens the client must take responsibility for its issue to the customer Eskom does not support reversal of tokens because of the inability to prevent the use of the token once it has been issued In the event of a transmission failure or if some other error occurs Eskom does support the ability to re request the previously requested token via the advice last response process In the event that a communication failure is taking time to resolve it is the vendor s responsibility to find a means of providing the token to the client via the advice last Page 8 response mechanism a reprint from another machine creation of a new communications channel POTS GPRS etc or via some other means e g call the Eskom call centre etc All tokens produced by the Eskom vending server are valid and will be deducted from the vendor s account To prevent duplicate vend requests for a meter the client must implement the following process e Save the MessagelD and meter serial number MSNO to persistent storage before submitting the request e If the Client is only a single device with one operator do not allow any further requests to be sent until a valid answer has been received from the Server If the Client is a gateway device with multiple operators allow further requests before a valid answer has been received but no further requests must be allowed for the same meter serial number for which a response
4. case e g Advice Last Response messages can be queued and multi threaded or single threaded etc Eskom has attempted to provide a list of generic mandatory requirements which satisfy both the needs of suppliers creating XMLVend gateways that remain compatible with their own internal protocols as well as those implementing XMLVend clients that communicate directly with the Online Vending Server Suppliers are reminded that all discrepancies losses or consequential damage that may arise from not fully adhering to this specification as well as the Guideline for the Development of Online Vending Clients will be totally the accountability of the supplier Page 6 SCOPE This document is equally intended for suppliers of vending equipment i e Clients as well as for Vending Service providers that develop their own Gateway and Terminal devices to supply the relevant Online Services to Eskom The generic term Supplier is used throughout this document to indicate equipment suppliers as well as suppliers of the online services In addition to the above the document often refers to the term Client As far as Eskom and the Eskom Online Vending Server is concerned this may mean equally well a single Local Client machine or it may mean a Gateway that communicates to many proprietary terminals transparently for the Eskom Vending Server The Gateway developer may decide whether the functionality is provided by t
5. the supplier client has made an application i e vending only extended vend etc must be completely supported as per NRSO09 6 10 Note that this requirement does not place any restriction on the token types to be supported i e a supplier may choose to only support numeric tokens only magnetic tokens or both types of tokens for the various use cases The receipt formats shall be formatted as per the Eskom Receipt format specification Where this format cannot be accommodated a signed acceptance of a modified receipt format for the device shall be obtained from Eskom before implementation in the field Note that this requirement applies to both printed receipts as well as cellular SMS based receipts Eskom must have a list of all the client generated error messages Eskom must be satisfied that the customer facing interface is of sufficient quality and clearly understandable Note that the customer facing interface includes the receipt or the message display for a cellular telephone It also includes the vending terminal display for a customer driven device like an auto teller machine but it does not include the terminal display for an operator driven device e g when a vending service is provided by a National Vendor Page 13 MANDATORY SCENARIOS 6 1 6 2 Introduction Eskom wishes to specify as few mandatory requirements as possible to allow the maximum number of new solutions to be applicable in the business However wher
6. the supplier must resubmit the device for testing In this case the functionality offered by the client has changed substantially and this needs to be retested Similarly if the supplier decided to use WAP a different protocol to achieve the same ends as previously performed by the http client the application has changed significantly and need to be re submitted Additional non XMLVend functionality offered to the vendor over and above the functionality specified in this document can be added without re submission provided that the base functionality is not affected E g the supplier decides to offer an accounting software add on so that the vendor can more easily manage the prepayment transactions In summary resubmission must occur when Page 19 e The XMLVend client software is substantially different or the client is materially so different that the functional outputs of the system are affected e The customer facing screen or print formats must change because of the new technology e Any customer facing changes to the user interface e The messages that the client uses to communicate with the customer change e g a new error message have been created to handle a specific condition Should a XMLVend client be certified for field use the XMLVend client will be added to the an accepted supplier list at Eskom This will allow the Eskom regions to purchase from this list or pass on this list to vendors for their purchase Eskom wish
7. Client can use the same swipe card encoder as mentioned above to create key change tokens and encode the Page 16 customer s meter card a mandatory requirement for a key change If this function is not supported the vendor will not be able to vend to the customer Some meters are not registered on the Eskom database but the server still allows vending to such customers if all the necessary data is entered manually This is known as a blind vend and the data can be supplied by swiping the customer s meter card or by manually entering the necessary fields from an old receipt It is recommended that all operator driven vending points also allow these manually entered forms of data entry Customer driven interfaces like an automatic teller machine must not allow this feature since incorrect entry may result in non working tokens Page 17 PROCESS NOTES In the event that a client device is not able to complete a transaction because of a communication failure or other problem the client must poll the server at regular intervals This will ensure that when communication is restored the client can automatically continue vending the current transaction Generally in this case some period will have elapsed which means the client must issue an advice last response for the original message ID before the communication break Should the transaction have been issued but the generated token was not received by the client because of th
8. all errors that can be caused by their client but a list of all the possible Client generated error messages is required by Eskom to ensure that Eskom has knowledge of the faults which are expected on the device and the recommended manner of resolving these faults Eskom has spent a large amount of time attempting to make the errors that are produced by the server assist problem resolution Eskom will therefore attempt to ensure that client generated errors also assist in problem resolution Eskom therefore requires this list of all possible Client generated error messages as well as a vendor operator manual when the Client device is submitted for evaluation Equipment will not be accepted for Eskom testing or field use without such a complete list Channel Strategy Each supplier may offer Eskom a range of technologies and protocols to generate prepayment tokens Eskom has no wish to restrict the mechanism whereby customers purchase electricity All technologies will be entertained with the following prerequisites e Tokens must be requested in real time from the Eskom Server via XMLVend e Suppliers must ensure that Eskom s customers have a pleasant experience when purchasing tokens i e no unnecessary delays etc Page 11 5 6 5 7 5 8 5 9 5 10 e Any non http technology must first be translated into http via a supplier built XMLVend gateway e Vendors will be liable for risks introduced into the system via their technol
9. e many solutions meet Eskom s requirements Eskom has opted out of specifying these requirements explicitly but has chosen instead to ask the vendor how the vendor proposes to deal with these problems Dependant on their implementation and use cases implemented suppliers may or may not encounter the following scenarios but it is mandatory for suppliers to describe how they will address the following scenarios Scenario Requirement to update a meter card with update meter key The Client shall update the meter card when doing an Update Meter key token or engineering key change token Should the customer not do so the vending Server will prompt the vendor for a key change every time that the vendor swipes a customer card In addition if the customer purchase the token from an Offline Vendor with the non updated card the vendor may issue the customer with a token will may not work in his meter 6 2 1 Question Please explain how your terminal prevents the scenario where the card is not successfully encoded One option may be to prevent the terminal from cancelling a request for a meter card write before a card has been swiped through the meter card writer Page 14 7 MINIMUM USE CASES Clients fall into the following categories each category is listed with the use cases which are required to support it below e Vend Vend FBE Advice Last Response e Extended vend Any other use cases in addition to the above e Engi
10. e communication break the system will resend an auto reprint of the transaction Should the original request not have been processed by the server the server will respond with an exception message stating that the Message ID was never received by the server and vending can continue normally Page 18 10 ESKOM S APPROVAL PROCESS 10 1 Approval of make and model Should Eskom accept a suppliers client product the client is at liberty to make changes to that client provided that it conforms to the XMLVend specification Should the supplier create a materially different product Eskom requires that product to be re certified To illustrate this concept please review the following scenarios when attempting to determine whether re certification is required A supplier creates a website whereby customers can purchase their prepayment tokens online Should the supplier then decide that he can leverage an existing footprint in the region or area where he is allowed to sell based on an Eskom contract he may do so via a PDA provided that the PDA uses GPRS communication and http communication with his website In this case although the device is materially different from the device already issued to Eskom for testing the application has not changed Should the supplier decide to implement the same functionality on a PDA and decides not to issue a receipt because practically receipts are not as easy to generate from a PDA then
11. eeeeeeeeneceeeeeeeeeeeeecaaeaeeeeeeeeeensaaaaaeeeeeeeteesesaaaees 14 6 1 PALOCUICHION saien a ae a e a AEREE 14 6 2 Scenario Requirement to update a meter card with update meter key 14 Mi im m Use CAaSOS crassa oe eee ores etc ete ee cans meee 15 Specific RECOMMENGATIONS ccccceeeeeeeeeeeeeeeeeeeeeeeeeeenaaaeeeeeeeeeeeeescnaeeeeeeeeees 16 8 1 Benefit from the use of Trial Vend ccccceeeeeeeeeeseeeeeeeeeeeeeeeeeneeeeeeeeeeeeeeees 16 8 2 Flexibility for deposit amounts sascc20srestectecece tis eee aecetie ere eedeaee eeteceeaeehs 16 8 3 Optimum use Of DAMAWIGUA ccseucecceneeeneeeescedce pentweceeneesdeede eeeeeneeedtecestreeeceeens 16 8 4 Serving the most CUSLOMETS cccceeeeeeeeeeeeeeeeeeeeeeeeeeeeaaeeeeeeeeeeeeeessaeeeeeeeens 16 9 Process Notos ocara a a aaea EE aaa 18 10 Eskom s Approval ProGe Ss mssi n epo ene ou Sieveetaseepeerad 19 10 1 Approval of make and mod lausta keene aoa eek ad 19 Page 2 Document Title Document Number Document Issue Compiled By Issue Date Controlled By Electronic Media Approval Mandatory Requirements for Online Vending Clients J O Kennedy K Subramoney Media Media Identifier Disk identifier Online Vending File Identifier Mandatory requirements for clients doc Disk controlled by Date Position Executive Sponsor Signature Name Brian Mokgele Dean Villet Sham Dhrampal Program Manager Sys
12. es to allow the individual vendor the ability to choose the solution which is most appropriate based on his solution Page 20
13. he Terminals or by the Gateway but the Eskom requirements are defined from the perspective of the Eskom Vending Server via the XMLVend connection Page 7 MANDATORY REQUIREMENTS 5 1 5 2 Ensuring unique XMLVend Message IDs XMLVend defines a robust protocol for vend requests and responses which guarantees that vendors and Eskom are both protected as long as they adhere to the requirements Each message ID sent from the client shall be unique Should the message ID not be unique the vending server will reject the new vend request To ensure all XMLVend requests will have a unique MessagelD the MessagelD is made up of two components namely e MsglDDateTime Date Time stamp in the following format yyyymmddHHMMSS e MsglDUniqueNumber a 6 digit sequential number However in some cases the CPU clock may be inaccurate or is reset which may result in duplicate MessagelDs which will prevent a client from vending further To prevent such a scenario from occurring the client must implement the prescribed MsgIDDateTime based on the Client device s real time clock The MsgIDUniqueNumber must start with zero and increment by one for every new request until it eventually reaches 999999 and then roll over to zero again This solution will ensure that the possibility of duplicate MessagelDs is minimized even when the clock is inaccurate or adjusted Correct implementation of Advice Last Response As the Eskom server does not
14. is still outstanding e When the Client times out issue an Advice Last Response for that MessagelD Always allow at least a few seconds for every time out period before repeating the Advice Last Response This process must be repeated until a valid positive or negative response has been received for that request If the server is not available to respond on the Advice Last Response it will also not be able to service other requests e Ifthe client application is terminated because of power failure or restart it must first process all outstanding Advice Last Response tokens as described above before allowing normal vending may continue If the server advises that the requested response does not exist the client must do a completely new request with new unique MessagelID The original MessagelD is now void and must not be re used Some vendors may be tempted to ignore the Advice Last Response message and merely re vend a completely new token This will decrement the Vendor s available credit and he will be liable for the full value of all the tokens that he has vended Page 9 5 3 Example for successful vend transaction XMLVend XMLVend Client d L Server d OP urchase credit MoT S XA CreditVendResp Client timeout p d vice Req LastRe sponse AdviceResp LastResponse 4 Auto reprint Token Auto reprint To customer Example for unsuccessful vend transaction XMLVend
15. neering Any device which does not support the Vend use case Page 15 SPECIFIC RECOMMENDATIONS 8 1 8 2 8 3 8 4 Benefit from the use of Trial Vend Some clients may want to reserve customer funds before requesting a token from the server and Eskom has implemented the Trial Vend request for this purpose The client can request a free Trial Vend token before doing the normal Vend operation for the meter to ensure that the server has all the required information and credit to perform the transaction Flexibility for deposit amounts In the event that the vending client is a stand alone unit it is recommended that vending client has a feature whereby the vendor can modify the amount to be printed on his bank deposit slip Optimum use of bandwidth Please note that GZip is implemented on the server so that requests and responses from the server can be GZipped Devices which will connect via the Eskom APN will have Gzip switched on Serving the most customers There are a number of scenarios that may prevent a transaction to be completed but manufacturers may optimize their Clients to address as many of these as possible e Several areas still have magnetic card meters and it will allow Clients to serve these areas if they can encode magnetic tokens with a separate swipe card encoder e There are scenarios where the Eskom server will require key change tokens to be issued to a meter before a vend can take place A
16. ogy i e should the vendor wish to vend a token via a technology whereby he cannot support the issue advice Use Case the vendor will be liable for lost tokens and or tokens responses SSL All clients shall encrypt their transmissions via SSL Business Rule Validations The Eskom Vending Server will implement the required business rules and they may change in future as deemed necessary The Clients must therefore not implement business rules in their processing e g do not limit multiple requests for the same FBE token per month do not evaluate contents of the meter card Track2data field apart from confirming the data was read correctly etc Magnetic Card Reader If the terminal has a magnetic card reader the application must ignore the date field on the magnetic card Magnetic Card Writer If the terminal has a magnetic card writer to update the Eskom meter cards the magnetic card writer must write an into the date time field as specified in the track2data field A Client or terminal shall never allow locally submitted sourced data entries to be used to encode a meter card Meter cards shall only be encoded with data received from the Eskom Vending Server This data is retrievable via the confirm meter details use case Minimum Requirements for Acceptance In order to be accepted as a client supplier or an Online Vending service provider Eskom requires that as a minimum Page 12 The vending use cases for which
17. tems Architecture Prepayment Development Manager Deon van Rooi Page 3 Amendment History Doc Date Changed Chapter No of Checked by Issue Topic Page Pages Name Initial 1 6 11 2006 Initial Release B E B 1 1 7 11 2006 Updated with B E B comments 1 3 12 11 2007 Release for full J O K implementation 1 4 01 04 2008 Many small 19 J O K clarifications 1 5 20 04 2012 Added example 20 J O K drawings for advice 0 0 Page 4 REFERENCES Please refer to the following documents should you be unsure of any details 1 Online Vending Receipt Formats 2 Glossary And Definition of Terms 3 Online Vending Processes 4 Eskom Online Vending XMLVend Extensions Restrictions and Optional Fields 5 NRS 009 06 10 XMLVend 6 RFC 1952 GZip File Format Specification Page 5 EXECUTIVE SUMMARY This document incorporates some of Eskom s Online Vending team s experience since the original RFP This document specifies a minimum set of requirements which is more output based than the original RFP We wish to challenge the market to respond with new solutions without making the requirements too onerous Client and Gateway suppliers should study this document carefully and fully understand their obligations in terms of the solution required In creating this list of requirements and with the wide range of implementation possibilities for each XMLVend use
Download Pdf Manuals
Related Search