id2 Logo
Bringing you energy to live by.
Bringing you the energy to live by.

Resources

XMLVend

Overview

ID2 provides an XMLVend-compliant interface to electricity vendors. A subset of the published specification is implemented.

"XMLVend is a South African developed, open interface standard, which facilitates the sale of prepaid electricity credit between electricity utilities and clients. It is an application of Web Services to facilitate trade between various types of devices and a utility prepayment vending server." - Wikipedia

"XMLVend is an industry standard protocol that was developed by the NRS009 working group with participation from the Electricity Suppliers Liaison Committee (ESLC), Eskom and Prepayment Manufacturers.

  • This communication protocol allows Vending Client machines from many different manufacturers to connect seamlessly with a Utility’s Online Vending Server.
  • It provides a compatible and secure interface with vending machines from many different suppliers. (similar to the benefits provided by STS for prepayment meters)
  • Utilises proven technology standards for security, communication and interoperability e.g. SSL, XML, SOAP, GZIP, HTTP, TCP/IP etc.
  • Supports existing prepayment standards such as, STS and the Common Vending System functionality (NRS009 Series)
  • Uses technologies that are supported by generally available software development tool sets and employs developer skills that are commonly available in the industry. (No more reliance on specialised prepayment knowledge)
  • Meets common business requirements for most users but still allows for extensibility and customisation where required."
- Eskom

Specification

The specification and source code can be downloaded from here. Note that the generic specification was implemented by ID2.

Integration process

  1. Download the Eskom specification.
  2. Implement and test your XMLVend client code.
  3. Contact vending@id2metering.com to request integration access details.
  4. If all tests with the ID2 team are successful, you will receive a certificate from ID2 and production access.

Examples

Below are some of the requests (blue) and responses (red) for the following three use cases:

  • CONFIRMCUSTOMER
  • CREDITVEND
  • LASTRESPADVICE

CONFIRMCUSTOMER

POST /imms/services/XMLVendWebService HTTP/1.1 Accept: text/xml, multipart/related Content-Type: text/xml; charset=utf-8 SOAPAction: "" User-Agent: JAX-WS RI 2.2.9-b130926.1035 svn-revision#5f6196f2b90e9460065a4c2f4e30e065b245e51e Host: imms-qa.id2metering.com:8443 Connection: keep-alive Content-Length: 1020 <?xml version="1.0" ?> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns4:ConfirmCustomerRequest xmlns:ns4="http://www.nrs.eskom.co.za/xmlvend/service/2.1" xmlns:ns3="http://www.nrs.eskom.co.za/xmlvend/meter/2.1/schema" xmlns:ns2="http://www.nrs.eskom.co.za/xmlvend/revenue/2.1/schema" xmlns="http://www.nrs.eskom.co.za/xmlvend/base/2.1/schema"> <ns2:confirmCustomerReq> <clientID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="2016010100011"></clientID> <terminalID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="2016010100011"></terminalID> <msgID dateTime="20161129085743" uniqueNumber="1"></msgID> <authCred> <opName>usr</opName> <password>passwd</password> </authCred> <ns2:idMethod xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="CustIDMethod"> <custIdentifier xsi:type="CustAccountNo" accNo="1716052601"></custIdentifier> </ns2:idMethod> </ns2:confirmCustomerReq> </ns4:ConfirmCustomerRequest> </S:Body> </S:Envelope> HTTP/1.1 200 OK Content-Type: text/xml;charset=UTF-8 Content-Length: 1376 Date: Tue, 29 Nov 2016 06:57:43 GMT Server: Apache <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns3:ConfirmCustomerRequestResponse xmlns:ns4="http://www.nrs.eskom.co.za/xmlvend/meter/2.1/schema" xmlns:ns3="http://www.nrs.eskom.co.za/xmlvend/service/2.1" xmlns:ns2="http://www.nrs.eskom.co.za/xmlvend/revenue/2.1/schema" xmlns="http://www.nrs.eskom.co.za/xmlvend/base/2.1/schema"> <ns2:confirmCustomerResp> <clientID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="2016010100011" /> <serverID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="0000000000001" /> <terminalID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="2016010100011" /> <reqMsgID dateTime="20161129085743" uniqueNumber="1" /> <respDateTime>2016-11-29T08:57:43.954+02:00</respDateTime> <dispHeader>Ekurhuleni</dispHeader> <operatorMsg>Success</operatorMsg> <custMsg>Success</custMsg> <ns2:confirmCustResult> <ns2:custVendDetail name="Mr null null" address="House41 ID2 Epiuse Tshwane" contactNo="0836565471" accNo="1716052601" locRef="41" /> <ns2:custVendConfig> <ns2:canVend>true</ns2:canVend> <ns2:fbeDue>false</ns2:fbeDue> <ns2:maxVendAmt value="500000" symbol="R" /> <ns2:minVendAmt value="0" symbol="R" /> </ns2:custVendConfig> </ns2:confirmCustResult> </ns2:confirmCustomerResp> </ns3:ConfirmCustomerRequestResponse> </soap:Body> </soap:Envelope>

