mpesa_stk 2.0.0 → 3.0.0

data/lib/mpesa_stk/push.rb

@@ -1,160 +1,69 @@
 # 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 'date'
-require 'mpesa_stk/access_token'
+require 'mpesa_stk/client'
 
 module MpesaStk
-  # Initiates STK Push payment for multiple applications with custom credentials
-  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)
-
-      raise StandardError, "Failed to push payment: #{response.code} - #{response.body}" unless response.success?
-
-      JSON.parse(response.body)
+      post('process_request_url', stk_push_payload, error_message: 'Failed to push payment')
     end
 
     private
 
-    def url
-      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('process_request_url', nil)}"
-    end
-
-    def headers
-      {
-        'Authorization' => "Bearer #{token}",
-        'Content-Type' => 'application/json'
-      }
-    end
+    def stk_push_payload
+      short_code, passkey, timestamp = stk_credentials
 
-    def body
       {
-        BusinessShortCode: get_business_short_code,
-        Password: generate_password,
+        BusinessShortCode: short_code,
+        Password: stk_password(short_code, passkey, timestamp),
         Timestamp: timestamp.to_s,
         TransactionType: transaction_type,
         Amount: amount.to_s,
         PartyA: phone_number.to_s,
-        PartyB: get_till_number,
+        PartyB: party_b(short_code),
         PhoneNumber: phone_number.to_s,
-        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 ArgumentError, 'Business Short Code is not defined'
-        end
-
-        ENV.fetch('business_short_code', nil)
-
-      else
-        business_short_code
-      end
-    end
-
-    def get_business_passkey
-      if business_passkey.nil? || business_passkey.eql?('')
-        raise ArgumentError, 'Business Passkey is not defined' if ENV['business_passkey'].nil? || ENV['business_passkey'].eql?('')
-
-        ENV.fetch('business_passkey', nil)
-
-      else
-        business_passkey
-      end
+        CallBackURL: option('callback_url'),
+        AccountReference: random_reference,
+        TransactionDesc: random_reference
+      }
     end
 
-    def get_callback_url
-      if callback_url.nil? || callback_url.eql?('')
-        raise ArgumentError, 'Callback URL is not defined' if ENV['callback_url'].nil? || ENV['callback_url'].eql?('')
-
-        ENV.fetch('callback_url', nil)
-
-      else
-        callback_url
-      end
+    def stk_credentials
+      [option('business_short_code'), option('business_passkey'), stk_timestamp]
     end
 
-    def get_till_number
-      if transaction_type.eql?('CustomerPayBillOnline')
-        get_business_short_code
-      elsif till_number.nil?
-        raise ArgumentError, 'Till number is not defined' if ENV['till_number'].nil? || ENV['till_number'].eql?('')
+    def party_b(short_code)
+      return short_code if transaction_type == 'CustomerPayBillOnline'
 
-        ENV.fetch('till_number', nil)
-
-      else
-        till_number
-      end
+      option('till_number')
     end
   end
 end

data/lib/mpesa_stk/ratiba.rb

@@ -1,118 +1,37 @@
 # 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'
+require 'mpesa_stk/client'
 
 module MpesaStk
-  # M-Pesa Ratiba (Standing Orders) - create recurring payments
-  class Ratiba
+  # Create M-Pesa Ratiba standing orders (recurring payments).
+  class Ratiba < Client
     class << self
-      def create_standing_order(hash = {})
-        new(hash).create
+      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
 
-    attr_reader :token, :standing_order_name, :business_short_code, :transaction_type, :amount, :party_a,
-                :receiver_party_identifier_type, :callback_url, :account_reference, :transaction_desc,
-                :frequency, :start_date, :end_date
-
-    def initialize(hash = {})
-      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
-      @standing_order_name = hash['standing_order_name'] || 'Standing Order'
-      @business_short_code = hash['business_short_code'] || ENV.fetch('business_short_code', nil)
-      @transaction_type = hash['transaction_type'] || 'Standing Order Customer Pay Bill'
-      @amount = hash['amount']
-      @party_a = hash['party_a']
-      @receiver_party_identifier_type = hash['receiver_party_identifier_type'] || '4'
-      @callback_url = hash['callback_url'] || ENV.fetch('callback_url', nil)
-      @account_reference = hash['account_reference'] || ''
-      @transaction_desc = hash['transaction_desc'] || ''
-      @frequency = hash['frequency'] || '3'
-      @start_date = hash['start_date']
-      @end_date = hash['end_date']
-    end
-
     def create
-      response = HTTParty.post(url, headers: headers, body: body)
-
-      raise StandardError, "Failed to create standing order: #{response.code} - #{response.body}" unless response.success?
-
-      JSON.parse(response.body)
+      post('ratiba_url', ratiba_payload, error_message: 'Failed to create standing order')
     end
 
     private
 
