README

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 dist.leetsoft.com
• Alternatively you can get the library packaged at 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 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 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