CREDITVEND

POST /imms/services/XMLVendWebService HTTP/1.1 Accept: text/xml, multipart/related Content-Type: text/xml; charset=utf-8 SOAPAction: "" User-Agent: JAX-WS RI 2.2.9-b130926.1035 svn-revision#5f6196f2b90e9460065a4c2f4e30e065b245e51e Host: imms-qa.id2metering.com:8443 Connection: keep-alive Content-Length: 1238 <?xml version="1.0" ?> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns4:CreditVendRequest xmlns:ns4="http://www.nrs.eskom.co.za/xmlvend/service/2.1" xmlns:ns3="http://www.nrs.eskom.co.za/xmlvend/meter/2.1/schema" xmlns:ns2="http://www.nrs.eskom.co.za/xmlvend/revenue/2.1/schema" xmlns="http://www.nrs.eskom.co.za/xmlvend/base/2.1/schema"> <ns2:creditVendReq> <clientID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="2016010100011"></clientID> <terminalID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="2016010100011"></terminalID> <msgID dateTime="20161129085852" uniqueNumber="1"></msgID> <authCred> <opName>usr</opName> <password>passwd</password> </authCred> <resource xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="Electricity"></resource> <idMethod> <meterIdentifier xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="MeterNumber" msno="1716052601"></meterIdentifier> </idMethod> <ns2:purchaseValue xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:PurchaseValueCurrency"> <ns2:amt value="20.0" symbol="R"></ns2:amt> </ns2:purchaseValue> </ns2:creditVendReq> </ns4:CreditVendRequest> </S:Body> </S:Envelope> HTTP/1.1 200 OK Content-Type: text/xml;charset=UTF-8 Content-Length: 1737 Date: Tue, 29 Nov 2016 06:58:54 GMT Server: Apache <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns3:CreditVendRequestResponse xmlns:ns4="http://www.nrs.eskom.co.za/xmlvend/meter/2.1/schema" xmlns:ns3="http://www.nrs.eskom.co.za/xmlvend/service/2.1" xmlns:ns2="http://www.nrs.eskom.co.za/xmlvend/revenue/2.1/schema" xmlns="http://www.nrs.eskom.co.za/xmlvend/base/2.1/schema"> <ns2:creditVendResp> <clientID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="2016010100011" /> <serverID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="0000000000001" /> <terminalID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="EANDeviceID" ean="2016010100011" /> <reqMsgID dateTime="20161129085852" uniqueNumber="1" /> <respDateTime>2016-11-29T08:58:53.835+02:00</respDateTime> <operatorMsg>Success</operatorMsg> <custMsg>Success</custMsg> <clientStatus> <availCredit value="0" symbol="R" /> </clientStatus> <utility name="Ekurhuleni" address="" taxRef="" /> <ns2:creditVendReceipt receiptNo="489"> <ns2:transactions> <ns2:tx xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:CreditVendTx" receiptNo="489"> <ns2:amt value="17.54" symbol="R" /> <ns2:tax xsi:type="VAT" rate="14"> <amt value="2.46" symbol="R" /> </ns2:tax> <ns2:creditTokenIssue> <desc></desc> <meterDetail msno="1716052601" sgc="000000" krn="0" ti="00"> <meterType at="00" tt="00" /> </meterDetail> <token xsi:type="STS1Token"> <stsCipher>METER UPDATED</stsCipher> </token> <units value="16.20" siUnit="kWh" /> <resource xsi:type="Electricity" /> </ns2:creditTokenIssue> </ns2:tx> <ns2:tenderAmt value="20.0" symbol="R" /> </ns2:transactions> </ns2:creditVendReceipt> </ns2:creditVendResp> </ns3:CreditVendRequestResponse> </soap:Body> </soap:Envelope>

