elucid-adaptive_pay 0.2.1

data/.gitignore

@@ -0,0 +1 @@
+pkg

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Frederik Fix
+
+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/README

@@ -0,0 +1,186 @@
+Adaptive Pay
+============
+
+A wrapper for the Paypal Adaptive Payments API. For details see: https://www.x.com/docs/DOC-1408
+
+The adaptive payments API allows you to:
+1) send money to multiple (up to 5) recipients in one transaction
+2) preapprove payments, which can then be executed later without user intervention
+
+
+Installation
+-----------
+As plugin:
+script/plugin install git://github.com/derfred/adaptive_pay.git
+
+As gem:
+(in config/environment.rb)
+config.gem "adaptive_pay"
+Then run:
+rake gems:install
+
+
+Configuration
+-------------
+
+This plugin expects a file named config/adaptive_pay.yml to contain the configuration
+
+development:
+  instance: "sandbox"
+  username: "my_development_username"
+  password: "my_development_password"
+  signature: "my_development_signature"
+  application_id: "my_development_app_id"
+
+test:
+  retain_requests_for_test: true
+
+production:
+  instance: "production"
+  username: "my_production_username"
+  password: "my_production_password"
+  signature: "my_production_signature"
+  application_id: "my_production_app_id"
+
+Description of config parameters:
+  instance: can be either sandbox or production and refers to which instance of the Paypal service should be used
+  username, password, signature, application_id: the relevant authentication parameters for your account
+  retain_requests_for_test: mark this Rails environment as a test environment. If this parameter is set then all interactions with the API will remain local. For details see the testing section.
+  
+
+Chained/Split Payment Usage
+-------------------------------------
+
+The following example shows how to set up a chained payment for a total of 110 GBP, 10 GBP going to a primary receipient with the paypal account "agent@email.com" and 100 GBP going to the account "supplier@email.com". Because this is a chained payment it will seem to the user that the complete total will go to the primary account.
+
+interface = AdaptivePay::Interface.new
+response = interface.request_payment do |request|
+  request.currency_code = "GBP"
+
+  request.cancel_url = "http://example.com/cancelled_payment"        # this is where the user will be redirected should he cancel the payment
+  request.return_url = "http://example.com/completed_payment"       # and here should the payment be succesful
+  request.ipn_notification_url = "http://example.com/ipn_callback"      
+
+  request.add_recipient :email => "supplier@email.com",
+                        :amount => 100,
+                        :primary => false
+
+  request.add_recipient :email => "agent@email.com",
+                        :amount => 10,
+                        :primary => true
+end
+
+if response.created?
+  # the payment has been setup successfully, now the user will need to be redirected to the Paypal site:
+  redirect_to response.payment_page_url
+else
+  # the payment could not be setup, most likely because of a missing parameter or validation error
+  # the array of errors reported by the service can be retrieved using:
+  response.errors
+end
+
+This example could be changed to a Split Payment by setting the primary parameter to false for each recipient.
+
+After the payment has been set up and the user has been redirected to the payment page url, the application will need to wait for the IPN callback which indicates whether the payment has actually gone through. This is done in the next snippet. For this to work the ipn_callback_url specified above needs to be connected to a controller action.
+
+def ipn_callback
+  callback = AdaptivePay::Callback.new params
+  if callback.completed?
+    # payment has been processed, now mark order as paid etc
+  else
+    # payment failed
+  end
+end
+
+
+
+Preapproved Payment Usage
+---------------------------
+
+The next example will ask the user to preapprove a payment of 300 dollars and then distribute it equally among three recipients at a later date
+
+interface = AdaptivePay::Interface.new
+response = interface.request_preapproval do |request|
+  request.currency_code = "USD"
+
+  request.max_total_amount_of_all_payments = 300
+  request.ending_date = 3.months.from_now
+  request.starting_date = Time.now
+end
+
+if response.created?
+  # The preapproval has been set up. In addition to redirecting the user to the payment page we will have to keep track of the
+  # preapproval key for making the payment at a later time:
+  Approval.create :key => response.preapproval_key
+  redirect_to response.payment_page_url
+else
+  # error in request, same as above
+end
+
+Now at a later time the payment can be initiated without user intervention, in a cron job or rake task etc:
+
+approval = Approval.first :conditions => ....   # find the approval object created above
+interface = AdaptivePay::Interface.new
+response = interface.request_payment do |request|
+  request.currency_code = "USD"
+
+  request.ipn_notification_url = "http://example.com/ipn_callback"
+
+  request.preapproval_key = approval.key    # this is the preapproval key generated in the first step
+  request.add_recipient :email => "recipient1@email.com", :amount => 100
+  request.add_recipient :email => "recipient2@email.com", :amount => 100
+  request.add_recipient :email => "recipient3@email.com", :amount => 100
+end
+
+if response.pending?
+  # some payment methods require longer to process, in that case the API will return pending and notify using IPN callback
+elsif response.completed?
+  # payment has been processed, mark the order as paid etc
+else
+  # there was an error, see the errors array for details
+  response.errors
+end
+
+
+Object based calls
+-----------------
+
+Rather than using the block based calls shown above you can explicitly create a Request object and pass it to the perform method:
+
+payment_request = AdaptivePay::PaymentRequest.new
+payment_request.currency_code = "USD"
+payment_request.ipn_notification_url = "http://example.com/ipn_callback"
+payment_request.add_recipient :email => "recipient1@email.com", :amount => 100
+
+interface = AdaptivePay::Interface.new
+interface.perform  payment_request
+
+
+This is equivalent to:
+
+interface = AdaptivePay::Interface.new
+response = interface.request_payment do |request|
+  request.currency_code = "USD"
+  request.ipn_notification_url = "http://example.com/ipn_callback"
+  request.add_recipient :email => "recipient1@email.com", :amount => 100
+end
+
+Since the Request objects are stateless you can reuse them.
+
+
+Testing
+---------
+
+The main benefit to using this library is the support for testing. When a RAILS_ENV has the retain_requests_for_test parameter set in the config/adaptive_pay.yml file requests will not be delivered to the Paypal servers but rather added to a queue, just like ActionMailer does. One difference though is that you need to provide a stub response.
+
+it "should create preapproval request" do
+  AdaptivePay::Interface.test_response = stub(:response, :completed? => true, :pending? => false)
+  @payment_processor.process @order
+
+  AdaptivePay::Interface.requests.size.should == 1
+  request = AdaptivePay::Interface.requests.first
+
+  request.should be_a(AdaptivePay::PreapprovalRequest)
+  request.max_total_amount_of_all_payments.should == 130
+  request.currency_code.should == "GBP"
+end

