This guide covers how to manage and configure payment gateways within Spree. After reading it, you should be familiar with:
- The community supported gateways available in the Spree Gateway gem
- The functionality provided by payment gateways
- How to configure an existing gateway
- How to create a new gateway
- Testing your payment gateway
Payment gateways are web-based services which support secure processing of payment information.
The Spree community maintains support for a wide variety of payment providers both in the USA and internationally. Many of the popular payment gateways are provided by the Spree Gateway Gem.
The community payment gateways are easy to set up in Spree and ready for immediate use. They just need to be configured via the administrator interface.
If your gateway is not available, you can easily add it with Active Merchant. We encourage you to contribute new gateways to the Spree Gateway Gem.
For information on implementing payment methods that don’t communicate with a payment gateway, see the payments guide.
2.1 Default Gateways
When you install Spree from the command line, you are prompted to install gateways. This will add the Spree Gateway gem to your Gemfile.
$ rails new my_store $ spree install my_store Would you like to install the default gateways? (recommended) (yes/no) [yes]
$ bundle install
2.2 Bogus Gateway
Spree comes with a Bogus Gateway 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.
3 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.
4 Configuring an Installed Gateway
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:
|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 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.1 Other Gateways
The Spree community currently supports the following gateways:
- 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.
|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 Authorize.net 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.
Let’s take the Authorize.net implementation as an example. The Active Merchant implementation reveals that there are two important configuration options: login and password.
You can ignore the option. This is a standard preference for all gateways that is already provided for you by the base 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 Authorize.net, 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 ActiveMerchant 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 it’s 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” ActiveMerchant 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 team has a business to run and it’s 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.
Let’s 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 Authorize.net CIM gateway or Customer Information Manager through ActiveMerchant. CIM allows card details to be stored securely on Authorize.net’s servers along with other customer details. See www.authorize.net/solutions/merchantsolutions/merchantservices/cim/ 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. It’s 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. It’s providing multiple gateways for you to choose from and so it’s 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.