eFactory


eFactory Integration Guide

This guide details the integration of a Third-Party platform to eFactory energy management system. The purpose of this integration is to allow access to the Meter data Repository and Billing and Collection Module of eFactory.

Getting Started

Pre-Requsite

To register you are expected to provide:
1. VPN tunnel
All integration messages will flow through the tunnel to ensure data protection and security
2. IP address of the server that will be using the API.
3. Profiling of payment devices (ATM/POS and others) of devices that will be sending payment request to MPG
4. Settlement Account
This accounts is where all monies collected will be settled
5. Fees Account
This account will be debited for agreed fees for all processed requests. ResponseCode - 12 is returned if the debit for fees fails.

Once Registration is complete you will be given an API KEY and API Authentication token which must be kept secret.

API Overview

It is important to understand that eFactory exposes RESTful API endpoints, so the following applies:

  • Ony standard HTTP methods apply (GET, PUT, POST, or DELETE) and attention should be given to the method required by a particular resource (URL).
  • Posts are expected in JSON format.
  • Attention should also be put the headers stated for each resource being accessed.

Meter Data Validation

The proper validation of a meter involves knowledge of the kind of meter being worked with, POSTPAID or PREPAID meter. A prepaid meter requires you provide a proper meter number while a post-paid meter requires you supply the right meter account number.

API endpoint: http://demo.efactory.com.ng/ext/int/data/{apiKey}/{meterType}/{meterId}
Method: GET

Required Parameter Data type Description
Required apiKey String The authentication identifier of the system invoking the service.
Required meterId String The meter identifier. This is either the meter number or the meter account number, depending on the type of meter supplied.
Required meterType String The Type of meter - prepaid or post-paid. And is currently marked by either 'PREPAID' or 'POSTPAID'.

RESPONSE DETAILS
The expected response sample is as shown below

{ 
   "responseCode":"00",
   "responseMessage":"Meter Found",
   "requestId":"1433971256830",
   "responseId":"1433971256830/1433971256830",
   "responseDate":"10-06-2015 21:21.0 PM",
   "requestDate":"10-06-2015 21:21.0 PM",
   "name":"mole mole",
   "email":"jiji@yahoo.com",
   "phoneNumber":"07068004234",
   "meterType":"PREPAID",
   "outstandingAmount":"0.00",
   "minimumAmount":"0.00"
}

Bill Payment Request

This is a bill payment request and the request for service from MPG. In the case of a STS PPM payment request, STS tokens will be sent along with successful processing of the request.

API endpoint: http://demo.efactory.com.ng/pay/data/{apiKey}/{meterType}
Method: POST
Required Headers : Content-Type=application/json

Required Parameter Data type Description
Required apiKey String The authentication identifier of the system invoking the service.
Required meterId String The meter identifier. This is either the meter number or the meter account number, depending on the type of meter supplied.
Required meterType String The Type of meter - prepaid or post-paid. And is currently marked by either 'PREPAID' or 'POSTPAID'.
Required scId String Service center Id. This Identifies the Business unit under which the request will be logged against.
Required itemTypeId String Refer to Item Id section for List of Ids.
Required itemId String This is a unique identifier which Identify the payment notification request.
Required hash String SHA512(merchantId+itemTypeId+itemId+amount+terminalId+apiKey+authToken).
Required terminalId String The terminal ID of the POS/terminal machine. This must be pre-registered on eFactory.
Required amount String This is the total monetary value of the transaction. This should be formatted ##.## i.e. 50.00 denotes a payment notification request of Fifty Naira.
The value of energy that will be given will be less all deductions with added refunds where applicable
Optional payerEmail String Upon successfully processing the request, a receipt will the sent to the payer via Email. If no value is specified as part of the request an SMS will be sent to the email address specified at the time of registering the meter.
Optional payerName String This is the name of the customer.
Optional payerPhoneNumber String Upon successfully processing the request, a receipt will the sent to the payer via SMS.
If no value is specified as part of the request an SMS will be sent to the phonenumber specified at the time of registering the meter.

GENERATING REQUEST HASH
You are required to hash your payment details with your API Key and API Authorization Token.

Upon registration on eFactory you will be given an API Authorization Token which should be kept secret. A valid payment request hash is generated by concatenating the following payment details and hashed using SHA512 algorithm and the assigned API Key:

meterId+itemTypeId+ItemId+amt+terminalId+apikey+authToken

RESPONSE DETAILS
The expected response sample is as shown below

