pesapal 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8166e77a88a3f62b22458f737b9342b1750aa18d
-  data.tar.gz: d95d4174f1b2b324b08c9a3a611d7a187e915d05
+  metadata.gz: 2b77c7352914478f5db52c64dd9e5611cd9c8652
+  data.tar.gz: 382a808b6a1d6464587477cd0ab30aa4c6e53b5b
 SHA512:
-  metadata.gz: 23618f43a0a739ff6871a1f1dba80324b6cad7de1f8006c13c651708792c3d7ba2d3fdea0f608a10e95a3fef8b5d4c52c16ca10e494da704bce922dbef6159e9
-  data.tar.gz: a833ad55d35d4c83b736ec708d4e4e4762565ca1d0d2a044059d099b4ef7479c0b54b26e33d370cf555e81140fd64a62791937fd1feda9aa61b9502a85103a15
+  metadata.gz: 74576337022966c7ae613394507be8f2a4d1611fee53067430b80ae7d2376a8c34acb21cf933ab6c9f8697c119892c3608b17e9fd4604c59977fea2c6dd4e646
+  data.tar.gz: 35fe01d3f3a0dbe097474e85710e65862f14a041ea5726df5c21ff2f1c13e94796b7ea07036acca4b800f672f034f4572481126939cdd0ea1bc8c680c6c7ea5f

data/CHANGELOG.md

@@ -1,6 +1,20 @@
 Changelog
 =========
 
+v1.0.0
+------
+
+* Automate release date to reduce chances of forgetting to update it
+* Add new functionality: Query Payment Status
+* Add new functionality: Query Payment Details
+* Add `set_mode()` method to enable changing mode at runtime
+* `api_domain` & `api_endpoints` are now private, use `set_mode` to alter them
+
+v0.2.1
+------
+
+* Fix screwed up rubygem date
+
 v0.2.0
 ------
 

data/README.md

@@ -7,10 +7,10 @@ Make authenticated Pesapal API calls without the fuss! Handles all the [oAuth
 stuff][1] abstracting any direct interaction with the API endpoints so that you
 can focus on what matters. _Building awesome_.
 
-This gem is work in progress. At the moment, the only functionality built-in is
-posting an order i.e. fetching the URL that is required to display the post-
-order iframe. Everything else should be easy to do as the groundwork has already
-been laid. If you are [feeling generous and want to contribute, feel free][9].
+This gem, in a nutshell, allows you to easily post an order, query payment
+status and fetch payment details.
+
+If you are [feeling generous and want to contribute, feel free][9].
 
 Submit [issues and requests here][6] and [find all the releases here][12].
 
@@ -19,11 +19,6 @@ The gem should be [up on RubyGems.org][7] and it's [accompanying RubyDoc referen
 _Ps: No 3rd party oAuth library dependencies, it handles all the oAuth flows on
 it's own so your app is one dependency less._
 
-_Ps 2: We are still at pre-release stage ... target is version 1.0.0 for a
-public release (suitable for production deployment with the basic functionality
-in place). As a result always check the documentation carefully on upgrades to
-mitigate breaking changes._
-
 
 Installation
 ------------
@@ -49,7 +44,13 @@ Usage
 -----
 
 
-### Setup ###
+### Initialization ###
+
+There are 3 ways to initialize the Pesapal object:
+
+1. YAML config at `/config/pesapal.yml` (default & recommended)
+2. YAML config at custom location
+3. Config hash
 
 Initialize Pesapal object and choose the mode, there are two modes;
 `:development` and `:production`. They determine if the code will interact
@@ -60,12 +61,18 @@ with the testing or the live Pesapal API.
 pesapal = Pesapal::Merchant.new(:development)
 ```
 
-You can set the configuration details from a YAML file at the location of your
-choice upon initialization as shown in the example below for a Rails app. The
-second parameter is optional and has a default value of
-`"#{Rails.root}/config/pesapal.yml"` if left out as in the example above. In
-this case, please note that this YAML file is only loaded when your application
-starts and not everytime an object is initialized.
+####Option 1####
+
+In the case, the configuration has already been loaded (at application start by
+initializer) from a YAML file located at `"#{Rails.root}/config/pesapal.yml"` by
+default. This is the recommended method.
+
+####Option 2####
+
+It's also possible to set the configuration details from a YAML file at the
+location of your choice upon initialization as shown in the example below. This
+option overrides the default YAML config (explained above) and will be loaded
+everytime during initialization (which is not a good idea for production).
 
 ```ruby
 # initiate pesapal object set to development mode and use the YAML file found at
