# Mpesa Welcome to [mpesa](https://developer.safaricom.co.ke/) API gem. The gem defines the API resources and helps developers to make requests cleanly. When you receive a JSON response from an API endpoint, it's really easy to convert this to a Ruby hash. But hashes don't feel very Ruby-ish when you're working with them. To help on this gem parse the responses to `OpenStruct` Objects so a developer can interact with the response just like regular ruby objects we are used to. This Gem provides an interface that developers can use to convert JSON to `OpenStruct` objects, this is useful when you want to parse results callbacks data. ## Installation Install via `Gemfile` ``` gem 'mpesarb', '~> 0.3.2' ``` Or ``` bundle add mpesarb ``` ## Usage ### Initialization ```ruby client = Mpesa::Client.new(key: 'ZtkRW6ATbVtFpNml5w5SfG26Adfyagn9', secret: 'dosFI1yQ8bvHEVFw', env: 'sandbox') response = client.auth response.access_token # XiKf3D6UrY0J8S2aeOQ7R7w0BuA5 response.expires_in # 3599 ``` __Parameters__ Required - `key` - API consumer key - Required - `secret` - API consumer secret - Required Optional - `env` - API environment. Default `production` - `adapter` - Faraday HTTP adapter. Default `:net_http` - `shortcode` - Mpesa shortcode - `pass_key` - LPNMO pass Key( used by STK API) - `raise_errors` - `Boolean` raise errors if response status code is not 200. Default: `true` ### Register Urls Register C2B Urls( confirmation and validation url) ```ruby response = client.register( shortcode: "44445", confirmation_url: 'http://example.com/confirm', validation_url: 'http://example.com/validate' ) response.OriginatorCoversationID # "807-15591582-1" response.ResponseCode # "0" response.ResponseDescription # "success" ``` ### STK (LPNMO) Lipa na mpesa online(Stk Push) ```ruby response = client.stk( shortcode: "174379", pass_key: "bfb279f9aa9bdbcf158e97dd71a467cd2e0c893059b10f78e6b72ada1ed2c919", # Optional if passed in client initialization amount: "10", phone: "254705112855", callback_url: "https://test.com", reference: "REF", trans_desc: "desc" ) response.CheckoutRequestID # "ws_CO_040920212326513616" response.inspect # to see all available attributes ``` ### B2C (Payout) ```rb response = client.payout( shortcode: "600998", # Optional if added in client initialization initiator_username: "testapi", initiator_password: "Safaricom998!", command_id: "BusinessPayment", phone: "254708374149", amount: "100", result_url: "https://example.com/result", timeout_url: "https://example.com/result", occasion: "some desc", remarks: "remarks" ) response.ConversationID # AG_20210904_0000574b3c8d93651740 response.OriginatorConversationID # "28831-15819693-1" respose.ResponseDescription # "Accept the service request successfully." ``` ### Transaction Status Check Transation Status ```rb response = client.status( shortcode: '600426', transaction_id: 'OEI2AK4Q16', identifier_type: 1, initiator_username: 'testapi', initiator_password: 'Safaricom426!', timeout_url: 'https://example.com/result', result_url: 'https://example.com/result' ) response.ConversationID response.ResponseCode ``` ### Reversal Initiate a reversal ``` response = client.reversal( initiator_password: 'Safaricom426!', initiator_username: 'testapi', transaction_id: 'OEI2AK4Q16', amount: '100', receiver: '600610', receiver_type: '4', timeout_url: 'https://example.com/result', result_url: 'https://example.com/result' ) response.ConversationID response.ResponseCode ``` ## Development After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run `bundle exec rake install`. ## Contributing Bug reports and pull requests are welcome on GitHub at https://github.com/gathuku/mpesa. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/gathuku/mpesa/blob/master/CODE_OF_CONDUCT.md). ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT). ## Code of Conduct Everyone interacting in the Mpesa project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/gathuku/mpesa/blob/master/CODE_OF_CONDUCT.md).