More at Features | Support | Blog | Demo | Community | Download

Payment Gateways

This guide covers how to manage and configure payment gateways within Spree, using ActiveMerchant or another gateway solution of your choice. After reading it, you should be familiar with:

1 Overview

Payment gateways are web-based services which support secure processing of payment information. Some gateways are already set up in Spree for immediate use and just need to be configured via the administrator interface. A large collection of other gateways can be added easily via Active Merchant.

For information on implementing payment methods that don’t communicate with a payment gateway, see the payments guide.

2 Basic Gateway Functionality

From a developer’s viewpoint, a gateway supports five core operations or transactions:

  • purchase - immediate transfer from customer to vendor
  • credit - immediate transfer from vendor to customer
  • void - cancellation of transfer
  • authorize and capture - immediate approval of transfer, with actual transfer (capture) of funds occurring at a later date

Note that authorize and capture are the main operations used in Spree at present.

3 Configuring an Existing Gateway

Spree comes with several gateways ready for use. You can select and configure the default gateway via the Payment Methods section of the Configuration menu. You are able to configure several different gateways at once. The typical use case for this is when you would like to use your gateway with different settings in development vs. production mode.

Each gateway comes with the following configuration options:

Configuration Option Description
Name Human readable name of your choosing. Helps you to identify the gateway in the index view.
Description Additional descriptive information about the configuration.
Environment The Rails environment for which this gateway will be used. This is the same as specifying the RAILS_ENV for this configuration (ie. development, test or production.)
Server Which server the gateway should be connecting to (this is a reference to the gateway server, not the Spree server.) Choices are: live and test.
Test Mode Transactions should be processed in test mode (if such a mode is supported by your gateway.)
Active Whether or not the current gateway configuration is active.

Spree gives you the flexibility to specify the exact combination of gateways and settings that you would like. You can have your development environment point to a bogus gateway or perhaps the test gateway environment for that particular gateway provider. Most gateway providers also allow you do to test transactions against the live production server. You can change the server option to live in order to achieve this set up.

You do not need to configure the URL for your gateway. The URL for your gateway provider is already known and the appropriate URL will be used based on the server setting in your configuration.

Most gateway providers require additional information to be provided during configuration. The information typically includes an account identifier and API key. Once you have chosen the gateway and the basic configuration values (environment, etc.) then you will also need to provide these gateway specific values.

After you change the gateway (or assign one for the first time) you will need to save the configuration and click the link to edit it. Only after a successful save will you see the configuration settings specific to the new gateway.

Gateway configurations can also be temporarily deactivated. This would allow you to configure a production gateway with all of the live settings and then disable it until you’re ready to launch. Only one gateway can be active per environment.

4 Available Gateways

4.1 Bogus Gateway

This gateway is provided for basic testing purposes, particularly in development mode. It returns a successful responses for the main five transactions if one of a test set of card numbers is used, else failure responses. See below for how to use it in testing. Unsurprisingly, this gateway requires no configuration options.

4.2 Other Gateways

Spree currently supports the following gateways:

  • Beanstream
  • Linkpoint
  • Paypal - Website Payments Pro
  • Protx (without 3D secure)

Additional gateway support is fairly trivial. Most of the functionality is provided by the Active Merchant plugin so if your favorite gateway is supported by this plugin, it will not be difficult to get it working with Spree.

5 Adding a New Gateway

Spree relies on the Active Merchant plugin to provide the majority of its gateway functionality. Spree introduces a thin wrapper, around the Active Merchant gateway implementation to assist with configuration and a few other conveniences.

Active Merchant currently supports around 40 payment gateways. Most of them have not yet been officially implemented in Spree but this is just because the core team generally uses only a few of the popular choices and there’s not yet been a need to support more. It should be trivial to support an existing Active Merchant gateway if your gateway is not yet included. The following sections will discuss in detail how to implement a gateway.

If you implement a new gateway, we’re interested in including it in the core. You should read the contribution guidelines for more details on how to contribute code to Spree.

5.1 The Gateway Model

All gateway implementations inherit from the common Gateway class which in turn extends ActiveRecord::Base. The primary motivation for this is to take advantage of Spree’s standard system for configuration of preferences.

The Gateway model provides the following public methods shared by all gateway implementations.

Method Description
provider Returns a fully configured instance of the gateway.
provider_class The Active Merchant gateway class to be used.
authorize Authorize a new charge.
capture Capture a previously authorized charge.
purchase Perform a simultaneous authorization and capture of a new charge.
void Void a previously authorized charge. (Not yet fully supported)
credit Issue a credit. (Not yet fully supported)

All new gateway implementations should extend Gateway. By convention, they should also be part of the Gateway namespace. For example, the implementation is defined as Gateway::AuthorizeNet.

5.2 Implementing provider_class

All gateway instances must implement the provider_class method. This is because the Spree wrapper used for gateway implementation is intended for providing a means to configure the gateway. Most of the actual work is delegated to the an instance of provider_class.

