Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/donnc/hot-recharge-zw

perform hot-recharge services with hot-recharge python library
https://github.com/donnc/hot-recharge-zw

hot-recharge mobile python recharge

Last synced: 2 months ago
JSON representation

perform hot-recharge services with hot-recharge python library

Awesome Lists containing this project

README 

        
# [Hot Recharge](https://ssl.hot.co.zw/)

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



- ℹ Not an official hot-recharge python library



## Library installation

```sh

$ pip install hot-recharge

```

or update with

```sh

$ pip install -U hot-recharge

```



## [CHANGELOG](CHANGELOG.md)

please see full [changelog here](CHANGELOG.md)



## Examples

Check examples available [here](example)



## Sign Up

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

- ![sign up](https://raw.githubusercontent.com/DonnC/Hot-Recharge-ZW/master/Docs/images/signup_cooperate.png)



## Authentication Header

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

```python

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`

```python

# <..>



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

```python

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

```

```python

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



    response = api.dataBundleRecharge(product_code="", number="077xxxxxxx", mesg=customer_sms)



    pprint(response)



except Exception as ex:

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

```



### Recharge pinless

```python

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 

```python



    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

```python

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