ruby-paypal 0.0.4 → 0.0.5

data/lib/ruby-paypal/paypal.rb

@@ -6,7 +6,7 @@ require 'ruby-paypal/credit_card_checks'
 
 SANDBOX_SERVER = 'api-3t.sandbox.paypal.com/nvp'
 PRODUCTION_SERVER = 'api-3t.paypal.com/nvp'
-API_VERSION = '3.2'
+API_VERSION = '56.0' 
 
 module Net
   #
@@ -59,13 +59,16 @@ end
 
 
 =begin rdoc
-Author::    Chang Sau Sheong  (mailto:sausheong.chang@gmail.com)
-Copyright:: Copyright (c) 2007 Chang Sau Sheong
+Author::	Chang Sau Sheong  (mailto:sausheong.chang@gmail.com)
+Author::	Philippe F. Monnet (mailto:pfmonnet@gmail.com)
+Copyright:: Copyright (c) 2007-2009 Chang Sau Sheong & Philippe F. Monnet
 License::   Distributes under the same terms as Ruby
-Version:: 0.0.2
+Version:: 0.0.5
+
+:main: Paypal
 
 =Installing Ruby-PayPal
-A lightweight ruby wrapper for PayPal NVP APIs. To install type the following
+A lightweight ruby wrapper for PayPal NVP (Name-Value Pair) APIs. To install type the following
 at the command line:
 
   $ gem install ruby-paypal
@@ -74,13 +77,18 @@ at the command line:
 =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). 
+Reference - see:
+- https://www.paypal.com/en_US/ebook/PP_NVPAPI_DeveloperGuide/index.html
+- https://cms.paypal.com/us/cgi-bin/?&cmd=_render-content&content_ID=developer/e_howto_api_soap_NVPAPIOverview
+
 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.
 
+By setting Paypal.debug=true, the API will "pretty-print" the PayPal parameters to the console.
+
 ==Direct Payment
 To use credit card payment through PayPal, you need to use the DoDirectPayment APIs:
 
@@ -114,14 +122,144 @@ To use the customer's PayPal account for payment, you will need to use the Expre
 
 <to be documented>
 
-=More information
-I will be continually providing updates in my blog at http://blog.saush.com
+==PayPal Subscriptions
+
+PayPal Subscriptions is a service offering allowing you to sell subscriptions, consisting of an initial payment followed by
+several recurring payments. For a good technical overview, review the following guide:
+- https://www.paypal.com/en_US/ebook/PP_ExpressCheckout_IntegrationGuide/RecurringPayments.html
+
+Using the subscriptions service involve understanding the series of exchanges to perform using the NVP API.
+There are 3 key phases of a subscription:
+1. Creating a subscription request (and button for the customer)
+2. Customer review and confirmation on the PayPal site
+3. Processing of a subscription agreement
+Each phase involves specific APIs.
+
+===Phase 1 - Subscription Request
+In this phase, the do_set_express_checkout method will be called. PayPal will return a token we can use in subsequent API calls.
+
+Let's create a subcription request with the details of our subscription:
+
+	subscription_request = create_monthly_subscription_request(
+		name='_Why's Ruby Camping Adventures',
+		id='MNWRCA',
+		description='_Why's Ruby Camping Adventures - Monthly Tips And Tricks For Camping Development',
+		invoice_number='INV20091122',
+		amount='5.00')
+
+Let's call do_set_express_checkout to get a token back:
+				
+	response = paypal.do_set_express_checkout(
+		return_url='http://www.yoursite.com/subscription-confirmed', 
+		cancel_url='http://www.yoursite.com/subscription-aborted', 
+		amount='5.00',
+		other_params=subscription_request)
+	
+	token = (response.ack == 'Success') ? response['TOKEN'] : ''
+
+Let's use the token to create a PayPal button to request payment via the sandbox:
+
+	form( { :method => 'post' , 
+				:action => 'https://www.sandbox.paypal.com/cgi-bin/webscr' #sandbox
+				} ) do
+
+			input :id => 'cmd', :name => 'cmd', :type => 'hidden', 
+				  :value => "_express-checkout"; 
+
+			input :id => 'token', :name => 'token', :type => 'hidden', 
+				  :value => "#{token}"; 
+
+			input :id => 'submit_subscription_request', :name => 'submit', :type => 'submit', 						 
+				  :value => 'Subscribe Via PayPal'
+	end #form
+			
+===Phase 2 - Customer Review and Confirmation
+
+The customer will see the details of the subscription agreement we created previously.
+Upon confirmation, PayPal will redirect the customer to the return_url we specified passing 
+the token back as well as the payerid.
 
