ez_paypal 1.0.0

data/ez_paypal.gemspec

@@ -0,0 +1,32 @@
+lib = File.expand_path("../lib/", __FILE__)
+$:.unshift lib unless $:.include?(lib)
+
+require "date"
+require "ez_paypal/version"
+
+Gem::Specification.new do |s|
+
+  # Basic info
+  s.name        = "ez_paypal"
+  s.version     = EZPaypal::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.date        = Date.today.to_s
+  s.summary     = "Paypal express checkout plugin"
+  s.description = "Paypal express checkout plugin"
+  s.authors     = ["Tianyu Huang"]
+  s.email       = ["tianhsky@yahoo.com"]
+  s.homepage    = "http://rubygems.org/gems/ez_paypal"
+
+  # Dependencies
+  #s.required_rubygems_version = ">= 1.8.22"
+  s.add_dependency "ez_http", ">= 1.0.4"
+  s.add_dependency "json", ">= 1.6.6"
+  s.add_dependency "activesupport", ">= 3.2.2"
+
+  # Files
+  s.files       = `git ls-files`.split("\n")
+  s.require_paths = ["lib"]
+  s.executables = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.extra_rdoc_files   = ["README.md", "doc/index.html"]
+
+end

data/lib/config.rb

@@ -0,0 +1,55 @@
+module EZPaypal
+  module Config
+
+    # Account setting
+    @setting
+
+    def self.Setting
+      @setting
+    end
+
+    # API endpoint
+    @endpoint
+
+    def self.EndPoint
+      @endpoint
+    end
+
+    # Setup config
+    # @param [Hash] options = { "user", "password", "signature",
+    #                         "version", "mode" => "sandbox / live",
+    #                         "customer_service_tel"}
+    #
+    def self.Setup (options)
+      # Setup account setting
+      @setting={
+          "USER" => options["user"],
+          "PWD" => options["password"],
+          "SIGNATURE" => options["signature"],
+          "VERSION" => options["version"] || 84.0,
+          "CUSTOMERSERVICENUMBER" => options["customer_service_tel"]
+      }
+
+      # Setup endpoint
+      express_checkout_endpoint = {
+          "sandbox" => "https://api-3t.sandbox.paypal.com/nvp",
+          "live" => "https://api-3t.paypal.com/nvp"
+      }
+      set_express_checkout = {
+          "sandbox" => "https://www.sandbox.paypal.com/webscr?cmd=_express-checkout",
+          "live" => "https://www.paypal.com/webscr?cmd=_express-checkout",
+      }
+
+      @endpoint ||= {}
+      if (options["mode"] == 'sandbox')
+        @endpoint.merge!("express_checkout_endpoint" => express_checkout_endpoint["sandbox"])
+        @endpoint.merge!("express_checkout_url" => set_express_checkout["sandbox"])
+      else
+        @endpoint.merge!("express_checkout_endpoint" => express_checkout_endpoint["live"])
+        @endpoint.merge!("express_checkout_url" => set_express_checkout["live"])
+      end
+
+
+    end
+  end
+end

data/lib/core/data.rb