data/Rakefile

@@ -0,0 +1,39 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+# Rakefile
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gemspec|
+    gemspec.name = "elucid-adaptive_pay"
+    gemspec.summary = "Wrapper around the Paypal Adaptive Payments API"
+    gemspec.description = "Wrapper around the Paypal Adaptive Payments API"
+    gemspec.email = %q{elucid@gmail.com}
+    gemspec.homepage = "http://github.com/elucid/adaptive_pay"
+    gemspec.authors = ["Frederik Fix", "Justin Giancola"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install jeweler -s http://gemcutter.org"
+end
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the <%= file_name %> plugin.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for the <%= file_name %> plugin.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = '<%= class_name %>'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.2.1

data/config/adaptive_pay.yml

@@ -0,0 +1,19 @@
+development:
+  environment: "sandbox"
+  username: "my_development_username"
+  password: "my_development_password"
+  signature: "my_development_signature"
+  application_id: "APP-80W284485P519543T"
+
+test:
+  retain_requests_for_test: true
+
+cucumber:
+  retain_requests_for_test: true
+
+production:
+  environment: "production"
+  username: "my_production_username"
+  password: "my_production_password"
+  signature: "my_production_signature"
+  application_id: "APP-80W284485P519543T"

data/elucid-adaptive_pay.gemspec

@@ -0,0 +1,90 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run the gemspec command
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{elucid-adaptive_pay}
+  s.version = "0.2.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Frederik Fix", "Justin Giancola"]
+  s.date = %q{2010-08-05}
+  s.description = %q{Wrapper around the Paypal Adaptive Payments API}
+  s.email = %q{elucid@gmail.com}
+  s.extra_rdoc_files = [
+    "README"
+  ]
+  s.files = [
+    ".gitignore",
+     "MIT-LICENSE",
+     "README",
+     "Rakefile",
+     "VERSION",
+     "config/adaptive_pay.yml",
+     "elucid-adaptive_pay.gemspec",
+     "init.rb",
+     "install.rb",
+     "lib/adaptive_pay.rb",
+     "lib/adaptive_pay/abstract_payment_request.rb",
+     "lib/adaptive_pay/callback.rb",
+     "lib/adaptive_pay/cancel_preapproval_request.rb",
+     "lib/adaptive_pay/interface.rb",
+     "lib/adaptive_pay/parser.rb",
+     "lib/adaptive_pay/payment_request.rb",
+     "lib/adaptive_pay/preapproval_request.rb",
+     "lib/adaptive_pay/recipient.rb",
+     "lib/adaptive_pay/refund_request.rb",
+     "lib/adaptive_pay/request.rb",
+     "lib/adaptive_pay/response.rb",
+     "lib/adaptive_pay/sender.rb",
+     "spec/adaptive_pay/abstract_payment_request_spec.rb",
+     "spec/adaptive_pay/callback_spec.rb",
+     "spec/adaptive_pay/cancel_preapproval_request_spec.rb",
+     "spec/adaptive_pay/interface_spec.rb",
+     "spec/adaptive_pay/parser_spec.rb",
+     "spec/adaptive_pay/payment_request_spec.rb",
+     "spec/adaptive_pay/preapproval_request_spec.rb",
+     "spec/adaptive_pay/recipient_spec.rb",
+     "spec/adaptive_pay/refund_request_spec.rb",
+     "spec/adaptive_pay/request_spec.rb",
+     "spec/adaptive_pay/response_spec.rb",
+     "spec/adaptive_pay/sender_spec.rb",
+     "spec/fixtures/config/adaptive_pay.yml",
+     "spec/rails_mocks.rb",
+     "spec/spec_helper.rb",
+     "uninstall.rb"
+  ]
+  s.homepage = %q{http://github.com/elucid/adaptive_pay}
+  s.rdoc_options = ["--charset=UTF-8"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.3.5}
+  s.summary = %q{Wrapper around the Paypal Adaptive Payments API}
+  s.test_files = [
+    "spec/adaptive_pay/abstract_payment_request_spec.rb",
+     "spec/adaptive_pay/callback_spec.rb",
+     "spec/adaptive_pay/cancel_preapproval_request_spec.rb",
+     "spec/adaptive_pay/interface_spec.rb",
+     "spec/adaptive_pay/parser_spec.rb",
+     "spec/adaptive_pay/payment_request_spec.rb",
+     "spec/adaptive_pay/preapproval_request_spec.rb",
+     "spec/adaptive_pay/recipient_spec.rb",
+     "spec/adaptive_pay/refund_request_spec.rb",
+     "spec/adaptive_pay/request_spec.rb",
+     "spec/adaptive_pay/response_spec.rb",
+     "spec/adaptive_pay/sender_spec.rb",
+     "spec/rails_mocks.rb",
+     "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    else
+    end
+  else
+  end
+end
+

data/init.rb

@@ -0,0 +1 @@
+require "adaptive_pay"

data/install.rb

@@ -0,0 +1,4 @@
+config_path = File.join('config', 'adaptive_pay.yml')
+unless File.exist?(File.join(RAILS_ROOT, config_path))
+  FileUtils.cp File.join(File.dirname(__FILE__), config_path), File.join(RAILS_ROOT, config_path)
+end

data/lib/adaptive_pay.rb

@@ -0,0 +1,12 @@
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/interface')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/request')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/abstract_payment_request')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/preapproval_request')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/payment_request')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/refund_request')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/cancel_preapproval_request')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/parser')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/response')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/sender')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/recipient')
+require File.expand_path(File.dirname(__FILE__) + '/adaptive_pay/callback')