@@ -73,6 +80,29 @@ starts and not everytime an object is initialized.
 pesapal = Pesapal::Merchant.new(:development, "<PATH_TO_YAML_FILE>")
 ```
 
+####Option 3####
+
+If you wish not to use the YAML config method or the YAML file for some reason
+does not exist, then the object is set up with some bogus credentials which
+would not work anyway and therefore, the other option is that you set them
+yourself. Which, you can do using a hash as shown below (please note that
+Pesapal provides different keys for different modes and since this is like an
+override, there's the assumption that you chose the right one).
+
+```ruby
+# set pesapal api configuration manually (override YAML & bogus credentials)
+pesapal.config = {  :callback_url => 'http://0.0.0.0:3000/pesapal/callback'
+                    :consumer_key => '<YOUR_CONSUMER_KEY>',
+                    :consumer_secret => '<YOUR_CONSUMER_SECRET>'
+                  }
+```
+
+_Ps: You can change the mode using `pesapal.set_mode(:development)` (example) if
+for some reason you want to override what was set in the constructor._
+
+
+###YAML Configuration###
+
 The YAML file should look something like this. If you ran the generator you
 should have it already in place with some default values. Feel free to change
 them appropriately.
@@ -89,27 +119,8 @@ production:
     consumer_secret: '<YOUR_CONSUMER_SECRET>'
 ```
 
