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 programmatically

  • ℹ 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
  • 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(
    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

Project details


Download files

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

Files for hot-recharge, version 3.3.1
Filename, size File type Python version Upload date Hashes
Filename, size hot_recharge-3.3.1-py3-none-any.whl (12.6 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size hot-recharge-3.3.1.tar.gz (10.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page