@@ -0,0 +1,241 @@
+require 'active_support/hash_with_indifferent_access'
+require 'cgi'
+
+module EZPaypal
+
+  # Paypal NVP Documentation:
+  #  Express checkout:
+  #   https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_nvp_r_GetExpressCheckoutDetails
+  #  Recurring payments:
+  #   https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_ECRecurringPayments
+  #   https://cms.paypal.com/us/cgi-bin/?cmd=_render-content&content_ID=developer/e_howto_api_nvp_r_CreateRecurringPayments
+  module Cart
+
+    # A cart object that holds all one time purchase items
+    #  How to use:
+    #    -> initialize Cart
+    #    -> add items (optional)
+    #    -> setup shipping info(optional)
+    #    -> setup summary(required)
+    #    -> done (if involve recurring purchase, please create profile, this cart only shows agreement for recurring items)
+    #  Note:
+    #    you are responsible for all the cost calculations
+    #
+    class OneTimePurchaseCart < HashWithIndifferentAccess
+
+      # Max cart size of this cart type
+      def cartSize
+        10
+      end
+
+      # Add item to the cart (optional)
+      # @param [Hash] item = {"category" => "digital / physical",
+      #                       "name", "item_code", "description", "amount", "quantity" }
+      #
+      def addItem(item)
+
+        # Check max cart size, make sure do not exceed the limit
+        max = 0
+        self.each do |key, value|
+          max = max + 1 if key.match(/^L_PAYMENTREQUEST_0_NAME/)
+        end
+        throw "Exceed max cart size: #{cartSize}" if (max+1 > cartSize)
+
+        # Add item to cart
+        current_index = max
+        current_item = {
+            "L_PAYMENTREQUEST_0_ITEMCATEGORY#{current_index}" => item["category"] || "Physical",
+            "L_PAYMENTREQUEST_0_NAME#{current_index}" => item["name"] || "",
+            "L_PAYMENTREQUEST_0_NUMBER#{current_index}" => item["item_code"] || "",
+            "L_PAYMENTREQUEST_0_DESC#{current_index}" => item["description"] || "",
+            "L_PAYMENTREQUEST_0_AMT#{current_index}" => item["amount"] || "0",
+            "L_PAYMENTREQUEST_0_QTY#{current_index}" => item["quantity"] || "0"
+        }
+        self.merge!(current_item)
+
+      end
+
+      # Setup shipping info (optional)
+      # @param [Hash] shipping = {"name", "street", "street2", "city", "state", "country", "zip", "phone" }
+      def setupShippingInfo(shipping)
+        item = shipping
+        options = {
+            "PAYMENTREQUEST_0_SHIPTONAME" => item["name"] || "",
+            "PAYMENTREQUEST_0_SHIPTOSTREET" => item["street"] || "",
+            "PAYMENTREQUEST_0_SHIPTOSTREET2" => item["street2"] || "",
+            "PAYMENTREQUEST_0_SHIPTOCITY" => item["city"] || "",
+            "PAYMENTREQUEST_0_SHIPTOSTATE" => item["state"] || "",
+            "PAYMENTREQUEST_0_SHIPTOCOUNTRYCODE" => item["country"] || "",
+            "PAYMENTREQUEST_0_SHIPTOZIP" => item["zip"] || "",
+            "PAYMENTREQUEST_0_SHIPTOPHONENUM" => item["phone"] || ""
+        }
+        self.merge!(options)
+      end
+
+      # Add cart summary, please calculate yourself (required)
+      # @param [Hash] summary = {"currency" => "USD"(default "USD"),
+      #                         "subtotal", "tax", "shipping", "handling", "shipping_discount", "insurance", "total",
+      #                         "disable_change_shipping_info" => "1 / 0" (default 1),
+      #                         "allow_note" => "1 / 0" (default 0) }
+      #
+      def setupSummary (summary)
+        item = summary
+        options = {
+            "PAYMENTREQUEST_0_PAYMENTACTION" => item["payment_action"] || "Sale",
+            "PAYMENTREQUEST_0_CURRENCYCODE" => item["currency"] || "USD",
+
+            "PAYMENTREQUEST_0_ITEMAMT" => item["subtotal"] || "0",
+            "PAYMENTREQUEST_0_TAXAMT" => item["tax"] || "0",
+            "PAYMENTREQUEST_0_SHIPPINGAMT" => item["shipping"] || "0",
+            "PAYMENTREQUEST_0_HANDLINGAMT" => item["handling"] || "0",
+            "PAYMENTREQUEST_0_SHIPDISCAMT" => item["shipping_discount"] || "0",
+            "PAYMENTREQUEST_0_INSURANCEAMT" => item["insurance"] || "0",
+            "PAYMENTREQUEST_0_AMT" => item["total"] || "0",
+
+            "ALLOWNOTE" => item["allow_note"] || "0",
+            "NOSHIPPING" => item["disable_change_shipping_info"] || "1"
+        }
+        self.merge!(options)
+      end
+
+      # Clean the cart
+      def reset
+        self.clear
+      end
+
+    end
+
+
+    # A cart object that holds all recurring purchase items
+    # Note that this cart only support one subscription item at a time
+    #  How to use:
+    #    -> initialize Cart
+    #    -> setup agreement (required)
+    #    -> setup summary(required)
+    #    -> done (please create profile after this, this cart only shows agreement for recurring items)
+    #  Note:
+    #    you are responsible for all the cost calculations
+    #
+    class RecurringPurchaseCart < HashWithIndifferentAccess
+
+      # Max cart size of this cart type
+      def cartSize
+        1
+      end
+
+      # Setup recurring payment agreement
+      # @param [Hash] agreement = {"category" => "digital / physical" (default physical),
+      #                            "currency" => "USD"(default "USD")
+      #                            "item_code" => ""(code should be unique and meaningful),
+      #                            "unit_price", "quantity" ,"amount"}
+      #
+      def setupAgreement(agreement)
+
+        # Check max cart size, make sure do not exceed the limit
+        max = 0
+        self.each do |key, value|
+          max = max + 1 if key.match(/^L_PAYMENTREQUEST_0_NAME/)
+        end
+        throw "Exceed max cart size: #{cartSize}" if (max+1 > cartSize)
+
+        item = agreement
+        current_index = max
+        current_item = {
+            "L_PAYMENTREQUEST_0_NAME#{current_index}" => item["item_code"] || "",
+            #"L_PAYMENTREQUEST_0_NUMBER#{current_index}" => item["item_code"] || "",
+            #"L_PAYMENTREQUEST_0_DESC#{current_index}" => item["description"] || "",
+            "L_PAYMENTREQUEST_0_AMT#{current_index}" => item["unit_price"] || "0",
+            "L_PAYMENTREQUEST_0_QTY#{current_index}" => item["quantity"] || "0",
+
+            "L_PAYMENTREQUEST_0_ITEMCATEGORY#{current_index}" => item["category"] || "Physical",
+            "L_BILLINGTYPE#{current_index}" => "RecurringPayments",
+            "L_BILLINGAGREEMENTDESCRIPTION#{current_index}" => item["item_code"] || ""
+        }
+
+        summary = {
+            "PAYMENTREQUEST_0_PAYMENTACTION" => item["payment_action"] || "Sale",
+            "PAYMENTREQUEST_0_CURRENCYCODE" => item["currency"] || "USD",
+            #"PAYMENTREQUEST_0_ITEMAMT" => item["total"] || "0",
+            #"PAYMENTREQUEST_0_TAXAMT" => item["tax"] || "0",
+            #"PAYMENTREQUEST_0_SHIPPINGAMT" => item["shipping"] || "0",
+            #"PAYMENTREQUEST_0_HANDLINGAMT" => item["handling"] || "0",
+            #"PAYMENTREQUEST_0_SHIPDISCAMT" => item["shipping_discount"] || "0",
+            #"PAYMENTREQUEST_0_INSURANCEAMT" => item["insurance"] || "0",
+            "PAYMENTREQUEST_0_AMT" => item["amount"] || "0",
+
+            "ALLOWNOTE" => item["allow_note"] || "0",
+            "NOSHIPPING" => item["disable_change_shipping_info"] || "1"
+        }
+        self.merge!(current_item).merge!(summary)
+      end
+
+      # Clean the cart
+      def reset
+        self.clear
+      end
+    end
+
+
+    class RecurringProfile < HashWithIndifferentAccess
+
+      # Setup profile
+      # @param [Hash] profile = {"token", "email", "currency" => "USD" (default "USD"),
+      #                         "item_code", "unit_price", "quantity", "amount",
+      #                         "initial_amount" => "0" (recurring profile will do auto-charge since begining! do not use this if you are not sure),
+      #                         "start_date" => "2012/02/02" (Default Time.now),
+      #                         "period" => "Day/Week/Month/Year" (default "Month"),
+      #                         "frequency" => "1" (how many periods a purchase, default 1),
+      #                         "cycles" => "0" (total cycles of recurring billing, default 0 means infinite)
+      #                          }
+      def initialize(profile)
+        item = profile
+        options = {
+            "TOKEN" => item["token"],
+            "EMAIL" => item["email"],
+            "CURRENCYCODE" => item["currency"] || "USD",
+            "FAILEDINITAMTACTION" => "CancelOnFailure", #ContinueOnFailure / CancelOnFailure
+
+            # Display details
+            "L_PAYMENTREQUEST_0_ITEMCATEGORY0" => item["category"] || "Physical",
+            "L_PAYMENTREQUEST_0_NAME0" => item["item_code"] || "",
+            "L_PAYMENTREQUEST_0_AMT0" => item["unit_price"] || "0",
+            "L_PAYMENTREQUEST_0_QTY0" => item["quantity"] || "0",
+
+            # Profile details
+            "DESC" => item["item_code"] || "",
+            "AMT" => item["amount"] || "0",
+            "QTY" => item["quantity"] || "0",
+            "INITAMT" => item["initial_amount"] || "0",
+
+            # Recurring details
+            "PROFILESTARTDATE" => item["start_date"] || Time.now,
+            "BILLINGFREQUENCY" => item["frequency"] || "1",
+            "BILLINGPERIOD" => item["period"] || "Month",
+            "TOTALBILLINGCYCLES" => item["cycles"] || "0"
+
+        }
+
+        self.merge!(options)
+      end
+
+      def self.ConvertFromCheckoutDetails (checkout_details)
+        profile = {
+            "token" => checkout_details["TOKEN"],
+            "email" => checkout_details["EMAIL"],
+            "item_code" => checkout_details["L_PAYMENTREQUEST_0_NAME0"],
+            "unit_price" => checkout_details["L_PAYMENTREQUEST_0_AMT0"],
+            "quantity" => checkout_details["L_PAYMENTREQUEST_0_QTY0"],
+            "amount" => checkout_details["PAYMENTREQUEST_0_AMT"],
+            "start_date" => Time.now,
+            "period" => "Month",
+            "frequency" => "1"
+        }
+
+        profile = self.new(profile)
+      end
+
+    end
+
+
+  end
+end

