api package

Submodules

api.auth module

class api.auth.MpesaBase(env='sandbox', app_key=None, app_secret=None, sandbox_url='https://sandbox.safaricom.co.ke', live_url='https://api.safaricom.co.ke')[source]

Bases: object

authenticate()[source]

To make Mpesa API calls, you will need to authenticate your app. This method is used to fetch the access token required by Mpesa. Mpesa supports client_credentials grant type. To authorize your API calls to Mpesa, you will need a Basic Auth over HTTPS authorization token. The Basic Auth string is a base64 encoded string of your app’s client key and client secret.

Args:

  • env (str): Current app environment. Options: sandbox, live.

  • app_key (str): The app key obtained from the developer portal.

  • app_secret (str): The app key obtained from the developer portal.

  • sandbox_url (str): Base Safaricom sandbox url.

  • live_url (str): Base Safaricom live url.

Returns:

  • access_token (str): This token is to be used with the Bearer header for further API calls to Mpesa.

api.b2b module

class api.b2b.B2B(env='sandbox', app_key=None, app_secret=None, sandbox_url='https://sandbox.safaricom.co.ke', live_url='https://api.safaricom.co.ke')[source]

Bases: api.auth.MpesaBase

transact(initiator=None, security_credential=None, command_id=None, sender_identifier_type=None, receiver_identifier_type=None, amount=None, party_a=None, party_b=None, remarks=None, account_reference=None, queue_timeout_url=None, result_url=None)[source]

This method uses Mpesa’s B2B API to transact from one company to another.

Args:

  • initiator (str): Username used to authenticate the transaction.

  • security_credential (str): Generate from developer portal

  • command_id (str): Options: BusinessPayBill, BusinessBuyGoods, DisburseFundsToBusiness, BusinessToBusinessTransfer ,BusinessTransferFromMMFToUtility, BusinessTransferFromUtilityToMMF, MerchantToMerchantTransfer, MerchantTransferFromMerchantToWorking, MerchantServicesMMFAccountTransfer, AgencyFloatAdvance

  • sender_identifier_type (str): 2 for Till Number, 4 for organization shortcode

  • receiver_identifier_type (str): # 2 for Till Number, 4 for organization shortcode

  • amount (str): Amount.

  • party_a (int): Sender shortcode.

  • party_b (int): Receiver shortcode.

  • remarks (str): Comments that are sent along with the transaction(maximum 100 characters).

  • account_reference (str): Use if doing paybill to banks etc.

  • queue_timeout_url (str): The url that handles information of timed out transactions.

  • result_url (str): The url that receives results from M-Pesa api call.

Returns:

  • OriginatorConverstionID (str): The unique request ID for tracking a transaction.

  • ConversationID (str): The unique request ID returned by mpesa for each request made

  • ResponseDescription (str): Response Description message

api.b2c module

class api.b2c.B2C(env='sandbox', app_key=None, app_secret=None, sandbox_url='https://sandbox.safaricom.co.ke', live_url='https://api.safaricom.co.ke')[source]

Bases: api.auth.MpesaBase

transact(initiator_name=None, security_credential=None, command_id=None, amount=None, party_a=None, party_b=None, remarks=None, queue_timeout_url=None, result_url=None, occassion=None)[source]

This method uses Mpesa’s B2C API to transact between an M-Pesa short code to a phone number registered on M-Pesa..

Args:

  • initiator_name (str): Username used to authenticate the transaction.

  • security_credential (str): Generate from developer portal

  • command_id (str): Options: SalaryPayment, BusinessPayment, PromotionPayment

  • `amount`(str): Amount.

  • party_a (int): Organization/MSISDN making the transaction - Shortcode (6 digits) - MSISDN (12 digits).

  • party_b (int): MSISDN receiving the transaction (12 digits).

  • remarks (str): Comments that are sent along with the transaction(maximum 100 characters).

  • account_reference (str): Use if doing paybill to banks etc.

  • queue_timeout_url (str): The url that handles information of timed out transactions.

  • result_url (str): The url that receives results from M-Pesa api call.

  • ocassion (str):

