mpesa_stk 1.3 → 2.0.0

data/Rakefile

@@ -1,10 +1,12 @@
-require "bundler/gem_tasks"
-require "rake/testtask"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rake/testtask'
 
 Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
+  t.libs << 'test'
+  t.libs << 'lib'
+  t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :test
+task default: :test

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+Use this section to tell people about which versions of your project are
+currently being supported with security updates.
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 5.1.x   | :white_check_mark: |
+| 5.0.x   | :x:                |
+| 4.0.x   | :white_check_mark: |
+| < 4.0   | :x:                |
+
+## Reporting a Vulnerability
+
+Use this section to tell people how to report a vulnerability.
+
+Tell them where to go, how often they can expect to get an update on a
+reported vulnerability, what to expect if the vulnerability is accepted or
+declined, etc.

data/bin/console

@@ -1,7 +1,8 @@
 #!/usr/bin/env ruby
+# frozen_string_literal: true
 
-require "bundler/setup"
-require "mpesa_stk"
+require 'bundler/setup'
+require 'mpesa_stk'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -10,5 +11,5 @@ require "mpesa_stk"
 # require "pry"
 # Pry.start
 
-require "irb"
+require 'irb'
 IRB.start(__FILE__)

data/lib/mpesa_stk/access_token.rb

@@ -1,7 +1,33 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2018 mboya
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
 require 'base64'
+require 'json'
 require 'redis'
 
 module MpesaStk
+  # Handles OAuth access token generation, caching, and refreshing for M-Pesa APIs
   class AccessToken
     class << self
       def call(key = nil, secret = nil)
@@ -10,34 +36,38 @@ module MpesaStk
     end
 
     def initialize(key = nil, secret = nil)
-      @key = key.nil? ? ENV['key'] : key
-      @secret = secret.nil? ? ENV['secret'] : secret
-      @redis = Redis.new
+      @key = key.nil? ? ENV.fetch('key', nil) : key
+      @secret = secret.nil? ? ENV.fetch('secret', nil) : secret
+      begin
+        @redis = Redis.new
+      rescue Redis::CannotConnectError, Redis::ConnectionError => e
+        raise StandardError, "Failed to connect to Redis: #{e.message}"
+      end
 
       load_from_redis
     end
 
-    def is_valid?
-      has_token? && !token_expired?
+    def valid?
+      token? && !token_expired?
     end
 
     def token_expired?
       expire_time = @timestamp.to_i + @expires_in.to_i
-      return expire_time < Time.now.to_i + 58
+      expire_time < Time.now.to_i + 58
     end
 
-    def has_token?
-      return !@token.nil?
+    def token?
+      !@token.nil?
     end
 
     def refresh
-      get_new_access_token
+      new_access_token
       load_from_redis
     end
 
     def load_from_redis
       data = @redis.get(@key)
-      if (data.nil? || data.empty?)
+      if data.nil? || data.empty?
         @token = nil
         @timestamp = nil
         @expires_in = nil
@@ -47,38 +77,40 @@ module MpesaStk
         @timestamp = parsed['time_stamp']
         @expires_in = parsed['expires_in']
       end
+    rescue Redis::BaseError => e
+      raise StandardError, "Redis error: #{e.message}"
     end
 
     def access_token
-      if is_valid?
-        return @token
-      else
-        refresh
-        return @token
-      end
+      refresh unless valid?
+      @token
     end
 
-    def get_new_access_token
+    def new_access_token
       response = HTTParty.get(url, headers: headers)
 
-      hash = JSON.parse(response.body).merge(Hash['time_stamp', Time.now.to_i])
+      raise StandardError, "Failed to get access token: #{response.code} - #{response.body}" unless response.success?
+
+      hash = JSON.parse(response.body).merge({ 'time_stamp' => Time.now.to_i })
       @redis.set @key, hash.to_json
+    rescue Redis::BaseError => e
+      raise StandardError, "Redis error while saving token: #{e.message}"
     end
 
     private
 
     def url
