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

CHANGELOG

please see full changelog here

Examples

Check examples available here

Sign Up

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

Authentication Header

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

import hotrecharge

# create config class
config = hotrecharge.HRAuthConfig(
    access_code='acc-email', 
    access_password='acc-pwd',
    reference='random-ref'
)

# 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

# <..>

try:
    # 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
    print(evds.AgentReference)
    print(evds.ReplyMsg)

    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)
        
        print('-----------------------------')

        x++

# 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

try:
    # get wallet balance
    wallet_bal_response = api.walletBalance()

    # get data bundles
    data_bundles_resp = api.getDataBundles()

    print("Wallet Balance: ")
    pprint.pprint(wallet_bal_response)

    print("Data Bundles Balance: ")
    pprint.pprint(data_bundles_resp)

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

Recharge

Recharge data bundles

use bundle product code
an optional customer sms can be send together upon request
Place holders used include

%AMOUNT% 	    $XXX.XX
%COMPANYNAME%	As Defined by Customer on the website www.hot.co.zw
%ACCESSNAME%	Defined by Customer on website – Teller or Trusted User or branch name
%BUNDLE%	    Name of the Data Bundle

try:
    # 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
    api.updateReference('<new-random-string>')

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

    pprint(response)

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

Recharge pinless

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

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

    print(response)

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 www.hot.co.zw

Note on Zesa Recharges

Requirements

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

    try:
        customer = api.checkZesaCustomer(meterNumber)

        print(customer)

        # 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

try:
    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

DonnC/Hot-Recharge-ZW