Returns:

  • OriginatorConverstionID (str): The unique request ID for tracking a transaction.

  • ConversationID (str): The unique request ID returned by mpesa for each request made

  • ResponseDescription (str): Response Description message

api.balance module

class api.balance.Balance(env='sandbox', app_key=None, app_secret=None, sandbox_url='https://sandbox.safaricom.co.ke', live_url='https://api.safaricom.co.ke')[source]

Bases: api.auth.MpesaBase

get_balance(initiator=None, security_credential=None, command_id=None, party_a=None, identifier_type=None, remarks=None, queue_timeout_url=None, result_url=None)[source]

This method uses Mpesa’s Account Balance API to to enquire the balance on an M-Pesa BuyGoods (Till Number).

Args:

  • initiator (str): Username used to authenticate the transaction.

  • security_credential (str): Generate from developer portal.

  • command_id (str): AccountBalance.

  • party_a (int): Till number being queried.

  • identifier_type (int): Type of organization receiving the transaction. Options: 1 - MSISDN 2 - Till Number 4 - Organization short code

  • remarks (str): Comments that are sent along with the transaction(maximum 100 characters).

  • queue_timeout_url (str): The url that handles information of timed out transactions.

  • result_url (str): The url that receives results from M-Pesa api call.

Returns:

  • OriginatorConverstionID (str): The unique request ID for tracking a transaction.

  • ConversationID (str): The unique request ID returned by mpesa for each request made

  • ResponseDescription (str): Response Description message

api.c2b module

class api.c2b.C2B(env='sandbox', app_key=None, app_secret=None, sandbox_url='https://sandbox.safaricom.co.ke', live_url='https://api.safaricom.co.ke')[source]

Bases: api.auth.MpesaBase

register(shortcode=None, response_type=None, confirmation_url=None, validation_url=None)[source]

This method uses Mpesa’s C2B API to register validation and confirmation URLs on M-Pesa.

Args:

  • shortcode (int): The short code of the organization.

  • response_type (str): Default response type for timeout. Incase a tranaction times out, Mpesa will by default Complete or Cancel the transaction.

  • confirmation_url (str): Confirmation URL for the client.

  • validation_url (str): Validation URL for the client.

Returns:

  • OriginatorConversationID (str): The unique request ID for tracking a transaction.

  • ConversationID (str): The unique request ID returned by mpesa for each request made

  • ResponseDescription (str): Response Description message

simulate(shortcode=None, command_id=None, amount=None, msisdn=None, bill_ref_number=None)[source]

This method uses Mpesa’s C2B API to simulate a C2B transaction.

Args:

  • shortcode (int): The short code of the organization.

  • command_id (str): Unique command for each transaction type. - CustomerPayBillOnline - CustomerBuyGoodsOnline.

  • amount (int): The amount being transacted

  • msisdn (int): Phone number (msisdn) initiating the transaction MSISDN(12 digits)

  • bill_ref_number: Optional

Returns:

  • OriginatorConverstionID (str): The unique request ID for tracking a transaction.

  • ConversationID (str): The unique request ID returned by mpesa for each request made

  • ResponseDescription (str): Response Description message

api.mpesa_express module

class api.mpesa_express.MpesaExpress(env='sandbox', app_key=None, app_secret=None, sandbox_url='https://sandbox.safaricom.co.ke', live_url='https://api.safaricom.co.ke')[source]

Bases: api.auth.MpesaBase

query(business_shortcode=None, checkout_request_id=None, passcode=None)[source]

This method uses Mpesa’s Express API to check the status of a Lipa Na M-Pesa Online Payment..

Args:

  • business_shortcode (int): This is organizations shortcode (Paybill or Buygoods - A 5 to 6 digit account number) used to identify an organization and receive the transaction.

  • checkout_request_id (str): This is a global unique identifier of the processed checkout transaction request.

  • passcode (str): Get from developer portal

Returns:

  • CustomerMessage (str):

  • CheckoutRequestID (str):

  • ResponseDescription (str):

  • MerchantRequestID (str):

  • ResponseCode (str):

