mpesa_stk 1.3 → 3.0.0

data/lib/mpesa_stk/pull_transactions.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Register and query pull transaction callbacks.
+  class PullTransactions < Client
+    class << self
+      def register(**options)
+        new(**options).register_url
+      end
+
+      def call(start_date, end_date, **options)
+        new(**options).query_transactions(start_date, end_date)
+      end
+    end
+
+    def register_url
+      post(
+        'pull_transactions_register_url',
+        {
+          ShortCode: option('business_short_code', :short_code),
+          RequestType: @options.fetch(:request_type, ''),
+          NominatedNumber: @options.fetch(:nominated_number, ''),
+          CallBackURL: option('callback_url')
+        },
+        error_message: 'Failed to register pull transactions URL'
+      )
+    end
+
+    def query_transactions(start_date, end_date)
+      post(
+        'pull_transactions_query_url',
+        {
+          ShortCode: option('business_short_code', :short_code),
+          StartDate: start_date,
+          EndDate: end_date,
+          OffSetValue: @options.fetch(:offset_value, '0')
+        },
+        error_message: 'Failed to query pull transactions'
+      )
+    end
+  end
+end

data/lib/mpesa_stk/push.rb

@@ -1,131 +1,69 @@
-require "mpesa_stk/access_token"
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
 
 module MpesaStk
-  class Push
-    class << self
-      def pay_bill(amount, phone_number, hash = {})
-        new(amount, phone_number, "CustomerPayBillOnline", nil, hash["business_short_code"], hash["callback_url"], hash["business_passkey"], hash["key"], hash["secret"]).push_payment
-      end
+  # STK Push (Lipa na M-Pesa): PayBill and Buy Goods.
+  #
+  #   MpesaStk::Push.call(amount, phone)                    # PayBill, ENV only
+  #   MpesaStk::Push.call(amount, phone, type: :buy_goods)  # Buy Goods
+  #   MpesaStk::Push.call(amount, phone, key: '...', ...)   # per-request overrides
+  class Push < Client
+    TRANSACTION_TYPES = {
+      pay_bill: 'CustomerPayBillOnline',
+      buy_goods: 'CustomerBuyGoodsOnline'
+    }.freeze
 
-      def buy_goods(amount, phone_number, hash = {})
-        new(amount, phone_number, "CustomerBuyGoodsOnline", hash["till_number"], hash["business_short_code"], hash["callback_url"], hash["business_passkey"], hash["key"], hash["secret"]).push_payment
+    class << self
+      def call(amount, phone_number, type: :pay_bill, **options)
+        new(amount, phone_number, type: type, **options).push_payment
       end
     end
 
-    attr_reader :token, :amount, :phone_number, :till_number, :business_short_code, :callback_url, :business_passkey, :transaction_type
+    attr_reader :amount, :phone_number, :transaction_type
 
-    def initialize(amount, phone_number, transaction_type, till_number = nil, business_short_code = nil, callback_url = nil, business_passkey = nil, key = nil, secret = nil)
-      @token = MpesaStk::AccessToken.call(key, secret)
-      @transaction_type = transaction_type
-      @till_number = till_number
-      @business_short_code = business_short_code
-      @callback_url = callback_url
-      @business_passkey = business_passkey
+    def initialize(amount, phone_number, type: :pay_bill, **options)
+      @transaction_type = TRANSACTION_TYPES.fetch(type) do
+        raise ArgumentError, "Unknown STK type: #{type}. Use :pay_bill or :buy_goods"
+      end
+
+      super(**options)
       @amount = amount
       @phone_number = phone_number
     end
 
     def push_payment
-      response = HTTParty.post(url, headers: headers, body: body)
-      JSON.parse(response.body)
+      post('process_request_url', stk_push_payload, error_message: 'Failed to push payment')
     end
 
     private
 
-    def url
-      "#{ENV['base_url']}#{ENV['process_request_url']}"
-    end
+    def stk_push_payload
+      short_code, passkey, timestamp = stk_credentials
 
