pesapal 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: be6b9604e4788df7261b80d64ae81c03181af7b5
+  data.tar.gz: 08721ecf0cd162eeca31abe10a448477bd482ed1
+SHA512:
+  metadata.gz: 533b27e99df804b0b7678b2e03ca495cb57c4ef537ffdb6d1b50c29e5fdc868b915694ec683c2f091b86c92e8dd634300bad094a3ec67f02ad414088361cefea
+  data.tar.gz: 5631b6072f4ce540e87cc7a00864c9ab4a7b66898c42f1b54b4d84cde00aa23882e5fe385ca7605779a57e80f8155544bc0ac2a44f3098816b6721a87c18a2e6

data/.gitignore

@@ -0,0 +1,13 @@
+# Ignore bundler config #
+/.bundle
+
+# Ignore bundled gems #
+/vendor/bundle
+
+# Ignore all logfiles and tempfiles #
+/log/*
+/tmp/*
+
+# Other Files #
+*.gem
+Gemfile.lock

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in pesapal.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 King'ori Maina
+
+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.

data/README.md

@@ -0,0 +1,119 @@
+Pesapal RubyGem
+===============
+
+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].
+
+Submit [issues and requests here][6]. The gem should be [up on RubyGems.org][7].
+
+_Ps: No 3rd party oAuth library dependencies, it handles all the oAuth flows on
+it's own so it's light on your app._
+
+
+Installation
+------------
+
+Add this line to your application's Gemfile:
+
+    gem 'pesapal'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install pesapal
+
+
+Usage
+-----
+
+### Setup ###
+
+Initialize Pesapal object and choose the mode, there are two modes;
+`:development` and `:production`. They determine if you the code will interact
+with Pesapal for testing or for a live deployment.
+
+```ruby
+# initiate pesapal object set to development mode
+pesapal = Pesapal::Merchant.new(:development)
+```
+
+Now set the Pesapal credentials. This assumes that you've chosen the appropriate
+credentials as they differ based on the mode chosen above (Pesapal provide the
+keys). Replace the placeholders below with your own credentials.
+
+```ruby
+# set pesapal api credentials
+pesapal.credentials = { :consumer_key => '<YOUR_CONSUMER_KEY>',
+                        :consumer_secret => '<YOUR_CONSUMER_SECRET>' 
+                    }
+```
+
+### Post Order ###
+
+Once you've set up the credentials, set up the order details in a hash as shown
+in the example below ... all keys **MUST** be present. If there's one that you
+wish to ignore just leave it with a blank string but make sure it's included
+e.g. the phonenumber.
+
+```ruby
+#set order details 
+pesapal.order_details = { :amount => 1000,
+                          :description => 'this is the transaction description',
+                          :type => 'MERCHANT',
+                          :reference => 808-707-606,
+                          :first_name => 'Swaleh',
+                          :last_name => 'Mdoe',
+                          :email => 'user@example.com',
+                          :phonenumber => '+254722222222'
+                        }
+```
+
+Then generate the transaction url as below. In the example, the value is
+assigned to the variable `order_url` which you can pass on to the templating
+system of your to generate an iframe.
+
+```ruby
+# generate transaction url
+order_url = pesapal.generate_order_url
+```
+
+
+Contributing
+------------
+
+1. [Fork it][8]
+2. Create your feature branch (`git checkout -b wip-my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature with awesome'`)
+4. Push to the branch (`git push origin wip-my-new-feature`)
+5. Create new pull request
+
+_Ps: Please prefix branch name with 'wip-' ... means 'work in progress'._
+
+
+References
+----------
+
+* [oAuth 1.0 Spec][1]
+* [Developing a RubyGem using Bundler][2]
+* [Make your own gem][3]
+* [Pesapal API Reference (Official)][4]
+* [Pesapal PHP API Reference (Unofficial)][5]
+
+[1]: http://oauth.net/core/1.0/
+[2]: https://github.com/radar/guides/blob/master/gem-development.md
+[3]: http://guides.rubygems.org/make-your-own-gem/
+[4]: http://developer.pesapal.com/how-to-integrate/api-reference
+[5]: https://github.com/itsmrwave/pesapal-php#pesapal-php-api-reference-unofficial
+[6]: https://github.com/itsmrwave/pesapal-rubygem/issues
+[7]: http://rubygems.org/gems/pesapal
+[8]: https://github.com/itsmrwave/pesapal-rubygem/fork
+[9]: https://github.com/itsmrwave/pesapal-rubygem#contributing

data/Rakefile

@@ -0,0 +1 @@
+require "bundler/gem_tasks"

data/lib/pesapal.rb

@@ -0,0 +1,6 @@
+require "htmlentities"
+require "pesapal/merchant"
+require "pesapal/merchant/post"
+require "pesapal/oauth"
+require "pesapal/version"
+

data/lib/pesapal/merchant.rb

@@ -0,0 +1,114 @@
+module Pesapal
+    
+    class Merchant
+
+        attr_accessor :callback_url, :credentials, :order_details
+        attr_reader :api_domain, :api_endpoints
+
+        def api_domain
+            @api_domain
+        end
+
+        def api_endpoints
+            @api_endpoints
+        end
+
+        def callback_url
+            @callback_url
+        end
+
+        def credentials
+            @credentials
+        end
+
+        def order_details
+            @order_details
+        end
+
+        private
+
+            def params
+                @params
+            end
+
+            def post_xml
+                @post_xml
+            end
+
+            def token_secret
+                @token_secret
+            end
+
+        public
+
+            # constructor
+            def initialize(mode = :development)
+
+                # convert symbol to string and downcase
+                mode.to_s.downcase!
+
+                # initialize
+                @params = nil
+                @post_xml = nil
+                @token_secret = nil
+
+                # set the credentials from the config (if initializers/pesapal.rb
+                # exists they should have set these values)
+                @credentials = nil
+
+                # set the callback url that the iframe will respond to
+                @callback_url = 'http://0.0.0.0:3000/pesapal/callback'
+
+                # set api endpoints depending on the mode
+                @api_endpoints = {}
+                if mode == 'development'
+                    set_endpoints_development
+                elseif mode == 'production'
+                    set_endpoints_production
+                else
+                    set_endpoints_development
+                end
+            end
+
+            # generate pesapal order url (often iframed)
+            def generate_order_url
+
+                # build xml with input data, the format is standard so no editing is
+                # required
+                @post_xml = Pesapal::Post::generate_post_xml @order_details
+
+                # initialize setting of @params (oauth_signature left empty) ... this gene
+                @params = Pesapal::Post::set_parameters(@callback_url, @credentials[:consumer_key], @post_xml)
+
+                # generate oauth signature and add signature to the request parameters
+                @params[:oauth_signature] = Pesapal::Oauth::generate_oauth_signature("GET", @api_endpoints[:postpesapaldirectorderv4], @params, @credentials[:consumer_secret], @token_secret)
+
+                # change params (with signature) to a query string
+                query_string = Pesapal::Oauth::generate_encoded_params_query_string @params
+
+                "#{@api_endpoints[:postpesapaldirectorderv4]}?#{query_string}"
+            end
+
+        private
+
+            # set all endpoint for use in development mode
+            def set_endpoints_development
+                @api_domain = 'http://demo.pesapal.com'
+                set_endpoints @api_domain
+            end
+
+            # set all enpoints for use in production mode
+            def set_endpoints_production
+                @api_domain = "https://www.pesapal.com"
+                set_endpoints @api_domain
+            end
+
+            # set endpoints
+            def set_endpoints(domain_string)
+                @api_endpoints[:postpesapaldirectorderv4] = "#{domain_string}/API/PostPesapalDirectOrderV4"
+                @api_endpoints[:querypaymentstatus] = "#{domain_string}/API/QueryPaymentStatus"
+                @api_endpoints[:querypaymentstatusbymerchantref] = "#{domain_string}/API/QueryPaymentStatus"
+                @api_endpoints[:querypaymentdetails] = "#{domain_string}/API/QueryPaymentDetails"
+            end
+    end
+end

data/lib/pesapal/merchant/post.rb

@@ -0,0 +1,50 @@
+module Pesapal
+
+    module Post
+
+        # build html encoded xml string for PostPesapalDirectOrderV4
+        def Post.generate_post_xml(details)
+            
+            # build xml with input data, the format is standard so no editing is
+            # required
+            post_xml = ''
+            post_xml.concat '<?xml version="1.0" encoding="utf-8"?>'
+            post_xml.concat '<PesapalDirectOrderInfo '
+            post_xml.concat 'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" '
+            post_xml.concat 'xmlns:xsd="http://www.w3.org/2001/XMLSchema" '
+            post_xml.concat "Amount=\"#{details[:amount]}\" "
+            post_xml.concat "Description=\"#{details[:description]}\" "
+            post_xml.concat "Type=\"#{details[:type]}\" "
+            post_xml.concat "Reference=\"#{details[:reference]}\" "
+            post_xml.concat "FirstName=\"#{details[:first_name]}\" "
+            post_xml.concat "LastName=\"#{details[:last_name]}\" "
+            post_xml.concat "Email=\"#{details[:email]}\" "
+            post_xml.concat "PhoneNumber=\"#{details[:phonenumber]}\" "
+            post_xml.concat 'xmlns="http://www.pesapal.com" />'
+
+            encoder = HTMLEntities.new(:xhtml1)
+            post_xml = encoder.encode post_xml
+
+            "#{post_xml}"
+        end
+        
+        # set parameters required by the PostPesapalDirectOrderV4 
+        def Post.set_parameters(callback_url, consumer_key, post_xml)
+
+            # parameters required by the PostPesapalDirectOrderV4 call (excludes
+            # oauth_signature parameter as per the instructions here
+            # http://developer.pesapal.com/how-to-integrate/api-reference#PostPesapalDirectOrderV4)
+            
+            timestamp = Time.now.to_i.to_s
+
+            params = { :oauth_callback => callback_url,
+                       :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_request_data => post_xml
+                    }
+        end
+    end
+end

data/lib/pesapal/oauth.rb

@@ -0,0 +1,178 @@
+module Pesapal
+
+    module Oauth
+
+        # generate query string from parameters hash
+        def Oauth.generate_encoded_params_query_string(params = {})
+
+            # 1) percent encode every key and value that will be signed
+            # 2) sort the list of parameters alphabetically by encoded key
+            # 3) for each key/value pair
+            # - append the encoded key to the output string
+            # - append the '=' character to the output string
+            # - append the encoded value to the output string
+            # 4) if there are more key/value pairs remaining, append a '&'
+            # character to the output string
+
+            #  the oauth spec says to sort lexigraphically, which is the default
+            #  alphabetical sort for many libraries. in case of two parameters
+            #  with the same encoded key, the oauth spec says to continue
+            #  sorting based on value
+
+            queries = []
+            params.each do |k,v| queries.push "#{self.parameter_encode(k.to_s)}=#{self.parameter_encode(v.to_s)}" end
+
+            # parameters are sorted by name, using lexicographical byte value
+            # ordering
+            queries.sort!
+            
+            queries.join('&')
+        end
+
+        # generate oauth nonce
+        def Oauth.generate_nonce(length)
+
+            # the consumer shall then generate a nonce value that is unique for
+            # all requests with that timestamp. a nonce is a random string,
+            # uniquely generated for each request. the nonce allows the service
+            # provider to verify that a request has never been made before and
+            # helps prevent replay attacks when requests are made over a non-
+            # secure channel (such as http).
+
+            chars = 'abcdefghjkmnpqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ0123456789'
+            nonce = ''
+            length.times { nonce << chars[rand(chars.size)] }
+
+            "#{nonce}"
+        end
+
+        # generate the oauth signature using hmac-sha1 algorithm
+        def Oauth.generate_oauth_signature(http_method, absolute_url, params, consumer_secret, token_secret = nil)
+
+            # the signature is calculated by passing the signature base string
+            # and signing key to the hmac-sha1 hashing algorithm. the output of
+            # the hmac signing function is a binary string. this needs to be
+            # base64 encoded to produce the signature string.
+
+            # for pesapal flow we don't have a token secret to we will set as
+            # nil and the appropriate action will be taken as per the oauth
+            # spec. see notes in the method that creates signing keys
+            
+            # prepare the values we need
+            digest = OpenSSL::Digest::Digest.new('sha1')
+            signature_base_string = self.generate_signature_base_string(http_method, absolute_url, params)
+            signing_key = self.generate_signing_key(consumer_secret, token_secret)
+
+            hmac = OpenSSL::HMAC.digest(digest, signing_key, signature_base_string)
+            Base64.encode64(hmac).chomp
+        end
+
+        # generate query string from signable parameters hash
+        def Oauth.generate_signable_encoded_params_query_string(params = {})
+
+            # oauth_signature parameter MUST be excluded, assumes it was already
+            # initialized by calling set_parameters
+            params.delete(:oauth_signature)
+
+            self.generate_encoded_params_query_string params
+        end
+
+        # generate the oauth signature
+        def Oauth.generate_signature_base_string(http_method, absolute_url, params)
+
+            #  three values collected so far must be joined to make a single
+            #  string, from which the signature will be generated. This is
+            #  called the signature base string by the OAuth specification
+
+            # step 1: convert the http method to uppercase
+            http_method = http_method.upcase
+
+            # step 2: percent encode the url
+            url_encoded = self.parameter_encode(self.normalized_request_uri(absolute_url))
+
+            # step 3: percent encode the parameter string
+            parameter_string_encoded = self.parameter_encode(self.generate_signable_encoded_params_query_string params)
+
+            # the signature base string should contain exactly 2 ampersand '&'
+            # characters. The percent '%' characters in the parameter string should
+            # be encoded as %25 in the signature base string
+
+            "#{http_method}&#{url_encoded}&#{parameter_string_encoded}"
+        end
+
+        # generate signing key
+        def Oauth.generate_signing_key(consumer_secret, token_secret = nil)
+
+            # the signing key is simply the percent encoded consumer secret,
+            # followed by an ampersand character '&', followed by the percent
+            # encoded token secret
+
+            # note that there are some flows, such as when obtaining a request
+            # token, where the token secret is not yet known. In this case, the
+            # signing key should consist of the percent encoded consumer secret
+            # followed by an ampersand character '&'
+
+            # "#{@credentials[:consumer_secret]}"
+            consumer_secret_encoded = self.parameter_encode(consumer_secret)
+
+            token_secret_encoded = ""
+            unless token_secret.nil?
+                token_secret_encoded = self.parameter_encode(token_secret)
+            end
+
+            "#{consumer_secret_encoded}&#{token_secret_encoded}"
+        end
+
+        # normalize request absolute URL
+        def Oauth.normalized_request_uri(absolute_url)
+
+            # the signature base string includes the request absolute url, tying
+            # the signature to a specific endpoint. the url used in the
+            # signature base string must include the scheme, authority, and
+            # path, and must exclude the query and fragment as defined by
+            # [rfc3986] section 3.
+
+            # if the absolute request url is not available to the service
+            # provider (it is always available to the consumer), it can be
+            # constructed by combining the scheme being used, the http host
+            # header, and the relative http request url. if the host header is
+            # not available, the service provider should use the host name
+            # communicated to the consumer in the documentation or other means.
+
+            # the service provider should document the form of url used in the
+            # signature base string to avoid ambiguity due to url normalization.
+            # unless specified, url scheme and authority must be lowercase and
+            # include the port number; http default port 80 and https default
+            # port 443 must be excluded.
+          
+            u = URI.parse(absolute_url)
+
+            scheme = u.scheme.downcase
+            host = u.host.downcase
+            path = u.path
+            port = u.port
+
+            port = (scheme == 'http' && port != 80) || (scheme == 'https' && port != 443) ? ":#{port}" : ""
+            path = (path && path != '') ? path : '/'
+
+            "#{scheme}://#{host}#{port}#{path}"
+        end
+
+        # percentage encode value as per the oauth spec
+        def Oauth.parameter_encode(string)
+
+            # all parameter names and values are escaped using the [rfc3986]
+            # percent-encoding (%xx) mechanism. characters not in the unreserved
+            # character set ([rfc3986] section 2.3) must be encoded. characters
+            # in the unreserved character set must not be encoded. hexadecimal
+            # characters in encodings must be upper case. text names and values
+            # must be encoded as utf-8 octets before percent-encoding them per
+            # [rfc3629].
+
+            # reserved character regexp, per section 5.1
+            reserved_characters = /[^a-zA-Z0-9\-\.\_\~]/
+
+            URI::escape(string.to_s.force_encoding(Encoding::UTF_8), reserved_characters)
+        end
+    end
+end

data/lib/pesapal/version.rb

@@ -0,0 +1,3 @@
+module Pesapal
+    VERSION = "0.0.1"
+end

data/pesapal.gemspec

@@ -0,0 +1,23 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "pesapal/version"
+
+Gem::Specification.new do |spec|
+    spec.name          = "pesapal"
+    spec.version       = Pesapal::VERSION
+    spec.date          = "2013-09-28"
+    spec.authors       = ["Job King'ori Maina"]
+    spec.email         = ["j@kingori.co"]
+    spec.description   = "Make authenticated Pesapal API calls without the fuss!"
+    spec.summary       = "Make authenticated Pesapal API calls without the fuss! Handles all the oAuth stuff abstracting any direct interaction with the API endpoints so that you can focus on what matters. Building awesome."
+    spec.homepage      = "http://rubygems.org/gems/pesapal"
+    spec.license       = "MIT"
+
+    spec.files         = `git ls-files`.split($/)
+    spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+    spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+    spec.require_paths = ["lib"]
+
+    spec.add_development_dependency "bundler", "~> 1.3"
+    spec.add_development_dependency "rake"
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: pesapal
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Job King'ori Maina
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Make authenticated Pesapal API calls without the fuss!
+email:
+- j@kingori.co
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/pesapal.rb
+- lib/pesapal/merchant.rb
+- lib/pesapal/merchant/post.rb
+- lib/pesapal/oauth.rb
+- lib/pesapal/version.rb
+- pesapal.gemspec
+homepage: http://rubygems.org/gems/pesapal
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.1.5
+signing_key: 
+specification_version: 4
+summary: Make authenticated Pesapal API calls without the fuss! Handles all the oAuth
+  stuff abstracting any direct interaction with the API endpoints so that you can
+  focus on what matters. Building awesome.
+test_files: []