perform hot-recharge services with hot-recharge python library programmaticaly
- ℹ Not an official hot-recharge python library
$ pip install hot-recharge
or update with
$ pip install -U hot-recharge
please see full changelog here
Check examples available here
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)
- model returned is auto-generated by
Munch
library - To enable it, flag the
return_model=True
, defaults toFalse
# <..>
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}")
- 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}")
- 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}")
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}")
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
- 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.
- 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}")
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 aMunch
). In some cases this will beNone
, so dont get mad if you seeNone
😁. - One of the best use cases of the
response
property is when aPendingZesaTransaction
exception gets raised. you can saverechargeID
, then you can use it later to query the transaction status.
- 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