Metadata-Version: 2.1
Name: k2-connect
Version: 0.0.1
Summary: A python SDK to connect to Kopo Kopo API
Home-page: https://github.com/kopokopo/k2-connect-python
Author: Philip Wafula, David Mwangi
Author-email: philipwafula2@gmail.com, david.mwangi@kopokopo.com
License: MIT
Description: # k2-connect-python
        
        k2-connect is a Python library for accessing the Kopo Kopo APIs.
        
        ## Installation
        
        Use the package manager [pip](https://pip.pypa.io/en/stable/) to install k2connect.
        
        ```bash
        pip install k2connect
        ```
        
        ## Usage
        ### Initialization
        The library is initialized once then all services maybe accessed by creating different instances for specific services.
        The `BASE_URL` is a custom value and any url maybe passed provided it is secured and should only be accessible over TLS (HTTPS) and your server should have a valid certificate.
        Initialization requires the following arguments:
        * `base_url`
        * `client_id`
        * `client_secret`
        
        ```python
        import os
        import k2connect
        
        CLIENT_ID = 'my_client_id'
        CLIENT_SECRET = os.getenv('MY_CLIENT_SECRET')
        BASE_URL = 'https://Changed_from_localhost:3000/'
        
        #initialize the library
        k2connect.initialize(CLIENT_ID, CLIENT_SECRET, BASE_URL)
        ```
        
        ### k2connect services
        After initialization, k2connect services may be accessed by creating instances of a specific service. For instance:
        ```python
        # create an instance of the service 
        authenticator = k2connect.Tokens
        
        # access a method provided by the service
        authenticator.request_access_token()
        ```
        One can access the following k2connect services:
        - [TokensService](#token-service)
        - [PayService](#pay-service)
        - [ReceivePaymentsService](#receive-payments-service)
        - [TransferService](#transfers-service)
        - [WebhookService](#webhook-service)
        
        #### Token service
        The token service allows you to request access tokens that you will use in order to communicate with the Kopo Kopo APIs.
        The token service avails the option for you to implement token refresh mechanism by providing the duration within which
        the token will expire.
        
        The `get_access_token()` and `get_token_expiry_duration()` methods each take a response object from which they extract the
        token and expiry duration values.A request token and expiry duration time can be gotten as follows: 
        
        ```python
        # create an instance of the token service
        token_service = k2connect.Tokens
        
        # request the access token
        access_token_request = token_service.request_access_token()
        
        # get access token
        access_token = token_service.get_access_token(access_token_request)
        
        # get expiry duration
        token_expiry_duration = token_service.get_token_expiry_duration(access_token_request)
        ```
        
        #### Pay service
        The pay service enables you to add external entities (recipients) as destinations for payments made withe the pay service. 
        It also enables you to make payments and check for a payment's status.
        
        
        To add pay recipients the `add_pay_recipient()` method is used. The currently supported recipient types are `bank_account` and 
        `mobile_wallet` the method then takes a set of key worded arguments required to create a recipient of either type. The accepted 
        key worded arguments are as follows:
        
        Common for both types:
        * first_name `REQUIRED`
        * last_name `REQUIRED`
        * phone `REQUIRED`
        * email `REQUIRED`
        
        For `bank_account` recipient:  
        * account_name `REQUIRED`
        * account_number `REQUIRED`
        * bank_branch_id `REQUIRED`
        * bank_id `REQUIRED`
        
        
        For `mobile_wallet` recipient:
        * network `REQUIRED`
        
        To send payments the `send_pay()` method is used. It takes the following arguments:
        * bearer_token `REQUIRED`
        * callback_url `REQUIRED`
        * destination `REQUIRED`
        * value `REQUIRED`
        * currency='KES' `REQUIRED`
        
         
        Note: the currency argument is set to `KES` as the default currency since that is the only ISO currency currently supported. It may however, 
        be overridden by passing a different currency value in its place. If you do not wish to override the `KES` currency you can simply avoid 
        passing it as an argument.
        
        The pay service also enables you to check the status of a transaction by querying a URL that points to the transaction resource, using the 
        `pay_transaction_status()`.
        
        
         The Resource Location URL is returned by the either of the methods.
        
         ```python
        # create an instance of the pay service
        pay_service = k2connect.Pay
        
        # define recipient types
        BANK_ACCOUNT = 'bank_account'
        MOBILE_WALLET = 'mobile_wallet'
        
        # create bank account pay recipient
        bank_kwargs = {"first_name": "first_name", "last_name": "last_name", "account_name": "account_name",
                     "bank_id": "bank_id", "bank_branch_id": "bank_branch_id", "account_number": "account_number",
                     "email": "email", "phone": "phone"}
        bank_pay_location = pay_service.add_pay_recipient(bearer_token=BEARER_TOKEN,
                                                                  recipient_type=BANK_ACCOUNT,
                                                                  **bank_kwargs)
        
        # create mobile wallet pay recipient
        mobile_kwargs = {"first_name": "first_name", "last_name": "last_name",
                          "phone": "phone", "network": "network", "email": "email"}
        mobile_pay_location = pay_service.add_pay_recipient(bearer_token=BEARER_TOKEN,
                                                                    recipient_type=MOBILE_WALLET,
                                                                    **mobile_kwargs)
                                                                        
        # send pay transaction
        create_pay_location = pay_service.send_pay(bearer_token=BEARER_TOKEN,
                                                    callback_url='https://myawesomeapp.com/',
                                                    destination='7894571548',
                                                    value='2650'
                                                    # optional metadata values
                                                    )
        
        # get payment request status
        pay_request_status = pay_service.pay_transaction_status(create_pay_location)
        ```
        
        #### Receive payments service
        The receive payments service allows you to create requests for incoming payments over a specific channel and receive the payments 
        to your account. You can also check the status of your payment requests and access the payment request through a URL.
        
        
        In order to create a payment request, the `create_payment_request()` method is used. This method can be passed the following arguments:
        * bearer_token `REQUIRED`
        * callback_url `REQUIRED`
        * first_name `REQUIRED`
        * last_name `REQUIRED`
        * payment_channel `REQUIRED`
        * phone `REQUIRED`
        * till_number `REQUIRED`
        * value `REQUIRED`
        * currency='KES' `REQUIRED`
        
        Note: the currency argument is set to `KES` as the default currency since that is the only ISO currency currently supported. It may however, 
        be overridden by passing a different currency value in its place. If you do not wish to override the `KES` currency you can simply avoid 
        passing it as an argument.
        
        
        The method also creates the provision for optional `email` information to be passed in the key worded argument form, 
        for instance:
        
        `email='mycool@email.domain'`
        
        Furthermore, the `create_payment_request()` allows you to add metadata information passed in the form of a maximum of 5 key worded arguments.  
        The URL required for checking a payment request status is returned by default with the `create_payment_request` method.  
        
        ```python
        import os
        
        # get the access token
        BEARER_TOKEN = os.getenv('MY_BEARER_TOKEN')
        
        # create an instance of the receive payments service
        receive_payments_service = k2connect.ReceivePayments
        
        # create a payment request
        mpesa_payment_location = receive_payments_service.create_payment_request(bearer_token=BEARER_TOKEN,
                                                                                callback_url='https://my-cool-application-callback.com',
                                                                                first_name='Jon',
                                                                                last_name='Snow',
                                                                                payment_channel='MPESA',
                                                                                phone='+254712345678',
                                                                                till_number='111111',
                                                                                value='5000',
                                                                                # metadata values
                                                                                )
        
        # get payment request status
        payment_request_status = receive_payments_service.payment_request_status(mpesa_payment_location)
        ```
        
        #### Transfers service
        The transfer service enables you to create verified settlement mobile and bank accounts with respective `add_settlement_account()` methods. The method takes the following arguments:
        
        Common for both:
        * bearer_token `REQUIRED`
        
        For `add_bank_settlement_account`:  
        * account_name `REQUIRED`
        * account_number `REQUIRED`
        * bank_id `REQUIRED`
        * bank_branch_id `REQUIRED`
        
        For `add_mobile_wallet_settlement_account` recipient:  
        * msisdn `REQUIRED`
        * network: 'Safaricom' `REQUIRED`
        
        
        The transfer service enables you to transfer funds to these pre-approved settlement accounts. To settle funds the `settle_funds()` is used. It enables you to make two types of transfer
        transactions, a blind settlement and a targeted settlement. A blind transaction is made with the `destination` argument set to `None`, in the event that an ID for the destination of funds 
        is provided then a targeted transfer is made to that destination. The method takes the following arguments:
        
        * bearer_token `REQUIRED`
        * transfer_value `REQUIRED`
        * transfer_currency = 'KES' `REQUIRED`
        * destination_type `OPTIONAL`
        * destination_reference `OPTIONAL`  
        
        Note: the currency argument is set to `KES` as the default currency since that is the only ISO currency currently supported. It may however, 
        be overridden by passing a different currency value in its place. If you do not wish to override the `KES` currency you can simply avoid 
        passing it as an argument.
        
        
        You can check a transfer transaction's status by querying the transaction resource's location 
        URL which is returned by the `settle_funds` method by default.  
        The `transfer_transaction_status()` method is then used to check a transfer transaction status.
        
        ```python
        # initialize the transfer service
        transfer_service = k2connect.Transfers
        
        # create verified settlement bank account
        settlement_account = transfer_service.add_bank_settlement_account(bearer_token=BEARER_TOKEN,
                                                                     account_name='Jon Snow',
                                                                     account_number='4578124578556',
                                                                     bank_id='7814548785',
                                                                     bank_branch_id='87456874464')
        # create verified settlement mobile account
        settlement_account = transfer_service.add_mobile_wallet_settlement_account(bearer_token=BEARER_TOKEN,
                                                                     msisdn='254712345678',
                                                                     network='Safaricom')
        
        # settle funds (blind transfer)
        transfer_transaction = transfer_service.settle_funds(bearer_token=BEARER_TOKEN,
                                                             transfer_value='26000')
        # TODO blind transfer missing                                                     
        # settle funds (targeted transfer to a merchant_wallet)
        transfer_transaction_mobile_location = transfer_service.settle_funds(bearer_token=BEARER_TOKEN, 
                                                               destination_type='merchant_wallet',
                                                               destination_reference='457126554788',
                                                               transfer_value='26000')
        # settle funds (targeted transfer to a merchant_wallet)
        transfer_transaction_bank_location = transfer_service.settle_funds(bearer_token=BEARER_TOKEN, 
                                                               destination_type='merchant_bank_account',
                                                               destination_reference='457126554788',
                                                               transfer_value='26000')
        
        # get transfer transaction status
        transfer_transaction_status = transfer_service.transfer_transaction_status(transfer_transaction_mobile_location or transfer_transaction_bank_location)
        ```
        
        ##### The destination_reference number corresponding to a settlement account must exist before you can settle_funds to it. 
        
        #### Webhook service
        The webhook service allows you to create subscriptions to events that occur on the KopoKopo application. The `create_subscription()` method is used, 
        it takes the following arguments:
        
        * bearer_token `REQUIRED`
        * event_type `REQUIRED`
        * webhook_endpoint `REQUIRED`
        * client_secret `REQUIRED`
        
        
        Currently the following events are supported:
        * b2b_transaction_received
        * buygoods_transaction_received
        * buygoods_transaction_reversed
        * m2m_transaction_received
        * settlement_transfer_completed
        * customer_created
        
        ```python
        import os
        
        # initialize webhook service
        webhook_service = k2connect.Webhooks
        
        # define a webhook secret
        WEBHOOK_SECRET = os.getenv('MY_CLIENT_SECRET')
        
        # create webhook subscription
        customer_created_subscription = webhook_service.create_subscription(bearer_token=BEARER_TOKEN,
                                                                            event_type='customer_created',
                                                                            webhook_endpoint='https://myawesomeapplication.com/webhooks/customer_created',
                                                                            webhook_secret=WEBHOOK_SECRET)
        ```
        
        #### Result processor 
        Results (inclusive of webhook results and results posted to callback URLs asynchronously) sent from KopoKopo have to be processed before payloads can 
        be accessed. The result processor can be used to accomplish this using the `process()` method.
        
        ```python
        # initialize result handler
        result_handler = k2connect.ResultHandler
        
        # process result 
        processed_payload = result_handler.process(some_result)
        ```
        
        #### Payload decomposer
        Once a result is processed an a payload has been returned, it can be decomposed into its constituent result data using the payload decomposer.
        The payload decomposer achieves this using the `decompose()` method.
        
        ```python
        from k2connect import payload_decomposer
        
        # decompose a payload
        decomposer = payload_decomposer.decompose(processed_payload)
        
        # get first name
        first_name = decomposer.first_name
        ```
        
        ### Author
        This library was written by [PhilipWafula](https://github.com/PhilipWafula) and [David Kariuki Mwangi](https://github.com/DavidJonKariz).
        
        ### Contributing
        Bug reports and pull requests are welcome. Feel free raise issues on our [issues tracker](https://github.com/kopokopo/k2-connect-python/issues)
        
        ### License
        k2connect-python is [MIT](https://github.com/kopokopo/k2-connect-python/blob/master/LICENSE) Licensed.
        
        ### Changelog
        
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3
Description-Content-Type: text/markdown
