webpay_interswitch 1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3e59162aaf80b3b37d6feb352229568cb5a180f0
+  data.tar.gz: 256eb634543a590ca016bf67888b634cf2be8c18
+SHA512:
+  metadata.gz: f30180b731e9c48d3345b78556b683d1e7ed90e7c1f428ec1324cae79a28cea9b484464ae510605eb2e3d6495feb846ed3403ba906c0cade746d645c413e614c
+  data.tar.gz: 4034b8020a85b0a57bbdc74fd82076192cf81834d9584776a72d1d405df5a671fd20f1f4780d061d3d5bf05ffbafdea732e0be7dd88eef6e96e6cd5ac2067bdb

data/README.md

@@ -0,0 +1,97 @@
+#WebpayInterswitch
+
+
+[![Code Climate](https://codeclimate.com/github/vinsol/webpay_interswitch.png)](https://codeclimate.com/github/vinsol/webpay_interswitch)
+
+
+A simple gem to integrate your Rails app with [Webpay Interswitch](http://www.interswitchng.com/), a nigerian payment gateway. It provides methods to add webpay as a payment option in your Rails application out of the box. It also provides a simple API that can be used to fetch transactions (JSON Only).
+
+##Getting Started
+
+
+Include the gem in your Rails app by adding it to Gemfile:
+
+ `gem 'webpay_interswitch'` and run 
+
+ `bundle install`
+
+And then:
+
+ `rails generate webpay_interswitch:install`
+ 
+The generator will install an initializer which adds the configuration options for setting up the gateway from the webpay_interswitch.yml file.
+
+It also adds a `webpay_interswitch.yml.example` file which should be considered as a reference while setting up the gateway. Create `webpay_interswitch.yml` file in `config` directory and specify your mac_key, product_id, pay_item_id etc.
+
+
+##Helper
+
+
+It comes with a helper method that seamlessly adds a webpay form to your Rails application.
+
+```ruby
+    <%= form_for_webpay(txn_ref, amount) %>
+```
+
+This helper adds a button (Along with all the hidden elements required to make the transaction). You can also configure the text that appears on the button and add any valid html attributes to it like:
+
+```ruby
+    <%= form_for_webpay(txn_ref, amount, { submit_button_text: 'Make Payment', class: 'btn-class' }) %>
+```
+
+txn_ref must be a globally unique number generated by your application. Each request that hits the gateway must have a unique value of txn_ref. To avoid polluting the global space, consider prefixing it with a specific string. E.g. my_app_1, my_app_2 and so on for each transaction.
+
+The gateway accepts the amount only in Kobo. So, you must always pass the amount after converting the amount in Naira to Kobo.
+
+Once you click the submit button, you'll be redirected to the Webpay to carry out the transaction. Upon completion(success or failure), Webpay will send a POST request to the redirect URL along with a few parameters. Remember that the helper generates an HTML form for itself. So, make sure it is not placed inside another HTML form.
+
+
+##Querying Transactions
+
+
+The gem provides an API that should be used to query the transaction.
+
+Create an object of WebpayInterswitch::Transaction using:
+
+```ruby
+    transaction = WebpayInterswitch::TransactionQuery.new(params, amount)
+```
+
+It accepts the params hash that is sent by the gateway to the redirect URL. The amount of the transaction is a required parameter and must be set to ensure the payment amount was not tampered.
+
+You can then call methods on this object like:
+
+```ruby
+    transaction.success?
+    
+    transaction.fetch_response
+
+    transaction.full_error_message
+```
+
+##Configurations Parameters
+
+
+Below parameters are needed to setup the gateway.
+
+* product_id: It is provided when you sign up for interswitch webpay.
+    
+* pay_item_id: It is provided when you sign up for interswitch webpay.
+
+* site_redirect_url: This is the URL where the interswitch redirects back with a POST request when the transaction is complete (Successful Or Failed). This is the controller action, where you want to process the transaction response using `WebpayInterswitch::TransactionQuery` class.
+
+* mac_key: It is provided when you sign up for interswitch webpay.
+
+* currency (Optional, defaults to Naira): Currently, we only support Naira. Currency Code for Naira is `566`. The payment amount is always specified in Kobo. While interfacing with the gem, you must always pass in the amount in Kobo. `Conversion: 1 Naira = 100 Kobo`
+
+* test (Optional, defaults to true): This is used to specify Interswitch URL. If true, all the requests are made at the test gateway. For production environments (Making actual payments), you must set this explicitly to false. By default, it would always be set to true.
+
+## Find a Demo Application
+
+##### [Interswitch Demo](https://github.com/vinsol/webpay_interswitch_gem_demo_app)
+
+##Credits
+[![vinsol.com: Ruby on Rails, iOS and Android developers](http://vinsol.com/vin_logo.png "Ruby on Rails, iOS and Android developers")](http://vinsol.com)
+
+Copyright (c) 2014 [vinsol.com](http://vinsol.com "Ruby on Rails, iOS and Android developers"), released under the New MIT License
+

data/lib/generators/webpay_interswitch/install_generator.rb

@@ -0,0 +1,16 @@
+module WebpayInterswitch
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("../../../../templates", __FILE__)
+
+      def create_webpay_yml
+        copy_file 'webpay_interswitch.yml.example', 'config/webpay_interswitch.yml.example'
+      end
+
+      def create_webpay_initializer
+        copy_file 'webpay.rb', 'config/initializers/webpay.rb'
+      end
+
+    end
+  end
+end

data/lib/webpay_interswitch.rb

@@ -0,0 +1,7 @@
+require 'webpay_interswitch/view_helper.rb'
+require 'webpay_interswitch/core.rb'
+require 'webpay_interswitch/form_builder.rb'
+require 'webpay_interswitch/gateway.rb'
+require 'webpay_interswitch/transaction_query.rb'
+
+ActionView::Base.send(:include, WebpayInterswitch::ViewHelper) if defined?(::Rails)

data/lib/webpay_interswitch/core.rb

@@ -0,0 +1,10 @@
+module WebpayInterswitch
+  module Core
+
+    ## Returns the sha hash to be sent to webpay with params for querying or making payment.
+    def sha_hash(message='')
+      Digest::SHA512.hexdigest(message)
+    end
+
+  end
+end

data/lib/webpay_interswitch/form_builder.rb

@@ -0,0 +1,81 @@
+module WebpayInterswitch
+  class FormBuilder
+
+    include WebpayInterswitch::Core
+
+    def initialize(txn_ref, amount, html_options)
+      @txn_ref = txn_ref
+      @amount = amount
+      @html_options = html_options
+      sanitize_options
+    end
+
+    def generate_webpay_form
+      form_html = "<form action=#{ WebpayInterswitch::Gateway.url } method=post>"
+
+      form_html += generate_webpay_elements
+
+      form_html += generate_transaction_data_elements
+
+      # This generates the submit button alongwith the @submit_button_text
+      # If submit_button_text is not provided, it defaults to 'Make Payment'
+      form_html += generate_input_field('commit', @submit_button_text, 'submit', @html_options)
+
+      form_html += '</form>'
+
+    end
+
+    def valid?
+      @txn_ref.present? && Integer(@amount.to_s) > 0 rescue false
+    end
+
+    private
+
+      def generate_webpay_elements
+        webpay_elem_html = ''
+        %w(product_id pay_item_id currency site_redirect_url).each do |field_name|
+          webpay_elem_html += generate_input_field(field_name, WebpayInterswitch::Gateway.public_send("#{ field_name }"))
+        end
+        webpay_elem_html
+      end
+
+      def generate_transaction_data_elements
+        txn_elem_html  = generate_input_field('txn_ref', @txn_ref)
+        txn_elem_html += generate_input_field('amount', @amount)
+        txn_elem_html += generate_input_field('hash', sha_hash(string_for_hash_param))
+      end
+
+      # Generates the input tag alongwith the provided name, value, type and html_options if any.
+      def generate_input_field(name, value, type = 'hidden', html_options={})
+        html_string = string_for_html_options(html_options)
+        "<input type=#{ type } name=#{ name } value='#{ value }' #{html_string}>"
+      end
+
+      ## Returns a string that is used to compute the sha hash for POST request on webpay.
+      def string_for_hash_param
+        @txn_ref.to_s +
+        WebpayInterswitch::Gateway.product_id +
+        WebpayInterswitch::Gateway.pay_item_id +
+        @amount.to_s +
+        WebpayInterswitch::Gateway.site_redirect_url +
+        WebpayInterswitch::Gateway.mac_key
+      end
+
+      ## Returns a string from html_options that is embedded into the submit button.
+      ## e.g: html_options = {id: 'hi', class: 'c1 c2'}
+      ## output: "id='hi' class='c1 c2'"
+      def string_for_html_options(html_options)
+        html_string = ''
+        html_options.each do |attr, val|
+          html_string << " #{attr}='#{val}'"
+        end
+        html_string
+      end
+
+      def sanitize_options
+        @html_options.symbolize_keys!
+        @submit_button_text = @html_options.delete(:submit_button_text) || 'Make Payment'
+      end
+
+  end
+end

data/lib/webpay_interswitch/gateway.rb

@@ -0,0 +1,55 @@
+module WebpayInterswitch
+
+  class MissingParameterError < StandardError; end
+  class UnsupportedCurrencyError < StandardError; end
+
+  class Gateway
+
+    cattr_accessor :product_id, :pay_item_id, :currency, :site_redirect_url, :mac_key, :test
+
+    TEST_URL = 'https://stageserv.interswitchng.com/test_paydirect/pay'
+
+    LIVE_URL = 'https://webpay.interswitchng.com/paydirect/pay'
+
+    ## ACCEPTED_CURRENCIES:
+    ## * Naira (In Kobo)
+
+    ACCEPTED_CURRENCIES = ['566']
+
+    def self.url
+      WebpayInterswitch::Gateway.test ? TEST_URL : LIVE_URL
+    end
+
+    def self.setup
+      yield self
+      set_defaults!
+    end
+
+    def validate!
+      requires!(:product_id, :pay_item_id, :currency, :site_redirect_url, :mac_key)
+      validate_currency!
+    end
+
+    private
+
+      def self.set_defaults!
+        # Default currency to Naira (Kobo)
+        @@currency ||= '566'
+
+        ## Default test to true.
+        ## Set this to false explicitly only in production environment.
+        @@test ||= false
+      end
+
+      def requires!(*required_parameters)
+        required_parameters.each do |parameter|
+          raise WebpayInterswitch::MissingParameterError if (self.public_send(parameter).blank?)
+        end
+      end
+
+      def validate_currency!
+        raise WebpayInterswitch::UnsupportedCurrencyError unless ACCEPTED_CURRENCIES.include?(@@currency.to_s)
+      end
+  end
+
+end

data/lib/webpay_interswitch/transaction_query.rb

@@ -0,0 +1,91 @@
+require 'net/http'
+module WebpayInterswitch
+
+  #################################################################################################
+  ## This class can be used to fetch transaction details
+  ## Initialization Parameters:
+  ##
+  ## post_params: Parameters sent via POST by the gateway at the redirect_url
+  ## amount: This is needed to detect the masquerading or parameter tampering to alter the amount.
+  ## WebpayInterswitch::TransactionQuery.new(params, amount)
+  ##################################################################################################
+
+
+  class TransactionQuery
+
+    include WebpayInterswitch::Core
+
+    # resp and desc are empty when transaction is successful
+    # txnref is the unique number sent in request.
+    # cardNum is always zero
+    # apprAmt is always zero
+    # response is populated when a transactions search query is sent.
+    attr_accessor :txnref, :resp, :desc, :payRef, :retRef, :cardNum, :amount, :response
+
+    TEST_URL = 'https://stageserv.interswitchng.com/test_paydirect/api/v1/gettransaction.json'
+
+    LIVE_URL = 'https://webpay.interswitchng.com/paydirect/api/v1/gettransaction.json'
+
+    def initialize(post_params={}, amount)
+      post_params.to_hash.symbolize_keys!
+      post_params.each_pair do |key, val|
+        instance_variable_set("@#{key}", val)
+      end
+      @amount = amount
+      fetch_response
+    end
+
+    ## fetches a returns a transaction as json
+    def fetch_response
+      uri              = URI.parse(make_request)
+      http             = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl     = true
+      http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+      @response = JSON.parse http.get(uri.request_uri, { 'Hash' => sha_hash(string_for_get_query) }).body
+    end
+
+    ## Returns true or false
+    def success?
+      @response['ResponseCode'] == '00'
+    end
+
+    def full_error_message
+      "#{ error_message }. #{ query_error_message }"
+    end
+
+    ## Returns error message if present. Else returns a blank string.
+    ## This is generally due to incorrect parameters such as product_id, pay_item_id etc.
+    def error_message
+      @desc.strip.gsub(',', '')
+    end
+
+    ## Returns error message recd from the gateway if the txn query was failed.
+    ## else, returns nil
+    ## This is due to: incorrect amount, invalid card number etc.
+    def query_error_message
+      @response['ResponseDescription'] unless success?
+    end
+
+    def transaction_url
+      WebpayInterswitch::Gateway.test ? TEST_URL : LIVE_URL
+    end
+
+    private
+
+      def make_request
+        url =  transaction_url
+        url += "?productid=#{WebpayInterswitch::Gateway.product_id}"
+        url += "&transactionreference=#{@txnref}"
+        url += "&amount=#{@amount}"
+      end
+
+      ## Returns a string that is used to compute the sha hash for get transaction query on webpay.
+      def string_for_get_query
+        WebpayInterswitch::Gateway.product_id +
+        @txnref.to_s +
+        WebpayInterswitch::Gateway.mac_key
+      end
+
+  end
+end

data/lib/webpay_interswitch/version.rb

@@ -0,0 +1,3 @@
+module WebpayInterswitch
+  VERSION = '1.1'.freeze
+end

data/lib/webpay_interswitch/view_helper.rb

@@ -0,0 +1,11 @@
+module WebpayInterswitch
+  module ViewHelper
+
+    def form_for_webpay(txn_ref, amount, html_options={})
+      form_builder = WebpayInterswitch::FormBuilder.new(txn_ref, amount, html_options)
+      WebpayInterswitch::Gateway.new.validate!
+      form_builder.generate_webpay_form.html_safe if form_builder.valid?
+    end
+
+  end
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: webpay_interswitch
+version: !ruby/object:Gem::Version
+  version: '1.1'
+platform: ruby
+authors:
+- Shubham Gupta
+- Jitender Rai
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-01-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A simple gem to integrate your Rails app with Webpay Interswitch, a nigerian
+  payment gateway
+email:
+- info@vinsol.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/generators/webpay_interswitch/install_generator.rb
+- lib/webpay_interswitch.rb
+- lib/webpay_interswitch/core.rb
+- lib/webpay_interswitch/form_builder.rb
+- lib/webpay_interswitch/gateway.rb
+- lib/webpay_interswitch/transaction_query.rb
+- lib/webpay_interswitch/version.rb
+- lib/webpay_interswitch/view_helper.rb
+homepage: http://vinsol.com
+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.2.2
+signing_key: 
+specification_version: 4
+summary: A simple gem to integrate your Rails app with Webpay Interswitch, a nigerian
+  payment gateway
+test_files: []
+has_rdoc: