More at spreecommerce.com: 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.

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 Gateways section of the Configuration menu. The first step is to choose the gateway from the drop-down menu. This then causes a gateway-specific form to be shown where you can enter details such as vendor identifier or account signature. These details will be used when Spree processes a customer payment, typically to allow connection to a gateway service. Clicking ‘Update’ sets the selected gateway as the default and saves the associated details.

3.1 The Bogus Gateway

This gateway is provided for basic testing purposes, particularly in development mode. It returns success 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.

3.2 Other gateways

Spree currently supports:

  • Authorize.net
  • Linkpoint
  • Paypal – Website Payments Pro
  • Protx (without 3D secure)

Gateways for the following are in preparation:

  • Paypal Express
  • Protx 3D secure / Sagepay

4 Adding a new gateway

Spree assumes that gateway classes follow the interface and conventions of Active Merchant. The first step is to provide a class which implements the five core operations, using information passed in the Active Merchant format.

Active Merchant currently supports around 40 payment gateways. One of these may meet your needs or can be adapted with a bit of work. You could also look on the Active Merchant or Spree mailing lists or on GitHub to see if people are developing other relevant gateways. Posting requests to the mailing lists sometimes helps, e.g. to find someone to share the work with.

4.1 The payment_gateway wrapper

It’s worth noting first how Spree interacts with underlying gateways. The Creditcard model contains methods from the Spree::PaymentGateway module which roughly follow the ActiveMerchant interface. The high-level operations select the current gateway and create a new instance of the associated class. Next, the gateway-specific options (such as vendor account name and password) are merged with the result of converting Spree data (eg address objects) into the format used in Active Merchant. The assembled data is then passed to the relevant method of the new gateway object. On return, relevant information is converted back into Spree objects (e.g. saving an authorised credit card transaction) or suitable exceptions raised.

4.2 The ActiveMerchant interface

Here is a summary of the key details. Consult ActiveMerchant’s documentation for further information.

The core functions expect the following arguments:

  • authorize(money, creditcard, options = {})
  • purchase(money, creditcard, options = {})
  • credit(money, ident, options = {})
  • capture(money, ident, options = {})
  • void(ident, options = {})

Note that ActiveMerchant expects amounts in cents or pennies and so Spree passes numbers already multiplied by 100, so if you are implementing a gateway from scratch you should be ready to handle such numbers.

Creditcards can be objects that respond to requests for number, cvv code, expiry date etc. See the documentation for more detail.

Spree expects back an object in the ActiveMerchant::Billing::Response class.

4.3 Providing other information

Other information can be provided in the options hash, and it is up to your gateway for what extra is required. Note that Spree’s gateway wrapper converts and inserts much of the relevant information into this hash.

4.4 Setting up a gateway

This is generally done with a migration. See directory vendor/extensions/payment_gateway/db/migrate for examples. The gateway-specific fields are stored in the GatewayOption table, with each option having a name (used as the key in the options hash) and an informative description:

login = GatewayOption.create(:name => 'login', :description => 'Your login email.') signature = GatewayOption.create(:name => 'signature', :textarea => true, :description => 'Your Paypal API Credentials signature string.')

Specifying :textarea => true means that a textarea rather than a textbox will be provided to configure that field.

The actual gateway is specified like this:

gateway = Gateway.create(:name => 'Paypal - Website Payments Pro", :clazz => 'ActiveMerchant::Billing::PaypalGateway", :description => 'Active Merchant's Paypal Website Payments Pro (US) Gateway.", :gateway_options => [login, password, signature])

The clazz field names the class implementing your gateway. The gateway_options field sets the specific fields required for the gateway. Remember that to activate the gateway, you need to select it as the default in the Configurations menu.

Contributions of new gateways are always welcome. For flexibility, try to create a stand-alone extension which others can import into their projects. Please advertise new code or developments on the Spree mailing list (or the Active Merchant list).

5 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.

5.1 Using the Bogus Gateway

Spree will use the bogus gateway if (a) you are in development mode and have not changed Spree::Gateway::Config[:use_bogus] to false; or (b) if you have not selected any other gateway yet.

This gateway returns success for the five core operations on the following cards, else returns failure. It does not check CVV codes at present.

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

5.2 Putting a gateway into test mode

Once you have selected a non-bogus gateway, you probably need to run it in test mode before attempting live transactions. ActiveMerchant gateways can be put into test mode with the following line. You can add it at the end of config/environments/production.rb (where it is commented out by default), or better to go in your application’s initializer.

ActiveMerchant::Billing::Base.gateway_mode = :test

6 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]