-    def url
-      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('ratiba_url', nil)}"
-    end
-
-    def headers
+    def ratiba_payload
       {
-        'Authorization' => "Bearer #{token}",
-        'Content-Type' => 'application/json'
+        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
-
-    def body
-      {
-        StandingOrderName: standing_order_name,
-        BusinessShortCode: get_business_short_code,
-        TransactionType: transaction_type,
-        Amount: amount.to_s,
-        PartyA: party_a,
-        ReceiverPartyIdentifierType: receiver_party_identifier_type,
-        CallBackURL: get_callback_url,
-        AccountReference: account_reference,
-        TransactionDesc: transaction_desc,
-        Frequency: frequency,
-        StartDate: start_date,
-        EndDate: end_date
-      }.to_json
-    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 ArgumentError, 'Business Short Code is not defined'
-        end
-
-        ENV.fetch('business_short_code', nil)
-
-      else
-        business_short_code
-      end
-    end
-
-    def get_callback_url
-      if callback_url.nil? || callback_url.eql?('')
-        raise ArgumentError, 'Callback URL is not defined' if ENV['callback_url'].nil? || ENV['callback_url'].eql?('')
-
-        ENV.fetch('callback_url', nil)
-
-      else
-        callback_url
-      end
-    end
   end
 end

data/lib/mpesa_stk/reversal.rb

@@ -1,147 +1,40 @@
 # 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'
+require 'mpesa_stk/client'
 
 module MpesaStk
-  # Reverse M-Pesa transactions (full or partial)
-  class Reversal
+  # Reverse a completed M-Pesa transaction.
+  class Reversal < Client
     class << self
-      def reverse(transaction_id, amount, hash = {})
-        new(transaction_id, amount, hash).reverse_transaction
+      def call(transaction_id, amount, **options)
+        new(transaction_id, amount, **options).reverse_transaction
       end
     end
 
-    attr_reader :token, :transaction_id, :amount, :initiator, :security_credential, :receiver_party,
-                :receiver_identifier_type, :result_url, :queue_timeout_url
+    attr_reader :transaction_id, :amount
 
-    def initialize(transaction_id, amount, hash = {})
-      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+    def initialize(transaction_id, amount, **options)
+      super(**options)
       @transaction_id = transaction_id
       @amount = amount
-      @initiator = hash['initiator'] || ENV.fetch('initiator', nil)
-      @security_credential = hash['security_credential'] || ENV.fetch('security_credential', nil)
-      @receiver_party = hash['receiver_party'] || ENV.fetch('business_short_code', nil)
-      @receiver_identifier_type = hash['receiver_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 reverse_transaction
-      response = HTTParty.post(url, headers: headers, body: body)
-
-      raise StandardError, "Failed to reverse transaction: #{response.code} - #{response.body}" unless response.success?
-
-      JSON.parse(response.body)
-    end
-
-    private
-
-    def url
-      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('reversal_url', nil)}"
-    end
-
-    def headers
-      {
-        'Authorization' => "Bearer #{token}",
-        'Content-Type' => 'application/json'
-      }
-    end
-
-    def body
-      {
-        Initiator: get_initiator,
-        SecurityCredential: get_security_credential,
-        CommandID: 'TransactionReversal',
-        TransactionID: transaction_id,
-        Amount: amount.to_s,
-        ReceiverParty: get_receiver_party,
-        RecieverIdentifierType: receiver_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_receiver_party
-      if receiver_party.nil? || receiver_party.eql?('')
-        if ENV['business_short_code'].nil? || ENV['business_short_code'].eql?('')
-          raise ArgumentError, 'Receiver Party (Business Short Code) is not defined'
-        end
-
-        ENV.fetch('business_short_code', nil)
-
-      else
-        receiver_party
-      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
+      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

@@ -1,109 +1,38 @@
 # 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 'date'
-require 'mpesa_stk/access_token'
+require 'mpesa_stk/client'
 
 module MpesaStk
-  # Query STK Push transaction status using CheckoutRequestID
-  class StkPushQuery
+  # Query the status of an STK Push checkout request.
+  class StkPushQuery < Client
     class << self
-      def query(checkout_request_id, hash = {})
-        new(checkout_request_id, hash).query_status
+      def call(checkout_request_id, **options)
+        new(checkout_request_id, **options).query_status
       end
     end
 
-    attr_reader :token, :checkout_request_id, :business_short_code, :business_passkey
+    attr_reader :checkout_request_id
 
-    def initialize(checkout_request_id, hash = {})
-      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+    def initialize(checkout_request_id, **options)
+      super(**options)
       @checkout_request_id = checkout_request_id
-      @business_short_code = hash['business_short_code'] || ENV.fetch('business_short_code', nil)
-      @business_passkey = hash['business_passkey'] || ENV.fetch('business_passkey', nil)
     end
 
     def query_status
-      response = HTTParty.post(url, headers: headers, body: body)
-
-      raise StandardError, "Failed to query STK push status: #{response.code} - #{response.body}" unless response.success?
-
-      JSON.parse(response.body)
-    end
-
-    private
-
-    def url
-      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('stk_push_query_url', nil)}"
-    end
-
-    def headers
-      {
-        'Authorization' => "Bearer #{token}",
-        'Content-Type' => 'application/json'
-      }
-    end
-
-    def body
-      {
-        BusinessShortCode: get_business_short_code,
-        Password: generate_password,
-        Timestamp: timestamp.to_s,
-        CheckoutRequestID: checkout_request_id
-      }.to_json
-    end
-
-    def timestamp
-      DateTime.now.strftime('%Y%m%d%H%M%S').to_i
-    end
-
-    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 ArgumentError, 'Business Short Code is not defined'
-        end
-
-        ENV.fetch('business_short_code', nil)
-
-      else
-        business_short_code
-      end
-    end
-
-    def get_business_passkey
-      if business_passkey.nil? || business_passkey.eql?('')
-        raise ArgumentError, 'Business Passkey is not defined' if ENV['business_passkey'].nil? || ENV['business_passkey'].eql?('')
-
-        ENV.fetch('business_passkey', nil)
-
-      else
-        business_passkey
-      end
+      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