rave-python 1.4.2
Python library for Flutterwave for Business (F4B) v2 APIs.
License: MIT
Requires Python: !=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,>=2.7

<p align="center">
            <img title="Flutterwave" height="200" src="https://flutterwave.com/images/logo/full.svg" width="50%"/>
        </p>
        
        # Flutterwave Python Library.
        ![PyPI](https://img.shields.io/pypi/v/rave_python)
        ![PyPI - Downloads](https://img.shields.io/pypi/dm/rave_python)
        ![PyPI - License](https://img.shields.io/pypi/l/rave_python)
        
        
        ## Introduction
        The Python library provides easy access to Flutterwave for Business (F4B) v2 APIs from Django, Flask, and other Python apps. It abstracts the complexity involved in direct integration and allows you to make quick calls to the APIs.
        
        Available features include:
        
        - Collections: Card, Account, Mobile money, Bank Transfers, USSD, Barter, NQR.
        - Payouts and Beneficiaries.
        - Recurring payments: Tokenization and Subscriptions.
        - Split payments
        - Card issuing
        - Transactions dispute management: Refunds.
        - Transaction reporting: Collections, Payouts, Settlements, and Refunds.
        - Bill payments: Airtime, Data bundle, Cable, Power, Toll, E-bills, and Remitta.
        - Identity verification: Resolve bank account, resolve BVN information.
        
        ## Table of Contents
        1. [Requirements](#requirements)
        2. [Installation](#installation)
        3. [Initialization](#initialization)
        4. [Usage](#usage)
        5. [Testing](#testing)
        6. [Debugging Errors](#debugging-errors)
        7. [Support](#support)
        8. [Contribution guidelines](#)
        9. [License](#)
        10. [Changelog](#)
        
        ## Requirements
        1. Flutterwave for business [API Keys](https://developer.flutterwave.com/docs/integration-guides/authentication)
        2. Supported Python versions: >=2.7, !=3.0.\*, !=3.1.\*, !=3.2.\*, !=3.3.\*, !=3.4.\*
        
        
        ## Installation
        To install the library, run
        
        ```sh
        pip install rave_python
        ```
        
        Note: This is currently under active development
        
        
        ## Initialization
        
        ### Import Package
        The base class for this package is 'Rave'. To use this class, add:
        
        ```py
        from rave_python import Rave
        ```
        
        #### To instantiate in sandbox:
        To use Rave, instantiate the Rave class with your public key. We recommend that you store your secret key in an environment variable named, ```RAVE_SECRET_KEY```. Instantiating your rave object is therefore as simple as:
        
        ```py
        rave = Rave("YOUR_PUBLIC_KEY")
        ```
        
        ####  To instantiate without environment variables (Sandbox):
        If you choose not to store your secret key in an environment variable, we do provide a ```usingEnv``` flag which can be set to ```False```, but please be warned, do not use this package without environment variables in production
        
        ```py
        rave = Rave("YOUR_PUBLIC_KEY", "YOUR_SECRET_KEY", usingEnv = False)
        ```
        
        
        #### To instantiate in production:
        To initialize in production, simply set the ```production``` flag to ```True```. It is highly discouraged but if you choose to not use environment variables, you can do so in the same way mentioned above.
        
        ```py
        rave = Rave("YOUR_PUBLIC_KEY", production=True)
        ```
        
        
        
        # Usage
        This is the documentation for all of the components of rave_python
        
        ## ```rave.Card```
        This is used to facilitate card transactions.
        
        **Functions included:**
        
        * ```.charge```
        
        * ```.validate```
        
        * ```.verify```
        
        * ```.refund```
        
        * ```.getTypeOfArgsRequired```
        
        * ```.updatePayload```
        
        <br>
        
        ### ```.charge(payload)```
        This is called to start a card transaction. The payload should be a dictionary containing card information. It should have the parameters:
        
        * ```cardno```,
        
        * ```cvv```, 
        
        * ```currency```, 
        
        * ```country```, 
        
        * ```expirymonth```, 
        
        * ```expiryyear```, 
        
        * ```amount```, 
        
        * ```email```, 
        
        * ```phonenumber```,
        
        * ```firstname```, 
        
        * ```lastname```, 
        
        * ```IP```
        
        Optionally, you can add a custom transaction reference using the ```txRef``` parameter. Note that if you do not specify one, it would be automatically generated. We do provide a function for generating transaction references in the [Misc library](https://github.com/Flutterwave/rave-python/blob/master/rave_python/rave_misc.py).
        
        
        A sample call is:
        
        ```py
        res = rave.Card.charge(payload)
        ```
        
        #### Returns
        
        This call returns a dictionary. A sample response is:
        
        ```py
         {'validationRequired': True, 'suggestedAuth': u'PIN', 'flwRef': None, 'authUrl': None, 'error': False, 'txRef': 'MC-1538095398058'}
         ```
        
        This call raises a ```CardChargeError``` if there was a problem processing your transaction. The ```CardChargeError``` contains some information about your transaction. You can handle this as such:
        
        ```py
        try: 
            #Your charge call
        except RaveExceptions.CardChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        ```
        
        A sample ``` e.err ``` contains:
        
        ```py
        {'error': True, 'txRef': 'MC-1530897824739', 'flwRef': None, 'errMsg': 'Sorry, that card number is invalid, please check and try again'}
        ```
        
        
        <br>
        
        ### ```rave.Misc.updatePayload(authMethod, payload, arg)```
        
        Depending on the suggestedAuth from the charge call, you may need to update the payload with a pin or address. To know which type of authentication you would require, simply call ```rave.Card.getTypeOfArgsRequired(suggestedAuth)```. This returns either ```pin``` or ```address```. 
        
        In the case of ```pin```, you are required to call ```rave.Card.updatePayload(suggestedAuth, payload, pin="THE_CUSTOMER_PIN")```. 
        
        In the case of ```address```, you are required to call ```rave.Card.updatePayload(suggestedAuth, payload, address={ THE_ADDRESS_DICTIONARY })```
        
        A typical address dictionary includes the following parameters:
        
        ```billingzip```, 
        
        ```billingcity```,
        
        ```billingaddress```, 
         
        ```billingstate```,
         
        ```billingcountry```
        
        **Note:**
        ```suggestedAuth``` is the suggestedAuth returned from the initial charge call and ```payload``` is the original payload
        
        <br>
        
        ### ```.validate(txRef)```
        
        After a successful charge, most times you will be asked to verify with OTP. To check if this is required, check the ```validationRequired``` key in the ```res``` of the charge call.
        
        To validate, you need to pass the ```flwRef``` from the ```res``` of the charge call as well as the OTP.
        
        A sample validate call is: 
        
        ```py
        res2 = rave.Card.validate(res["flwRef"], "12345")
        ```
        
        #### Returns
        
        This call returns a dictionary containing the ```txRef```, ```flwRef``` among others if successful. 
        
        This call raises a ```TransactionValidationError``` if the OTP is not correct or there was a problem processing your request. 
        
        To handle this, write:
        
        ```py
        try:
            # Your charge call
        except RaveExceptions.TransactionValidationError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        ```
        
        A sample ``` e.err ``` contains:
        
        ```py
        {'error': True, 'txRef': None, 'flwRef': 'FLW-MOCK-a7911408bd7f55f89f0211819d6fd370', 'errMsg': 'otp is required'}
        ```
        
        <br>
        
        ### ```.verify(txRef)```
        
        You can call this to check if your transaction was completed successfully. You have to pass the transaction reference generated at the point of charging. This is the ```txRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.Card.verify(data["txRef"])
        ```
        
        #### Returns
        
        This call returns a dict with ```txRef```, ```flwRef``` and ```transactionComplete``` which indicates whether the transaction was completed successfully. 
        
        Sample
        ```py
        {'flwRef': None, 'cardToken': u'flw-t1nf-5b0f12d565cd961f73c51370b1340f1f-m03k', 'chargedAmount': 100, 'amount': 100, 'transactionComplete': True, 'error': False, 'txRef': u'MC-1538095718251'}
        ```
        
        > Please note that after charging a card successfully on rave, if you wish to save the card for further charges, in your verify payment response you will find an object: `"cardtoken": "flw-t0-f6f915f53a094671d98560272572993e-m03k"`.  This is the token you will use for card tokenization. Details are provided below.
        
        If your call could not be completed successfully, a ```TransactionVerificationError``` is raised.
        
        <br>
        
        ### ```.charge(payload_for_saved_card, chargeWithToken=True)```
        This is called to start a card transaction with a card that has been saved. The payload should be a dictionary containing card information. It should have the parameters:
        
        * ```token```,
        
        * ```country```, 
        
        * ```amount```, 
        
        * ```email```, 
        
        * ```firstname```, 
        
        * ```lastname```, 
        
        * ```IP```,
        
        * ```txRef```, 
        
        * ```currency```
        
        #### NB: email must be the same as before the card was saved
        Optionally, you can add a custom transaction reference using the ```txRef``` parameter. Note that if you do not specify one, it would be automatically generated. We do provide a function for generating transaction references in the [Misc library](https://github.com/Flutterwave/rave-python/blob/master/rave_python/rave_misc.py).
        
        A sample call is:
        
        ```py
        res = rave.Card.charge(payload_for_saved_card, chargeWithToken=True)
        ```
        
        #### Returns
        
        This call returns a dictionary. A sample response is:
        
         ```py
         {'status': u'success', 'validationRequired': False, 'suggestedAuth': None, 'flwRef': u'FLW-M03K-cdb24d740fb18c242dd277fb1f74d399', 'authUrl': None, 'error': False, 'txRef': 'MC-7666-YU'}
         ```
        
         This call raises a ```CardChargeError``` if a wrong token or email is passed or if there was a problem processing your transaction. The ```CardChargeError``` contains some information about your transaction. You can handle this as such:
        
        ```py
        try: 
            #Your charge call
        except RaveExceptions.CardChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        ```
        
        This call also raises an ```IncompletePaymentDetailsError``` if any of the required parameters are missing. The ```IncompletePaymentDetailsError``` contains information about which parameter was not included in the payload. You can handle this such as:
        
        ```py
        try:
            #Your charge call
        except RaveExceptions.IncompletePaymentDetailsError as e:
            print(e.err["errMsg"])
        ```
        
        Once this is done, call ```rave.Card.verify``` passing in the ```txRef``` returned in the response to verify the payment. Sample response:
        
        ```py
        {'flwRef': None, 'cardToken': u'flw-t1nf-5b0f12d565cd961f73c51370b1340f1f-m03k', 'chargedAmount': 1000, 'amount': 1000, 'transactionComplete': True, 'error': False, 'txRef': 'MC-7666-YU'}
        ```
        
        ```rave.Card.verify``` raises a ```TransactionVerificationError``` if an invalid ```txRef``` is supplied. You can handle this as such:
        
        ```py
        try: 
            #Your charge call
        except RaveExceptions.CardChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        ```
        #### NB: when charging saved cards, you do not need to call rave.card.Validate()
        
        
        ### ```.refund(flwRef, amount)```
        
        You can call this to refund a full or partial amount of a transaction that was completed successfully. You have to pass the flw reference generated at the point of verifing the transaction. This is the ```flwRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.Card.refund(data["flwRef"], amount)
        ```
        
        #### Returns
        
        This call returns a dict with ```status```, ```AmountRefunded```, ```disburse_ref``` and ```disburse_status``` which indicates whether the transaction was completed successfully. 
        
        Sample
        ```py
        (True, {'settlement_id': 'NEW', 'id': 36071, 'AccountId': 49278, 'TransactionId': 1664979, 'FlwRef': 'FLW-MOCK-62986ef948d6dd127102cdb58813d216', 'walletId': 50309, 'AmountRefunded': '5000', 'status': 'completed', 'destination': 'payment_source', 'meta': '{"source":"ledgerbalance","uniquereference":"62472228710"}', 'updatedAt': '2021-01-23T01:27:11.969Z', 'createdAt': '2021-01-23T01:27:08.672Z'})
        ```
        
        
        ### Complete card charge flow
        
        ```py
        from rave_python import Rave, RaveExceptions, Misc
        rave = Rave("YOUR_PUBLIC_KEY", "YOUR_SECRET_KEY", usingEnv = False)
        
        # Payload with pin
        payload = {
          "cardno": "5438898014560229",
          "cvv": "890",
          "expirymonth": "09",
          "expiryyear": "19",
          "amount": "10",
          "email": "user@gmail.com",
          "phonenumber": "0902620185",
          "firstname": "temi",
          "lastname": "desola",
          "IP": "355426087298442",
        }
        
        try:
            res = rave.Card.charge(payload)
        
            if res["suggestedAuth"]:
                arg = Misc.getTypeOfArgsRequired(res["suggestedAuth"])
        
                if arg == "pin":
                    Misc.updatePayload(res["suggestedAuth"], payload, pin="3310")
                if arg == "address":
                    Misc.updatePayload(res["suggestedAuth"], payload, address= {"billingzip": "07205", "billingcity": "Hillside", "billingaddress": "470 Mundet PI", "billingstate": "NJ", "billingcountry": "US"})
                
                res = rave.Card.charge(payload)
        
            if res["validationRequired"]:
                rave.Card.validate(res["flwRef"], "")
        
            res = rave.Card.verify(res["txRef"])
            print(res["transactionComplete"])
        
        except RaveExceptions.CardChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        
        except RaveExceptions.TransactionValidationError as e:
            print(e.err)
            print(e.err["flwRef"])
        
        except RaveExceptions.TransactionVerificationError as e:
            print(e.err["errMsg"])
            print(e.err["txRef"])
        ```
        
        <br><br>
        ## ```rave.Account```
        This is used to facilitate account transactions. Transactions initiated via this method are authorized by the user on their Banking platform.
        
        **Functions included:**
        
        * ```.charge```
        * ```.verify```
        
        <br>
        
        ### ```.charge(payload)```
        This is called to start an account transaction. The payload should be a dictionary containing payment information. It should have the parameters:
        
        * ```amount``` (The min amount for NGN account payments is N200. For GBP and EUR payments, the min amount is 1), 
        * ```currency``` (This payment option supports NGN, GBP and EUR),  
        * ```email```, 
        * ```firstname```, 
        * ```lastname```, 
        * ```IP``` (optional)
        * ```redirectUrl``` (optional)
        
        Optionally, you can add a custom transaction reference using the ```txRef``` parameter. Note that if you do not specify one, it would be automatically generated. We do provide a function for generating transaction references in the [Misc library](https://github.com/Flutterwave/rave-python/blob/master/rave_python/rave_misc.py).
        
        
        A sample call is:
        
        ```py
        res = rave.Account.charge(payload)
        ```
        
        #### Returns
        
        This call returns a dictionary. A sample response is:
        
        ```py
        # sample response for NGN account payments
         {
           "validationRequired":True,
           "authUrl":"https://api.ravepay.co/flwv3-pug/getpaid/api/short-url/vHWOLuy89",
           "flwRef":"XINH44931689941420152189",
           "txRef":"MC-1689941418883",
           "error":False
        }
        ```
        
         This call raises an ```AccountChargeError``` if there was a problem processing your transaction. The ```AccountChargeError``` contains some information about your transaction. You can handle this as such:
        
        ```py
        try: 
            #Your charge call
        except RaveExceptions.AccountChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        ```
        
        A sample ``` e.err ``` contains:
        
        ```py
        {'error': True, 'txRef': 'MC-1530897824739', 'flwRef': None, 'errMsg': 'Sorry, that account number is invalid, please check and try again'}
        ```
        
        <br>
        
        ### ```.verify(txRef)```
        
        You can call this to check if your transaction was completed successfully. You have to pass the transaction reference generated at the point of charging. This is the ```txRef``` in the ```res``` parameter returned any the ```charge```call. 
        
        A sample verify call is:
        
        ```py
        res = rave.Account.verify(data["txRef"])
        ```
        
        #### Returns
        
        This call returns a dict with ```txRef```, ```flwRef``` and ```transactionComplete``` which indicates whether the transaction was completed successfully. 
        
        Sample
        
        ```py
        {
           "status":"success",
           "vbvcode":"57",
           "chargemessage":"Pending validation",
           "chargedamount":200,
           "vbvmessage":"transaction was abandoned",
           "error":True,
           "flwRef":"XINH44931689941420152189",
           "currency":"NGN",
           "amount":200,
           "meta":[
              {
                 "getpaidTransactionId":984928641,
                 "metavalue":"12383",
                 "metaname":"test",
                 "updatedAt":"2023-07-21T12:10:19.000Z",
                 "deletedAt":"None",
                 "id":2168360293,
                 "createdAt":"2023-07-21T12:10:19.000Z"
              }
           ],
           "transactionComplete":False,
           "acctmessage":None,
           "chargecode":"02",
           "txRef":"MC-1689941418883"
        }
        ```
        
        If your call could not be completed successfully or if a wrong ```txRef``` is passed, a ```TransactionVerificationError``` is raised. You can handle that as such
        ```py
        try: 
            #Your charge call
        except RaveExceptions.TransactionVerificationError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        ```
        
        ### ```.refund(flwRef, amount)```
        
        You can call this to refund a full or partial amount of a transaction that was completed successfully. You have to pass the flw reference generated at the point of verifing the transaction. This is the ```flwRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.Account.refund(data["flwRef"], amount)
        ```
        
        #### Returns
        
        This call returns a dict with ```status```, ```AmountRefunded```, ```disburse_ref``` and ```disburse_status``` which indicates whether the transaction was completed successfully. 
        
        Sample
        ```py
        (True, {'settlement_id': 'NEW', 'id': 36070, 'AccountId': 49278, 'TransactionId': 1664654, 'FlwRef': '9792859961', 'walletId': 71139, 'AmountRefunded': '1500', 'status': 'pending-momo', 'destination': 'mobilemoney', 'meta': '{"source":"ledgerbalance","disburse_ref":"CC-REFD-31101658361-9792859961","disburse_status":"pending"}', 'updatedAt': '2021-01-23T01:17:43.665Z', 'createdAt': '2021-01-23T01:17:38.327Z'})
        ```
        
        
        <br>
        
        ### Complete account flow
        
        ```py
        from rave_python import Rave, RaveExceptions, Misc
        rave = Rave("ENTER_YOUR_PUBLIC_KEY", "ENTER_YOUR_SECRET_KEY", usingEnv = False)
        # account payload
        payload = {
           "amount":2,
           "PBFPubKey":"ENTER_YOUR_PUBLIC_KEY",
           "currency":"GBP",
           "email":"user@example.com",
           "meta":[
              {
                 "metaname":"test",
                 "metavalue":"12383"
              }
           ],
           "ip":"123.0.1.3",
           "firstname":"Flutterwave",
           "lastname":"Tester"
        }
        
        try:
            res = rave.Account.charge(payload)
            if res["authUrl"]:
                print(res["authUrl"])
        
            elif res["validationRequired"]:
                rave.Account.validate(res["flwRef"], "12345")
        
            res = rave.Account.verify(res["txRef"])
            print(res)
        
        except RaveExceptions.AccountChargeError as e:
            print(e.err)
            print(e.err["flwRef"])
        
        except RaveExceptions.TransactionValidationError as e:
            print(e.err)
            print(e.err["flwRef"])
        
        except RaveExceptions.TransactionVerificationError as e:
            print(e.err["errMsg"])
            print(e.err["txRef"])
        ```
        <br><br>
        
        ## ```rave.GhMobile```
        This is used to facilitate Ghanaian mobile money transactions.
        
        **Functions included:**
        
        * ```.charge```
        
        * ```.verify```
        
        <br>
        
        ### ```.charge(payload)```
        This is called to start a Ghana mobile money transaction. The payload should be a dictionary containing payment information. It should have the parameters:
        
        * ```amount```,
        
        * ```email```, 
        
        * ```phonenumber```,
        
        * ```network```,
        
        * ```IP```,
        
        * ```redirect_url```
        
        Optionally, you can add a custom transaction reference using the ```txRef``` parameter. Note that if you do not specify one, it would be automatically generated. We do provide a function for generating transaction references in the [Misc library](https://github.com/Flutterwave/rave-python/blob/master/rave_python/rave_misc.py).
        
        
        A sample call is:
        
        ```py
        res = rave.GhMobile.charge(payload)
        ```
        
        #### Returns
        
        This call returns a dictionary. A sample response is:
        
        ```py
        {
            "status": "success",
            "message": "Momo initiated",
            "data": {
                "code": "02",
                "status": "pending",
                "ts": 1591798138846,
                "link": "https://ravemodal-dev.herokuapp.com/captcha/verify/123:49fa60c0db04f0017d717a0a662194cd"
            }
        }
        ```
        
        
        In order to complete the charge, kindly redirect users to the link returned as `data.link` from the charge response.
        
         This call raises a ```TransactionChargeError``` if there was a problem processing your transaction. The ```TransactionChargeError``` contains some information about your transaction. You can handle this as such:
        
        ```py
        try: 
            #Your charge call
        except RaveExceptions.TransactionChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        
        ```
        
        A sample ``` e.err ``` contains:
        
        ```py
        {'error': True, 'txRef': 'MC-1530911537060', 'flwRef': None, 'errMsg': None}
        ```
        
        
        <br>
        
        ### ```.verify(txRef)```
        
        You can call this to check if your transaction was completed successfully. You have to pass the transaction reference generated at the point of charging. This is the ```txRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.GhMobile.verify(data["txRef"])
        ```
        
        #### Returns
        
        This call returns a dict with ```txRef```, ```flwRef``` and ```transactionComplete``` which indicates whether the transaction was completed successfully. 
        
        If your call could not be completed successfully, a ```TransactionVerificationError``` is raised.
        
        ### ```.refund(flwRef, amount)```
        
        You can call this to refund a full or partial amount of a transaction that was completed successfully. You have to pass the flw reference generated at the point of verifing the transaction. This is the ```flwRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.GhMobile.refund(data["flwRef"], amount)
        ```
        
        #### Returns
        
        This call returns a dict with ```status```, ```AmountRefunded```, ```disburse_ref``` and ```disburse_status``` which indicates whether the transaction was completed successfully. 
        
        Sample
        ```py
        (True, {'settlement_id': 'NEW', 'id': 36070, 'AccountId': 49278, 'TransactionId': 1664654, 'FlwRef': '9792859961', 'walletId': 71139, 'AmountRefunded': '1500', 'status': 'pending-momo', 'destination': 'mobilemoney', 'meta': '{"source":"ledgerbalance","disburse_ref":"CC-REFD-31101658361-9792859961","disburse_status":"pending"}', 'updatedAt': '2021-01-23T01:17:43.665Z', 'createdAt': '2021-01-23T01:17:38.327Z'})
        ```
        
        <br>
        
        ### Complete GhMobile charge flow
        
        ```py
        from rave_python import Rave, RaveExceptions, Misc
        rave = Rave("ENTER_YOUR_PUBLIC_KEY", "ENTER_YOUR_SECRET_KEY", usingEnv = False)
        
        # mobile payload
        payload = {
          "amount": "50",
          "email": "cornelius@example.com",
          "phonenumber": "054709929220",
          "network": "MTN",
          "redirect_url": "https://rave-webhook.herokuapp.com/receivepayment",
          "IP":""
        }
        
        try:
          res = rave.GhMobile.charge(payload)
          res = rave.GhMobile.verify(res["txRef"])
          print(res)
        
        except RaveExceptions.TransactionChargeError as e:
          print(e.err)
          print(e.err["flwRef"])
        
        except RaveExceptions.TransactionVerificationError as e:
          print(e.err["errMsg"])
          print(e.err["txRef"])
        ```
        
        <br><br>
        
        ## ```rave.Mpesa```
        This is used to facilitate Mpesa transactions.
        
        **Functions included:**
        
        * ```.charge```
        
        
        * ```.verify```
        
        <br>
        
        ### ```.charge(payload)```
        This is called to start an Mpesa transaction. The payload should be a dictionary containing payment information. It should have the parameters:
        
        * ```amount```, 
        
        * ```email```, 
        
        * ```phonenumber```, 
        
        * ```IP```
        
        Optionally, you can add a custom transaction reference using the ```txRef``` parameter. Note that if you do not specify one, it would be automatically generated. We do provide a function for generating transaction references in the [Misc library](https://github.com/Flutterwave/rave-python/blob/master/rave_python/rave_misc.py).
        
        
        A sample call is:
        
        ```py
        res = rave.Mpesa.charge(payload)
        ```
        
        #### Returns
        
        This call returns a dictionary. A sample response is:
        
        ```py
        {'error': False, 'validationRequired': True, 'txRef': 'MC-1530910216380', 'flwRef': 'N/A'}
        ```
        
         This call raises a ```TransactionChargeError``` if there was a problem processing your transaction. The ```TransactionChargeError``` contains some information about your transaction. You can handle this as such:
        
        ```py
        try: 
            #Your charge call
        except RaveExceptions.TransactionChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        ```
        
        A sample ``` e.err ``` contains:
        
        ```py
        {'error': True, 'txRef': 'MC-1530910109929', 'flwRef': None, 'errMsg': 'email is required'}
        ```
        
        
        <br>
        
        ### ```.verify(txRef)```
        
        You can call this to check if your transaction was completed successfully. You have to pass the transaction reference generated at the point of charging. This is the ```txRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.Mpesa.verify(data["txRef"])
        ```
        
        #### Returns
        
        This call returns a dict with ```txRef```, ```flwRef``` and ```transactionComplete``` which indicates whether the transaction was completed successfully. 
        
        If your call could not be completed successfully, a ```TransactionVerificationError``` is raised.
        
        
        ### ```.refund(flwRef, amount)```
        
        You can call this to refund a full or partial amount of a transaction that was completed successfully. You have to pass the flw reference generated at the point of verifing the transaction. This is the ```flwRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.Mpesa.refund(data["flwRef"], amount)
        ```
        
        #### Returns
        
        This call returns a dict with ```status```, ```AmountRefunded```, ```disburse_ref``` and ```disburse_status``` which indicates whether the transaction was completed successfully. 
        
        Sample
        ```py
        (True, {'settlement_id': 'NEW', 'id': 36070, 'AccountId': 49278, 'TransactionId': 1664654, 'FlwRef': '9792859961', 'walletId': 71139, 'AmountRefunded': '1500', 'status': 'pending-momo', 'destination': 'mobilemoney', 'meta': '{"source":"ledgerbalance","disburse_ref":"CC-REFD-31101658361-9792859961","disburse_status":"pending"}', 'updatedAt': '2021-01-23T01:17:43.665Z', 'createdAt': '2021-01-23T01:17:38.327Z'})
        ```
        
        <br>
        
        ### Complete Mpesa charge flow
        
        ```py
        from rave_python import Rave, RaveExceptions, Misc
        rave = Rave("ENTER_YOUR_PUBLIC_KEY", "ENTER_YOUR_SECRET_KEY", usingEnv = False)
        
        # mobile payload
        payload = {
            "amount": "100",
            "phonenumber": "0926420185",
            "email": "user@exampe.com",
            "IP": "40.14.290",
            "narration": "funds payment",
        }
        
        try:
            res = rave.Mpesa.charge(payload)
            res = rave.Mpesa.verify(res["txRef"])
            print(res)
        
        except RaveExceptions.TransactionChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        
        except RaveExceptions.TransactionVerificationError as e:
            print(e.err["errMsg"])
            print(e.err["txRef"])
        ```
        
        <br><br>
        
        ## ```rave.UGMobile```
        This is used to facilitate Uganda mobile money transactions.
        
        **Functions included:**
        
        * ```.charge```
        
        
        * ```.verify```
        
        <br>
        
        ### ```.charge(payload)```
        This is called to start a Ugandan mobile money transaction. The payload should be a dictionary containing payment information. It should have the parameters:
        
        * ```amount```,
        
        * ```email```, 
        
        * ```phonenumber```,
        
        * ```IP```,
        
        * ```redirect_url```
        
        Optionally, you can add a custom transaction reference using the ```txRef``` parameter. Note that if you do not specify one, it would be automatically generated. We do provide a function for generating transaction references in the [Misc library](https://github.com/Flutterwave/rave-python/blob/master/rave_python/rave_misc.py).
        
        
        A sample call is:
        
        ```py
        res = rave.UGMobile.charge(payload)
        ```
        
        #### Returns
        
        This call returns a dictionary. A sample response is:
        
        ```py
        {
            "status": "success",
            "message": "Momo initiated",
            "data": {
                "code": "02",
                "status": "pending",
                "ts": 1591798138846,
                "link": "https://ravemodal-dev.herokuapp.com/captcha/verify/123:49fa60c0db04f0017d717a0a662194cd"
            }
        }
        ```
        
        
        In order to complete the charge, kindly redirect users to the link returned as `data.link` from the charge response.
        
         This call raises a ```TransactionChargeError``` if there was a problem processing your transaction. The ```TransactionChargeError``` contains some information about your transaction. You can handle this as such:
        
        ```py
        try: 
            #Your charge call
        except RaveExceptions.TransactionChargeError as e:
            print(e.err["errMsg"])
            print(e.err["flwRef"])
        ```
        
        A sample ``` e.err ``` contains:
        
        ```py
        {'error': True, 'txRef': 'MC-1530911537060', 'flwRef': None, 'errMsg': None}
        ```
        
        
        <br>
        
        ### ```.verify(txRef)```
        
        You can call this to check if your transaction was completed successfully. You have to pass the transaction reference generated at the point of charging. This is the ```txRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.UGMobile.verify(data["txRef"])
        ```
        
        #### Returns
        
        This call returns a dict with ```txRef```, ```flwRef``` and ```transactionComplete``` which indicates whether the transaction was completed successfully. 
        
        If your call could not be completed successfully, a ```TransactionVerificationError``` is raised.
        
        
        ### ```.refund(flwRef, amount)```
        
        You can call this to refund a full or partial amount of a transaction that was completed successfully. You have to pass the flw reference generated at the point of verifing the transaction. This is the ```flwRef``` in the ```res``` parameter returned any of the calls (```charge``` or ```validate```). 
        
        A sample verify call is:
        
        ```py
        res = rave.UGMobile.refund(data["flwRef"], amount)
        ```
        
        #### Returns
        
        This call returns a dict with ```status```, ```AmountRefunded```, ```disburse_ref``` and ```disburse_status``` which indicates whether the transaction was completed successfully. 
        
        Sample
        ```py
        (True, {'settlement_id': 'NEW', 'id': 36070, 'AccountId': 49278, 'TransactionId': 1664654, 'FlwRef': '9792859961', 'walletId': 71139, 'AmountRefunded': '1500', 'status': 'pending-momo', 'destination': 'mobilemoney', 'meta': '{"source":"ledgerbalance","disburse_ref":"CC-REFD-31101658361-9792859961","disburse_status":"pending"}', 'updatedAt': '2021-01-23T01:17:43.665Z', 'createdAt': '2021-01-23T01:17:38.327Z'})
        ```
        
        <br>
        
        ### Complete UGMobile charge flow
        
        ```py
        from rave_python import Rave, RaveExceptions, Misc
        rave = Rave("ENTER_YOUR_PUBLIC_KEY", "ENTER_YOUR_SECRET_KEY", usingEnv = False)
        
        # mobile payload
        payload = {
          "amount": "50",
          "email": "cornelius@example.com",
          "phonenumber": "123456789",
          "redirect_url": "https://rave-webhook.herokuapp.com/receivepayment",
          "IP":""
        }
        
        try:
          res = rave.UGMobile.charge(payload)
          res = rave.UGMobile.verify(res["txRef"])
          print(res)
        
        except RaveExceptions.TransactionChargeError as e:
          print(e.err)
          print(e.err["flwRef"])
        
        except RaveExceptions.TransactionVerificationError as e:
          print(e.err["errMsg"])
          print(e.err["txRef"])
        ```
        
        <br><br>
        
        ## ```rave.ZBMobile```
        This is used to facilitate Zambian mobile money transactions.
        
        **Functions included:**
        
        * ```.charge```
        
        
        * ```.verify```
        
        <br>
        
        ### ```.charge(payload)```
        This is called to start a Zambian mobile money transaction. The payload should be a dictionary containing payment information. It should have the parameters:
        
        * ```amount```,
        
        * ```email```, 
        
        * ```phonenumber```,
        
        * ```IP```,
        
        * ```redirect_url```
        
        Optionally, you can add a custom transaction reference using the ```txRef``` parameter. Note that if you do not specify one, it would be automatically generated. We do provide a function for generating transaction references in the [Misc library](https://github.com/Flutterwave/rave-python/blob/master/rave_python/rave_misc.py).
        
        
        A sample call is:
        
        ```py
        res = rave.ZBMobile.charge(payload)
        ```
        
        #### Returns
        
        This call returns a dictionary. A sample response is:
        
        ```py
        {
            "status": "success",
            "message": "Momo initiated",
            "data": {
                "code": "02",
                "status": "pending",
                "ts": 15917981