Package: pesapy
pesapy version 1.0.0pesapy is an unofficial M-Pesa API wrapper. Its saves you all the hardwork and painthat most developers go through when intergrating theSafaricom M-PesaAPI into
their systems.This library does all the hardwork for you and exposes a simple interface that easy to use andmakes your code clean and maintainable.M-Pesa is Africa's largest mobile money platform with more than 40 million usersin seven African countries where it operates, Hence the need to understand its APIs.Covers the following transactions types:Mpesa Express/lipa na mpesa online/STK PushReversalsB2C(Business To Customer)B2B(Business To Business)C2B(Customer To Business)Transaction statusAccount BalanceGetting Started with mpesa_pyInstallationInstall mpesa_py with pippipinstallmpesa_pyNavigate to the root folder of your project and create a .env file that will
hold all the environment variables required by mpesa_py.For  example on a linux
system:cd/path_to_root_folder/touch.envDont forget the dot (.) before env when creating the .env fileUsing your favorite editor open  the .env file and paste and fill in the following requiredenvironment variablesBASE_URL=https://api.safaricom.co.keCONSUMER_KEY=CONSUMER_SECRET=LIPA_NA_MPESA_PASSKEY=MPESA_EXPRESS_CALLBACK_URL=MPESA_EXPRESS_BUSINESS_SHORTCODE=C2B_RESPONSE_TYPE=CompletedC2B_SHORTCODE=600981B2C_INITIATOR_PASSWORD=B2C_INITIATOR_NAME=B2C_SHORTCODE=B2C_QUEUE_TIMEOUT_URL=B2C_RESULT_URL=B2B_INITIATOR_PASSWORD=B2B_INITIATOR_NAMEB2B_SHORTCODE=B2B_QUEUE_TIMEOUT_URL=B2B_RESULT_URL=B2B_SENDER_TYPE=REVERSAL_INITIATOR_NAME=REVERSAL_INITIATOR_PASSWD=REVERSAL_RECEIVER_PARTY=REVERSAL_RECEIVER_IDENTIFIER_TYPE=REVERSAL_RESULT_URL=REVERSAL_QUEUE_TIMEOUT_URLTRANS_STATUS_INITIATOR_NAME=TRANS_STATUS_INITIATOR_PASSWD=TRANS_STATUS_BUSINESS_SHORTCODE=TRANS_STATUS_IDENTIFIER_TYPE=TRANS_STATUS_RESULT_URL=TRANS_STATUS_QUEUE_TIMEOUT_URL=ACC_BAL_INITIATOR_NAME=ACC_BAL_INITIATOR_PASSWD=ACC_BAL_RESULT_URL=ACC_BAL_QUEUE_TIMEOUT_URL=PUBKEY_PATH=Environment variables ExplanationBASE_URL--- Is the main URL for Safaricom M-Pesa API.production:https://api.safaricom.co.ke\development:https://sandbox.safaricom.co.keCONSUMER_KEY and CONSUMER_SECRET---Is your application's consumer key and secret respectively.They are provided by safaricom in the developers portalhttps://developer.safaricom.co.ke/MyApps.Used to generate access token.MPESA_EXPRESS_API_ENDPOINT--- Is Safaricom API endpoint for mpesa express transactions.MPESA_EXPRESS_CALLBACK_URL--- A CallBack URL is a valid secure URL that is used to receive notifications from M-Pesa API.It is the endpoint to which the results will be sent by M-Pesa API.MPESA_EXPRESS_BUSINESS_SHORTCODE--- This is organizations shortcode (Paybill or Buygoods - A 5 to 7 digit account number).Used to identify an organization and receive the transaction.LIPA_NA_MPESA_PASSKEY--- Used to generate the request password in combination with the business shortcodeC2B_REGISTRATION_API_ENDPOINT--- M-pesa api endpoint for customer to business transactions.It is used to register both the confirmatation and validation URLs.C2B_RESPONSE_TYPE- This parameter specifies what is to happen if for any reason the validation URL is nor reachable.Note that, This is the default action value that determines what MPesa will do in the scenario that your endpoint isunreachable or is unable to respond on time.Only two values are allowed: Completed or Cancelled.Completed means MPesa will automatically complete your transaction,whereas Cancelled means MPesa will automatically cancel the transaction, in the event MPesa is unable toreach your Validation URL.C2B_SHORTCODE--- Is the shortcode of the organization. eg 600981B2C_INITIATOR_NAME--- The username of the M-Pesa Business to Customer(B2C) account API operator.NOTE: the access channel for this operator must be API and the account must be in active status.B2C_INITIATOR_PASSWORD--- Used in combination with the public key certificate
to produce the security credentials.B2C_SHORTCODE--- This is the B2C organization shortcode from which the money is to be sent.B2C_QUEUE_TIMEOUT_URL--- This is the URL to be specified in your request that will be used by API Proxy to send notificationincase the payment request is timed out while awaiting processing in the queue.B2C_RESULT_URL--- This is the URL to be specified in your request that will be used by M-Pesa to send notification upon processing of the payment requestB2B_INITIATOR_PASSWORD---The password for M-Pesa B2B account API operatorB2B_INITIATOR_NAME--- The username for M-Pesa B2B account API operatorB2B_SHORTCODE--- This is the B2B organization shortcode from which the money is to be sentB2B_SENDER_TYPE---  Type of organization sending the transaction1 – MSISDN, 2 – Till Number, 4 – Organization short codeB2B_RESULT_URL--- The path that stores information of transaction after it has beenprocessed by M-PesaB2B_QUEUE_TIMEOUT_URL---The path that stores information of time out transactionREVERSAL_INITIATOR_NAME---The username for M-Pesa reversal account API operatorREVERSAL_INITIATOR_PASSWD---The password for M-Pesa reversal account API operatorREVERSAL_RECEIVER_PARTY---Shortcode for the organization initiating the reversalREVERSAL_RECEIVER_IDENTIFIER_TYPE---Type of organization receiving the transaction. Always set to 11.TRANS_STATUS_IDENTIFIER_TYPE---Type of organization sending the transaction
1 – MSISDN, 2 – Till Number, 4 – Organization short codePUBKEY_PATH-- Theabsolutepath to the file containing your public key certificate. A pem file.This must be downloaded from the daraja api portal:
sandboxlink,productionlinkUsage/Examplesmpesa_py library contains the following classes each with its own process_transaction
method that processes the transaction.C2BB2CB2BTransStatusReversalSTK push/Mpesa Express/lipa na mpesa onlineIt is used to send a  payment prompt on the customers phone (Popularly known as STK Push Prompt)to your customer's M-PESA registered phone number requesting them to enter their M-PESA pin toauthorize and complete a payment.The process_transaction method of MpesaExpress class takes the following key word arguments.amount--- Money that customer pays to the Shorcode. Only whole numbers are supported.customer_phone_no---The phone number sending money. The parameter expected is a Valid Safaricom Mobile Number that is M-Pesa registered.Must have the following format 2547XXXXXXXXshort_code---The organization receiving the funds. The parameter expected is a 5 to 7 Shortcode.This can be the same as BusinessShortCode value.account_reference--- Account Reference: This is an Alpha-Numeric parameter that is defined by your system as an Identifierof the transaction for CustomerPayBillOnline transaction type.Along with the business name, this value is also displayed to the customer in the STK Pin Prompt message. Maximum of 12 characterstransaction_desc--- This is any additional information/comment that can be sent along with the request from your system.Maximum of 13 CharactersUsing mpesa_py in interactive python mode(stk push)>>>frommpesa_py.mpesa_expressimportMpesaExpress>>>MpesaExpress.process_transaction(amount="1",phone_number="254741937028",account_reference="test_api",transaction_desc="pay school fees")>>>>ExampleThe return value of the method MpesaExpress.process_transaction is a json string of the
following format on success{'MerchantRequestID':'117890-42812180-1','CheckoutRequestID':'ws_CO_021020211021428942','ResponseCode':'0','ResponseDescription':'Success.Requestacceptedforprocessing','CustomerMessage':'Success.Requestacceptedforprocessing'}sample Python script.frommpesa_py.mpesa_expressimportMpesaExpressresp=MpesaExpress.process_transaction(amount="1",phone_number="254741937028",account_reference="test_api",transaction_desc="pay school fees")print(resp)B2C (Business to customer transaction)B2C API is an API used to make payments from a Business to Customers (Pay Outs).Also known as Bulk DisbursementsB2C API is used in several scenarios by businesses that require to either make Salary Payments,Cashback payments, Promotional Payments(e.g. betting winning payouts), winnings,financial institutions withdrawal of funds, loan disbursements etc.The process_transaction method of B2C class takes the following key word arguments.command_id-- This is a unique command that specifies B2C transaction typeSample values include SalaryPayment, BusinessPayment, PromotionPaymentamount-- The amount of money being sent to the customer.phone_number-- This is the customer mobile number  to receive the amount.Must have the following format 2547XXXXXXXXremarks-- Any additional information to be associated with the transactionoccasion-- Any other additional information to be associated with the transaction.Using mpesa_py in interactive python mode(b2c transaction)>>>frommpesa_pyimportB2C>>>B2C.process_transaction(command_id="BusinessPayment",amount=1000,phone_number="254708374149",remarks="Requested on Tuesday",occassion="issue closed")>>>Examplesample python script.You can save the same transaction in a python script and run the script.frommpesa_py.b2cimportB2Cresp=B2C.process_transaction(command_id="BusinessPayment",amount=1000,phone_number="254708374149",remarks="Requested on Tuesday",occassion="issue closed")print(resp)C2B (Customer to Business transaction)Enables Payments from Client to Business. A customer initiates a payment request to your Pay Bill or Buy Goods (Till Number)from their phone. Using the Safaricom app or from M-PESA menu in the Sim Tool Kit.The process_transaction  method of the C2B class registers your validation URL andconfirmation url. it takes the following key word arguments.confirmation_url--	This is the URL that receives the confirmation request from API upon payment completion.validation_url-- This is the URL that receives the validation request from API upon payment submission.The validation URL is only called if the external validation on the registered shortcode is enabled. (By default External Validation is dissabled)\Once you have successfully registered your URL's a confirmation request will be sent toyour confirmation_url whenever a client completes a transaction.Using mpesa_py in interactive python mode(C2B transaction)>>>frommpesa_py.c2bimportC2B>>>C2B.process_transaction(confirmation_url="https://secure-headland-36393.herokuapp.com/api/payments/c2b-confirmation/",validation_url="https://secure-headland-36393.herokuapp.com/api/payments/c2b-validation/",)>>>Examplesample  python script.frommpesa_py.c2bimportC2Bresponse=C2B.process_transaction(confirmation_url="https://secure-headland-36393.herokuapp.com/api/payments/c2b-confirmation/",validation_url="https://secure-headland-36393.herokuapp.com/api/payments/c2b-validation/",)print(response)You can use the simulate method of C2B class to simulate a situation where a customerpays to a paybill from their phone.frommpesa_py.c2bimportC2B>>>resp=C2B.simulate(amount=350,customer_phone_no=254708374149,short_code=600981)>>>print(resp)ExampleB2B (Business to Business transaction)The Business to Business (B2B) API is used to transfer money from one business to another business.This API enables the business to pay other businesses.The transaction flow is the same as the B2C API transaction flow, but this time the Credit Party is another Business/Company/Organization.It requires the same credentials and information as the B2C API.For the API to work, the 2 organizations will need to have the B2B product assigned to them, otherwise the transaction request will fail.The process_transaction method of B2B class takes the following key word arguments.command_id* --- Takes the following values only.BusinessPayBill: This is a transfer of funds from one Organization's Working Account to another Organization's Utility AccountBusinessBuyGoods: A transfer of funds from one Organization's Working Account to another Organization's Merchant AccountDisburseFundsToBusiness: A transfer of funds from one Organization's Utility Account to another Organization's Working Account.BusinessToBusinessTransfer: A transfer of funds from one Organization's Working Account to another Organization's Working Account.MerchantToMerchantTransfer: A transfer of funds from one Organization's Merchant Account to another Organization's Merchant Accountamount--- Is the actual transaction amount.credit_party--- Shortcode for the organization receiving the funds.b2b_receiver_type--- Type of organization receving the transaction\remarks--- Remarks about the transaction.ocassion---Additional information for the transaction. Optional.EXAMPLE>>>frommpesa_py.b2bimportB2B>>>resp=B2B.process_transaction(command_id="BusinessPayBill",amount=1900,credit_party=600977,b2b_receiver_type=4,remarks="Requested on Tuesday",ocassion="issue closed",account_reference="test_api")>>>print(resp)ReversalReverses a B2B, B2C or C2B M-Pesa transaction.The process_transaction method of this class reverses the transaction.It takes the following key word arguments.transaction_id-- Is the actual transaction id of the transaction you want toreverse.amount-- The amount transacted in the transaction to be reversed , down to the centremarks-- Comments that are sent along with the transaction.occasion-- Optional Parameter that contains additional information for the transactionUsing mpesa_py in interactive python mode(C2B transaction)>>>frommpesa_py.reversalimportReversal>>>response=Reversal.process_transaction(transaction_id="PIN51HK4SZ",amount=900,remarks="Double repayment",additional_info="first time customer")>>>print(response)ExampleTransaction StatusChecks the status of a transaction.The process_transaction method of this class takes the following key word arguments.transaction_id-- Is the actual transaction id.remarks-- Comments that are sent along with the transactionOccasion-- Any Additional information. OptionalThe result of this transaction will be sent to your rans_status_result_url defined in yourenvironment variables file.>>>frommpesa_py.trans_statusimportTransStatus>>>resp=TransStatus.process_transaction(transaction_id="PIR81HK5N2",remarks="Double repayment",Occasion="First time customer")>>>print(resp)ExampleNOTE: To check the status of an STK push sent to the customer.You can use the trans_status method of MpesaExpress class.The method takes a single argument ie checkout_request_id that is always sent backas a response from the STK/M-Pesa express transaction. This is used to query whetherthe customer did actually complete the STK push sent to their phone number.>>>frommpesa_py.mpesa_expressimportMpesaExpress>>>resp=MpesaExpress.trans_status(checkout_request_id="ws_CO_270920212251236524")>>>print(resp)ExampleThe above STK push was cancelled by the user as seen from the ResultDesc propertyof the response.Account BalanceChecks the account balance of M-Pesa BuyGoods (Till Number)The process transaction method of this class takes the followng keyword argumentsaccount_bal_party-- Type of organization receiving the transaction eg 600981 for abusiness shortcodeacc_bal_identifier_type--- Identifies the type of organization.1 – MSISDN, 2 – Till Number, 4 – Organization short coderemarks-- Comments that are sent along with the transaction>>>frommpesa_py.account_balanceimportAccountBalance>>>resp=AccountBalance.process_transaction(account_bal_party=600981,remarks="testing remarks",acc_bal_identifier_type=4)>>>print(resp)ExampleLICENCEpesapy  is open-sourced software licensed under theMIT licenceCONTRIBUTINGContributions are always welcome!Seecontributing.mdfor ways to get started.Please adhere to this project'scode of conduct.AUTHORSDavid Mutune - Full stack Software engineerinstagram-----github-----twitter