Permalink
Browse files

Add a GettingStarted file

  • Loading branch information...
1 parent ca3b38d commit 89714d74260678c8ed4b0b0823fbd6e08d498bad @dasch dasch committed Jul 24, 2011
Showing with 64 additions and 0 deletions.
  1. +1 −0 .yardopts
  2. +63 −0 GettingStarted.md
View
@@ -0,0 +1 @@
+- GettingStarted.md
View
@@ -0,0 +1,63 @@
+# 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.

0 comments on commit 89714d7

Please sign in to comment.