== 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 https://dist.leetsoft.com
* Alternatively you can get the library packaged at https://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 https://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), "bob@bigbusiness.com", :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_form_tag %> 
== 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.prm 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")
== Troubleshooting
uninitalized constant Paypal - Make sure your ruby has openssl support
== Changelog
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