How to Integrate Spree with PayPal

Marcin Jakubowski

May 20, 2016 • 9 min read

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


I assume you already have:

  • Rails app, version: 4.2.2;
  • Spree shop, version: 3-0 stable (gem: spree);
  • Spree auth devise plug-in, 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 a few reasons to do that. First of all, default PayPal gateway allows users to pay only with a credit card. Let’s take a look at the following example:

And that's 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 the payment has been successfully completed anyway. Besides, I have noticed some strange payment entries in the admin panel:

No, I have not made 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, the 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 the following commands:

bundle install
bundle exec rails g spree_paypal_express:install

The second command will create and run appropriate migrations. Restart your server after that.

Step 2

Enter your PayPal account and create sandbox (test) accounts in PayPal developer dashboard. Only a merchant account is necessary, but I also recommend creating a 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 the following form:

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

Let’s start with the credentials (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 the Profile link. You will see a window similar to the one below:

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

    • ‘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! :) Next, I will show you what you can expect from such a new functionality and what doesn't work at all.

Step 4

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

After clicking the “PayPal Check out” button, you will be redirected to a site which is well-known for anyone who has paid with PayPal.

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

Step 5

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

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

from the right sidebar menu.

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

You can issue a refund by clicking the "REFUND" button here. You will be able to type any amount. 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 the left menu. A small example below:

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

Click “Create reimbursement” and you'll see the following page:

You can update reimbursement details and simply make reimbursement here. So, let’s click on the “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 a refund this way for now. You can still go back to the Payments tab and make a “manual” refund.


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 some problems with making refunds (in customer return process, the "manual" refund works well). Looking at the last date of gem update, one may have doubts whether to use it, but - as I mentioned at the beginning - the gem is recommended by official Spree guides.

More posts by this author

Marcin Jakubowski

Codestories Newsletter