PayPal on Rails

After many searches in Google I found many explanations on how to use PayPal, however any of them did what I exactly needed. So here’s what I did step by step last time I needed it.

How PayPal works

Take a look at this flow diagram:

The buyer goes to PayPal and performs the needed payment. (This is steps 1 and 2 in the diagram)
PayPal takes the payment and redirects your buyer back to your application. (steps 3 and 4)
Some time after that, PayPal will send you a callback response with the details of the received payment. Your application will use those details to make sure the payment was OK and mark the order as paid. (Steps 5 and 6)

Set up your PayPal sandbox

Sign up here To get a sandbox account. This account will allow you to handle your development tools:
Seller and buyer mock accounts: That way you can test your payments without need to use a real account/bank account/credit card.
IPN (Instant Payment Notification) testing: This is the way that PayPal informs your application when the payment is done.
Create a seller and buyer mock accounts. Preconfigured seller accounts failed for me, they always failed for me 100% of times in a period of many months. I’m quite sure it’s my fault, but I just couldn’t find enough info to know what I did wrong.

Set up your application

Install ActiveMerchant.

Here it came my second big problem. Just couldn’t figure out how to make it work in the form of a gem. So I finally had to install it as a plugin. rails plugin install git://github.com/Shopify/active_merchant.git

From the above diagram you application will need to:

Be able to send payment details to PayPal.
Receive a callback from PayPal to acknowledge the received payment.

And here’s where ActiveMerchant enters. It provides a helper to craft a form with the needed hidden fields which you will send to PayPal and a class with the needed logic to receive and validate the callback from PayPal.

Configure Active Merchant

Set up an initializer file like config/initializers/active_merchant.rb with the following content (it explains itself… isn’t it?):

# config/initializer/active_merchant.rb if Rails.env.production? PAYPAL_ACCOUNT = 'production.paypal.account@domain.com' else PAYPAL_ACCOUNT = 'test.paypal.account@domain.com' ActiveMerchant::Billing::Base.mode = :test end

Set up the PayPal button

Use something like that to generate the button that your user has to push so that he makes the payment.

<% payment_service_for @order.id, PAYPAL_ACCOUNT, :amount => @order.price, :currency => 'EUR', :service => :paypal do |service| service.customer :first_name => current_user.name, :last_name => current_user.surname, :email => current_user.email service.item_name @order.items_summary # PayPal will POST a callback here when the payment is done service.notify_url notifications_url(@order) # PayPal will take your user here with a POST after he pays service.return_url paypal_return_notifications_url(@order) # PayPal will redirect your user here if he cancels the payment service.cancel_return_url paypal_cancel_notifications_url(@order) %> <%= submit_tag 'Pay this order' %> <% end %>

If you need to send more info to PayPal take a look at the ActiveMerchant’s doc or even at its code, to see which options are accepted by the payment_service_for helper. Just FYI, the helper doesn’t support multiple items. In case you need it you’ll need to craft your own helper… and maybe send a pull request to ActiveMerchant ^^.

Gather and acknowledge the PayPal response

PayPal will send you a notification so you can know when the order is paid. This following code is a sample of how this can be done.

# app/controllers/notifications_controller.rb class NotificationsController < ApplicationController include ActiveMerchant::Billing::Integrations protect_from_forgery :except => [:create, :paypal_return] # This action is for when the buyer returns to your site from PayPal def paypal_return flash[:notice] = "Thanks for buying this!" redirect_to root_path end # This action is for when the buyer cancels def paypal_cancel flash[:notice] = "We're sorry you didn't buy :(" redirect_to root_path end # This is what will receive the IPN from PayPal def create # You maybe want to log this notification notify = Paypal::Notification.new request.raw_post @order = Order.unpaid.find(notify.item_id) if notify.acknowledge # Make sure you received the expected payment! if notify.complete? and @order.price == BigDecimal.new( params[:mc_gross] ) # All your bussiness logic goes here @order.update_attributes(:paid => true) render :nothing => true end rescue #Make sure you log the exceptions you have. end end end

That’s all folks!

This is the most simple way I found to make PayPal work with ActiveMerchant. However it’s very limited and lacks support for things like multiple items and data encryption between your app and PayPal. Unluckly ActiveMerchant lacks support for these two things on its PayPal integration. However you can achieve this by using something like that.

If you find some stupid thing or some bug here, just let me know so that I can fix it :)