Ecommerce Rails Plugin

This plugin is used by Helicoid’s apps for taking payments through the UK-based Secure Trading payment processor.

Features

• The plugin maps between cards and Rails forms so they behave like ActiveRecord objects, making error messages easy
• There’s some UK-specific VAT-handling code, which helps you determine if your transaction should include VAT
• I’ve used it to do both continuous auth and subscription payments (subscriptions run on Secure Trading’s servers)

Requirements

I haven’t added an install script. The plugin needs one table called ‘orders’:

create_table :orders do |t| t.column :invoice_line, :string t.column :account_id, :integer t.column :created_at, :datetime end

This stores a unique ID for each transaction. The account_id is used internally by my software, so you don’t really need it. The invoice line is sent to Secure Trading in the OrderInformation string.

Integration Examples

Note: my apps have PricePlan and Payment classes, the plugin doesn’t dictate the structure of these.

There’s an example view for cards in the examples directory.

If you want the images I use, I open sourced them as well: open source card images.

# Billing info
card = Ecommerce::Cards.new params[:card]
billing = Ecommerce::Merchants::SecureTrading::CustomerInfo.new params[:billing]

# Checking if VAT details are valid
Ecommerce::Tax.valid_vat_number? @account.location, @account.vat_number

# Authorisation for a subscription
order = Ecommerce::Merchants::SecureTrading::Order.create :invoice_line => 'Tiktrac: ' + price_plan.name, :account_id => proxy_owner.id
response = Ecommerce::Merchants::SecureTrading::Subscription.authorise billing, card, order, amount_to_pay, next_payment_date

Create a new transaction:

Ecommerce::Merchants::SecureTrading.create(customer_info, card, order, amount, settlement_day = 1)

Schedule a repeat payment that uses continuous auth:

Ecommerce::Merchants::SecureTrading.repeat(customer_xml, order_object, amount)

Reverse authorisation (allow the customer to cancel an order before payment is authorised):

Ecommerce::Merchants::SecureTrading.auth_reversal(customer_xml, order, amount)

Check the status of settlement:

Ecommerce::Merchants::SecureTrading.settlement_query

Returns: Error, Declined, Pending, Settled

The subscription API is similar to the previous examples. See merchants/securetrading/subscription.rb

Exceptions

You must catch these in your payment handling code and deal with them appropriately:

Errors 1000, 1100, 2100, 3100: Ecommerce::MerchantConfigurationError

Errors 2500: Ecommerce::MerchantInvalidRequest

Errors 100, 101, 3000, 3010, 3330, 3350, 5000: Ecommerce::MerchantConnectionError => merchant_exception

Continuous auth vs. Subscription

Continuous auth is where Secure Trading allow you to store a reference to a transaction and bill again later on.

If you use their server’s subscriptions, pausing and restarting a subscription will cause it to charge for the missed months. I actually use this system but force customers to enter their card details again and therefore start a new subscription to avoid it billing for missed months.

Tests

The tests are application specific and some of the code is legacy (things I experimented with when I started using this API). I’ve stripped a lot of it out, and it should really be replaced for this open source plugin.

Future

This plugin was built before there were any popular Rails payment processing plugins, so I’d like to extract the Secure Trading-specific code and import it into Active Merchant in the future.

I designed the code to be namespaced so different ecommerce systems could be plugged in, but this probably isn’t necessary.

1. Get the tests sorted out so they run outside Rails
2. Consider streamlining the code so there’s less namespacing seeing as this will never be a generic ecommerce plugin
3. Contribute to ActiveMerchant or similar