The provider method of Gateway is meant to be used internally. It will return a new instance of provider_class after configuring it with the specified settings.

5.3 Specifying Configuration Options

Gateway implementations will most likely need to specify configuration options. Spree provides a standard method for the configuration of preferences.

It is important that you use the exact spelling of the Active Merchant gateway option value that you are trying to configure.

If you examine the source code for the Active Merchant gateway that you are trying to configure, you will likely notice some specific options documented in the Active Merchant source code. It is these options that you need to expose to the Spree system for configuration in the admin screen.

Lets take the implementation as an example. The Active Merchant implementation reveals that there are two important configuration options: login and password.

You can ignore the test option. This is a standard preference for all gateways that is already provided for you by the base Gateway class.

In this case, you would expose these options as preferences in your gateway/authorize_net.rb file:

preference :login, :string preference :password, :string

As we have already said, implementation of an existing Acitve Merchant gateway is trivial. In the case of, it is only seven lines of code:

class Gateway::AuthorizeNet < Gateway preference :login, :string preference :password, :string def provider_class ActiveMerchant::Billing::AuthorizeNetGateway end end

5.4 Other Architecture Implications

This approach to implementing and configuring gateways is extremely flexible. It makes it trivial to implement a new gateway that is already supported by Active Merchant. There are other useful benefits to this approach that a developer may be interested in knowing.

5.4.1 Support of Non Active Merchant Gateways

This architecture allows Spree to support gateways that are not officially supported by Active Merchant. Many times a new gateway is donated by someone in the community but its languishing in the queue waiting for someone to test and accept the patch. You have the option of taking that code (or writing your own from scratch) and implementing it within Spree. Instead of delegating to an Active Merchant class, you can simply implement that functionality yourself. You could also include the new gateway code from an Active Merchant fork inside your implementation and delegate the standard authorize, capture, etc operations to it.

5.4.2 Ability to “Patch” Active Merchant Gateways

We’ve noticed that sometimes it takes a while for a crucial Active Merchant patch to be applied. That’s certainly understandable, the Shopify guys have a business to run and its probably not a high priority for them to make sure that the latest obscure gateway patch is applied in a timely fashion. Fortunately, the Spree approach to wrapping these gateways provides you with a convenient option.

Lets say there is a bug with the authorize method. You could simply provide an implementation of the gateway that has the patched version of the authorize method and then delegates to the Active Merchant class for everything else (since that works just fine.)

5.4.3 Gateways supporting payment profiles

Spree currently supports the CIM gateway or Customer Information Manager through ActiveMerchant. CIM allows card details to be stored securely on’s servers along with other customer details. See for details.

Although CIM makes it possible for customers to not have to re-enter their card details on subsequent visits, this isn’t supported in Spree yet. Spree does support taking additional payments from the card the customer used in the admin interface in the event there is an outstanding balance on the order.

The ActiveMerchant class AuthorizeNetCimGateway doesn’t support the usual authorise, purchase and capture methods since with this gateway it is a 2 step process. Instead these methods are implemented in the corresponding Spree gateway class. First a customer profile is created and the id strings provided by the gateway are stored on the creditcard in the columns gateway_customer_profile_id and gateway_payment_profile_id. Then a transaction can be made using those ids rather than the the creditcard details.

Gateways supporting payment profiles must override the following method:

def payment_profiles_supported? true end

Note that capture is called differently for gateways supporting payment profiles since you will need access to the creditcard:

def capture(authorization, creditcard, gateway_options) ... end
5.4.4 Additional Functionality Beyond Active Merchant

Another benefit of the architecture is that it makes it possible for Spree to provide additional common functionality that was not envisioned by Active Merchant. Specifically, it is possible to provide an abstraction for storing credit card profiles to be used with recurring payments. There’s a good reason for Active Merchant to not care about this functionality. Its designed for people who just want to drop a single gateway provider into their application. Most programmers don’t need three different gateways at once. Spree is a specialized use case. Its providing multiple gateways for you to choose from and so its desirable to have a standard method for operations such as this.

Recurring payments are not yet supported in Spree although there are plans to provide this in the near future.

6 Testing Considerations

There’s a range of testing options, from testing with the bogus gateway in development mode, to using a real gateway in test mode.

6.1 Using the Bogus Gateway

This gateway returns success for the five core operations on the following cards, otherwise a failure response is returned. It does not check CVV codes at present.

  • TEST_VISA = 4111111111111111
  • TEST_MC = 5500000000000004
  • TEST_AMEX = 340000000000009
  • TEST_DISC = 6011000000000004

7 Other Useful Information

Whilst debugging, you may find the following options useful - but they must be turned off in production use to comply with relevant card processing requirements, e.g. PCI.

  • Spree::Config[:store_cc]
  • Spree::Config[:store_cvv]