mpesa_stk 1.2.1.1 → 2.0.0

data/lib/mpesa_stk/c2b.rb

@@ -0,0 +1,127 @@
+# 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
+  # Customer to Business API - register URLs and simulate C2B payments
+  class C2B
+    class << self
+      def register_url(hash = {})
+        new(hash).register
+      end
+
+      def simulate(amount, phone_number, hash = {})
+        new(hash).simulate_payment(amount, phone_number)
+      end
+    end
+
+    attr_reader :token, :short_code, :response_type, :confirmation_url, :validation_url, :command_id, :bill_ref_number
+
+    def initialize(hash = {})
+      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+      @short_code = hash['short_code'] || ENV.fetch('business_short_code', nil)
+      @response_type = hash['response_type'] || 'Completed'
+      @confirmation_url = hash['confirmation_url'] || ENV.fetch('confirmation_url', nil)
+      @validation_url = hash['validation_url']
+      @command_id = hash['command_id'] || 'CustomerPayBillOnline'
+      @bill_ref_number = hash['bill_ref_number'] || ''
+    end
+
+    def register
+      response = HTTParty.post(register_url_endpoint, headers: headers, body: register_body)
+
+      raise StandardError, "Failed to register C2B URL: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    def simulate_payment(amount, phone_number)
+      response = HTTParty.post(simulate_url_endpoint, headers: headers, body: simulate_body(amount, phone_number))
+
+      raise StandardError, "Failed to simulate C2B payment: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def register_url_endpoint
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('c2b_register_url', nil)}"
+    end
+
+    def simulate_url_endpoint
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('c2b_simulate_url', nil)}"
+    end
+
+    def headers
+      {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def register_body
+      body_hash = {
+        ShortCode: get_short_code,
+        ResponseType: response_type,
+        ConfirmationURL: get_confirmation_url
+      }
+      body_hash[:ValidationURL] = validation_url if validation_url
+      body_hash.to_json
+    end
+
+    def simulate_body(amount, phone_number)
+      {
+        ShortCode: get_short_code,
+        CommandID: command_id,
+        Amount: amount.to_s,
+        Msisdn: phone_number,
+        BillRefNumber: bill_ref_number
+      }.to_json
+    end
+
+    def get_short_code
+      if short_code.nil? || short_code.eql?('')
+        raise ArgumentError, 'Short Code is not defined' if ENV['business_short_code'].nil? || ENV['business_short_code'].eql?('')
+
+        ENV.fetch('business_short_code', nil)
+
+      else
+        short_code
+      end
+    end
+
+    def get_confirmation_url
+      if confirmation_url.nil? || confirmation_url.eql?('')
+        raise ArgumentError, 'Confirmation URL is not defined' if ENV['confirmation_url'].nil? || ENV['confirmation_url'].eql?('')
+
+        ENV.fetch('confirmation_url', nil)
+
+      else
+        confirmation_url
+      end
+    end
+  end
+end

data/lib/mpesa_stk/imsi.rb

@@ -0,0 +1,70 @@
+# 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
+  # IMSI/SWAP Operations - query IMSI and SIM swap information for fraud prevention
+  class IMSI
+    class << self
+      def check_ati(customer_number, hash = {}, version: 'v1')
+        new(hash).check_ati(customer_number, version)
+      end
+    end
+
+    attr_reader :token
+
+    def initialize(hash = {})
+      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+    end
+
+    def check_ati(customer_number, version = 'v1')
+      endpoint = version == 'v2' ? '/imsi/v2/checkATI' : '/imsi/v1/checkATI'
+      response = HTTParty.post(url(endpoint), headers: headers, body: body(customer_number))
+
+      raise StandardError, "Failed to check ATI: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def url(endpoint)
+      "#{ENV.fetch('base_url', nil)}#{endpoint}"
+    end
+
+    def headers
+      {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def body(customer_number)
+      {
+        customerNumber: customer_number
+      }.to_json
+    end
+  end
+end

data/lib/mpesa_stk/iot.rb

@@ -0,0 +1,206 @@
+# 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 'securerandom'
+
+module MpesaStk
+  # IoT SIM Management & Messaging - manage SIM cards and send/receive messages for IoT devices
+  class IoT
+    class << self
+      def sims(hash = {})
+        new(hash)
+      end
+
+      def messaging(hash = {})
+        new(hash)
+      end
+    end
+
+    attr_reader :token, :api_key, :vpn_group, :username
+
+    def initialize(hash = {})
+      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+      @api_key = hash['api_key'] || ENV['iot_api_key'] || 'Yl4S3KEcr173mbeUdYdjf147IuG3rJ824ArMkP6Z'
+      @vpn_group = hash['vpn_group'] || ENV['vpn_group'] || ''
+      @username = hash['username'] || ENV['username'] || ''
+    end
+
+    # SIM Operations
+    def get_all_sims(start_at_index: 0, page_size: 10)
+      post_request('/allsims', {
+                     vpnGroup: [vpn_group],
+                     startAtIndex: start_at_index.to_s,
+                     pageSize: page_size.to_s,
+                     username: username
+                   })
+    end
+
+    def query_lifecycle_status(msisdn)
+      post_request('/queryLifeCycleStatus', {
+                     msisdn: msisdn,
+                     vpnGroup: vpn_group,
+                     username: username
+                   })
+    end
+
+    def query_customer_info(msisdn)
+      post_request('/querycustomerinfo', {
+                     msisdn: msisdn,
+                     vpnGroup: vpn_group,
+                     username: username
+                   })
+    end
+
+    def sim_activation(msisdn)
+      post_request('/simactivation', {
+                     msisdn: msisdn,
+                     vpnGroup: vpn_group,
+                     username: username
+                   })
+    end
+
+    def get_activation_trends(start_date:, stop_date:)
+      post_request('/getactivationtrends', {
+                     vpnGroup: vpn_group,
+                     startDate: start_date,
+                     stopDate: stop_date,
+                     username: username
+                   })
+    end
+
+    def rename_asset(msisdn, asset_name)
+      post_request('/renameasset', {
+                     msisdn: msisdn,
+                     vpnGroup: vpn_group,
+                     username: username,
+                     assetName: asset_name
+                   })
+    end
+
+    def get_location_info(msisdn)
+      post_request('/getlocationinfo', {
+                     msisdn: msisdn,
+                     vpnGroup: vpn_group,
+                     username: username
+                   })
+    end
+
+    def suspend_unsuspend_sub(msisdn, product, operation)
+      post_request('/suspend_unsuspend_sub', {
+                     msisdn: msisdn,
+                     username: username,
+                     vpnGroup: vpn_group,
+                     product: product,
+                     operation: operation
+                   })
+    end
+
+    # Messaging Operations
+    def get_all_messages(page_no: 1, page_size: 10)
+      get_request("/getallmessages?pageNo=#{page_no}&pageSize=#{page_size}", {
+                    vpnGroup: vpn_group
+                  })
+    end
+
+    def search_messages(search_value, page_no: 1, page_size: 5)
+      get_request("/searchmessages?pageNo=#{page_no}&pageSize=#{page_size}", {
+                    searchValue: search_value,
+                    vpnGroup: vpn_group,
+                    username: username
+                  })
+    end
+
+    def filter_messages(start_date:, end_date:, status: '', page_no: 1, page_size: 10)
+      get_request("/filtermessages?pageNo=#{page_no}&pageSize=#{page_size}", {
+                    startDate: start_date,
+                    endDate: end_date,
+                    status: status,
+                    vpnGroup: vpn_group,
+                    username: username
+                  })
+    end
+
+    def send_single_message(msisdn, message)
+      post_request('/sendsinglemessage', {
+                     msisdn: msisdn,
+                     message: message,
+                     vpnGroup: vpn_group,
+                     username: username
+                   })
+    end
+
+    def delete_message(message_id)
+      post_request('/deletemessage', {
+                     id: message_id,
+                     vpnGroup: vpn_group,
+                     username: username
+                   })
+    end
+
+    def delete_message_thread(msisdn)
+      post_request('/deleteMessageThread', {
+                     msisdn: msisdn,
+                     vpnGroup: vpn_group,
+                     username: username
+                   })
+    end
+
+    private
+
+    def base_url
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('iot_base_url', nil)}"
+    end
+
+    def headers(msisdn: nil)
+      headers_hash = {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json',
+        'x-correlation-conversationid' => SecureRandom.uuid,
+        'x-source-system' => 'web-portal',
+        'x-api-key' => api_key,
+        'X-App' => 'web-portal',
+        'X-MessageID' => SecureRandom.uuid
+      }
+      headers_hash['X-MSISDN'] = msisdn if msisdn
+      headers_hash
+    end
+
+    def post_request(endpoint, body)
+      response = HTTParty.post("#{base_url}#{endpoint}", headers: headers(msisdn: body[:msisdn]), body: body.to_json)
+
+      raise StandardError, "Failed IoT request: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    def get_request(endpoint, body)
+      response = HTTParty.post("#{base_url}#{endpoint}", headers: headers, body: body.to_json)
+
+      raise StandardError, "Failed IoT request: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+  end
+end

data/lib/mpesa_stk/pull_transactions.rb

@@ -0,0 +1,126 @@
+# 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
+  # Pull Transactions API - register URLs and query historical transaction data
+  class PullTransactions
+    class << self
+      def register(hash = {})
+        new(hash).register_url
+      end
+
+      def query(start_date, end_date, hash = {})
+        new(hash).query_transactions(start_date, end_date)
+      end
+    end
+
+    attr_reader :token, :short_code, :request_type, :nominated_number, :callback_url, :offset_value
+
+    def initialize(hash = {})
+      @token = MpesaStk::AccessToken.call(hash['key'], hash['secret'])
+      @short_code = hash['short_code'] || ENV.fetch('business_short_code', nil)
+      @request_type = hash['request_type'] || ''
+      @nominated_number = hash['nominated_number'] || ''
+      @callback_url = hash['callback_url'] || ENV.fetch('callback_url', nil)
+      @offset_value = hash['offset_value'] || '0'
+    end
+
+    def register_url
+      response = HTTParty.post(register_endpoint, headers: headers, body: register_body)
+
+      unless response.success?
+        raise StandardError, "Failed to register pull transactions URL: #{response.code} - #{response.body}"
+      end
+
+      JSON.parse(response.body)
+    end
+
+    def query_transactions(start_date, end_date)
+      response = HTTParty.post(query_endpoint, headers: headers, body: query_body(start_date, end_date))
+
+      raise StandardError, "Failed to query pull transactions: #{response.code} - #{response.body}" unless response.success?
+
+      JSON.parse(response.body)
+    end
+
+    private
+
+    def register_endpoint
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('pull_transactions_register_url', nil)}"
+    end
+
+    def query_endpoint
+      "#{ENV.fetch('base_url', nil)}#{ENV.fetch('pull_transactions_query_url', nil)}"
+    end
+
+    def headers
+      {
+        'Authorization' => "Bearer #{token}",
+        'Content-Type' => 'application/json'
+      }
+    end
+
+    def register_body
+      {
+        ShortCode: get_short_code,
+        RequestType: request_type,
+        NominatedNumber: nominated_number,
+        CallBackURL: get_callback_url
+      }.to_json
+    end
+
+    def query_body(start_date, end_date)
+      {
+        ShortCode: get_short_code,
+        StartDate: start_date,
+        EndDate: end_date,
+        OffSetValue: offset_value
+      }.to_json
+    end
+
+    def get_short_code
+      if short_code.nil? || short_code.eql?('')
+        raise ArgumentError, 'Short Code is not defined' if ENV['business_short_code'].nil? || ENV['business_short_code'].eql?('')
+
+        ENV.fetch('business_short_code', nil)
+
+      else
+        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/push.rb

@@ -0,0 +1,160 @@
+# 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'
+
+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
+
+      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
+      end
+    end
+
+    attr_reader :token, :amount, :phone_number, :till_number, :business_short_code, :callback_url, :business_passkey,
+                :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
+      @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)
+    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 body
+      {
+        BusinessShortCode: get_business_short_code,
+        Password: generate_password,
+        Timestamp: timestamp.to_s,
+        TransactionType: transaction_type,
+        Amount: amount.to_s,
+        PartyA: phone_number.to_s,
+        PartyB: get_till_number,
+        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
+    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
+
+    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?('')
+
+        ENV.fetch('till_number', nil)
+
+      else
+        till_number
+      end
+    end
+  end
+end