Electricity API Usage

Step 1: Operators Retrieval.

A request to the operator retrieval endpoint returns a list of currently supported operators. call API endpoint

https://api.blochq.io/v1/bills/electricity/operators

{
  "success": true,
  "data": [
    {
      "desc": "Kano Electricity Distribution Company",
      "id": "op_s3Lb7zJJLh7VGF67wTut7U",
      "name": "KEDCO",
      "sector": "Electricity"
    },
    {
      "desc": "Eko Electricity Distribution Company",
      "id": "op_JDODSOE7fJjdhtX6v64TK",
      "name": "EKEDC",
      "sector": "Electricity"
    },
    {
      "desc": "Enugu Electricity Distribution Company",
      "id": "op_hNYNSsTbHp7YZAxn8tNHKR",
      "name": "EEDC",
      "sector": "Electricity"
    },
    {
      "desc": "Ikeja Electricity Distribution Company",
      "id": "op_te89Caom34mWbZbTPuuk6s",
      "name": "IKEDC",
      "sector": "Electricity"
    },
    
    ...

  ],
  "message": "supported operators"
}

Description of Response Fields

Fields	Description
id	The unique ID of this operator name
name	A simple and abbreviated name for this operator
sector	An umbrella name for the sector under which this operator functions
desc	A more descriptive name/representation of this operator.

Step 2: Product Retrieval.

A request to the product retrieval endpoint returns a list of electricity products. call API endpoint

https://api.blochq.io/v1/bills/electricity/operators/{operator_id}/products"

{
  "success": true,
  "data": [
    {
      "category": "pctg_aLrTqmTXE8sdDavnKtxPJG",
      "desc": null,
      "fee_type": "FLEXIBLE",
      "id": "prd_Uc28gg954YHftPPoZEVrCp",
      "meta": null,
      "name": "Operator Bill Payment",
      "operator": "op_hFzVYtRLcheuGenZXB45Aq"
    }
  ],
  "message": "supported operators"
}

Description of Response Fields

Fields	Description
id	The unique identifier of this product. (To be submitted during payment for this product.)
name	The name of this product
desc	The description of this product
fee_type	The flexibility of the amount you can pay for this product. (One of FIXED , FLEXIBLE or RANGE ) See Payment Fee Type
category	The unique identifier of the product category.
operator	The unique identifier of the service provider, that is, the disco.
meta	Extra information about the product, if any, as supplied by the service provider.

Step 3: Customer Validation.

The customer validation endpoint must be called to verify the account or meter number of the customer. Upon successful validation, this endpoint returns customer information like address, minimum purchase value and last bill due among other things. It also returns a payment_reference, which must be provided when making a subsequent call for payment. Do note that this reference has an expiration time, hence it must be used quickly. call API endpoint

Retrieve the details of a customer matching the given parameters. This must be called before initiating a payment for the customer.

https://api.blochq.io/v1/bills/electricity/customers/:operatorID/:productNumber?meter_type={meter_type}

{
    "success": true,
    "data": {
        "account_number": null,
        "address": "17,ADEDUROSIMI STREET, SHOMOLU",
        "category": "prepaid",
        "debt": null,
        "email": "",
        "meta": {
            "business_unit": "",
            "last_transaction_date": "0001-01-01T00:00:00Z",
            "undertaking": ""
        },
        "meter_number": null,
        "minimum_payable": "5.86",
        "name": "MR AKINBOTE WALE",
        "payment_reference": "7c34f2fe4a7942e399c8c28f043334",
        "phone": "",
        "tariff_class": null,
        "tariff_rate": null,
        "unique_id": "62180004202"
    },
    "message": "customer details"
}

Description of Request Fields

Fields	Description
operatorID	The unique identifier of the electricity operator.
productNumber	The meter number/account number identifier assigned to the customer. For a postpaid customer: use the customer’s account number. For a prepaid or a smart-meter customer: use the customer’s meter number.
category	The category of the customer account. Values could be postpaid ,prepaid or smart-meter .