stk_push(business_shortcode=None, passcode=None, amount=None, callback_url=None, reference_code=None, phone_number=None, description=None)[source]

This method uses Mpesa’s Express API to initiate online payment on behalf of a customer..

Args:

  • business_shortcode (int): The short code of the organization.

  • passcode (str): Get from developer portal

  • amount (int): The amount being transacted

  • callback_url (str): A CallBack URL is a valid secure URL that is used to receive notifications from M-Pesa API.

  • reference_code: Account Reference: This is an Alpha-Numeric parameter that is defined by your system as an Identifier of the transaction for CustomerPayBillOnline transaction type.

  • phone_number: The Mobile Number to receive the STK Pin Prompt.

  • description: This is any additional information/comment that can be sent along with the request from your system. MAX 13 characters

Returns:

  • CustomerMessage (str):

  • CheckoutRequestID (str):

  • ResponseDescription (str):

  • MerchantRequestID (str):

  • ResponseCode (str):

api.reversal module

class api.reversal.Reversal(env='sandbox', app_key=None, app_secret=None, sandbox_url='https://sandbox.safaricom.co.ke', live_url='https://api.safaricom.co.ke')[source]

Bases: api.auth.MpesaBase

reverse(initiator=None, security_credential=None, command_id='TransactionReversal', transaction_id=None, amount=None, receiver_party=None, receiver_identifier_type=None, queue_timeout_url=None, result_url=None, remarks=None, occassion=None)[source]

This method uses Mpesa’s Transaction Reversal API to reverse a M-Pesa transaction.

Args:

  • initiator (str): Username used to authenticate the transaction.

  • security_credential (str): Generate from developer portal

  • command_id (str): TransactionReversal

  • transaction_id (str): Unique identifier to identify a transaction on M-Pesa.

  • amount (int): The amount being transacted

  • receiver_party (int): Organization/MSISDN making the transaction - Shortcode (6 digits) - MSISDN (12 digits).

  • receiver_identifier_type (int): MSISDN receiving the transaction (12 digits).

  • queue_timeout_url (str): The url that handles information of timed out transactions.

  • result_url (str): The url that receives results from M-Pesa api call.

  • remarks (str): Comments that are sent along with the transaction(maximum 100 characters)

  • occassion (str):

Returns:

  • OriginatorConverstionID (str): The unique request ID for tracking a transaction.

  • ConversationID (str): The unique request ID returned by mpesa for each request made

  • ResponseDescription (str): Response Description message

api.transaction_status module

class api.transaction_status.TransactionStatus(env='sandbox', app_key=None, app_secret=None, sandbox_url='https://sandbox.safaricom.co.ke', live_url='https://api.safaricom.co.ke')[source]

Bases: api.auth.MpesaBase

check_transaction_status(party_a=None, identifier_type=None, remarks=None, initiator=None, passcode=None, result_url=None, queue_timeout_url=None, transaction_id=None, occassion=None, shortcode=None)[source]

This method uses Mpesa’s Transaction Status API to check the status of a transaction.

Args:

  • party_a (str): Organization/MSISDN receiving the transaction - MSISDN or shortcode.

  • identifier_type (str): Type of organization receiving the transaction 1-MSISDN. 2-Till Number, 3-Shortcode.

  • remarks (str): Comments that are sent along with the transaction(maximum 100 characters).

  • initiator (str): This is the credential/username used to authenticate the transaction request.

  • passcode (str): Get from developer portal

  • result_url (str): The url that handles information from the mpesa API call.

  • transaction_id (str): Unique identifier to identify a transaction on M-Pesa.

  • queue_timeout_url (str): The url that stores information of timed out transactions.

  • result_url (str): The url that receives results from M-Pesa api call.

  • shortcode (int): The short code of the organization.

  • occassion (str):

Returns:

  • ResultDesc: ,

  • CheckoutRequestID: ,

  • ResponseDescription: ,

  • MerchantRequestID: ,

  • ResponseCode: ,

  • ResultCode:

Module contents