This guide covers how to manage and configure payment gateways within Spree. After reading it, you should be familiar with:
- The Spree Commerce supported default gateways
- 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
Spree comes with two default payment gateways for stores both inside the United States
and Internationally. We have partnered with USA ePay and Skrill (Moneybookers) to provide
low transaction rates for all Spree stores. These solutions are supported by Spree Commerce
and 100% compatible with Spree.
Additionally, many of the popular payment gateways and provided by the Spree Gateway Gem. These are community supported.
The default and 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.
When you install Spree from the command line, you are prompted to install the default gateways. This will add the USA Epay and Skrill (Moneybookers) gems to your Gemfile.$ rails new my_store $ spree install my_store Would you like to install the default gateways? (yes/no) [yes]
If you are using one of the payment gateways available in the Spree Gateway Gem. You can add it to your Gemfile and install it with bundler.
- add to your Gemfile after the Spree gem
$ bundle install
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.
Basic Gateway Functionality
From a developer’s viewpoint, a gateway supports five core operations or
- – immediate transfer from customer to vendor
- – immediate transfer from vendor to customer
- – cancellation of transfer
- and – immediate approval of transfer, with actual transfer (capture) of funds occurring at a later date
Note that and are the main operations used in Spree at
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.
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. , or .)|
|Server||Which server the gateway should be connecting to (this is a reference to the gateway server, not the Spree server.) Choices are: and .|
|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 option to in order to achieve this set up.
INFO: 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.
INFO: 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.
Configuring Default Gateways
USA ePay Configuration
Add a payment gateway and select Spree::Gateway::UsaEpay as the provider.
You will need a Source Key and Pin from USA ePay. You can create these in your Mechant Console under the settings menu. Spree requires all Source Keys to have the optional pin.
You can find test credit card numbers in the developer documentation.
If you are using the USA ePay Sandbox then check the “Test Mode” checkbox.
Add a payment gateway and select Spree::BillingIntegration::Skrill::QuickCheckout as the provider.
Skrill will provide you with a Merchant Id. The defaults will let users enter a credit card or login in with their Skrill account.
Some typical Payment Options:
- ACC – All Credit Cards
- OBT,GIR,DID,SFT,ENT,EBT,SO2,IDL,NPY,PLI,PWY,EPY,MZM – local payment options
- WLT – Skrill Wallet
You can find additional options for Language, Currency and Payments in the Skrill documentation.
Skrill Test Credit Card Numbers
- 4000001234567890 (No BIN country)
- 4255251234567890 (Bulgaria)
- 4779271234567890 (Germany)
- 4042811234567890 (Malta)
- 4483951234567890 (Sweden)
- 4544356892455550 (United Kingdom)
- 4016671298391830 (USA)
- 5463332183823220 (Belgium)
- 5474381234567890 (Bulgaria)
- 5232000000123456, 5584011231231330 (Germany)
- 5422011234567890 (Malta)
- 5438311234567890 (Sweden)
- 5485081234567890 (United Kingdom)
- AMEX: 371234500012340, 377616655655440
- DISCOVER: 6011123456789000
- DINERS: 36123456789000
- LASER: 5612345678900001
- MAESTRO: 51234567912345670
- SOLO: 631234567891234560, 6767676767676767671
- JCB: 3555123456789120
- CARTEBLEUE: 5817840047112340
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.
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.
INFO: 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.
The Gateway Model
All gateway implementations inherit from the common class which in turn extends . The primary motivation for this is to take advantage of Spree’s standard system for configuration of preferences.
The model provides the following public methods shared by all gateway implementations.
|Returns a fully configured instance of the gateway.|
|The Active Merchant gateway class to be used.|
|Authorize a new charge.|
|Capture a previously authorized charge.|
|Perform a simultaneous authorization and capture of a new charge.|
|Void a previously authorized charge. (Not yet fully supported)|
|Issue a credit. (Not yet fully supported)|
All new gateway implementations should extend By convention, they should also be part of the namespace. For example, the Authorize.net implementation is defined as .
All gateway instances must implement the 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 .
The method of is meant to be used internally. It will return a new instance of after configuring it with the specified settings.
Specifying Configuration Options
Gateway implementations will most likely need to specify configuration options. Spree provides a standard method for the configuration of preferences.
INFO: 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 Authorize.net implementation as an example. The Active Merchant implementation reveals that there are two important configuration options: and .
NOTE: 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 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
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.
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.
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 method. You could simply provide an implementation of the gateway that has the patched version of the method and then delegates to the Active Merchant class for everything else (since that works just fine.)
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/
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
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.
INFO: Recurring payments are not yet supported in Spree although there are plans to provide this in the near future.
There’s a range of testing options, from testing with the bogus gateway
in development mode, to using a real gateway in test mode.
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.
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.