== Welcome to Paypal/ruby

This library is here to aid with integrating Paypal payments into ruby on rails 
applications or similar. To set this up you will need to log into your paypal 
business account and tell paypal where to send the IPN ( Instant payment notifications ). 

== Download

* Preferred method of installation is using rubygems. gem install paypal --source http://dist.leetsoft.com
* Alternatively you can get the library packaged at http://dist.leetsoft.com/pkg/

== Requirements

* Ruby 1.8.2 (may work with previous versions) With OpenSSL support compiled in. 
* Valid paypal business account. 
* (optional) The money library from http://dist.leetsoft.com/api/money 

== Installation 

1) Install the plugin using ./script/plugin install svn://vault.jadedpixel.com/paypal/trunk/paypal


2) Create a paypal_ipn ( or similar ) action like the one in the "Example rails controller" appendix. 

Within the new payment controller you can now create pages from which users can be sent to paypal. You always 
have to sent users to paypal using a HTTP Post so a standard link won't work (well OK but you need some javascript for that). The +Paypal::Helper+ namespace has some examples of how such a forward page may look. 

== Testing the integration

Under https://developer.paypal.com/ you can signup for a paypal developer account.
This allows you to set up "sandboxed" accounts which work and act like real accounts 
with the difference that no money is exchanged. Its a good idea to sign up for a 
sandbox account to use while the application is running in development mode. 


== Example rails controller

    class BackendController < ApplicationController

      # Simplification, please write better code then this...
      def paypal_ipn
       notify = Paypal::Notification.new(request.raw_post)

       if notify.acknowledge 
         order = Order.find(notify.item_id)
         order.success = (notify.complete? and order.total == notify.amount) ? 'success' : 'failure'
         order.save
       end

       render :nothing => true
      end
    end

== Example paypal forward page

   <%= paypal_form_tag %>
     <%= paypal_setup "Item 500", Money.us_dollar(50000), "[email protected]", :notify_url => url_for(:only_path => false, :action => 'paypal_ipn') %>  

     Please press here to pay $500US using paypal. <br/>
     <%= submit_tag "Go to paypal >>" %>

   </form>
   
   or, with the same results, the block version:

   <% paypal_form_tag do %>
     <%= paypal_setup "Item 500", Money.us_dollar(50000), "[email protected]", :notify_url => url_for(:only_path => false, :action => 'paypal_ipn') %>  

     Please press here to pay $500US using paypal. <br/>
     <%= submit_tag "Go to paypal >>" %>

   <% end %>

== Using encrypted form data

Paypal supports encrypted form data to prevent tampering by third parties.
You must have a verified paypal account to use this functionality.

1) Create a private key for yourself

    openssl genrsa -out business_key.pem 1024

2) Create a public certificate to share with Paypal

    openssl req -new -key business_key.pem -x509 -days 3650 -out business_cert.pem

3) Upload the public certificate to Paypal (under Profile -> Encrypted Payment Settings -> Your Public Certificates -> Add),
and note the "Cert ID" that Paypal shows for the certificate.

4) Update your controller to include the details for your key and certificate.

    @business_key = File::read("business_key.pem")
    @business_cert = File::read("business_cert.pem")
    @business_certid = "certid from paypal"

5) Update your views to populate the :business_key, :business_cert and :business_certid options in 'paypal_setup' - the rest of the signature is the same.

6) When you're ready to go live, download the production Paypal certificate and override the default certificate.

    Paypal::Notification.paypal_cert = File::read("paypal_cert.pem")

7) Finally, add the following line to your environment.rb or inside an initializer:

    Paypal::Notification.ipn_url = "https://www.paypal.com/cgi-bin/webscr"

== Troubleshooting

uninitalized constant Paypal - Make sure your ruby has openssl support

== Changelog

2008-10-16 -- 2.0.2
    NEW: Added block style support for paypal_form_tag (paypal_form_tag do blah.. blah... end)
    DEL: Removed patch for 2.0.0, no longer seems suitable.
    NEW: Added testing for the paypal_form_tag block style.
    NEW: Added a sample (actual from paypal sandbox) PayPal server response for IPN, to aid in testing.

2008-10-15 -- 2.0.1
    CHG: Modified README.
    FIX: Moved patch to own directory, was being caught by git-hub as gem's README
    NEW: Added patch for currently installed paypal-2.0.0 gem to apply directly on gems directory.
    NEW: Added relevant test statements.
    FIX: removed duplicate 'invoice' method in lib/notification.rb
    NEW: added correct 'custom' method to lib/notification.rb
    NEW: added pending_reason, reason_code, memo, payment_type, exchange_rate methods to lib/notification.rb

2006-04-20 -- 2.0.0 
* Uses paypal extended syntax. The plugin can now submit shipping and billing addresses using the paypal_address helper.

2006-04-20 -- 1.7.0 
* Now a rails plugin

2006-02-10 -- 1.5.1
* added complete list of valid paypal options (Paul Hart)

2006-02-02 -- 1.5.0
* Now report an error when invalid option is passed to paypal_setup
* Had to rename parameters cancel_url to cancel_return and return_url to return, please update your app
* Improved the test coverage strategy for helper tests
* Added support for encrypted form data (Paul Hart)

2005-09-16 -- 0.9.6
* Added readme note about the openssl requirement

2005-07-26 -- 0.9.5
* Added tax to the helper parameters
* fixed bug when money class was used to pass in amount. Cents were always 00 (doh!)
* Added invoice and custom optional parameters
* Added charset = utf-8 to all paypal posts
* Wrongly used undefined_quanitity parameter in 0.9.1, this caused users to be prompted for the quanitity on the paypal checkout page... fixed

2005-07-22 -- 0.9.1
* support for cancel_url as well as notify_url. This means you can now set the IPN callback address from the paypal_setup method and 
  you don't have to do that in the paypal admin interface!
* Removed the actual form tag from the paypal_setup generated code to conform better with docs