GettingStarted.md

Getting Started with Active Merchant

Before getting started using Active Merchant, a bit of terminology is needed.

In order to process credit card payments, your application needs to interface with a payment gateway. In Active Merchant, these are represented as subclasses of {ActiveMerchant::Billing::Gateway}.

Gateway Operations

A typical interaction consists of the application obtaining the necessary credit card credentials (card number, expiry date, etc.) and asking the gateway to authorize the required amount on the card holder's credit card.

If the authorization is successful, the funds are available and you can ask the gateway to capture them to your account. If the capture is completed, the payment has been made.

When combined into a single operation, this is called a purchase.

All of these operations are performed on an instance of a Gateway subclass:

gateway = SomeGateway.new

# Amounts are always specified in cents, so this is
# equal to $10.
response = gateway.purchase(1000, credit_card)

Both #authorize, #capture and #purchase return a {ActiveMerchant::Billing::Response} instance. This object contains the details of the operation, most notably whether it was successful.

if response.success?
  puts "Payment complete!"
else
  puts "Payment failed: #{response.message}"
end

As can be seen, {ActiveMerchant::Billing::Response#success?} returns whether the operation completed successfully. If false, the error message is available in #message.

Handling Credit Cards

In Active Merchant, credit cards are represented by instances of {ActiveMerchant::Billing::CreditCard}. Instantiating such an object is simple:

credit_card = ActiveMerchant::Billing::CreditCard.new(
  :first_name => 'Steve',
  :last_name  => 'Smith',
  :month      => '9',
  :year       => '2014',
  :type       => 'visa',
  :number     => '4242424242424242')

Most often, though, you'll be using user-supplied data. In a typical Rails controller:

credit_card = ActiveMerchant::Billing::CreditCard.new(params[:credit_card])

Validation

While the above attributes are always required for a CreditCard to be valid, some gateways also require a verification value, e.g. a CVV code, to be given.

Validating a credit card is as simple as calling #valid?, which returns true only if the credentials are syntactically valid. If there are any errors or omissions, the #errors attribute will be non-empty.