-    def headers
       {
-        "Authorization" => "Bearer #{token}",
-        "Content-Type" => "application/json"
-      }
-    end
-
-    def body
-      {
-        BusinessShortCode: get_business_short_code,
-        Password: generate_password,
-        Timestamp: "#{timestamp}",
+        BusinessShortCode: short_code,
+        Password: stk_password(short_code, passkey, timestamp),
+        Timestamp: timestamp.to_s,
         TransactionType: transaction_type,
-        Amount: "#{amount}",
-        PartyA: "#{phone_number}",
-        PartyB: get_till_number,
-        PhoneNumber: "#{phone_number}",
-        CallBackURL: get_callback_url,
-        AccountReference: generate_bill_reference_number(5),
-        TransactionDesc: generate_bill_reference_number(5)
-      }.to_json
-    end
-
-    def generate_bill_reference_number(number)
-      charset = Array('A'..'Z') + Array('a'..'z')
-      Array.new(number) { charset.sample }.join
-    end
-
-    def timestamp
-      DateTime.now.strftime("%Y%m%d%H%M%S").to_i
-    end
-
-    # shortcode
-    # passkey
-    # timestamp
-    def generate_password
-      key = "#{get_business_short_code}#{get_business_passkey}#{timestamp}"
-      Base64.encode64(key).split("\n").join
-    end
-
-    def get_business_short_code
-      if business_short_code.nil? || business_short_code.eql?("")
-        if ENV['business_short_code'].nil? || ENV['business_short_code'].eql?("")
-          raise Exception.new "Business Short Code is not defined"
-        else
-          ENV['business_short_code']
-        end
-      else
-        business_short_code
-      end
+        Amount: amount.to_s,
+        PartyA: phone_number.to_s,
+        PartyB: party_b(short_code),
+        PhoneNumber: phone_number.to_s,
+        CallBackURL: option('callback_url'),
+        AccountReference: random_reference,
+        TransactionDesc: random_reference
+      }
     end
 
-    def get_business_passkey
-      if business_passkey.nil? || business_passkey.eql?("")
-        if ENV['business_passkey'].nil? || ENV['business_passkey'].eql?("")
-          raise Exception.new "Business Passkey is not defined"
-        else
-          ENV['business_passkey']
-        end
-      else
-        business_passkey
-      end
+    def stk_credentials
+      [option('business_short_code'), option('business_passkey'), stk_timestamp]
     end
 
-    def get_callback_url
-      if callback_url.nil? || callback_url.eql?("")
-        if ENV['callback_url'].nil? || ENV['callback_url'].eql?("")
-          raise Exception.new "Callback URL is not defined"
-        else
-          ENV['callback_url']
-        end
-      else
-        callback_url
-      end
-    end
+    def party_b(short_code)
+      return short_code if transaction_type == 'CustomerPayBillOnline'
 
-    def get_till_number
-      if transaction_type.eql?("CustomerPayBillOnline")
-        get_business_short_code
-      else
-        if till_number.nil?
-          if ENV['till_number'].nil? || ENV['till_number'].eql?("")
-            raise Exception.new "Till number is not defined"
-          else
-            ENV['till_number']
-          end
-        else
-          till_number
-        end
-      end
+      option('till_number')
     end
   end
-end
+end

data/lib/mpesa_stk/ratiba.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Create M-Pesa Ratiba standing orders (recurring payments).
+  class Ratiba < Client
+    class << self
+      def call(amount:, party_a:, start_date:, end_date:, **options)
+        new(**options, amount: amount, party_a: party_a, start_date: start_date, end_date: end_date).create
+      end
+    end
+
+    def create
+      post('ratiba_url', ratiba_payload, error_message: 'Failed to create standing order')
+    end
+
+    private
+
+    def ratiba_payload
+      {
+        StandingOrderName: @options.fetch(:standing_order_name, 'Standing Order'),
+        BusinessShortCode: option('business_short_code'),
+        TransactionType: @options.fetch(:transaction_type, 'Standing Order Customer Pay Bill'),
+        Amount: @options.fetch(:amount).to_s,
+        PartyA: @options.fetch(:party_a),
+        ReceiverPartyIdentifierType: @options.fetch(:receiver_party_identifier_type, '4'),
+        CallBackURL: option('callback_url'),
+        AccountReference: @options.fetch(:account_reference, ''),
+        TransactionDesc: @options.fetch(:transaction_desc, ''),
+        Frequency: @options.fetch(:frequency, '3'),
+        StartDate: @options.fetch(:start_date),
+        EndDate: @options.fetch(:end_date)
+      }
+    end
+  end
+end