data/lib/core/helper.rb

@@ -0,0 +1,34 @@
+require 'active_support/hash_with_indifferent_access'
+require 'cgi'
+
+module EZPaypal
+  module Helper
+    # Helper method to convert query string to hash
+    # also convert hash to encoded hash
+    # @param [String / Hash] object to be converted or encoded
+    # @return [Hash] converted string or encoded hash
+    def self.ConvertParamToHash (object)
+      hash_obj = HashWithIndifferentAccess.new()
+      if (object.class.to_s == "String")
+        object.split("&").each do |e|
+          key = CGI::unescape(e.split("=")[0])
+          value = CGI::unescape(e.split("=")[1])
+          hash_obj.merge!(key => value)
+        end
+      else
+        object.each do |key, value|
+          key = CGI::unescape(key)
+          value = CGI::unescape(value)
+          hash_obj.merge!(key.upcase => value)
+        end
+      end
+
+      return hash_obj
+    end
+
+    def self.ConvertHashToQueryString (hash)
+      hash.map { |k, v| CGI::escape(k.to_s)+"="+CGI::escape(v.to_s) }.join("&")
+    end
+
+  end
+end

data/lib/core/request.rb

@@ -0,0 +1,159 @@
+require 'active_support/hash_with_indifferent_access'
+require 'cgi'
+require 'ez_http'
+require File.expand_path('../../config', __FILE__)
+require File.expand_path('../helper', __FILE__)
+
+module EZPaypal
+  module Request
+
+    # Setup express checkout cart
+    # @param [EZPaypal::Cart::OneTimePurchaseCart / EZPaypal::Cart::RecurringPurchaseCart] cart
+    # @param [String] returnUrl
+    # @param [String] cancelUrl
+    # @return [Hash] response = {"TOKEN"}
+    def self.SetupExpressCheckout (cart, returnUrl, cancelUrl)
+      begin
+        # Setup default options
+        setting = EZPaypal::Config.Setting.clone
+        default = {"METHOD" => "SetExpressCheckout",
+                   "RETURNURL" => returnUrl,
+                   "CANCELURL" => cancelUrl
+        }
+        setting.merge!(default).merge!(cart)
+
+        # Get setup express checkout details
+        query_string = EZPaypal::Helper.ConvertHashToQueryString(setting)
+        setup_ec_response_origin = EZHttp.Send(EZPaypal::Config.EndPoint["express_checkout_endpoint"], query_string, "post").body
+
+        # Convert express checkout details to Hash to return
+        setup_ec_response = EZPaypal::Helper.ConvertParamToHash(setup_ec_response_origin)
+
+        return setup_ec_response
+      rescue
+        throw "Error occured in SetupExpressCheckout"
+      end
+    end
+
+    # Get current checkout url to redirect user to, only works if token has obtained
+    # @param [String] token
+    # @return [String] paypal checkout url to redirect user to
+    def self.GetCheckoutURL(token)
+      EZPaypal::Config.EndPoint["express_checkout_url"]+ "&token=" + token unless token.nil?
+    end
+
+    # Get current checkout details, only works if token has obtained
+    # @param [String] token
+    # @return [Hash] checkout details associated with the given token
+    def self.GetCheckoutDetails(token)
+      unless (token.nil?)
+        begin
+          # Setup default options
+          setting = EZPaypal::Config.Setting.clone
+          setting.merge!({"METHOD" => "GetExpressCheckoutDetails"})
+          setting.merge!({"TOKEN" => token})
+
+          # Get checkout details
+          query_string = EZPaypal::Helper.ConvertHashToQueryString(setting)
+          checkout_details_origin = EZHttp.Send(EZPaypal::Config.EndPoint["express_checkout_endpoint"], query_string, "post").body
+
+          # Convert checkout details to Hash to return
+          checkout_details = EZPaypal::Helper.ConvertParamToHash(checkout_details_origin)
+
+          return checkout_details
+        rescue
+          throw "Error occured in GetExpressCheckoutDetails: token=#{token}"
+        end
+      end
+    end
+
+    # Confirm payment, only works if token and payer_id is obtained
+    # @param [String] token
+    # @param [String] payer_id
+    # @return [Hash] payment details associated with the given token and payer_id
+    def self.ConfirmPurchase(token, payer_id)
+      unless (token.nil? && payer_id.nil?)
+        begin
+          # Setup default options
+          setting = EZPaypal::Config.Setting.clone
+          setting.merge!({"METHOD" => "DoExpressCheckoutPayment"})
+          setting.merge!({"PAYMENTREQUEST_0_PAYMENTACTION" => "Sale"})
+          setting.merge!({"TOKEN" => token})
+          setting.merge!({"PAYERID" => payer_id})
+
+
+          # Get checkout details
+          checkout_details_origin = EZPaypal::Request.GetCheckoutDetails(token)
+          checkout_details_origin.each do |key, value|
+            key = CGI::unescape(key)
+            value = CGI::unescape(value)
+          end
+
+          # Submit checkout request to confirm the purchase
+          payment_response_origin = HashWithIndifferentAccess.new()
+          if (checkout_details_origin["ACK"].downcase == "success")
+            checkout_details_origin.merge!(setting)
+            query_string = EZPaypal::Helper.ConvertHashToQueryString(checkout_details_origin)
+            payment_response_origin = EZHttp.Send(EZPaypal::Config.EndPoint["express_checkout_endpoint"], query_string, "post").body
+          end
+
+          # Convert response to Hash to return
+          payment_response = EZPaypal::Helper.ConvertParamToHash(payment_response_origin)
+
+          return payment_response
+
+        rescue
+          throw "Error occured in ConfirmPurchase: TOKEN=#{token}, PAYERID=#{payer_id}"
+        end
+      end
+    end
+
+    # Create a recurring profile for a customer
+    # @param [EZPaypal::Cart::RecurringProfile] profile including all the config for the recurring profile
+    # @return [Hash] profile creation confirmation from paypal
+    def self.CreateRecurringProfile(profile)
+      begin
+        # Setup default options
+        setting = EZPaypal::Config.Setting.clone
+        default = {"METHOD" => "CreateRecurringPaymentsProfile"}
+        setting.merge!(default).merge!(profile)
+
+        # Http call to create profile and get response
+        query_string = EZPaypal::Helper.ConvertHashToQueryString(setting)
+        profile_response_origin = EZHttp.Send(EZPaypal::Config.EndPoint["express_checkout_endpoint"], query_string, "post").body
+
+        # Convert response to Hash to return
+        profile_response = EZPaypal::Helper.ConvertParamToHash(profile_response_origin)
+
+        return profile_response
+      rescue
+        throw "Error occured in CreateRecurringProfile"
+      end
+    end
+
+    # Refund money to a transaction
+    # @param [String] all
+    # @return [Hash]
+    def self.Refund(transaction_id, refund_type, amount, currency, note)
+      # Setup default options
+      setting = EZPaypal::Config.Setting.clone
+      options = {
+          "METHOD" => "RefundTransaction",
+          "TRANSACTIONID" => transaction_id,
+          "REFUNDTYPE" => refund_type || "Partial",
+          "AMT" => amount || "0",
+          "CURRENCYCODE" => currency || "USD",
+          "NOTE" => note || ""
+      }
+      setting.merge!(options)
+
+      # Http call to create profile and get response
+      query_string = EZPaypal::Helper.ConvertHashToQueryString(setting)
+      refund_response_origin = EZHttp.Send(EZPaypal::Config.EndPoint["express_checkout_endpoint"], query_string, "post").body
+
+      # Convert response to Hash to return
+      profile_response = EZPaypal::Helper.ConvertParamToHash(refund_response_origin)
+    end
+
+  end
+end