How to Integrate PayPal Express into Spree Commerce

In this article we’re going to show you how to integrate the PayPal Express Checkout payment gateway into an ecommerce project, using the example of Medshop Express. Medshop is an online store built on the Spree content management system (CMS).

The Spree CMS has many pre-installed plugins for payment gateways. However, Spree’s standard PayPal gateway is restricted to credit card payments only. That is, the option for direct payments from a user's PayPal account is unavailable in the default PayPal gateway. We had to add the PayPal Express Checkout extension to our project to facilitate all types of payments via PayPal on Medshop.

Before you integrate PayPal Express into Spree, you first need a PayPal Sandbox account. To create your own PayPal Sandbox account, follow this tutorial – Creating Sandbox Test Accounts. You'll need to use this account for testing purposes. Don’t forget to create several test profiles, including a buyer account. For our project, we used version 4.2.7 of the Ruby on Rails framework. We also run our project on one of the latest versions of Spree: 3-0-stable.

PayPal Express Checkout uses the Merchant Ruby Software Development Kit, which we expected be deprecated soon. But the message about its deprecation was removed recently from GitHub. This is great news, as you can now feel free to install PayPal Express in Rails!

Now let's move on to the PayPal Express Checkout integration with Spree!

Step 1. Install the Spree PayPal Express Gem

Since Spree’s developers recommend that we use the better_spree_paypal_express library for our PayPal gateway, we should go ahead and install it. Open the Gemfile for your project and enter the following line of code:

Note that the branch is 3-0-stable in our project. But if you have Spree 2.4.10 or 3.1.0, then type the appropriate version number for your setup.

There are also two commands that you have to run in order to install the better_spree_paypal_express gem.

This command will download and install all better_spree_paypal_express files necessary for our Spree project.

The next command will run necessary migrations:

Once this step is also completed, just restart the server.

The first step in integrating PayPal Express Checkout into Spree is completed!

Step 2. Set up PayPal Express in the Spree Admin Panel

Now you need to log in to the Spree admin panel. If your Spree admin panel shows the navigation panel in full, find the CONFIGURATIONS button. Click on it to open the menu and select Payment Methods. If this panel is collapsed, hover over the wrench icon and select Payment Methods from the pop-up window.

You are now on the Payment Methods tab, so click on the button + New Payment Method, which is located in the top-right corner of the admin panel.

First, choose an appropriate provider from the list. Note that Spree has a standard Spree::Gateway::PayPalGateway provider, but this isn't the one we need to add. Choose the Spree::Gateway::PayPalExpress provider instead.

Now, you need to edit the payment method for PayPal. First, log in to your Developer PayPal account and go to Account Details. There, open the API Credentials tab and just copy-paste your Username, Password, and Signature details from PayPal into the first three fields under the PROVIDER field in the Spree admin panel. Note that the PayPal API credentials for Username should be entered in the LOGIN field in the Spree admin panel.

Add a payment method name, which will be shown to your customers. As you can see, we simply entered PayPal. You can enter any name you want. It's recommended, however, to keep it short. The payment method description is optional.

Since we use our sandbox account for testing purposes, the SERVER field should be set to Sandbox. But when you're ready to test PayPal Express Checkout for production, change this field to LIVE.

If you have a logo for PayPal Express, enter the absolute URL into the field LOGOURL. You can also change the name for the payment method and add or delete the description.

There are other options to edit in this page.

Check the Test Mode box if you are only testing the application. When you are working with the production version of Spree, then disable this mode. The DISPLAY property lets you decide whether the PayPal Express Checkout payment method is available for the user.

There is also an AUTO CAPTURE feature. By setting the AUTO CAPTURE feature to Yes or No, you can turn on or off automatic capturing for the current payment methods. In our project, we set AUTO CAPTURE to Yes for PayPal Express, which allows automatic withdrawal of funds from the client's credit card. The other two options are No and Default; if you choose No, then you will have to capture each payment manually in the Spree admin panel. When you need to override this function for PayPal Express, open the file with the subclasses for the payment methods and set the auto_capture? function to false:

At last, you can activate and deactivate the PayPal Express payment method in the "Editing Payment Method / PayPal" tab.

This is how we integrated the PayPal Express Checkout gateway into Spree. As you can see, the procedure is very simple, but you get valuable functionality in the end. Your website customers will definitely be pleased with the option to pay directly from their PayPal accounts.