LASTRESPADVICE (failed)

POST /imms/services/XMLVendWebService HTTP/1.1 Accept: text/xml, multipart/related Content-Type: text/xml; charset=utf-8 SOAPAction: "" User-Agent: JAX-WS RI 2.2.4-b01 Host: xmlvend.server.com:8080 Connection: keep-alive Content-Length: 799 <?xml version="1.0" ?> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns4:AdviceRequest xmlns="http://www.nrs.eskom.co.za/xmlvend/base/2.1/schema" xmlns:ns2="http://www.nrs.eskom.co.za/xmlvend/meter/2.1/schema" xmlns:ns3="http://www.nrs.eskom.co.za/xmlvend/revenue/2.1/schema" xmlns:ns4="http://www.nrs.eskom.co.za/xmlvend/service/2.1"> <adviceReq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="LastRespAdviceReq"> <clientID xsi:type="EANDeviceID" ean="2016010100011" /> <terminalID xsi:type="EANDeviceID" ean="2016010100011" /> <msgID dateTime="20160525142914" uniqueNumber="1" /> <authCred> <opName>myusername</opName> <password>mypassword</password> </authCred> <adviceReqMsgID dateTime="201605251428" uniqueNumber="1" /> </adviceReq> </ns4:AdviceRequest> </S:Body> </S:Envelope> HTTP/1.1 500 Internal Server Error Server: Apache-Coyote/1.1 Content-Type: text/xml;charset=UTF-8 Content-Length: 1141 Date: Wed, 25 May 2016 12:29:16 GMT Connection: close <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <soap:Fault> <faultcode>soap:Server</faultcode> <faultstring>Schema invalid parameters supplied for request</faultstring> <detail> <xmlvendFaultResp xmlns:ns4="http://www.nrs.eskom.co.za/xmlvend/meter/2.1/schema" xmlns:ns3="http://www.nrs.eskom.co.za/xmlvend/service/2.1" xmlns:ns2="http://www.nrs.eskom.co.za/xmlvend/revenue/2.1/schema" xmlns="http://www.nrs.eskom.co.za/xmlvend/base/2.1/schema"> <clientID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ean="2016010100011" xsi:type="EANDeviceID" /> <serverID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ean="0000000000001" xsi:type="EANDeviceID" /> <terminalID xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" ean="2016010100011" xsi:type="EANDeviceID" /> <reqMsgID dateTime="20160525142914" uniqueNumber="1" /> <operatorMsg>Not valid. Verify the data provided and retry </operatorMsg> <custMsg>Not valid. Verify the data provided and retry</custMsg> <fault xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="SystemEx" /> </xmlvendFaultResp> </detail> </soap:Fault> </soap:Body> </soap:Envelope>

LASTRESPADVICE