+===Phase 3 = Subscription Processing
+
+First we will retrieve the details of the check-out:
+
+	response = paypal.do_get_express_checkout_details(token)
+
+Then we will execute the actual payment:
+	
+	response = paypal.do_express_checkout_payment(token=token,
+		payment_action='Sale',
+		payer_id=payerid,
+		amount='5.00')
+
+	transaction_id = response['TRANSACTIONID']
+
+Now we can create the actual PayPal subscription
+
+	response = @paypal.do_create_recurring_payments_profile(token,
+		start_date='2009-11-22 14:30:10',
+		profile_reference='INV20091122',
+		description='_Why's Ruby Camping Adventures - Monthly Tips And Tricks For Camping Development',
+		billing_period='Month',
+		billing_frequency=1, 
+		total_billing_cycles=11,
+		amount='5.00',
+		currency='USD')
+
+	profile_id = @response['PROFILEID']
+
+The profile_id can then be used in the future to access the details of the subscription,
+suspend it, reactivate it or cancel it using the following methods:
+- do_get_recurring_payments_profile_details
+
+	response = paypal.do_get_recurring_payments_profile_details(profile_id)
+	
+- do_manage_recurring_payments_profile_status
+	
+	# Suspend
+	response = paypal.do_manage_recurring_payments_profile_status(profile_id, 
+		action='Suspend', 
+		note='The subscription is being suspended due to payment cancellation by the customer')
+
+	# Re-Activate
+	response = paypal.do_manage_recurring_payments_profile_status(profile_id, 
+		action='Reactivate', 
+		note='The subscription is being reactivated due to new payment by the customer')
+
+	# Cancel
+	response = paypal.do_manage_recurring_payments_profile_status(profile_id, 
+		action='Cancel', 
+		note='The subscription is being cancelled due to cancellation of the account by the customer')
+		
+The customer information associated with the subscription can be retrieved using:
+- do_get_billing_agreement_customer_details
+	
+	response = paypal.do_get_billing_agreement_customer_details(token)
+
+Note: all subscriptions methods also accept an optional other_params hash for any other NVP you need to pass.
+
+	
+=More information
+Check for updates in our blogs:
+- http://blog.saush.com
+- http://blog.monnet-usa.com
 =end
 
 class Paypal
   include CreditCardChecks
 
+  @@debug = false
+  
+  def self.debug
+	@@debug
+  end
+  
+  # Controls whether or not PP debug statements will be produced and sent to the console	
+  #
+  def self.debug=(val) #:doc:
+	@@debug = val
+  end
+  
   # 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.
@@ -193,6 +331,10 @@ class Paypal
       #
       # Equivalent of SetExpressCheckout.
       #
+      def do_set_express_checkout(return_url, cancel_url, amount, other_params={})
+		return set_express_checkout(return_url, cancel_url, amount, other_params)
+	  end
+	  
       def set_express_checkout(return_url, cancel_url, amount, other_params={})
         params = {
           'METHOD' => 'SetExpressCheckout',
@@ -231,8 +373,6 @@ class Paypal
         }   
         
         params.merge! other_params
-        pp "DO EXPRESS CHECKOUT PAYMENT"
-        pp params
         make_nvp_call(params)    
       end
 
@@ -294,7 +434,8 @@ class Paypal
       # Makes the call to the PayPal NVP API. This is the workhorse method for the other method calls.
       #
       def make_nvp_call(params)
-        pp params
+		pp params if @@debug
+		
         @api_parameters.merge! params
         parameters = URI.escape(@api_parameters.to_a.collect {|pair| pair.join('=')}.join('&'))
         response = Net::HTTPS.post_form(URI.parse("https://#{@paypal_url}"), @api_parameters)
@@ -341,6 +482,146 @@ class Paypal
         make_nvp_call(params)        
       end
 