-      "#{ENV['base_url']}#{ENV['token_generator_url']}"
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('token_generator_url', nil)}"
     end
 
     def headers
       encode = encode_credentials @key, @secret
       {
-        "Authorization" => "Basic #{encode}"
+        'Authorization' => "Basic #{encode}"
       }
     end
 
-    def encode_credentials key, secret
+    def encode_credentials(key, secret)
       credentials = "#{key}:#{secret}"
       Base64.encode64(credentials).split("\n").join
     end

data/lib/mpesa_stk/account_balance.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2018 mboya
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'mpesa_stk/access_token'
+
+module MpesaStk
+  # Query account balance for PayBill or Till Number
+  class AccountBalance
+    class << self
+      def query(hash = {})
+        new(hash).query_balance
+      end
+    end
+
+    attr_reader :token, :initiator, :security_credential, :party_a, :identifier_type, :result_url, :queue_timeout_url
+
+    def initialize(hash = {})
+      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+      @initiator = hash['initiator'] || ENV.fetch('initiator', nil)
+      @security_credential = hash['security_credential'] || ENV.fetch('security_credential', nil)
+      @party_a = hash['party_a'] || ENV.fetch('business_short_code', nil)
+      @identifier_type = hash['identifier_type'] || '4'
+      @result_url = hash['result_url'] || ENV.fetch('result_url', nil)
+      @queue_timeout_url = hash['queue_timeout_url'] || ENV.fetch('queue_timeout_url', nil)
+    end
+
+    def query_balance
+      response = HTTParty.post(url, headers: headers, body: body)
+
+      raise StandardError, "Failed to query account balance: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def url
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('account_balance_url', nil)}"
+    end
+
+    def headers
+      {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def body
+      {
+        Initiator: get_initiator,
+        SecurityCredential: get_security_credential,
+        CommandID: 'AccountBalance',
+        PartyA: get_party_a,
+        IdentifierType: identifier_type,
+        ResultURL: get_result_url,
+        QueueTimeOutURL: get_queue_timeout_url
+      }.to_json
+    end
+
+    def get_initiator
+      if initiator.nil? || initiator.eql?('')
+        raise ArgumentError, 'Initiator is not defined' if ENV['initiator'].nil? || ENV['initiator'].eql?('')
+
+        ENV.fetch('initiator', nil)
+
+      else
+        initiator
+      end
+    end
+
+    def get_security_credential
+      if security_credential.nil? || security_credential.eql?('')
+        if ENV['security_credential'].nil? || ENV['security_credential'].eql?('')
+          raise ArgumentError, 'Security Credential is not defined'
+        end
+
+        ENV.fetch('security_credential', nil)
+
+      else
+        security_credential
+      end
+    end
+
+    def get_party_a
+      if party_a.nil? || party_a.eql?('')
+        if ENV['business_short_code'].nil? || ENV['business_short_code'].eql?('')
+          raise ArgumentError, 'PartyA (Business Short Code) is not defined'
+        end
+
+        ENV.fetch('business_short_code', nil)
+
+      else
+        party_a
+      end
+    end
+
+    def get_result_url
+      if result_url.nil? || result_url.eql?('')
+        raise ArgumentError, 'Result URL is not defined' if ENV['result_url'].nil? || ENV['result_url'].eql?('')
+
+        ENV.fetch('result_url', nil)
+
+      else
+        result_url
+      end
+    end
+
+    def get_queue_timeout_url
+      if queue_timeout_url.nil? || queue_timeout_url.eql?('')
+        if ENV['queue_timeout_url'].nil? || ENV['queue_timeout_url'].eql?('')
+          raise ArgumentError, 'Queue Timeout URL is not defined'
+        end
+
+        ENV.fetch('queue_timeout_url', nil)
+
+      else
+        queue_timeout_url
+      end
+    end
+  end
+end

data/lib/mpesa_stk/b2b.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2018 mboya
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'mpesa_stk/access_token'
+
+module MpesaStk
+  # Business to Business payment API - send money between businesses
+  class B2B
+    class << self
+      def pay(amount, receiver_party, hash = {})
+        new(amount, receiver_party, hash).send_payment
+      end
+    end
+
+    attr_reader :token, :amount, :receiver_party, :initiator, :security_credential, :command_id,
+                :sender_identifier_type, :receiver_identifier_type, :party_a, :account_reference,
+                :result_url, :queue_timeout_url
+
+    def initialize(amount, receiver_party, hash = {})
+      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+      @amount = amount
+      @receiver_party = receiver_party
+      @initiator = hash['initiator'] || ENV.fetch('initiator', nil)
+      @security_credential = hash['security_credential'] || ENV.fetch('security_credential', nil)
+      @command_id = hash['command_id'] || 'BusinessPayBill'
+      @sender_identifier_type = hash['sender_identifier_type'] || '4'
+      @receiver_identifier_type = hash['receiver_identifier_type'] || '4'
+      @party_a = hash['party_a'] || ENV.fetch('business_short_code', nil)
+      @account_reference = hash['account_reference'] || ''
+      @result_url = hash['result_url'] || ENV.fetch('result_url', nil)
+      @queue_timeout_url = hash['queue_timeout_url'] || ENV.fetch('queue_timeout_url', nil)
+    end
+
+    def send_payment
+      response = HTTParty.post(url, headers: headers, body: body)
+
+      raise StandardError, "Failed to send B2B payment: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def url
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('b2b_url', nil)}"
+    end
+
+    def headers
+      {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def body
+      {
+        Initiator: get_initiator,
+        SecurityCredential: get_security_credential,
+        CommandID: command_id,
+        SenderIdentifierType: sender_identifier_type,
+        RecieverIdentifierType: receiver_identifier_type,
+        Amount: amount.to_s,
+        PartyA: get_party_a,
+        PartyB: receiver_party,
+        AccountReference: account_reference,
+        QueueTimeOutURL: get_queue_timeout_url,
+        ResultURL: get_result_url
+      }.to_json
+    end
+
+    def get_initiator
+      if initiator.nil? || initiator.eql?('')
+        raise ArgumentError, 'Initiator is not defined' if ENV['initiator'].nil? || ENV['initiator'].eql?('')
+
+        ENV.fetch('initiator', nil)
+
+      else
+        initiator
+      end
+    end
+
+    def get_security_credential
+      if security_credential.nil? || security_credential.eql?('')
+        if ENV['security_credential'].nil? || ENV['security_credential'].eql?('')
+          raise ArgumentError, 'Security Credential is not defined'
+        end
+
+        ENV.fetch('security_credential', nil)
+
+      else
+        security_credential
+      end
+    end
+
+    def get_party_a
+      if party_a.nil? || party_a.eql?('')
+        if ENV['business_short_code'].nil? || ENV['business_short_code'].eql?('')
+          raise ArgumentError, 'PartyA (Business Short Code) is not defined'
+        end
+
+        ENV.fetch('business_short_code', nil)
+
+      else
+        party_a
+      end
+    end
+
+    def get_result_url
+      if result_url.nil? || result_url.eql?('')
+        raise ArgumentError, 'Result URL is not defined' if ENV['result_url'].nil? || ENV['result_url'].eql?('')
+
+        ENV.fetch('result_url', nil)
+
+      else
+        result_url
+      end
+    end
+
+    def get_queue_timeout_url
+      if queue_timeout_url.nil? || queue_timeout_url.eql?('')
+        if ENV['queue_timeout_url'].nil? || ENV['queue_timeout_url'].eql?('')
+          raise ArgumentError, 'Queue Timeout URL is not defined'
+        end
+
+        ENV.fetch('queue_timeout_url', nil)
+
+      else
+        queue_timeout_url
+      end
+    end
+  end
+end

data/lib/mpesa_stk/b2c.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+# Copyright (c) 2018 mboya
+#
+# MIT License
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+# THE SOFTWARE.
+
+require 'mpesa_stk/access_token'
+
+module MpesaStk
+  # Business to Customer payment API - send money from business to customers
+  class B2C
+    class << self
+      def pay(amount, phone_number, hash = {})
+        new(amount, phone_number, hash).send_payment
+      end
+    end
+
+    attr_reader :token, :amount, :phone_number, :initiator_name, :security_credential, :command_id, :party_a, :remarks,
+                :result_url, :queue_timeout_url, :occasion
+
+    def initialize(amount, phone_number, hash = {})
+      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+      @amount = amount
+      @phone_number = phone_number
+      @initiator_name = hash['initiator_name'] || ENV.fetch('initiator_name', nil)
+      @security_credential = hash['security_credential'] || ENV.fetch('security_credential', nil)
+      @command_id = hash['command_id'] || 'BusinessPayment'
+      @party_a = hash['party_a'] || ENV.fetch('business_short_code', nil)
+      @remarks = hash['remarks'] || 'Payment'
+      @result_url = hash['result_url'] || ENV.fetch('result_url', nil)
+      @queue_timeout_url = hash['queue_timeout_url'] || ENV.fetch('queue_timeout_url', nil)
+      @occasion = hash['occasion']
+    end
+
+    def send_payment
+      response = HTTParty.post(url, headers: headers, body: body)
+
+      raise StandardError, "Failed to send B2C payment: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def url
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('b2c_url', nil)}"
+    end
+
+    def headers
+      {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def body
+      body_hash = {
+        InitiatorName: get_initiator_name,
+        SecurityCredential: get_security_credential,
+        CommandID: command_id,
+        Amount: amount.to_s,
+        PartyA: get_party_a,
+        PartyB: phone_number,
+        Remarks: remarks,
+        QueueTimeOutURL: get_queue_timeout_url,
+        ResultURL: get_result_url
+      }
+      body_hash[:Occasion] = occasion if occasion
+      body_hash.to_json
+    end
+
+    def get_initiator_name
+      if initiator_name.nil? || initiator_name.eql?('')
+        raise ArgumentError, 'Initiator Name is not defined' if ENV['initiator_name'].nil? || ENV['initiator_name'].eql?('')
+
+        ENV.fetch('initiator_name', nil)
+
+      else
+        initiator_name
+      end
+    end
+
+    def get_security_credential
+      if security_credential.nil? || security_credential.eql?('')
+        if ENV['security_credential'].nil? || ENV['security_credential'].eql?('')
+          raise ArgumentError, 'Security Credential is not defined'
+        end
+
+        ENV.fetch('security_credential', nil)
+
+      else
+        security_credential
+      end
+    end
+
+    def get_party_a
+      if party_a.nil? || party_a.eql?('')
+        if ENV['business_short_code'].nil? || ENV['business_short_code'].eql?('')
+          raise ArgumentError, 'PartyA (Business Short Code) is not defined'
+        end
+
+        ENV.fetch('business_short_code', nil)
+
+      else
+        party_a
+      end
+    end
+
+    def get_result_url
+      if result_url.nil? || result_url.eql?('')
+        raise ArgumentError, 'Result URL is not defined' if ENV['result_url'].nil? || ENV['result_url'].eql?('')
+
+        ENV.fetch('result_url', nil)
+
+      else
+        result_url
+      end
+    end
+
+    def get_queue_timeout_url
+      if queue_timeout_url.nil? || queue_timeout_url.eql?('')
+        if ENV['queue_timeout_url'].nil? || ENV['queue_timeout_url'].eql?('')
+          raise ArgumentError, 'Queue Timeout URL is not defined'
+        end
+
+        ENV.fetch('queue_timeout_url', nil)
+
+      else
+        queue_timeout_url
+      end
+    end
+  end
+end