{ 
   "responseCode":"00",
   "responseMessage":"SUCCESS",
   "responseDate":"12-06-2015 07:37:38.84",
   "rrr":"SMS1434094655818",
   "amount":"10000",
   "itemTypeId":"389",
   "meterno":"54140724110",
   "payerEmail":"jiji@yahoo.com",
   "payerPhoneNumber":"08041941499",
   "payerName":"Mr Kokumo Adejare",
   "itemId":"001111111111",
   "terminalId":"12312312311111",
   "scId":"15001123456",
   "tokenData":[ 
      { 
         "index":"1",
         "type":"CREDIT",
         "token":"2547 4987 4401 3703"
      }
   ],
   "paymentData":{ 
      "tIndex":"R2-1Q",
      "rate":"16.11",
      "rnd":[ 
         { 
            "description":"Maintenance Fee For Single Phase Customers.",
            "amount":"2,500.00",
            "taxAmount":"125.00",
            "kind":"FIXED_CHARGE"
         }
      ],
      "kwH":451.28,
      "cFee":105,
      "sgc":"60045"
   }
}

Bill Payment Enquiry

This can be used to check the status of a previous Bill Payment Request. There are two endpoints available. In any case the response is identical.

REQUEST DETAILS BY MPG PAYMENT REFERENCE
API endpoint: http://demo.efactory.com.ng/pay/data/{apiKey}/{meterType}/{paymentReference}
Method: GET

Required Parameter Data type Description
Required apiKey String The authentication identifier of the system invoking the service.
Required meterType String The Type of meter - prepaid or post-paid. And is currently marked by either 'PREPAID' or 'POSTPAID'.
Required paymentReference String Payment reference that was previously return by eFactory from invoking the Payment Request API endpoint.

REQUEST BY ITEM ID
API endpoint: http://demo.efactory.com.ng/pay/data/{apiKey}/{meterType}/item/{itemId}
Method: GET

Required Parameter Data type Description
Required apiKey String The authentication identifier of the system invoking the service.
Required meterType String The Type of meter - prepaid or post-paid. And is currently marked by either 'PREPAID' or 'POSTPAID'.
Required itemId String ItemId used when previously invoking the Payment Request API endpoint.

RESPONSE DETAILS
The expected response sample is as shown below


				   { 
   "responseCode":"00",
   "responseMessage":"SUCCESS",
   "responseDate":"12-06-2015 07:37:38.84",
   "rrr":"SMS1434094655818",
   "amount":"10000",
   "itemTypeId":"389",
   "meterno":"54140724110",
   "payerEmail":"jiji@yahoo.com",
   "payerPhoneNumber":"08041941499",
   "payerName":"Mr KokumoAdejare",
   "itemId":"001111111111",
   "terminalId":"12312312311111",
   "scId":"15001123456",
   "tokenData":[ 
      { 
         "index":"1",
         "type":"CREDIT",
         "token":"2547 4987 4401 3703"
      }
   ],
   "paymentData":{ 
      "tIndex":"R2-1Q",
      "rate":"16.11",
      "rnd":[ 
         { 
            "description":"Maintenance Fee For Single Phase Customers.",
            "amount":"2,500.00",
            "taxAmount":"125.00",
            "kind":"FIXED_CHARGE"
         }
      ],
      "kwH":451.28,
      "cFee":105,
      "sgc":"600045"
   }
}


Response Code

Response Code Response Message
00 SUCCESS
01 TRANSACTION_FAILED
02 BAD REQUEST
03 UNKNOWN ITEM TYPE
04 AUTHENTICATION ERROR
05 UNKNOWN METER
06 SYSTEM ERROR
07 LIMIT REACHED
08 UNKNOWN PAYMENT REFERENCE
09 UNASSIGNED METER
10 INSUFFICENT AMOUNT
11 TOKEN DISPENSE ERROR
12 INSUFFICENT FEE AMOUNT

Item ID

ItemType Id Description
389 Electricitybills
789 Reconnectionbill
799 New meter payment

SC ID

BUSINESS UNIT SC ID
AkanranBusinessUnit AKRN
ApataBusinessUnit APTA
BabokoBusinessUnit BABO
ChallengeBusinessUnit CHAL
DugbeBusinessUnit DUGB
EdeBusinessUnit EDE
Ijebu-IgboServiceUnit IJB
Ijebu-OdeBusinessUnit I-OD
IkirunBusinessUnit IKRN
Ile-IfeBusinessUnit IFE
IlesaBusinessUnit ILES
JebbaServiceUnit JEBA
MoleteBusinessUnit MOLE
MonatanBusinessUnit MONO
NewBussaServiceUnit NBS
OffaServiceUnit OFFA
OgbomosoBusinessUnit OGBO
OjooBusinessUnit OJOO
OlumoBusinessUnit OLU
Omu-AranBusinessUnit OMRN
OsogboBusinessUnit OSOG
OtaBusinessUnit OTA
OyoBusinessUnit OYO
SagamuBusinessUnit SHAG
Abeokuta ABEO
Isesa ISE
IbadanBusinessUnit IBD

Demo Credentials

Please call our support line.

Sample Codes

Please check back soon.