data/lib/adaptive_pay/abstract_payment_request.rb

@@ -0,0 +1,44 @@
+module AdaptivePay
+  class AbstractPaymentRequest < Request
+
+    attribute "requestEnvelope.detailLevel"
+    attribute "requestEnvelope.errorLanguage", :default => "en_US"
+
+    attribute "clientDetails.ipAddress"
+    attribute "clientDetails.applicationId"
+    attribute "clientDetails.customerId"
+    attribute "clientDetails.customerType"
+    attribute "clientDetails.deviceId"
+    attribute "clientDetails.geoLocation"
+    attribute "clientDetails.model"
+    attribute "clientDetails.partnerName"
+
+    attribute "currencyCode"
+    attribute "ipnNotificationUrl"
+    attribute "cancelUrl"
+    attribute "returnUrl"
+
+    attribute "memo"
+    attribute "senderEmail"
+
+    attr_reader :sender
+
+    def sender=(sender_options)
+      if sender_options.is_a?(AdaptivePay::Sender)
+        @sender = sender_options
+      else
+        @sender = AdaptivePay::Sender.new sender_options
+      end
+    end
+
+    protected
+      def extra_attributes
+        return super if sender.blank?
+        result = {}
+        result["clientDetails.ipAddress"] = sender.client_ip
+        result["senderEmail"] = sender.email unless sender.email.blank?
+        super.merge(result)
+      end
+
+  end
+end

data/lib/adaptive_pay/callback.rb

@@ -0,0 +1,17 @@
+module AdaptivePay
+  class Callback
+
+    def initialize(params)
+      @params = params
+    end
+
+    def method_missing(name, *args)
+      @params[name.to_s] || super
+    end
+
+    def completed?
+      payment_status == "Completed"
+    end
+
+  end
+end