paypal-recurring 0.1.0

data/.gitignore

@@ -0,0 +1,3 @@
+.DS_Store
+pkg
+tmp

data/.rspec

@@ -0,0 +1 @@
+--color --format documentation

data/Gemfile

@@ -0,0 +1,2 @@
+source :rubygems
+gemspec

data/Gemfile.lock

@@ -0,0 +1,45 @@
+PATH
+  remote: .
+  specs:
+    paypal-recurring (0.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    archive-tar-minitar (0.5.2)
+    columnize (0.3.3)
+    diff-lcs (1.1.2)
+    fakeweb (1.3.0)
+    linecache19 (0.5.12)
+      ruby_core_source (>= 0.1.4)
+    rake (0.8.7)
+    rspec (2.6.0)
+      rspec-core (~> 2.6.0)
+      rspec-expectations (~> 2.6.0)
+      rspec-mocks (~> 2.6.0)
+    rspec-core (2.6.4)
+    rspec-expectations (2.6.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.6.0)
+    ruby-debug-base19 (0.11.25)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby_core_source (>= 0.1.4)
+    ruby-debug19 (0.11.6)
+      columnize (>= 0.3.1)
+      linecache19 (>= 0.5.11)
+      ruby-debug-base19 (>= 0.11.19)
+    ruby_core_source (0.1.5)
+      archive-tar-minitar (>= 0.5.2)
+    vcr (1.10.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  fakeweb (~> 1.3.0)
+  paypal-recurring!
+  rake (~> 0.8.7)
+  rspec (~> 2.6)
+  ruby-debug19
+  vcr (~> 1.10)

data/README.rdoc

@@ -0,0 +1,128 @@
+= PayPal Recurring Billing
+
+PayPal Express Checkout API Client for recurring billing.
+
+== Installation
+
+  gem install paypal-recurring
+
+== Usage
+
+First, you need to set up your credentials:
+
+  require "paypal/recurring"
+
+  PayPal::Recurring.configure do |config|
+    config.sandbox = true
+    config.username = "seller_1308793919_biz_api1.simplesideias.com.br"
+    config.password = "1308793931"
+    config.signature = "AFcWxV21C7fd0v3bYYYRCpSSRl31AzaB6TzXx5amObyEghjU13.0av2Y"
+  end
+
+Then, you can request a new payment authorization:
+
+  ppr = PayPal::Recurring.new({
+    :return_url   => "http://example.com/paypal/thank_you",
+    :cancel_url   => "http://example.com/paypal/canceled",
+    :ipn_url      => "http://example.com/paypal/ipn",
+    :description  => "Awesome - Monthly Subscription",
+    :amount       => "9.00",
+    :currency     => "USD"
+  })
+
+  response = ppr.checkout
+  puts response.checkout_url if response.valid?
+
+You need to redirect your user to the url returned by <tt>response.checkout_url</tt>.
+After the user accepts or rejects your payment request, he will be redirected to one of those urls you specified.
+The return url will receive two parameters: <tt>PAYERID</tt> and <tt>TOKEN</tt>. You can use the <tt>TOKEN</tt>
+parameter to identify your user on your database.
+
+If you need to retrieve information about your buyer, like address or e-mail, you can use the
+<tt>checkout_details()</tt> method.
+
+  ppr = PayPal::Recurring.new(:token => "EC-05C46042TU8306821")
+  response = ppr.checkout_details
+
+Now, you need to request payment. The information you provide here should be exactly the same when you started
+the checkout process.
+
+  ppr = PayPal::Recurring.new({
+    :token       => "EC-05C46042TU8306821",
+    :payer_id    => "WTTS5KC2T46YU",
+    :amount      => "9.00",
+    :description => "Awesome - Monthly Subscription"
+  })
+  response = ppr.request_payment
+  response.approved?
+  response.completed?
+
+Finally, you need to create a new recurring profile.
+
+  ppr = PayPal::Recurring.new({
+    :amount      => "9.00",
+    :currency    => "USD",
+    :description => "Awesome - Monthly Subscription",
+    :ipn_url     => "http://example.com/paypal/ipn",
+    :frequency   => 1,
+    :token       => "EC-05C46042TU8306821",
+    :period      => :monthly,
+    :reference   => "1234",
+    :payer_id    => "WTTS5KC2T46YU",
+    :start_at    => Time.now,
+    :failed      => 1,
+    :outstanding => :next_billing
+  })
+
+  response = ppr.create_recurring_profile
+  puts response.profile_id
+
+You can manage your recurring profile.
+
+  ppr = PayPal::Recurring.new(:profile_id => "I-VCEL6TRG35CU")
+
+  ppr.suspend
+  ppr.reactivate
+  ppr.cancel
+
+=== What information do I need to keep?
+
+You should save two paramaters to your database: <tt>TOKEN</tt> and <tt>PROFILEID</tt>.
+<tt>TOKEN</tt> is required when user returns to your website after he authorizes (or not) the billing process. You
+need to save it so you can find him later. You can remove this info after payment and recurring profile are set.
+
+The <tt>PROFILEID</tt> allows you to manage the recurring profile, like canceling billing when an user don't
+want to use your service anymore.
+
+<b>NOTE:</b> TOKEN will expire after approximately 3 hours.
+
+== TO-DO
+
+* handle Instant Payment Notifications (IPN)
+
+== Maintainer
+
+* Nando Vieira (http://nandovieira.com.br)
+
+== License
+
+(The 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/Rakefile

@@ -0,0 +1,5 @@
+require "bundler"
+Bundler::GemHelper.install_tasks
+
+require "rspec/core/rake_task"
+RSpec::Core::RakeTask.new

data/lib/paypal-recurring.rb

@@ -0,0 +1 @@
+require "paypal/recurring"

data/lib/paypal/recurring.rb

@@ -0,0 +1,106 @@
+require "net/https"
+require "cgi"
+require "uri"
+require "logger"
+require "ostruct"
+require "time"
+
+module PayPal
+  module Recurring
+    autoload :Base, "paypal/recurring/base"
+    autoload :Request, "paypal/recurring/request"
+    autoload :Response, "paypal/recurring/response"
+    autoload :Version, "paypal/recurring/version"
+
+    ENDPOINTS = {
+       :sandbox => {
+         :api  => "https://api-3t.sandbox.paypal.com/nvp",
+         :site => "https://www.sandbox.paypal.com/cgi-bin/webscr"
+       },
+       :production => {
+         :api  => "https://api-3t.paypal.com/nvp",
+         :site => "https://www.paypal.com/cgi-bin/webscr"
+       }
+    }
+
+    class << self
+      # Define if requests should be made to PayPal's
+      # sandbox environment. This is specially useful when running
+      # on development or test mode.
+      #
+      #   PayPal::Recurring.sandbox = true
+      #
+      attr_accessor :sandbox
+
+      # Set PayPal's API username.
+      #
+      attr_accessor :username
+
+      # Set PayPal's API password.
+      #
+      attr_accessor :password
+
+      # Set PayPal's API signature.
+      #
+      attr_accessor :signature
+
+      # Set application logger. By default, will send output to +STDOUT+.
+      #
+      attr_accessor :logger
+    end
+
+    self.logger = Logger.new(STDOUT)
+
+    # Just a shortcut for <tt>PayPal::Recurring::Base.new</tt>.
+    #
+    def self.new(options = {})
+      Base.new(options)
+    end
+
+    # Configure PayPal::Recurring options.
+    #
+    #   PayPal::Recurring.configure do |config|
+    #     config.sandbox = true
+    #   end
+    #
+    def self.configure(&block)
+      yield PayPal::Recurring
+    end
+
+    # Detect if sandbox mode is enabled.
+    #
+    def self.sandbox?
+      sandbox == true
+    end
+
+    # Return a name for current environment mode (sandbox or production).
+    #
+    def self.environment
+      sandbox? ? :sandbox : :production
+    end
+
+    # Return URL endpoints for current environment.
+    #
+    def self.endpoints
+      ENDPOINTS[environment]
+    end
+
+    # Return API endpoint based on current environment.
+    #
+    def self.api_endpoint
+      endpoints[:api]
+    end
+
+    # Return PayPal's API version.
+    #
+    def self.api_version
+      "72.0"
+    end
+
+    # Return site endpoint based on current environment.
+    #
+    def self.site_endpoint
+      endpoints[:site]
+    end
+  end
+end

data/lib/paypal/recurring/base.rb

@@ -0,0 +1,149 @@
+module PayPal
+  module Recurring
+    class Base
+      attr_accessor :amount
+      attr_accessor :cancel_url
+      attr_accessor :currency
+      attr_accessor :description
+      attr_accessor :failed
+      attr_accessor :frequency
+      attr_accessor :ipn_url
+      attr_accessor :outstanding
+      attr_accessor :payer_id
+      attr_accessor :period
+      attr_accessor :profile_id
+      attr_accessor :reference
+      attr_accessor :return_url
+      attr_accessor :start_at
+      attr_accessor :token
+      attr_accessor :email
+
+      def initialize(options = {})
+        options.each {|name, value| send("#{name}=", value)}
+      end
+
+      # Just a shortcut convenience.
+      #
+      def request # :nodoc:
+        @request ||= Request.new
+      end
+
+      # Request a checkout token.
+      #
+      #   ppr = PayPal::Recurring.new({
+      #     :return_url         => "http://example.com/checkout/thank_you",
+      #     :cancel_url         => "http://example.com/checkout/canceled",
+      #     :ipn_url            => "http://example.com/paypal/ipn",
+      #     :description        => "Awesome - Monthly Subscription",
+      #     :amount             => "9.00",
+      #     :currency           => "USD"
+      #   })
+      #
+      #   response = ppr.request_token
+      #   response.checkout_url
+      #
+      def checkout
+        params = collect(:amount, :return_url, :cancel_url, :currency, :description, :ipn_url).merge(:payment_action => "Authorization", :no_shipping => 1, :L_BILLINGTYPE0 => "RecurringPayments")
+        request.post(:checkout, params)
+      end
+
+      # Suspend a recurring profile.
+      # Suspended profiles can be reactivated.
+      #
+      #   ppr = PayPal::Recurring.new(:profile_id => "I-HYRKXBMNLFSK")
+      #   response = ppr.suspend
+      #
+      def suspend
+        request.post(:manage_profile, :action => :suspend, :profile_id => profile_id)
+      end
+
+      # Reactivate a suspended recurring profile.
+      #
+      #   ppr = PayPal::Recurring.new(:profile_id => "I-HYRKXBMNLFSK")
+      #   response = ppr.reactivate
+      #
+      def reactivate
+        request.post(:manage_profile, :action => :reactivate, :profile_id => profile_id)
+      end
+
+      # Cancel a recurring profile.
+      # Cancelled profiles cannot be reactivated.
+      #
+      #   ppr = PayPal::Recurring.new(:profile_id => "I-HYRKXBMNLFSK")
+      #   response = ppr.cancel
+      #
+      def cancel
+        request.post(:manage_profile, :action => :cancel, :profile_id => profile_id)
+      end
+
+      # Return checkout details.
+      #
+      #   ppr = PayPal::Recurring.new(:token => "EC-6LX60229XS426623E")
+      #   response = ppr.checkout_details
+      #
+      def checkout_details
+        request.post(:details, :token => token)
+      end
+
+      # Request payment.
+      #
+      #   # ppr = PayPal::Recurring.new({
+      #     :token       => "EC-6LX60229XS426623E",
+      #     :payer_id    => "WTTS5KC2T46YU",
+      #     :amount      => "9.00",
+      #     :description => "Awesome - Monthly Subscription"
+      #   })
+      #   response = ppr.request_payment
+      #   response.completed? && response.approved?
+      #
+      def request_payment
+        params = collect(:amount, :return_url, :cancel_url, :ipn_url, :currency, :description, :payer_id, :token).merge(:payment_action => "Sale")
+        request.post(:payment, params)
+      end
+
+      # Create a recurring billing profile.
+      #
+      #   ppr = PayPal::Recurring.new({
+      #     :amount      => "9.00",
+      #     :currency    => "USD",
+      #     :description => "Awesome - Monthly Subscription",
+      #     :ipn_url     => "http://example.com/paypal/ipn",
+      #     :frequency   => 1,
+      #     :token       => "EC-05C46042TU8306821",
+      #     :period      => :monthly,
+      #     :reference   => "1234",
+      #     :payer_id    => "WTTS5KC2T46YU",
+      #     :start_at    => Time.now,
+      #     :failed      => 1,
+      #     :outstanding => :next_billing
+      #   })
+      #
+      #   response = ppr.create_recurring_profile
+      #
+      def create_recurring_profile
+        params = collect(:amount, :currency, :description, :payer_id, :token, :reference, :start_at, :failed, :outstanding, :ipn_url, :frequency, :period, :email)
+        request.post(:create_profile, params)
+      end
+
+      # Retrieve information about existing recurring profile.
+      #
+      #   ppr = PayPal::Recurring.new(:profile_id => "I-VCEL6TRG35CU")
+      #   response = ppr.profile
+      #
+      def profile
+        request.post(:profile, :profile_id => profile_id)
+      end
+
+      private
+      # Collect specified attributes and build a hash out of it.
+      #
+      def collect(*args) # :nodoc:
+        args.inject({}) do |buffer, attr_name|
+          value = send(attr_name)
+          buffer[attr_name] = value if value
+          buffer
+        end
+      end
+    end
+  end
+end