From 89714d74260678c8ed4b0b0823fbd6e08d498bad Mon Sep 17 00:00:00 2001
From: Daniel Schierbeck <daniel.schierbeck@gmail.com>
Date: Sun, 24 Jul 2011 21:53:05 +0200
Subject: [PATCH] Add a GettingStarted file

---
 .yardopts         |  1 +
 GettingStarted.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)
 create mode 100644 .yardopts
 create mode 100644 GettingStarted.md

diff --git a/.yardopts b/.yardopts
new file mode 100644
index 00000000000..8c3523426a1
--- /dev/null
+++ b/.yardopts
@@ -0,0 +1 @@
+- GettingStarted.md
diff --git a/GettingStarted.md b/GettingStarted.md
new file mode 100644
index 00000000000..5ac90a839fc
--- /dev/null
+++ b/GettingStarted.md
@@ -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.