koduc_express_paypal 1.0.0 → 1.1.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YTU0OTkwZTZjZWVhMGIzN2JmMWMyNDllZjM5OWFhODAyNDY2NjM2Yw==
+    NjI5OTZjOTgyMWExMTg2NDQ2M2ZhZjA4NTFmOWI3M2U3NTBjOTA1NA==
   data.tar.gz: !binary |-
-    MWVjY2VhOTI1MDE1MzMzN2UzOGY4MjI3YTU2YWMxNjI3ZTg3ZGZlMA==
+    YzNlYTNiNDkwNzIwNmI1NjdiYTg3NjExY2M4ZTdkMTk0OGM0OTViYg==
 SHA512:
   metadata.gz: !binary |-
-    MDUzNWI4MzZiZjg4YTM0MWI2NjU4ZjZiNGFjOGZhM2FmMzFkN2Y3MzA2Nzkx
-    ZDJhNWEzYWIzYzdjMzc4OWVjYWI0ZWJkNzNlZjc4ZDIzYzFhMmRiOThjZjQ1
-    ZjNlMGQyZGQ0MWQ2MTNkZmRlOTI0ZGJiN2NjOGNlYTBjN2JhZDY=
+    YmYxYjFiNGY4MmVhYjIwMmUyNWM5NmNmMjRkZDIwYmM3NGQ1NjNlYTA1MjZl
+    NGMxMDYzMzJkMzYyNmM0OWI5OWVkMTRkMzE1MzYyOWMyOGE0YTYzMTBiNDhk
+    NzE2MWMwN2M1ZmU5NjkzYjk2YTMzMTJhMTMwMjI3M2RhMTA4ZDM=
   data.tar.gz: !binary |-
-    M2QxZjM3ZGEwYjQ2YTRjZjU0MGUwZTY4MjVjM2Q3ZGI5NzE4ZTk1ZTA1NTBi
-    OWUxMTNiYTUyYTRhZTFmZWMxZTcyZjMyM2JjNGU4M2I1YTQyMDVkZjAxMDNh
-    YzljNmMxNzA4ODllZTAyZTA3MzUyODg1OGE3YTE0ZjAyNmM3OTE=
+    ZGY4M2YwMmI5YWE5YTc5YTA5Yjc1NDM1MmEzMWM5ODY1Yzk2YzFhMTc2Y2E0
+    M2M5YjYxZmE1MDA0MjlkZjI3MTdkOGUzODYzNGI0MWIyMDA4YTEwOTZmM2Rm
+    ZmI5NTBmODYxYjBhNzQzMWI0ZGEwYjc5MTFlZTZmZmQ0NWZhYmU=

data/README.md

@@ -1,10 +1,13 @@
 # KoducExpressPaypal
 
-KoducExpressPaypal is a simple gem used for fulfilling the requirement of one time Paypal Express Checkout integration using NVP(Name Value Pair). The chief principle of designing this library is the involvement of different internal Express Checkout Paypal APIs.
+> Gem used for Paypal Express Checkout integration using NVP with both Full and Partial refunds.
+
+### Description
+KoducExpressPaypal is a simple gem used for fulfilling the requirement of one time Paypal Express Checkout integration using NVP(Name Value Pair). One can also make refunds (both full and partial) with the help of the gem. The chief principle of designing this library is the involvement of different internal Express Checkout Paypal APIs.
 
 It is developed for the usage in Ruby on Rails web applications and integrates as a Rails plugin.
 