+	 # techarch> Subscription APIs
+	 
+    # Creates a payment subscription based on a start date, billing period, frequency, number of periods and amount
+    # 
+    # Equivalent to CreateRecurringPaymentsProfile
+    #
+    def do_create_recurring_payments_profile(token, start_date, profile_reference, description, billing_period, billing_frequency, total_billing_cycles, amount, currency, other_params={})
+      params = {
+        'METHOD' => 'CreateRecurringPaymentsProfile',
+        'TOKEN' => token,
+		'PROFILESTARTDATE' => start_date,
+		'PROFILEREFERENCE' => profile_reference,
+		'DESC' => description,
+		'BILLINGPERIOD' => billing_period,
+		'BILLINGFREQUENCY' => billing_frequency,
+		'TOTALBILLINGCYCLES' => total_billing_cycles,
+		'AMT' => amount,
+		'CURRENCYCODE' => currency
+		} 
+        params.merge! other_params
+
+        make_nvp_call(params)
+     end
+	  
+    # Retrieves the details of a payment subscription for a given profile id
+	# Will return for e.g. the  start date, billing period, frequency, number of periods and amount
+    # 
+    # Equivalent to GetRecurringPaymentsProfileDetails
+    #
+    def do_get_recurring_payments_profile_details (profile_id, other_params={})
+      params = {
+        'METHOD' => 'GetRecurringPaymentsProfileDetails',
+        'PROFILEID' => profile_id } 
+        params.merge! other_params
+
+        make_nvp_call(params)
+    end
+
+    # Manages a recurring subscription profile in terms of status:
+    #   - Cancel
+	#   - Suspend
+	#   - Reactivate
+    # Equivalent to ManageRecurringPaymentsProfileStatus
+    #
+	def do_manage_recurring_payments_profile_status(profile_id, action, note='', other_params={})
+      params = {
+        'METHOD' => 'ManageRecurringPaymentsProfileStatus',
+        'PROFILEID' => profile_id,
+		'ACTION' => action,
+		'NOTE' => note
+		} 
+        params.merge! other_params
+
+        make_nvp_call(params)
+	end
+	
+    # Retrieves the customer details for the billing agreement associated with the current token
+    # Equivalent to GetBillingAgreementCustomerDetails
+    #
+	def do_get_billing_agreement_customer_details(token, other_params={})
+      params = {
+        'METHOD' => 'GetBillingAgreementCustomerDetails',
+        'TOKEN' => token
+		} 
+        params.merge! other_params
+
+        make_nvp_call(params)
+	end
+	
+    # Initiates the creation of a billing agreement 
+    # Equivalent to SetCustomerBillingAgreement
+    #
+	def do_set_billing_agreement_customer_details(return_url, cancel_url, billing_desc, billing_type='RecurringPayments', payment_type='', custom='', other_params={})
+      params = {
+        'METHOD' => 'SetCustomerBillingAgreement',
+			'RETURNURL' => return_url,
+			'CANCELURL' => cancel_url,
+			'L_BILLINGAGREEMENTDESCRIPTION0' => billing_desc,
+			'L_BILLINGTYPE0' => billing_type,
+			'L_PAYMENTTYPE0' => payment_type,
+			'L_BILLINGAGREEMENTCUSTOM0' => custom
+		} 
+        params.merge! other_params
+
+        make_nvp_call(params)
+	end
+	
+    # Retrieves the details of a transaction for a given transaction id
+    # 
+    # Equivalent to GetTransactionDetails
+    #
+    def do_get_transaction_details (transaction_id, other_params={})
+      params = {
+        'METHOD' => 'GetTransactionDetails',
+        'TRANSACTIONID' => transaction_id } 
+        params.merge! other_params
+
+        make_nvp_call(params)
+    end
+
+    # Retrieves the details of a express checkout for a given token
+    # 
+    # Equivalent to GetExpressCheckoutDetails
+    #
+    def do_get_express_checkout_details (token, other_params={})
+      params = {
+        'METHOD' => 'GetExpressCheckoutDetails',
+        'TOKEN' => token } 
+        params.merge! other_params
+
+        make_nvp_call(params)
+      end
+
+    # Search transactions between payee and payer
+    # Equivalent to TransactionSearch
+    #
+	def do_transaction_search(start_date,payee_email, payer_email='', payer_first='', payer_middle='', payer_last='', 
+												transaction_class='Subscription', other_params={})
+      params = {
+        'METHOD' => 'TransactionSearch',
+			'STARTDATE' => start_date,
+			'RECEIVER' => payee_email,
+			'TRANSACTIONCLASS' => transaction_class
+		} 
+		
+		if !payer_email.nil? && !payer_email.empty?
+			params['EMAIL'] = payer_email 
+		else
+			params['FIRSTNAME'] 		= payer_first		!payer_first.nil? && !payer_first.empty?
+			params['MIDDLENAME']	= payer_middle	!payer_middle.nil? && !payer_middle.empty?
+			params['LASTNAME'] 		= payer_last		!payer_last.nil? && !payer_last.empty?
+		end
+		
+        params.merge! other_params
+
+        make_nvp_call(params)
+	end
+	
+	# --------------------------------------------------------------------------------------------------------------------------------------
+	  
       private
 
       #

metadata

@@ -1,20 +1,23 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-paypal
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors: 
 - Chang Sau Sheong
+- Philippe F. Monnet
 autorequire: ruby-paypal
 bindir: bin
 cert_chain: []
 
-date: 2008-07-19 00:00:00 +08:00
+date: 2009-11-27 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
-description: 
-email: sausheong.chang@gmail.com
+description: "  ruby-paypal is a lightweight wrapper for the PayPal Name-Value Pair API providing:\n   - direct payments\n   - subscription and recurring payments\n"
+email: 
+- sausheong.chang@gmail.com
+- pfmonnet@gmail.com
 executables: []
 
 extensions: []
@@ -22,14 +25,15 @@ extensions: []
 extra_rdoc_files: 
 - README
 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
 - README
 has_rdoc: true
-homepage: http://blog.saush.com
+homepage: http://rubyforge.org/projects/ruby-paypal/
+licenses: []
+
 post_install_message: 
 rdoc_options: []
 
@@ -49,10 +53,10 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   version: 
 requirements: []
 
-rubyforge_project: 
-rubygems_version: 1.0.1
+rubyforge_project: ruby-paypal
+rubygems_version: 1.3.5
 signing_key: 
-specification_version: 2
-summary: A lightweight Ruby wrapper for PayPal NVP API
+specification_version: 3
+summary: A lightweight Ruby wrapper for the PayPal NVP API providing payment and subscriptions capabilities
 test_files: 
 - test/ts_ruby-paypal.rb