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

• add latest version of hot_recharge to your pubspec.yaml file

dependencies:
  flutter:
    sdk: flutter

  hot_recharge:

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

• 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
);

• [✔] 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

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

// 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}');
    }

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

print(result);

• 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);

• 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

• 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}');
    }

• 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.

• 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

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.