ruby-paypal 0.0.1 → 0.0.2

data/README

@@ -42,7 +42,11 @@ DoDirectPayment APIs:
 	  # do your thing
 	end
 	
-The above code is for a final sale only
+The above code is for a final sale only.
+
+Note that the credit card number is checked against a modulo-10 algorithm (Luhn check) as well as a simple credit card
+type check. For more information please refer to http://en.wikipedia.org/wiki/Luhn_algorithm and 
+http://en.wikipedia.org/wiki/Credit_card_number
 
 2. For the Express Checkout using the customer's PayPal account for payment, you will need to use the ExpressCheckout APIs:
 

data/lib/ruby-paypal.rb

@@ -2,4 +2,5 @@
 #
 # Ruby-PayPal is a lightweight wrapper around the PayPal NVP APIs
 
-require 'ruby-paypal/paypal'
+require 'ruby-paypal/paypal'
+require 'ruby-paypal/credit_card_checks'

data/lib/ruby-paypal/credit_card_checks.rb

@@ -0,0 +1,58 @@
+#
+# Performs a series of credit card number checks.
+#
+module CreditCardChecks  
+  # Perform Luhn check on a credit card number. Refer to http://en.wikipedia.org/wiki/Luhn_algorithm
+  # 
+  def luhn_check(number)
+    num = 0
+    number.length.times { |p|
+        position = number.length - p - 1
+      if position % 2 == 0 then            
+        doubled = number[position,1].to_i * 2
+        if doubled > 9 then
+          num = num + doubled.to_s[0,1].to_i +  doubled.to_s[1,1].to_i
+        else
+          num = num + doubled.to_i
+        end
+      else
+        num = num + number[position,1].to_i            
+      end
+    }
+    if num.to_i % 10 == 0 then
+      return true
+    else
+      return false
+    end    
+  end
+  
+  # Perform checks on credit card numbers with reference to the length of the credit card number
+  # and the type of credit card. Refer to http://en.wikipedia.org/wiki/Credit_card_number
+  #
+  def card_type_check(type, number)
+    validity = false
+    case type.upcase
+      when "VISA"
+        validity = true if (number.length == 16 or number.length = 13) and number[0,1] == "4"
+      when "MASTERCARD"
+        validity = true if (number.length == 16) and (52..55).include?(number[0,2].to_i)
+      when "AMEX"
+        validity = true if (number.length == 16) and ['34', '37'].include?(number[0,2])
+      when "DISCOVER"
+        validity = true if (number.length == 16) and (number[0,2] == "65" or number[0,4] == "6011")
+      when "SWITCH"
+        # TODO checks for Switch cards
+        validity = true
+      when "SOLO"
+        # TODO checks for Solo cards
+        validity = true
+      else
+        raise "Invalid card type entered"
+    end
+    
+    return validity
+  end
+  
+  
+  
+end

data/lib/ruby-paypal/paypal.rb

@@ -2,12 +2,16 @@ require 'pp'
 require 'net/http'
 require 'net/https'
 require 'uri'
+require 'lib/ruby-paypal/credit_card_checks'
 
 SANDBOX_SERVER = 'api-3t.sandbox.paypal.com/nvp'
-LIVE_SERVER = 'api-3t.paypal.com/nvp'
+PRODUCTION_SERVER = 'api-3t.paypal.com/nvp'
 API_VERSION = '3.2'
 
 module Net
+  #
+  # A convenience class to enable this library to call PayPal's HTTPS NVP APIs
+  #
   class HTTPS < HTTP
     def initialize(address, port = nil, verify = :no_verify)
       super(address, port)
@@ -17,6 +21,23 @@ module Net
   end
 end
 
+#
+# A container for the response from PayPal. Each call to PayPal returns a generic set
+# of information as well as a specific set for the call. For more information please refer
+# to PayPal NVP API Developer Guide and Reference.
+#
+# To use retrieve information in the response, call the corresponding name of the object. For 
+# example, all responses from PayPal includes the field <tt>ACK</tt>. To get the data for this 
+# field:
+#
+# 
+#   if response.ack == 'Success' then
+#    # do your stuff
+#   end
+# 
+# This is because this class uses a meta-programming trick with method_missing to redirect all 
+# known method calls to its internal hash data structure.
+#
 class PayPalResponse < Hash
   def method_missing(m,*a)
     if m.to_s.upcase =~ /=$/