-If the YAML file does not exist, then the object is set up with some bogus
-credentials which would not work anyway and therefore, the next logical step is
-that you set them yourself. Which, you can do using a hash as shown below
-(please note that Pesapal provides different keys for different modes and since
-this is like an override, there's the assumption that you chose the right one).
-
-```ruby
-# set pesapal api configuration manually (override YAML & bogus credentials)
-pesapal.config = {  :callback_url => 'http://0.0.0.0:3000/pesapal/callback'
-                    :consumer_key => '<YOUR_CONSUMER_KEY>',
-                    :consumer_secret => '<YOUR_CONSUMER_SECRET>'
-                  }
-```
-
-_Ps: Make sure this hash has the appropriate values before running any methods
-that interact with the API as the methods pick from these values. This means
-that you can also override them at runtime for a truly dynamic/complex app that
-might have different values for different scenarios._
-
 
-### Post Order ###
+### Posting An Order ###
 
 Once you've finalized the configuration, set up the order details in a hash as
 shown in the example below ... all keys **MUST** be present. If there's one that
@@ -149,6 +160,50 @@ url. Refer to [official Pesapal Step-By-Step integration guide][18] for more
 details._
 
 
+### Querying Payment Status ###
+
+Use this to query the status of the transaction. When a transaction is posted to
+Pesapal, it may be in a PENDING, COMPLETED, FAILED or INVALID state. If the
+transaction is PENDING, the payment may complete or fail at a later stage.
+
+Both the unique merchant reference generated by your system (compulsory) and the
+pesapal transaction tracking id (optional) are input parameters to this method
+but if you don't ensure that the merchant reference is unique for each order on
+your system, you may get INVALID as the response. Because of this, it is
+recommended that you provide both the merchant reference and transaction
+tracking id as parameters to guarantee uniqueness.
+
+```ruby
+# option 1: using merchant reference only
+payment_status = pesapal.query_payment_status("<MERCHANT_REFERENCE>")
+
+# option 2: using merchant reference and transaction id (recommended)
+payment_status = pesapal.query_payment_status("<MERCHANT_REFERENCE>","<TRANSACTION_ID>")
+```
+
+
+### Querying Payment Details ###
+
+Same as querying payment status above, but the return value contains more
+information (and is a hash as opposed to a string).
+
+```ruby
+# pass in merchant reference and transaction id
+payment_details = pesapal.query_payment_details("<MERCHANT_REFERENCE>","<TRANSACTION_ID>")
+```
+
+The result is a hash that looks something like this ...
+
+```
+{ 
+  :method=>"MPESA",
+  :status=>"COMPLETED",
+  :merchant_reference=>"<MERCHANT_REFERENCE>",
+  :transaction_tracking_id=>"<TRANSACTION_ID>"
+}
+```
+
+
 Contributing
 ------------
 

data/lib/pesapal/merchant/details.rb

@@ -0,0 +1,24 @@
+module Pesapal
+
+    module Details
+        
+        # set parameters required by the QueryPaymentDetails call
+        def Details.set_parameters(consumer_key, merchant_reference, transaction_tracking_id)
+
+            # parameters required by the QueryPaymentDetails call (excludes
+            # oauth_signature parameter as per the instructions here
+            # http://developer.pesapal.com/how-to-integrate/api-reference#QueryPaymentDetails)
+            
+            timestamp = Time.now.to_i.to_s
+
+            params = { :oauth_consumer_key => consumer_key,
+                       :oauth_nonce => "#{timestamp}" + Pesapal::Oauth.generate_nonce(12),
+                       :oauth_signature_method => 'HMAC-SHA1',
+                       :oauth_timestamp => "#{timestamp}",
+                       :oauth_version => '1.0',
+                       :pesapal_merchant_reference => merchant_reference,
+                       :pesapal_transaction_tracking_id => transaction_tracking_id
+                    }
+        end
+    end
+end

data/lib/pesapal/merchant/post.rb

@@ -28,7 +28,7 @@ module Pesapal
             "#{post_xml}"
         end
         
-        # set parameters required by the PostPesapalDirectOrderV4 
+        # set parameters required by the PostPesapalDirectOrderV4 call
         def Post.set_parameters(callback_url, consumer_key, post_xml)
 
             # parameters required by the PostPesapalDirectOrderV4 call (excludes

data/lib/pesapal/merchant/status.rb

@@ -0,0 +1,29 @@
+module Pesapal
+
+    module Status
+        
+        # set parameters required by the QueryPaymentStatus & QueryPaymentStatusByMerchantRef calls
+        def Status.set_parameters(consumer_key, merchant_reference, transaction_tracking_id = nil)
+
+            # parameters required by the QueryPaymentStatus call (excludes
+            # oauth_signature parameter as per the instructions here
+            # http://developer.pesapal.com/how-to-integrate/api-reference)
+            
+            timestamp = Time.now.to_i.to_s
+
+            params = { :oauth_consumer_key => consumer_key,
+                       :oauth_nonce => "#{timestamp}" + Pesapal::Oauth.generate_nonce(12),
+                       :oauth_signature_method => 'HMAC-SHA1',
+                       :oauth_timestamp => "#{timestamp}",
+                       :oauth_version => '1.0',
+                       :pesapal_merchant_reference => merchant_reference
+                    }
+
+            unless transaction_tracking_id.nil? # do, if not true
+                params[:pesapal_transaction_tracking_id] = transaction_tracking_id
+            end
+
+            params
+        end
+    end
+end

data/lib/pesapal/merchant.rb

@@ -3,15 +3,6 @@ module Pesapal
     class Merchant
 
         attr_accessor :config, :order_details
-        attr_reader :api_domain, :api_endpoints
-
-        def api_domain
-            @api_domain
-        end
-
-        def api_endpoints
-            @api_endpoints
-        end
 
         def config
             @config
@@ -23,6 +14,14 @@ module Pesapal
 
         private
 
+            def api_domain
+                @api_domain
+            end
+
+            def api_endpoints
+                @api_endpoints
+            end
+
             def mode
                 @mode
             end
@@ -49,8 +48,7 @@ module Pesapal
                 @post_xml = nil
                 @token_secret = nil
 
-                # convert symbol to string and downcase
-                @mode = "#{mode.to_s.downcase}"
+                set_mode mode
 
                 # set the credentials if we have not set a custom path for the YAML config file
                 if path_to_file.nil?
@@ -61,8 +59,6 @@ module Pesapal
                     set_configuration_from_yaml path_to_file
                 end
 
-                # set api endpoints depending on the mode
-                set_endpoints
             end
 
             # generate pesapal order url (often iframed)
@@ -72,7 +68,7 @@ module Pesapal
                 # required
                 @post_xml = Pesapal::Post::generate_post_xml @order_details
 
-                # initialize setting of @params (oauth_signature left empty) ... this gene
+                # initialize setting of @params (oauth_signature left empty)
                 @params = Pesapal::Post::set_parameters(@config[:callback_url], @config[:consumer_key], @post_xml)
 
                 # generate oauth signature and add signature to the request parameters
@@ -84,6 +80,59 @@ module Pesapal
                 "#{@api_endpoints[:postpesapaldirectorderv4]}?#{query_string}"
             end
 
+            # query the details of the transaction
+            def query_payment_details(merchant_reference, transaction_tracking_id)
+
+                # initialize setting of @params (oauth_signature left empty)
+                @params = Pesapal::Details::set_parameters(@config[:consumer_key], merchant_reference, transaction_tracking_id)
+
+                # generate oauth signature and add signature to the request parameters
+                @params[:oauth_signature] = Pesapal::Oauth::generate_oauth_signature("GET", @api_endpoints[:querypaymentdetails], @params, @config[:consumer_secret], @token_secret)
+
+                # change params (with signature) to a query string
+                query_string = Pesapal::Oauth::generate_encoded_params_query_string @params
+
+                # get status response
+                response = Net::HTTP.get(URI("#{@api_endpoints[:querypaymentdetails]}?#{query_string}"))
+                response = CGI::parse(response)
+                response = response["pesapal_response_data"][0].split(',')
+
+                details = { :method => response[1],
+                            :status => response[2],
+                            :merchant_reference => response[3],
+                            :transaction_tracking_id => response[0] }
+            end
+
+            # query the status of the transaction
+            def query_payment_status(merchant_reference, transaction_tracking_id = nil)
+                
+                # initialize setting of @params (oauth_signature left empty)
+                @params = Pesapal::Status::set_parameters(@config[:consumer_key], merchant_reference, transaction_tracking_id)
+
+                # generate oauth signature and add signature to the request parameters
+                @params[:oauth_signature] = Pesapal::Oauth::generate_oauth_signature("GET", @api_endpoints[:querypaymentstatus], @params, @config[:consumer_secret], @token_secret)
+
+                # change params (with signature) to a query string
+                query_string = Pesapal::Oauth::generate_encoded_params_query_string @params
+
+                # get status response
+                response = Net::HTTP.get(URI("#{@api_endpoints[:querypaymentstatus]}?#{query_string}"))
+                response = CGI::parse(response)
+
+                # return the string result of what we want
+                response["pesapal_response_data"][0]
+            end
+
+            # set mode when called
+            def set_mode(mode = :development)
+                
+                # convert symbol to string and downcase
+                @mode = "#{mode.to_s.downcase}"
+
+                # set api endpoints depending on the mode
+                set_endpoints
+            end
+
         private
 
             # set endpoints
@@ -98,7 +147,6 @@ module Pesapal
                 @api_endpoints = {}
                 @api_endpoints[:postpesapaldirectorderv4] = "#{@api_domain}/API/PostPesapalDirectOrderV4"
                 @api_endpoints[:querypaymentstatus] = "#{@api_domain}/API/QueryPaymentStatus"
-                @api_endpoints[:querypaymentstatusbymerchantref] = "#{@api_domain}/API/QueryPaymentStatus"
                 @api_endpoints[:querypaymentdetails] = "#{@api_domain}/API/QueryPaymentDetails"
             end
 

data/lib/pesapal/version.rb

@@ -1,3 +1,3 @@
 module Pesapal
-    VERSION = "0.2.1"
+    VERSION = "1.0.0"
 end

data/lib/pesapal.rb

@@ -1,7 +1,9 @@
 require "rails"
 require "htmlentities"
 require "pesapal/merchant"
+require "pesapal/merchant/details"
 require "pesapal/merchant/post"
+require "pesapal/merchant/status"
 require "pesapal/oauth"
 require "pesapal/version"
 

data/pesapal.gemspec

@@ -5,7 +5,7 @@ require "pesapal/version"
 Gem::Specification.new do |spec|
     spec.name          = "pesapal"
     spec.version       = Pesapal::VERSION
-    spec.date          = "2013-10-13"
+    spec.date          = Time.new.getlocal("+03:00").strftime("%Y-%m-%d")
     spec.authors       = ["Job King'ori Maina"]
     spec.email         = ["j@kingori.co"]
     spec.description   = "Make authenticated Pesapal API calls without the fuss!"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pesapal
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Job King'ori Maina
@@ -71,7 +71,9 @@ files:
 - lib/generators/templates/pesapal.yml
 - lib/pesapal.rb
 - lib/pesapal/merchant.rb
+- lib/pesapal/merchant/details.rb
 - lib/pesapal/merchant/post.rb
+- lib/pesapal/merchant/status.rb
 - lib/pesapal/oauth.rb
 - lib/pesapal/version.rb
 - pesapal.gemspec