How To Integrate Spree With PayPal

In today's e-commerce world payment gateways are invaluable tools to help customers choose your offer and establish trust. Here's a guide for Spree and PayPal gateway. Enjoy!

I assume you already have:

• Rails app, version: 4.2.2
• Spree shop, version: 3-0 stable (gem: spree)
• Spree auth devise plugin, version: 3-0 stable (gem: spree_auth_devise)
• Paypal account

What you will use:

We will use better_spree_paypal_express gem. Now, let’s stop for a while. Why not use default gateways in which PayPal gateway is included? (Spree default payment gateways has been moved to external gem called spree_gateway). There are few reasons to do that. First of all, default PayPal gateway allows users to pay only with credit card. Let’s take a look at an example:

And that is all.

There is no possibility to pay using your paypal account balance. Secondly, there are some problems with regions - e.g. I have been informed that the payment is not available for my region (Poland) but anyway the payment has been successfully completed. I noticed some strange payment entries in admin panel, too:

No, I did not try 3 different payment attempts. These are the entries after only one successful checkout process.

Finally, the main reason: Spree official guides recommends to use better_spree_paypal_express gem. So decision has been made.

Step 1

Add better_spree_paypal_express gem to your Gemfile:

gem 'spree_paypal_express', github: 'spree-contrib/better_spree_paypal_express', branch: '3-0-stable'

and run following commands:

Second command will create appropriate migrations and run them. Restart your server after that.

Step 2

Enter your PayPal account and create sandbox (test) accounts in PayPal developer dashboard. Only merchant account is necessary but I also recommend creating personal (buyer) account for testing purposes.

Step 3

Let’s step further to configure PayPal gateway in Spree. Go to admin panel / configurations / payment methods and click ‘Add Payment Method’. You will see following form:

Just select Spree::Gateway::PayPalExpress in PROVIDER and enter NAME - this will be displayed on checkout page.Other options are described in Spree guides but let’s stop on one of these - AUTO-CAPTURE. Here you should be able to decide whether payment will be auto captured. Anyway, this option doesn’t work for me (regardless of the choice, payments will be always auto captured). Click “Create” button and you will have to provide additional but obligatory data:

Let’s start withcredentials (login, password, signature). Where can you find them? Get back to your PayPal test accounts (in PayPal developer dashboard). Click on your business account and then on Profile link. You will see window similar to the one below:

In the API Credentials tab you will find what you need. Just copy appropriate values to gateway configuration form. Now let’s focus on other available options:

• SERVER
  • ‘sandbox’ for development / testing,
  • ‘live’ for production
• TEST MODE: unchecked for production

That’s all! You have just integrated Spree shop with Paypal. Good job! :) In next steps I will show you what can you expect from such new functionality and what does not work at all.

Step 4

Firstly, checkout process. Let's go straight to the payment step:

After clicking the “PayPal Check out” button you will be redirected to site which is well-know for anyone who was paying with PayPal at least once.

You can use your personal (buyer) test account to finish the order. I strongly recommend this, as it is required to do next step from this tutorial.

Step 5

Let’s assume that you have finished the order. Now, head to admin panel / orders.

As you can see the payment status is set to PAID so payment has been captured. Click on edit button or order number and you will be moved to page with order details (shipments tab). Select the payments tab

from right sidebar menu.

Click on payment number to see page with single payment details:

You can issue a refund by clicking "REFUND" button here. You will be able to type any amount of refund. Notice: You can make refund only once! So if you made a partial refund, you will not be able to make another one.
At every stage of the payment process we can follow notifications. Just go to Paypal developer dashboard and select "Notifications" from left menu. Small example below:

We have finished simple refund process. But what if we want to issue a refund which is part of entire process of returning the item (make return authorization, record the returned item and then make refund)? Let’s see.
To begin process of return, order must satisfy two conditions: it is paid and it is shipped. Then we can create return authorization, stating which item can be returned, reason of return and value of refund for each item (order details / return authorizations tab). After this you can mark item as returned by creating new "customer return" (in customer returns tab). After this series of actions, we will be able to see page with customer return details:

Click on “Create reimbursement” button and following page will be shown:

You can update reimbursement details and simply make reimburse here.So let’s click on “Reimburse” button. What a pretty 500. This issue has been reported by many Spree users but it still has not been fixed. You will not be able to make refund in this way for now. You can still go back to Payments tab and make “manual” refund.

Summary

As you can see, making Spree and Paypal work together is not so difficult. With better_spree_paypal_express gem payments work almost out of the box. There are still little problems with making refunds (in customer return process, "manual" refund works well). Looking at the last date of gem update may have doubts whether to use it but as I mentioned at the beginning - the gem is recommended by official Spree guides.