@@ -29,27 +50,117 @@ class PayPalResponse < Hash
   end
 end
 
+
+=begin rdoc
+Author::    Chang Sau Sheong  (mailto:sausheong.chang@gmail.com)
+Copyright:: Copyright (c) 2007 Chang Sau Sheong
+License::   Distributes under the same terms as Ruby
+Version:: 0.0.2
+
+=Installing Ruby-PayPal
+A lightweight ruby wrapper for PayPal NVP APIs. To install type the following
+at the command line:
+
+  $ gem install ruby-paypal
+
+
+=Using Ruby-PayPal
+It's critical that you understand how PayPal works and how the PayPal NVP API
+works. You should be relatively well-versed in the NVP API Developer Guide and 
+Reference (https://www.paypal.com/en_US/ebook/PP_NVPAPI_DeveloperGuide/index.html). 
+You should also visit and register yourself with the PayPal Developer Network
+and get a Sandbox account with in the PayPal Development Central
+(https://developer.paypal.com/). 
+
+Note that this library only supports the API signature method of securing the API credentials.
+
+==Direct Payment
+To use credit card payment through PayPal, you need to use the DoDirectPayment APIs:
+
+	username = <PayPal API username>
+	password = <PayPal API password>
+	signature = <PayPal API signature>
+	
+	ipaddress = '192.168.1.1' # can be any IP address
+	amount = '100.00' # amount paid
+	card_type = 'VISA' # can be Visa, Mastercard, Amex etc
+	card_no = '4512345678901234' # credit card number
+	exp_date = '022010' # expiry date of the credit card
+	first_name = 'Sau Sheong'
+	last_name = 'Chang'
+	
+    paypal = Paypal.new(username, password, signature) # uses the PayPal sandbox
+    response = paypal.do_direct_payment_sale(ipaddress, amount, card_type,
+			   card_no, exp_date, first_name, last_name)
+	if response.ack == 'Success' then
+	  # do your thing
+	end
+	
+The above code is for a final sale only.
+
+Note that the credit card number is checked against a modulo-10 algorithm (Luhn check) as well as a simple credit card
+type check. For more information please refer to http://en.wikipedia.org/wiki/Luhn_algorithm and 
+http://en.wikipedia.org/wiki/Credit_card_number
+
+==Express Checkout
+To use the customer's PayPal account for payment, you will need to use the ExpressCheckout APIs:
+
+<to be documented>
+
+=More information
+I will be continually providing updates in my blog at http://blog.saush.com
+
+=end
+
 class Paypal
-  def initialize(user, password, signature, url=SANDBOX_SERVER, subject=nil)
+  include CreditCardChecks
+
+  # Create a new object with the given user name, password and signature. To enable production
+  # access to PayPal change the url to the live PayPal server. Set url to <tt>:production</tt> to change
+  # access to PayPal production servers.
+  #
+  def initialize(user, password, signature, url=:sandbox, subject=nil)
     @api_parameters = {'USER' => user, 
       'PWD' => password, 
       'VERSION' => API_VERSION, 
       'SIGNATURE' => signature }
-      @paypal_url = url
+      if url == :sandbox
+        @paypal_url = SANDBOX_SERVER
+      elsif url == :production
+        @paypal_url = PRODUCTION_SERVER
+      else
+        raise 'Invalid url specified'
+      end
     end
 
+    # Performs credit card payment with PayPal, but only requesting for authorization. You need
+    # to capture the funds later. Calls do_direct_payment.
+    #
+    # Equivalent of DoDirectPayment with the PAYMENTACTION of 'authorization'
+    #
     def do_direct_payment_authorization(ipaddress, amount, credit_card_type, credit_card_no, expiry_date, 
       first_name, last_name, cvv2=nil, other_params={})
       do_direct_payment('Authorization', ipaddress, amount, credit_card_type, credit_card_no, 
       expiry_date, first_name, last_name, cvv2, other_params)
     end
 
+    # Performs credit card payment with PayPal, finalizing the sale. Funds are captured immediately.
+    # Calls do_direct_payment.
+    #
+    # Equivalent of DoDirectPayment with the PAYMENTACTION of 'sale'
+    #
     def do_direct_payment_sale(ipaddress, amount, credit_card_type, credit_card_no, expiry_date, 
       first_name, last_name, cvv2=nil, other_params={})
       do_direct_payment('Sale', ipaddress, amount, credit_card_type, credit_card_no, 
       expiry_date, first_name, last_name, cvv2, other_params)
     end
 
+    # Performs credit card payment with PayPal.
+    #
+    # Equivalent of DoDirectPayment.
+    #
+    # Performs Luhn check and a simple credit card type check based on the card number.
+    #
     def do_direct_payment(payment_action, ipaddress, amount, credit_card_type, 
       credit_card_no, expiry_date, first_name, last_name, cvv2=nil, other_params={})
       params = {
@@ -62,12 +173,19 @@ class Paypal
         'FIRSTNAME' => first_name,
         'LASTNAME' => last_name,
         'IPADDRESS' => ipaddress } 
-      params['CVV2'] = cvv2 unless cvv2.nil?   
-      params.merge! other_params
-      make_nvp_call(params)
-      end
+        params['CVV2'] = cvv2 unless cvv2.nil?   
+        params.merge! other_params
 
+        raise 'Invalid credit card number' if not luhn_check(params['ACCT'])
+        raise 'Invalid credit card type' if not card_type_check(params['CREDITCARDTYPE'], params['ACCT'])
 
+        make_nvp_call(params)
+      end
+
+      # Performs payment through PayPal. 
+      #
+      # Equivalent of SetExpressCheckout.
+      #
       def set_express_checkout(return_url, cancel_url, amount)
         params = {
           'METHOD' => 'SetExpressCheckout',
@@ -78,6 +196,10 @@ class Paypal
         make_nvp_call(params)
       end
 
+      # Gets the details of the request started through set_express_checkout.
+      #
+      # Equivalent of GetExpressCheckoutDetails.
+      #
       def get_express_checkout_details(token)
         params = {
           'METHOD' => 'GetExpressCheckoutDetails',
@@ -86,6 +208,11 @@ class Paypal
         make_nvp_call(params)    
       end
 
+      #
+      # Gets payment through PayPal for Express Checkout.
+      #
+      # Equivalent of DoExpressCheckoutPayment
+      #
       def do_express_checkout_payment(token, payment_action,payer_id, amount)
         params = {
           'METHOD' => 'DoExpressCheckoutPayment',
@@ -97,16 +224,63 @@ class Paypal
         make_nvp_call(params)    
       end
 
-      def do_authorization(transaction_id, amount)
+      # 
+      # Does authorization of a request.
+      # 
+      # Equivalent of DoAuthorization.
+      #
+      def do_authorization(transaction_id, amount, currency_code = 'USD')
         params = {
           'METHOD' => 'DoAuthorization',
           'TRANSACTIONID' => transaction_id,
           'AMT' => amount.to_s,
-          'TRANSACTIONENTITY' => 'Order'
+          'TRANSACTIONENTITY' => 'Order',
+          'CURRENCYCODE' => currency_code 
         }
         make_nvp_call(params)
       end
 
+      #
+      # Captures payment for a transaction.
+      #
+      # Equivalent of DoCapture.
+      #
+      def do_capture(authorization_id, amount, complete=true, currency_code='USD', invoice_no=nil, note=nil, soft_descriptor=nil)
+        params = {
+          'METHOD' => 'DoCapture',
+          'AUTHORIZATIONID' => authorization_id,
+          'AMT' => amount.to_s,
+          'CURRENCYCODE' => currency_code
+        }
+        if complete then
+          params['COMPLETETYPE'] = 'Complete'
+        else
+          params['COMPLETETYPE'] = 'NotComplete'          
+        end
+        params['INVNUM'] = invoice_no unless invoice_no.nil?
+        params['NOTE'] = note unless note.nil?
+        params['SOFTDESCRIPTOR'] = soft_descriptor unless soft_descriptor.nil?                
+        make_nvp_call(params)
+      end
+
+      #
+      # Re-authorizes an authorized transaction.
+      #
+      # Equivalent of DoReauthorization.
+      #
+      def do_reauthorization(authorization_id, amount, currency_code = 'USD')
+        params = {
+          'METHOD' => 'DoReauthorization',
+          'AUTHORIZATIONID' => authorization_id,
+          'AMT' => amount.to_s,
+          'CURRENCYCODE' => currency_code 
+        }
+        make_nvp_call(params)
+      end
+
+      #
+      # Makes the call to the PayPal NVP API. This is the workhorse method for the other method calls.
+      #
       def make_nvp_call(params)
         @api_parameters.merge! params
         parameters = URI.escape(@api_parameters.to_a.collect {|pair| pair.join('=')}.join('&'))
@@ -115,9 +289,20 @@ class Paypal
         PayPalResponse.new.merge get_hash(response.body)    
       end
 
-      private
+      #
+      # Checks and returns information on the card based on the given BIN (Bank Identification Number).
+      # Currently inactive since bindatabase.com is down.
+      #
+      def bin_check(bin)
+        # stub for check to bindatabase.com, currently down
+      end
 
+      private
 
+      #
+      # Gets a hash from a string, with a set of name value pairs joined by '='
+      # and concatenated with '&'
+      #
       def get_hash(string)
         hash = {}  
         string.split('&').collect { |pair| pair.split('=') }.each { |a|

data/test/ts_ruby-paypal.rb

@@ -1,20 +1,34 @@
-require 'rubygems'
 require 'pp'
-require 'ruby-paypal'
 require 'test/unit'
+require 'lib/ruby-paypal/paypal'
+require 'lib/ruby-paypal/credit_card_checks'
+
 
 class RubyPayPal < Test::Unit::TestCase 
+  def setup
+    @test_data = {"visa" => "4154727623381301", "visa" => "4015262522324137", "visa" => "4574806205610007"}    
+    @paypal = Paypal.new('css.pa_1195828529_biz_api1.gmail.com', '1195828547', 'AJsoTDMhNESFz43L9WKtkP2tVCZZAZ3Wl.IxVLj8IfJQsjg8WZYMENpS')
+  end
   def test_do_direct_payment_sale 
-    paypal = Paypal.new('css.pa_1195828529_biz_api1.gmail.com', '1195828547', 
-             'AJsoTDMhNESFz43L9WKtkP2tVCZZAZ3Wl.IxVLj8IfJQsjg8WZYMENpS')
-    resp = paypal.do_direct_payment_sale('202.156.13.1', '14.34', 'VISA', 
-           '4574806205610007', '022017', 'Test', 'User')
+    resp = @paypal.do_direct_payment_sale('202.156.13.1', '14.34', 'visa', '4574806205610007', '022017', 'Test', 'User')
     assert_equal("Success", resp.ack) 
   end
+
+  def test_luhn_check
+    @test_data.each { |type, number|
+      assert_equal(@paypal.luhn_check(number), true)      
+    }
+  end
   
+  def test_card_type_check
+    @test_data.each { |type, number|
+      assert_equal(@paypal.card_type_check(type,number), true)
+    }
+  end
+
   def test_do_direct_payment_authorization
-    
+
   end
-     
+
 end 
 

metadata

@@ -3,9 +3,9 @@ rubygems_version: 0.9.4
 specification_version: 1
 name: ruby-paypal
 version: !ruby/object:Gem::Version 
-  version: 0.0.1
-date: 2007-12-23 00:00:00 +08:00
-summary: An lightweight Ruby wrapper for PayPal NVP API
+  version: 0.0.2
+date: 2008-01-02 00:00:00 +08:00
+summary: A lightweight Ruby wrapper for PayPal NVP API
 require_paths: 
 - lib
 email: sausheong.chang@gmail.com
@@ -30,6 +30,7 @@ authors:
 - Chang Sau Sheong
 files: 
 - lib/ruby-paypal
+- lib/ruby-paypal/credit_card_checks.rb
 - lib/ruby-paypal/paypal.rb
 - lib/ruby-paypal.rb
 - test/ts_ruby-paypal.rb