-It is developed in November 2015 by [KSolves](http://ksolves.com/) team with the help of valuable contributors.
+It is developed in November 2015 by [Koduc](http://koduc.com/) team with the help of valuable contributors.
 
 ## Installation
 
@@ -28,18 +31,19 @@ Or install it yourself as:
     $ gem install koduc_express_paypal
 
 ## Usage
-
-This simple example demonstrates how a purchase can be made using the KoducExpressPaypal gem.
+### Payment Gateway Integration
+>This simple example demonstrates how a purchase can be made using the koduc_express_paypal gem.
 
 ```ruby
+# Require the gem in the controller
 require 'koduc_express_paypal'	
 
-# Declare the following paypal credentials in the same format in the environment files present in the config folder. Use development.rb for sandbox credentials and production.rb for live credentials. Write everything is string.
+# Declare the following API credentials in the same format in the environment files present in the config folder. Use development.rb for sandbox (test) credentials and production.rb for live credentials. The API credentials can be found from the paypal account created.
 
 config.paypal_credentials = {
-            :USER => <userid>, 
-            :PWD => <password>, 
-            :SIGNATURE => <signature>
+            :USER => <Username>, 
+            :PWD => <Password>, 
+            :SIGNATURE => <Signature>
          }
 
 # Set the environment in the format given below. 
@@ -51,70 +55,130 @@ KsCheckEnvironment::ks_sandbox(true)
 # For Live mode use
 KsCheckEnvironment::ks_sandbox(false)
 
+# Parameters required for payment
+# payment_amount => payment amount (Integers and float values are allowed else it will throw error message)
+# payment_action => type of transaction (Only alphabets are allowed)
+# payment_currency => payment currency code (Only alphabets are allowed in capital letters)
+# cancel_url => redirect URL for use if the customer does not authorize payment
+# return_url => redirect URL for use if the customer authorizes payment
+
 # Form a hash of the required parameters in the format given below.
 # All the fields are mandatory
-# payment_amount   => payment amount (Integers and float values are allowed else it will throw error message )
-# payment_action   => type of transaction (Only alphabets are allowed.)
-# payment_currency => payment currency code (Only alphabets are allowed in capital letters.)
-# cancel_url       => redirect URL for use if the customer does not authorize payment
-# return_url       => redirect URL for use if the customer authorizes payment
 # Pass the parameters in string
-
 hash = {:payment_amount =><paymentAmount>,:payment_action=><paymentAction>,:payment_currency=><paymentCurrency>,:cancel_url=><cancelURL>,:return_url=><returnURL>}
 
-# Form an object using the above hash
-
+# Form an object of the class KsRequest present in KsExpressPaypal module with the hash of the parameters formed above
 obj = KsExpressPaypal::KsRequest.new(hash)
 
 # Check if the passed parameters are valid using the object formed above
-
 validity = obj.valid?
 
 # The format of the response obtained is {success: true/false ,response:[Error Array]}
 # The value of success is true is the parameters are verified completely else it will be false.
-# The value of response will be an Array consisting of the error messages in case the validation of the parameters failed. In case the value of success is true the response will be an empty array.
-
-# If the success is true call the following method with the same object formed above
+# The value of the response will either be an Array consisting of the error messages in case the validation of the parameters fails else it will be an empty array.
 
+# If the value of success in the above call is true call the following method with the same object formed above
 set_checkout = obj.ks_set_express_checkout
 
 # The format of the response in case of success is {success: true ,response:[Response returned from Paypal]}
 # The format of the response in case of failure is {success: false ,response:[Error Message returned from Paypal]} 
 # If the above call is successful the response will contain the TOKEN. 
-# If the above call is a failure refer the paypal errors.
 
-# In case of success, using the token valued returned from above, redirect the customer to PayPal so they can approve the transaction:
+# In case of success, using the token valued returned from above call, redirect the customer to PayPal so they can approve the transaction:
 
-# For sandbox 
+# For sandbox redirect the customer to
 https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=<tokenValue>
 
 # For LIVE redirect the customer to 
 https://www.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=<tokenValue>
 
 # The redirect presents the customer with a PayPal log-in page. After the customer logs in, PayPal displays the transaction details on the Payments Review page. The customer approves the payment on this page by clicking Continue.
-
-# If the customer approves the payment, PayPal directs the customer to the payment confirmation page (the return URL specified above in the parameters described above). If the customer doesn't authorize the payment, PayPal directs the customer to the cancel URL that you also specified in the parameters described above, and you can attempt to re-initiate the checkout.
-
+# If the customer approves the payment, PayPal directs the customer to the payment confirmation page (the return URL specified above in the parameters described above). If the customer doesn't authorize the payment, PayPal directs the customer to the cancel URL, also specified in the parameters described above, and you can attempt to re-initiate the checkout.
 # If the customer approves the payment, find the checkout details using the following method by passing the TOKEN obtained above with the same object.
 # It is advisable to display the details on the payment confirmation page using the below method
-
 checkout_details = KsExpressPaypal::KsRequest.ks_checkout_details(<tokenValue>)
 
 # The format of the response in case of success is {success: true ,response:[Response returned from Paypal]}
 # The format of the response in case of failure is {success: false ,response:[Error Message returned from Paypal]} 
-# If the above call is successful the response will contain the TOKEN and the various other details with the PAYERID if the customer has verified the payment. Utilise the details obtained above accordingly.
-# If the above call is a failure refer the paypal errors.
-
-# In addition to the transaction details, your payment confirmation page should include a Confirm button. When the customer confirms the payment, call the below method to capture (collect) the payment. The following sample shows how to specify the PayerID and token value returned from the previous call. Provide the Payment Action with token and payerId:
-
+# If the above call is successful the response will contain the TOKEN and the various other details with the PAYERID if the customer has verified the payment.
+# In addition to the transaction details, your payment confirmation page should include a Confirm button. When the customer confirms the payment, call the below method to capture (collect) the payment. The following sample shows how to specify the PayerID and token value returned from the previous call. Provide the Payment Action with token and payerId.
 do_checkout = KsExpressPaypal::KsRequest.ks_do_checkout(<tokenValue>,<paymentAction>,<payerId>)
 
 # When PayPal processes the above call, it captures the payment by transferring the funds from the customer account to the appropriate merchant account and sends a confirmation e-mail to the customer.
+# The format of the response in case of success is {success: true ,response:[Response returned from Paypal]}
+# The format of the response in case of failure is {success: false ,response:[Error Message returned from Paypal]} 
+# Refer the paypal errors in case of failure.
+```
+## Refund
+>This simple example demonstrates how a refund can be made using the koduc_express_paypal gem.
+
+```ruby
+# Require the gem in the controller
+require 'koduc_express_paypal'
+
+# Declare the following API credentials (if not declared) in the same format in the environment files present in the config folder. Use development.rb for sandbox (test) credentials and production.rb for live credentials. The API credentials can be found from the paypal account created.
+
+config.paypal_credentials = {
+            :USER => <Username>, 
+            :PWD => <Password>, 
+            :SIGNATURE => <Signature>
+         }
+         
+# Set the environment in the format given below. 
+# Default it will be a sandbox mode.
+
+# For Sandbox mode use
+KsCheckEnvironment::ks_sandbox(true)
 
+# For Live mode use
+KsCheckEnvironment::ks_sandbox(false)
+
+# Parameters for Refund
+# In case of Full refund, pass only the transaction id as a parameter else the refund will be considered as partial.
+# transaction_id => id of the transaction for which refund is to be made (mandatory)
+# amount => amount of transaction (conditional: only required in case of partial payment)
+# currency_code => payment currency code (Only alphabets are allowed in capital letters, conditional: Only required in case of partial payment.)
+# note => description of the partial payment (conditional:Only required in case of partial payment.)
+
+# Pass the parameters in string
+# In case of full refund form the hash in the following format
+ hash = {:transaction_id => <TransactionId>}
+
+# In case of partial refund form the hash in the following format
+ hash = {:transaction_id => <TransactionId>, :amount=><AmountToBeRefunded> , :currency_code=><PaymentCurrencyCode>,:note=><DescriptionOfThePartialPayment>}
+ 
+# Form an object of the class KsRefund present in KsAPIRefund module with the hash of the parameters formed above
+obj = KsAPIRefund::KsRefund.new(hash)
+
+# Call the below method with the object formed above.
+obj.ks_refund
+
+# When PayPal processes the above call, it refunds the funds (either 'Full' or 'Partial') from the merchant account to the appropriate customer account.
 # The format of the response in case of success is {success: true ,response:[Response returned from Paypal]}
 # The format of the response in case of failure is {success: false ,response:[Error Message returned from Paypal]} 
 # Refer the paypal errors in case of failure.
 ```
+
+## Response format
+>Success :
+```
+    {
+        :success => true, 
+        :response => [<Response return by Paypal>]
+    } 
+```
+
+> Error : 
+```
+    {
+        :success => false, 
+        :response => [<Error messages separated by commas>]
+    } 
+```
+## Important points
+* In case the response is failure refer the [Paypal Errors](https://developer.paypal.com/docs/classic/api/errorcodes/) for more details.
+* All the parameters should be passed in string.
+
 ## Queries and Issues 
 
 Your valuable queries and suggestions are welcomed. Please report the issues on GitHub at https://github.com/kartiksolves/koduc-paypal-express 

data/koduc_express_paypal.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Koduc"]
   spec.email         = ["ratan@ksolves.com"]
 
-  spec.summary       = "Gem deals with express checkout one time Paypal Payment using NVP Gateway."
-  spec.description   = "Ks Express Paypal is a simple gem used for Paypal Payment Gateway integration. This gem is written by KSolves. The main aim of this project is to deal with the one time Paypal payment using express checkout method using NVP(Name Value Pair)."
+  spec.summary       = "Gem deals with express checkout one time Paypal Payment using NVP Gateway with partial and full refunds."
+  spec.description   = "koduc_express_paypal is a simple gem used for Paypal Payment Gateway integration with partial and full refunds. This gem is written by KSolves. The main aim of this project is to deal with the one time Paypal payment using express checkout method using NVP(Name Value Pair). One can also make partial and full refunds."
   spec.homepage      = "https://github.com/kartiksolves/koduc-paypal-express"
   spec.license       = "MIT"
 
@@ -27,6 +27,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  # Specify the minimum version of the ruby
+  spec.required_ruby_version = '>= 1.9.3'
+
   spec.add_development_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec"

data/lib/koduc_express_paypal.rb

@@ -1,12 +1,15 @@
-# This is the first file to be loaded when this gem is firstly installed
-# Require each file here
+# First file to be loaded when the gem is invoked.
+# Need to require everything here
+# Fetch all the configuration values here
 
 require "koduc_express_paypal/version"
 require "koduc_express_paypal/koduc_check_environment"
 require "koduc_express_paypal/koduc_request"
 require "koduc_express_paypal/koduc_validation"
-require "koduc_exception_handling/koduc_api_errors"
 require "koduc_express_paypal/koduc_response"
+require "koduc_exception_handling/koduc_api_errors"
+require "koduc_refund/koduc_refund"
+require "koduc_refund/koduc_refund_validation"
 require "active_support"
 require "active_support/core_ext"
 require "rest_client"

data/lib/koduc_express_paypal/koduc_response.rb

@@ -1,5 +1,5 @@
 # Return the custom response generated by Paypal APIS
-# Inherit the StandardError not Exception 
+# Inherited from StandardError
 class KsResponse < StandardError
 	attr_accessor :ks_response 
 

data/lib/koduc_express_paypal/version.rb

@@ -1,7 +1,8 @@
 # Version of the gems are described here as a constant
 # Change the VERSION before submitting to rubygems.org
 # For initial phase keep it as it is 
+# For every update change the version before submitting to Rubygems.org
 
 module KoducExpressPaypal
-  VERSION = "1.0.0"
+  VERSION = "1.1.0"
 end

data/lib/koduc_refund/koduc_refund.rb

@@ -0,0 +1,87 @@
+# The file is loaded so as to refund the transaction
+# Initialize the object's constructor first
+# Refund could be Full or Partial
+# transaction_id => The transaction id for which the refund is to be made(required in both Full and Partial payments)
+# amount => The amount in case of partial refund
+# currency_code => The currency code required in case of partial refund
+# note => The description of the partial refund
+# refund_type => The refund type 'Full' or 'Partial'
+
+module KsAPIRefund
+
+	class KsRefund
+
+		attr_accessor :transaction_id, :params, :amount, :currency_code, :note, :refund_type
+
+		# Class default constructor
+		def initialize(params)
+			@transaction_id = params[:transaction_id]
+			@amount = params[:amount]
+			@currency_code = params[:payment_currency]
+			@note = params[:note]
+			@refund_type = ''
+		end
+
+		# Method will check the validity of the parameters initialised with the help of the constructor
+		# Form a new object of the RefundValidation class
+		# Returns the response fetched from the check_validity method
+		def valid?
+			obj= RefundValidation.new(transaction_id,amount,currency_code,note)
+			response = obj.check_validity
+			return response
+		end
+
+		# Check for the refund type
+		# If amount, currency code and note are blank, it will be 'Full'
+		# Else it will be partial
+		# Returns the refund type
+		def refund_type?
+			if amount.blank? && currency_code.blank? && note.blank?
+				refund_type = 'Full'
+			else
+				refund_type = 'Partial'	
+			end
+			return refund_type
+		end
+
+		# Returns the parameters for the partial payment
+		def partial_params
+		    partial_params = {
+		      		:AMT => amount,
+		      		:CURRENCYCODE => currency_code,
+		      		:NOTE => note
+		      	}
+		    return partial_params
+		end
+
+		# Returns the transaction id in the hash format
+		def transaction
+			transaction = {
+				:TRANSACTIONID=>transaction_id
+			}
+			return transaction
+		end
+
+		# Method to invoke the refund functionality 
+		# If the refund type is 'full' dont merge the amount, currency code and note
+		# Check the validity of the parameters first
+		# If response[:success] is true call the Refund API
+		# Else return the response obtained from the valid? method
+		def ks_refund
+			env = KsCheckEnvironment::ks_sandbox(false)
+			response = valid?
+			if response[:success]
+				refund_type = refund_type?
+				case refund_type
+	        		when 'Full'
+	          			ks_response = KsExpressPaypal::KsRequest.ks_request :RefundTransaction,KsExpressPaypal.ks_merchants_details.merge(transaction).merge(:REFUNDTYPE=>refund_type)
+	        		else
+	        			ks_response = KsExpressPaypal::KsRequest.ks_request :RefundTransaction,KsExpressPaypal.ks_merchants_details.merge(transaction).merge(:REFUNDTYPE=>refund_type).merge(partial_params)
+	        		end	
+			else
+				return response	
+			end	
+		end
+
+	end	
+end		

data/lib/koduc_refund/koduc_refund_validation.rb

@@ -0,0 +1,111 @@
+# To validate the refund parameters
+# transaction_id => id of the transaction that needs to be refunded (mandatory for both partial and full refund)
+# amount => The amount to be refunded in case of partial payments
+# currency_code => The currency code required only in case of partial paymanets
+# note => Description of the partial payment
+# ks_error => Array that will hold the error messages.
+
+class RefundValidation
+
+	attr_accessor :transaction_id, :amount, :currency_code, :note, :ks_error
+
+	# Default constructor of the class
+	def initialize(transaction_id,amount,currency_code,note)
+		@transaction_id = transaction_id
+		@amount = amount
+		@currency_code = currency_code
+		@note = note
+		@ks_error = []
+	end
+
+	# Method invoke so as to check the validity of the parameters passed
+	def check_validity
+		success = true
+		if !empty_transaction_id? 
+			success = false
+		else
+			if !amount.blank? && !currency_code.blank?
+				success = false if !check_payment_amount? 
+				success = false if !payment_number? 
+				success = false if !currency_code? 
+			end
+		end
+		response = validate_response(success)
+		return response	
+	end
+
+	# It returns the response in both the cases (success or failure)
+	# The format of response is {success: true/false, error_messages: array of the error messages(blank if success is true)}
+	# Check the uniqueness of the array of the error messages with uniq keyword
+	def validate_response(success)
+		unique_errors = ks_error.uniq
+		response = {success:success,response:unique_errors}	
+		return response
+	end
+
+	# Check for the empty transaction id
+	# Returns true for the success if verified else false with error message
+	def empty_transaction_id?
+		if transaction_id.blank? 
+			ks_error << "Missing Parameters : Transaction Id can not be blank."
+			puts "Check for transaction id is failed."
+			success = false
+		else
+			puts "Check for transaction id is successful."
+			success = true		
+		end
+		return success
+	end
+
+	# Invoke the below method to check if the payment amount is smaller than or equals to zero
+	# Returns the value of success accordingly
+	def check_payment_amount?
+		if !amount.blank?
+			payment_amount = amount.to_i
+			if !(payment_amount <= 0)
+				success = true
+				puts "Check for payment amount is successful"
+			else	
+				ks_error << "Payment Amount is invalid."
+				success = false
+				puts "Check for payment Amount is failed."
+			end
+			return success
+		end	
+	end
+
+	# Check if the string passed consists of only numbers and the decimal values 
+	# Returns true and false accordingly
+	# Returns the error message if success is false
+	def payment_number?	
+		if !amount.blank?
+			if amount =~ /\A[-+]?\d*\.?\d+\z/
+				success = true
+				puts "Check for payment amount is successful."
+			else	
+				ks_error << "Payment Amount is invalid."
+				success = false
+				puts "Check for payment amount is failed."
+			end
+			return success
+		end	
+	end
+
+	# Check if the currency code is invalid (contains capital letters)
+	# Returns true and false accordingly
+	# Returns the error message
+	def currency_code?
+		if !currency_code.blank?
+			if currency_code.match(/^[A-Z]+$/)
+				success = true
+				puts "Check for currency code is successful."
+			else
+				ks_error << 'Currency Code is invalid'
+				success = false
+				puts "Check for currency code is failed."
+			end
+			return success
+		end
+	end
+
+end	

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: koduc_express_paypal
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Koduc
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-12-11 00:00:00.000000000 Z
+date: 2015-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -80,9 +80,10 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '1.4'
-description: Ks Express Paypal is a simple gem used for Paypal Payment Gateway integration.
-  This gem is written by KSolves. The main aim of this project is to deal with the
-  one time Paypal payment using express checkout method using NVP(Name Value Pair).
+description: koduc_express_paypal is a simple gem used for Paypal Payment Gateway
+  integration with partial and full refunds. This gem is written by KSolves. The main
+  aim of this project is to deal with the one time Paypal payment using express checkout
+  method using NVP(Name Value Pair). One can also make partial and full refunds.
 email:
 - ratan@ksolves.com
 executables: []
@@ -107,6 +108,8 @@ files:
 - lib/koduc_express_paypal/koduc_response.rb
 - lib/koduc_express_paypal/koduc_validation.rb
 - lib/koduc_express_paypal/version.rb
+- lib/koduc_refund/koduc_refund.rb
+- lib/koduc_refund/koduc_refund_validation.rb
 homepage: https://github.com/kartiksolves/koduc-paypal-express
 licenses:
 - MIT
@@ -119,7 +122,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ! '>='
@@ -130,6 +133,7 @@ rubyforge_project:
 rubygems_version: 2.4.3
 signing_key: 
 specification_version: 4
-summary: Gem deals with express checkout one time Paypal Payment using NVP Gateway.
+summary: Gem deals with express checkout one time Paypal Payment using NVP Gateway
+  with partial and full refunds.
 test_files: []
 has_rdoc: