hot_recharge

Description:

hot recharge

Hot Recharge #
perform airtime topup across all networks, vouchers and zesa recharge with hot-recharge flutter plugin

ℹ Not an official hot-recharge flutter plugin
a flutter plugin port of hot-recharge python library and hot-recharge node package

screenshots #

Plugin installation #

add latest version of hot_recharge to your pubspec.yaml file

dependencies:
flutter:
sdk: flutter

hot_recharge:
copied to clipboard
Sign Up #

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


Authentication keys #

accessCode := the email address used on registration
accessPswd := the password of the account used on registration

// import hot-recharge plugin
import 'package:hot_recharge/hot_recharge.dart';

// create api instance
hotRecharge = HotRecharge(
accessCode: '<your-email>',
accessPswd: '<your-pwd>',
enableLogger: false, // flag to true to enable detailed log while testing, use while testing ONLY
);
copied to clipboard
Features #

[✔] perfom airtime topup
[✔] perfom zesa recharge
[✔] query airtime topup transaction
[✔] query zesa transaction
[✔] get account airtime balance
[✔] get account zesa balance
[✔] check zesa customer
[❌] perform evd transaction
[❌] perform bundle topup
(...) and more

Performing requests #

all requests returns an instance of ApiResponse response model
this shows how to perform api requests to hot-recharge services

topup number
// supports both mobile and '08xxxx...' numbers
final bal = await hotRecharge.topupNumber(1.50, '07xxxxxx');

// check response status
if (bal.rechargeResponse == RechargeResponse.SUCCESS) {
final PinlessRecharge result = bal.apiResponse;
showSnackbar(message: result.replyMsg);
}

// there was a problem
else {
showSnackbar(message: 'failed to sent airtime: ${bal.message}');
}

copied to clipboard
query transaction
// query a previous transaction agent reference for reconcilliation
final result = await hotRecharge.queryTopupTransaction('previous-agent-reference');

print(result);

copied to clipboard
Custom messages

the api supports sending OPTIONAL custom messages to the user as confirmation messages
you can customize how the message will arrive like on the client | user side
certain placeholders have to be used and total message length should be less than 150 chars



For airtime topup

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


%AMOUNT% - $xxx.xx


%INITIALBALANCE% - $xxx.xx


%FINALBALANCE% - $xxx.xx


%TXT% - xxx texts


%DATA% - xxx MB


%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
`


example
final mesg = 'Recharge of \$ %AMOUNT% is successful.\nThe best %COMPANYNAME%!';

var response = await hotRecharge.topupNumber(
2.0,
'07xxxxxxxx',
customMessage: mesg,
);

print(response);
copied to clipboard




For zesa transactions

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

%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 checkCustomerDetail() method

final result = await api.checkZesaCustomer(meterNumber);

// check response status
if (result.rechargeResponse == RechargeResponse.SUCCESS) {
ZesaCustomerDetail details = result.apiResponse;
var customerInfo = details.customerInfo;

// prompt for user to verify info obtained from api
zesaUserPromptDialog(message: customerInfo.customerName);
}

// there was a problem
else {
showSnackbar(message: 'failed to check zesa user: ${result.message}');
}
copied to clipboard

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 (RechargeResponse.PENDING). Transactions in this state can result in successful transactions after a period of time once ZESA complete transaction.
You must call Query ZESA method (api.queryZesaTransaction(...)) 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.

Support 🤿 #


A little support can go a long way


For general questions and discussions please make use of github discussions here


You can help by making PR on any changes you would like to contribute to


Fork or star this repo, it will help us lot


With 💙 from FlutterDevZW by @DonnC & @iamngoni


Getting Started #
This project is a starting point for a Dart
package,
a library module containing code that can be shared easily across
multiple Flutter or Dart projects.
For help getting started with Flutter, view our
online documentation, which offers tutorials,
samples, guidance on mobile development, and a full API reference.