data/lib/mpesa_stk/reversal.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Reverse a completed M-Pesa transaction.
+  class Reversal < Client
+    class << self
+      def call(transaction_id, amount, **options)
+        new(transaction_id, amount, **options).reverse_transaction
+      end
+    end
+
+    attr_reader :transaction_id, :amount
+
+    def initialize(transaction_id, amount, **options)
+      super(**options)
+      @transaction_id = transaction_id
+      @amount = amount
+    end
+
+    def reverse_transaction
+      post(
+        'reversal_url',
+        {
+          Initiator: option('initiator'),
+          SecurityCredential: option('security_credential'),
+          CommandID: 'TransactionReversal',
+          TransactionID: transaction_id,
+          Amount: amount.to_s,
+          ReceiverParty: option('business_short_code', :receiver_party),
+          RecieverIdentifierType: @options.fetch(:receiver_identifier_type, '4'),
+          ResultURL: option('result_url'),
+          QueueTimeOutURL: option('queue_timeout_url')
+        },
+        error_message: 'Failed to reverse transaction'
+      )
+    end
+  end
+end

data/lib/mpesa_stk/stk_push_query.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Query the status of an STK Push checkout request.
+  class StkPushQuery < Client
+    class << self
+      def call(checkout_request_id, **options)
+        new(checkout_request_id, **options).query_status
+      end
+    end
+
+    attr_reader :checkout_request_id
+
+    def initialize(checkout_request_id, **options)
+      super(**options)
+      @checkout_request_id = checkout_request_id
+    end
+
+    def query_status
+      short_code = option('business_short_code')
+      passkey = option('business_passkey')
+      timestamp = stk_timestamp
+
+      post(
+        'stk_push_query_url',
+        {
+          BusinessShortCode: short_code,
+          Password: stk_password(short_code, passkey, timestamp),
+          Timestamp: timestamp.to_s,
+          CheckoutRequestID: checkout_request_id
+        },
+        error_message: 'Failed to query STK push status'
+      )
+    end
+  end
+end

data/lib/mpesa_stk/transaction_status.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'mpesa_stk/client'
+
+module MpesaStk
+  # Query the status of any M-Pesa transaction by ID.
+  class TransactionStatus < Client
+    class << self
+      def call(transaction_id, **options)
+        new(transaction_id, **options).query_status
+      end
+    end
+
+    attr_reader :transaction_id
+
+    def initialize(transaction_id, **options)
+      super(**options)
+      @transaction_id = transaction_id
+    end
+
+    def query_status
+      post(
+        'transaction_status_url',
+        {
+          Initiator: option('initiator'),
+          SecurityCredential: option('security_credential'),
+          CommandID: 'TransactionStatusQuery',
+          TransactionID: transaction_id,
+          PartyA: option('business_short_code', :party_a),
+          IdentifierType: @options.fetch(:identifier_type, '4'),
+          ResultURL: option('result_url'),
+          QueueTimeOutURL: option('queue_timeout_url')
+        },
+        error_message: 'Failed to query transaction status'
+      )
+    end
+  end
+end

data/lib/mpesa_stk/version.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module MpesaStk
-  VERSION = "1.3"
+  VERSION = '3.0.0'
 end

data/lib/mpesa_stk.rb

@@ -1,5 +1,29 @@
-require "mpesa_stk/version"
-require 'mpesa_stk/push_payment'
+# frozen_string_literal: true
+
+require 'mpesa_stk/version'
+require 'mpesa_stk/config'
+require 'mpesa_stk/client'
+require 'mpesa_stk/access_token'
 require 'mpesa_stk/push'