Description of Response Fields

Fields	Description
unique_id	The account/meter number assigned to the customer.
name	The account name of the customer
address	The address of the customer.
email	The email address of the customer
phone	The phone number of the customer.
debt	The current debt of customer, if any, in nairas.
minimum_payable	The minimum amount the customer must pay on their. next payment, in nairas.
payment_reference	The reference to be presented when completing a payment for the customer, following the validation.
meta	The meta is a key-value object containing disco-specific information. The values may vary per call and/or operation
category	The customer account category.
account_number	The customer account number applies to postpaid customers.
meter_number	The customer meter number applies to prepaid and smart-meter customers.
tariff_class	The tariff classification of the customer with the disco.
tariff_rate	The tariff rate that applies to the customer’s tariff_class

Step 4: Payment Fulfillments.

After successful validation of a customer, a request is made to the payment endpoint to
complete a payment transaction in favour of the validated customer. call API endpoint

For some discos, it is required that the amount paid in a transaction should surpass the minimum payable amount of the customer. The minimum payable amount is contained in the response of a Customer Validation request.

https://api.blochq.io/v1/bills/electricity/payment

{
    "amount": 100000,
    "product_id": "prd_XHSjeVHW9MNi3LvHkL2tQc",
    "operator_id": "op_hFzVYtRLcheuGenZXB45Aq",
    "payment_reference": "ae4d32d2f7d940f191c0fe0ed5c2c8c4"
}

{
    "success": true,
    "data": {
        "amount": "1000.00",
        "created": "2022-10-25T15:01:08.862319",
        "account_number": "1015124143-01",
        "address": "OGUNSHADE ST 44 LEKKI LA",
        "business_unit": “LEKKI”,
        "current_debt": null,
        "customer_category": "prepaid",
        "e_receipt": “”,
        "meta": {
            "debt": 0,
            "debt_deduction": null,
            "meter_type": ""
        },
        "meter_number": "",
        "name": "FREDRICH ADEWALE",
        "operator": "EKEDC",
        "operator_receipt”: null,
        "operator_reference": "",
        "operator_vat": null,
        "payer": {
            "name": "BlocMobile"
        },
        "payment_reference": "ab486df3f40f42a49871763a7678e2c3",
        "previous_debt": null,
        "status": "ACTIVE",
        "tariff_class": null,
        "tariff_rate": null,
        "token": "2323234223233342323",
        "token_cost": null,
        "units": "108.2"
    },
    "message": "make payment"
}

Description of Request Fields

Fields	Description
amount	The amount being paid ( in kobos. )
payment_reference	The payment_reference value retrieved during Customer Validation.
product_id	Product Id of the service

Description of Response Fields

Fields	Description
account_number	The customer’s account number.
address	The address of the customer.
amount	Amount paid (in naira) .
business_unit	The business unit of the operator under which the customer falls.
created	The date and time of the request.
current_debt	The amount currently owed by the customer.
e_receipt	A unique invoice number generated for this transaction.
meta	The meta is a key-value object containing operator-specific information. The values may vary per call and/or operation.
meter_number	The customer’s meter number.
name	The name of the customer.
operator_receipt	The payment receipt, if any, provided by the operator.
operator_vat	The operator’s VAT charge for the transaction.
payment_reference	The unique transaction identifier used for the transaction.
previous_debt	Previous amount owed by the customer, if any.
tariff_class	The tariff classification of the customer with the disco.
tariff_rate	The tariff rate that applies to the customer’s tariff_class .
token	The token generated for the transaction. ( Applies to prepaid-meter type transactions. )
token_cost	The actual cost for the token, as specified by the operator. ( Applies to prepaid-meter type transactions. )
units	The energy value of the generated token. ( Applies to prepaid-meter type transactions. )