POST /imms/services/XMLVendWebService HTTP/1.1 Accept: text/xml, multipart/related Content-Type: text/xml; charset=utf-8 SOAPAction: "" User-Agent: JAX-WS RI 2.2.9-b130926.1035 svn-revision#5f6196f2b90e9460065a4c2f4e30e065b245e51e Host: imms-qa.id2metering.com:8443 Connection: keep-alive Content-Length: 843 <?xml version="1.0" ?> <S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/"> <S:Body> <ns4:AdviceRequest xmlns:ns4="http://www.nrs.eskom.co.za/xmlvend/service/2.1" xmlns:ns3="http://www.nrs.eskom.co.za/xmlvend/meter/2.1/schema" xmlns:ns2="http://www.nrs.eskom.co.za/xmlvend/revenue/2.1/schema" xmlns="http://www.nrs.eskom.co.za/xmlvend/base/2.1/schema"> <adviceReq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="LastRespAdviceReq"> <clientID xsi:type="EANDeviceID" ean="2016010100011"></clientID> <terminalID xsi:type="EANDeviceID" ean="2016010100011"></terminalID> <msgID dateTime="20161129090134" uniqueNumber="1"></msgID> <authCred> <opName>usr</opName> <password>passwd</password> </authCred> <adviceReqMsgID dateTime="20161129085852" uniqueNumber="1"></adviceReqMsgID> </adviceReq> </ns4:AdviceRequest> </S:Body> </S:Envelope> HTTP/1.1 200 OK Content-Type: text/xml;charset=UTF-8 Content-Length: 2036 Date: Tue, 29 Nov 2016 07:01:36 GMT Server: Apache <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns3:AdviceRequestResponse xmlns:ns4="http://www.nrs.eskom.co.za/xmlvend/meter/2.1/schema" xmlns:ns3="http://www.nrs.eskom.co.za/xmlvend/service/2.1" xmlns:ns2="http://www.nrs.eskom.co.za/xmlvend/revenue/2.1/schema" xmlns="http://www.nrs.eskom.co.za/xmlvend/base/2.1/schema"> <adviceResp xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="LastRespAdviceResp"> <clientID xsi:type="EANDeviceID" ean="2016010100011" /> <serverID xsi:type="EANDeviceID" ean="0000000000001" /> <terminalID xsi:type="EANDeviceID" ean="2016010100011" /> <reqMsgID dateTime="20161129090134" uniqueNumber="1" /> <respDateTime>2016-11-29T09:01:36.311+02:00</respDateTime> <operatorMsg>Success</operatorMsg> <custMsg>Success</custMsg> <adviceReqMsgID dateTime="20161129085852" uniqueNumber="1" /> <lastResponse xsi:type="ns2:CreditVendResp"> <clientID xsi:type="EANDeviceID" ean="2016010100011" /> <serverID xsi:type="EANDeviceID" ean="0000000000001" /> <terminalID xsi:type="EANDeviceID" ean="2016010100011" /> <reqMsgID dateTime="20161129085852" uniqueNumber="1" /> <respDateTime>2016-11-29T08:58:53.835+02:00</respDateTime> <operatorMsg>Success</operatorMsg> <custMsg>Success</custMsg> <clientStatus> <availCredit value="0" symbol="R" /> </clientStatus> <utility name="Ekurhuleni" address="" taxRef="" /> <ns2:creditVendReceipt receiptNo="489"> <ns2:transactions> <ns2:tx xsi:type="ns2:CreditVendTx" receiptNo="489"> <ns2:amt value="17.54" symbol="R" /> <ns2:tax xsi:type="VAT" rate="14"> <amt value="2.46" symbol="R" /> </ns2:tax> <ns2:creditTokenIssue> <desc></desc> <meterDetail msno="1716052601" sgc="000000" krn="0" ti="00"> <meterType at="00" tt="00" /> </meterDetail> <token xsi:type="STS1Token"> <stsCipher>METER UPDATED</stsCipher> </token> <units value="16.20" siUnit="kWh" /> <resource xsi:type="Electricity" /> </ns2:creditTokenIssue> </ns2:tx> <ns2:tenderAmt value="20.0" symbol="R" /> </ns2:transactions> </ns2:creditVendReceipt> </lastResponse> </adviceResp> </ns3:AdviceRequestResponse> </soap:Body> </soap:Envelope>

In Property24 News of 20 October 2010 is was stated that


“...six of South Africa’s metropolitan councils are owed R29 billion for unpaid water, electricity and property rates bills ... this is having an impact on service delivery in each of the regions.”

© 2012 ID2, All Rights Reserved