We recently added a few functionality to the Ogone gateway of the popular active_merchant payment processing gem, and felt it was a good time to take it from the top and detail how you can use this service in your own Rails application.

Warning: Handling and storing bank information is a dangerous task, and may be regulated in your country. Make sure your application conforms to the required norms and standards ( PSI DSS might be a good place to start) before implementing payment yourself.

Installation

As usual, you will need to add active_merchant to your Gemfile:

Gemfile

gem 'activemerchant'

Then you need to create a new Ogone gateway with your account settings. Depending on how often and where you accept payments, you may want to put this in a initializer:

active_merchant.rb

OGONE_GATEWAY = ActiveMerchant::Billing::OgoneGateway.new(
:login => "login of your Ogone account (PDPID)",
:user => "username of API user (Userid)",
:password => "password for API user",
:signature => "SHA-IN Pass phrase",
:signature_encryptor => "sha512",
:test => true # Change to false when using your production account
)

Usage

To make a simple payment, create a credit card and make a purchase with it:

credit_card = ActiveMerchant::Billing::CreditCard.new(
:first_name => 'John',
:last_name => 'Matrix',
:number => '4111 1111 1111 1111',
:month => 4,
:year => 2013,
:verification_value => 123 # CVC code
)

# Charge 10 EUR
response = OGONE_GATEWAY.purchase(1000, credit_card, :order_id => "1", :store => "john_matrix")

puts response.success? # Check whether the transaction was successful
puts response.message # Retrieve the message returned by Ogone
puts response.authorization # Retrieve the unique transaction ID returned by Ogone (you should save this somewhere)

order_id is optional, and will be automatically generated by Ogone if left blank. store is optional and used to remember a credit card that will be used regularly, but more on this in a while.

Refunds and authorization

Making a refund is as easy as charging a customer, simply call refund with the authorization you received after calling purchase:

# Refund 10 EUR
refund_response = OGONE_GATEWAY.refund(1000, response.authorization)

Transactions can also be done in two steps. First, we will authorize the amount on the credit card, which will make sure it is available, and freeze it on the credit card for 7 days. Within these 7 days, we can then capture the amount to make the actual transaction.

# Freeze 10 EUR on the credit card
response = OGONE_GATEWAY.authorize(1000, credit_card)

# Charge the frozen 10 EUR
capture_response = OGONE_GATEWAY.capture(1000, response.authorization)

# Or unfreeze them
void_response = OGONE_GATEWAY.void(response.authorization)

Storing credit cards

As I mentioned before, you can store credit cards you charge regularly using Ogone’s Alias feature. This can be done either at the first purchase with the store option, or using the new store method.

# Storing at first purchase
response = OGONE_GATEWAY.purchase(1000, credit_card, :store => "john_matrix")

# Storing without a purchase
response = OGONE_GATEWAY.store(credit_card, :store => "john_matrix")

# Storing with an Ogone-generated alias
response = OGONE_GATEWAY.store(credit_card)
puts response.alias # Retrieve the generated alias

# Future purchases can now be made using the alias:
new_response = OGONE_GATEWAY.purchase(2000, "john_matrix")

# The alias can be used any time in place of the credit card:
new_response = OGONE_GATEWAY.authorize(1500, "john_matrix")