-require 'dotenv/load'
+require 'mpesa_stk/transaction_status'
+require 'mpesa_stk/stk_push_query'
+require 'mpesa_stk/b2c'
+require 'mpesa_stk/b2b'
+require 'mpesa_stk/c2b'
+require 'mpesa_stk/account_balance'
+require 'mpesa_stk/reversal'
+require 'mpesa_stk/ratiba'
+require 'mpesa_stk/iot'
+require 'mpesa_stk/imsi'
+require 'mpesa_stk/pull_transactions'
+
+require 'dotenv/load' unless ENV['MPESA_STK_SKIP_DOTENV'] == 'true'
 require 'httparty'
+require 'securerandom'
+
+# Ruby client for Safaricom Daraja M-Pesa APIs (STK Push, B2C, B2B, C2B, and related services).
+module MpesaStk
+  def self.configure(&block)
+    Config.configure(&block)
+  end
+end

data/mpesa_stk.gemspec

@@ -1,36 +1,49 @@
+# frozen_string_literal: true
 
-lib = File.expand_path("../lib", __FILE__)
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "mpesa_stk/version"
+require 'mpesa_stk/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = "mpesa_stk"
+  spec.name          = 'mpesa_stk'
   spec.version       = MpesaStk::VERSION
-  spec.authors       = ["mboya", "cess"]
-  spec.email         = ["mboyaberry@gmail.com", "cessmbuguar@gmail.com"]
+  spec.authors       = %w[mboya cess]
+  spec.email         = ['mboyaberry@gmail.com', 'cessmbuguar@gmail.com']
 
-  spec.summary       = %q{Lipa na M-Pesa Online Payment.}
-  spec.description   = %q{initiate a M-Pesa transaction on behalf of a customer using STK Push.}
-  spec.homepage      = "https://github.com/mboya/mpesa_stk"
-  spec.license       = "MIT"
+  spec.summary       = 'Lipa na M-Pesa Online Payment.'
+  spec.description   = 'initiate a M-Pesa transaction on behalf of a customer using STK Push.'
+  spec.homepage      = 'https://github.com/mboya/mpesa_stk'
+  spec.license       = 'MIT'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+  spec.required_ruby_version = '>= 2.6.0'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = "exe"
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
-  spec.add_dependency 'httparty', '>= 0.15.6', '< 0.19.0'
-  spec.add_dependency 'redis-rack', '~> 2.0', '>= 2.0.2'
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = "#{spec.homepage}.git"
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/master/CHANGELOG.md"
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.add_dependency 'base64', '>= 0.1.0'
+  spec.add_dependency 'csv', '>= 3.0.0'
+  spec.add_dependency 'httparty', '>= 0.15.6', '< 0.25.0'
+  spec.add_dependency 'redis', '>= 4.0'
   spec.add_dependency 'redis-namespace', '~> 1.5', '>= 1.5.3'
+  spec.add_dependency 'redis-rack', '~> 2.0', '>= 2.0.2'
 
-  spec.add_development_dependency "bundler"
-  spec.add_development_dependency "rake", ">= 12.3.3"
-  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'minitest', '~> 5.20'
+  spec.add_development_dependency 'rake', '>= 12.3.3'
 
-  spec.add_development_dependency 'pry', '~> 0.10.4'
-  spec.add_development_dependency 'pry-nav', '~> 0.2.4'
-  spec.add_development_dependency 'webmock', '~> 3.0', '>= 3.0.1'
-  spec.add_development_dependency "dotenv", "2.7.5"
+  spec.add_development_dependency 'dotenv', '~> 3.0'
+  spec.add_development_dependency 'pry', '~> 0.14'
+  spec.add_development_dependency 'pry-nav', '~> 1.0'
+  spec.add_development_dependency 'rubocop', '~> 1.0'
+  spec.add_development_dependency 'simplecov', '~> 0.22'
+  spec.add_development_dependency 'webmock', '~> 3.18'
 end