Skip to main content

perform hot-recharge services with hot-recharge library programmatically

Project description

Hot Recharge

perform hot-recharge services with hot-recharge python library programmaticaly

  • ℹ Not an official hot-recharge python library

Library installation

$ pip install hot-recharge

or update with

$ pip install -U hot-recharge


please see full changelog here


Check examples available here

Sign Up

  • needs a hot recharge co-operate account or contact hot-recharge for proper account
  • sign up

Authentication Header

Use the new HRAuthConfig (from v2.x.x) class to pass auth header keys

import hotrecharge

# create config class
config = hotrecharge.HRAuthConfig(

# pass config object to api constructor
api = hotrecharge.HotRecharge(config)

New in v3.x

You can now return response models rather than dict

  • model returned is auto-generated by Munch library
  • To enable it, flag the return_model=True, defaults to False
# <..>

    # flag return_model -> True in order to return model, (Munch object)
    api = hotrecharge.HotRecharge(config, return_model=True)    

    # lets get available EVDs (electronic vouchers) as models
    evds = api.getEVDs()

    # you can now do

    x = 0

    # can loop around available evds in stock
    for evd_pin in evds.InStock:
        print(f'------- EVD Pin [{x}]-------')

        print('EVD Brand Name:    ', evd_pin.BrandName)
        print('EVD Pin Value:     ', evd_pin.PinValue)
        print('EVD Current Stock: ', evd_pin.Stock)


# can also catch api exceptions
# HotRechargeException is the base class for all exceptions
# check example folder for more
except hotrecharge.HotRechargeException as ex:
    print(f"[HOTRECHARGE ERROR] There was a problem: {ex}")

Performing requests

  • this shows how to do basic get requests for different services
import hotrecharge
import pprint

    # get wallet balance
    wallet_bal_response = api.walletBalance()

    # get data bundles
    data_bundles_resp = api.getDataBundles()

    print("Wallet Balance: ")

    print("Data Bundles Balance: ")

except Exception as ex:
    print(f"There was a problem: {ex}")


Recharge data bundles

  • use bundle product code
  • an optional customer sms can be send together upon request
  • Place holders used include
%COMPANYNAME%	As Defined by Customer on the website
%ACCESSNAME%	Defined by Customer on website – Teller or Trusted User or branch name
%BUNDLE%	    Name of the Data Bundle
    # option message to send to user
    customer_sms =  " Amount of %AMOUNT% for data %BUNDLE% recharged! " \
                    " %ACCESSNAME%. The best %COMPANYNAME%!"

    # need to update reference manually, if `use_random_ref` is set to False

    response = api.dataBundleRecharge(product_code="<bundle-product-code>", number="077xxxxxxx", mesg=customer_sms)


except Exception as ex:
    print(f"There was a problem: {ex}")

Recharge pinless

    customer_sms = "Recharge of %AMOUNT% successful" \
                   "Initial balance $%INITIALBALANCE%" \
                   "Final Balance $%FINALBALANCE%" \

    response = api.rechargePinless(amount=3.5, number="077xxxxxxx", mesg=customer_sms)


except Exception as ex:
    print(f"There was a problem: {ex}")

Zesa Recharge

custom Message place holders to use and their representation on end user for zesa transactions:

  • %AMOUNT% - $xxx.xx
  • %KWH% - Unit in Kilowatt Hours(Kwh)
  • %ACOUNTNAME% - Account holdername of meter number
  • %METERNUMBER% - meter number
  • %COMPANYNAME% - as defined by Customer on the website

Note on Zesa Recharges


  • A method for Purchasing ZESA Tokens
  • It is a ZESA requirement that any purchase must be verified. As such please ensure that you use the checkZesaCustomer() method
        customer = api.checkZesaCustomer(meterNumber)


        # prompt user to confirm their details first before performing a recharge

    except Exception as err:
        print('[ERROR] Error getting zesa customer: ', err)
  • and prompt the customer to confirm the details before calling this method (api.rechargeZesa(...)).
  • There is a new transaction state specifically for ZESA that is Pending verification indicated by reply code 4. Transactions in this state can result in successful transactions after a period of time once ZESA complete transaction.
  • You must call Query ZESA method TBD periodically until a permanent resolution of the transaction occurs. This polling of a pending transaction should not exceed more that 4 request a minute. Resending of transactions that have not yet failed can result in the duplication of transaction and lose of funds.
  • Please note ZESA does not allow refunds so the cost of any errors cannot be recovered.

Query transaction

  • You can now query a previous transaction by its agentReference for reconciliation.
  • It is reccommended to query within the last 30 days of the transaction
    response = api.rechargePinless(amount=3.5, number="077xxxxxxx")

    # save agentReference to query for reconciliation
    prevTransactionAgentReference = response.get("agentReference")

    result = api.queryTransactionReference(prevTransactionAgentReference)

    print(response, result)

except Exception as ex:
    print(f"There was a problem: {ex}")

Note on Exceptions

  • HotRechargeException is the base class for all exceptions
  • All exceptions are subclasses of HotRechargeException
  • All exceptions have a message property that contains the error message
  • All exceptions have a response property that contains the response object(which is a Munch). In some cases this will be None, so dont get mad if you see None😁.
  • One of the best use cases of the response property is when a PendingZesaTransaction exception gets raised. you can save rechargeID, then you can use it later to query the transaction status.

Support 🤿

  • This is not an official hot-recharge python library
  • I initiated, develop and maintain this library on my own spare time
  • A little support can go a long way, i would appreciate it

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hot-recharge-4.0.0.tar.gz (10.8 kB view hashes)

Uploaded Source

Built Distribution

hot_recharge-4.0.0-py3-none-any.whl (12.6 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page