spreedly 1.4.0 → 2.0.0

data/.gitignore

@@ -0,0 +1,8 @@
+Gemfile.lock
+doc/
+pkg
+*.gem
+.bundle
+tmp
+vendor/ruby
+test/credentials/personal_credentials.yml

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+gemspec
+

data/HISTORY.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 2.0.0
+* This gem is now intended for the Spreedly API.  For the Spreedly
+  Subscriptions API, you can use the spreedly_subscriptions gem
+  which has everything that 1.4.0 had.
+
 ## 1.4.0
 
 * Add accessor for invoices

data/README.md

@@ -1,42 +1,375 @@
-# Spreedly gem
+# Spreedly Gem
 
-* https://github.com/spreedly/spreedly-gem
+A convenient Ruby wrapper for the Spreedly API.
 
-## Description
+## Philosophy
 
-The Spreedly gem provides a convenient Ruby wrapper for the Spreedly
-Subscriptions API.
+* No global configuration of authentication credentials.
+* No implicit calls to the Spreedly server.
+* Don't be too clever.  The real goal is for this to be a thin and simple layer over the API.  The correlation between an API call and a ruby method should be as clear as possible.
+* Avoid the approach of using a proxy that at some point gets filled in with data from the server.
+* Avoid self-mutation and prefer value objects.  This isn't ActiveRecord so we won't be doing things like gateway.update_attributes(attributes).
+* Don't try to improve the interface of the API by doing cool Ruby things in the gem which fix or hide icky parts of the API.  Instead, improve the underlying API to reflect the improvements and then adjust the gem to use the improved underlying API.
+* Limit the number of dependencies on other gems to make it as easy possible to incorporate the gem into any project.  Resist the temptation to use the goodness in gems like ActiveSupport or ActiveModel.
 
-## Features
 
-* Makes it easy to get started.
-* Fully tested.
-* (Mostly) fully substitutable mock implementation for fast tests.
-* Great example code.
+## Installation
 
-## Synopsis
+If you're using bundler, add the gem to your Gemfile:
 
-    # For real
-    require 'spreedly'
-    Spreedly.configure('site short name', 'crazy hash token')
-    url = Spreedly.subscribe_url('customer id', 'plan id')
-    subscriber = Spreedly::Subscriber.find('customer id')
-    subscriber.active?
+    gem 'spreedly'
 
-    # For fast tests
-    require 'spreedly/mock'
-    Spreedly.configure('site short name', 'crazy hash token')
-    url = Spreedly.subscribe_url('customer id', 'plan id')
-    subscriber = Spreedly::Subscriber.find('customer id')
-    subscriber.active?
+Otherwise gem install:
 
-Yup, they're exactly the same except for the require and the speed!
+    $ gem install spreedly
 
-## Requirements
 
-* A Spreedly Subscriptions account.
-* HTTParty
+## Usage
 
-## Install
+#### Basic purchase
 
-    $ gem install spreedly
+Let's start with a simple purchase when you already have a gateway token and a payment method token:
+
+``` ruby
+env = Spreedly::Environment.new(environment_key, access_secret)
+
+transaction = env.purchase_on_gateway(gateway_token, payment_method_token, 4432)
+
+transaction.succeeded?    # => true
+transaction.token         # => "aGJlY5srn7TFeYKxO5pmwi3CyJd"
+```
+
+The amount specified in that example was 4432.  Amounts are always in cents so in this case, we're charging $44.32.
+
+#### Add a gateway
+What if you don't have a gateway token yet?  It's pretty easy to add a test gateway:
+
+``` ruby
+gateway = env.add_gateway(:test)
+gateway.token     # => "DnbEJaaY2egcVkCvg3s8qT38xgt"
+```
+
+
+#### Add a payment method
+Need a payment method token to try things out?  With Spreedly it's pretty straightforward to use a
+[transparent redirect](https://core.spreedly.com/manual/quickstart#submit-payment-form) to give you a
+payment method token.  A payment form in your application could look something like this:
+
+``` html
+<form action="<%= env.transparent_redirect_form_action %>" method="POST">
+  <fieldset>
+    <input name="redirect_url" type="hidden" value="http://yourdomain.com/transparent_redirect_done" />
+    <input name="environment_key" type="hidden" value="<%= env.key %>" />
+    <label for="credit_card_full_name">Name</label>
+    <input id="credit_card_full_name" name="credit_card[full_name]" type="text" />
+
+    <label for="credit_card_number">Card Number</label>
+    <input id="credit_card_number" name="credit_card[number]" type="text" />
+
+    <label for="credit_card_verification_value">Security Code</label>
+    <input id="credit_card_verification_value" name="credit_card[verification_value]" type="text" />
+
+    <label for="credit_card_month">Expires on</label>
+    <input id="credit_card_month" name="credit_card[month]" type="text" />
+    <input id="credit_card_year" name="credit_card[year]" type="text" />
+
+    <button type='submit'>Submit Payment</button>
+  </fieldset>
+</form>
+```
+
+Notice that we can ask the environment for the form action url and that the environment knows its key to use in the hidden field.
+
+Once Spreedly has recorded the information, it will redirect the browser to the url specified in the `redirect_url` field, tacking on a token that represents the credit card your customer entered. This is the payment_method token you're looking for. In this case your customer would be sent to this url:
+
+    http://yourdomain.com/transparent_redirect_done?token=OEj2G2QJZM4C10AfTLYTrsKIsZH
+
+Once you have the payment method token (OEj2G2QJZM4C10AfTLYTrsKIsZH in this case), you can remember it and use it whenever you'd like.  These [test cards](https://core.spreedly.com/manual/test-data) will help.
+
+#### Retrieve a payment method
+Let's say you'd like some additional information about the payment method.  You can find a payment method like so:
+
+``` ruby
+credit_card = env.find_payment_method(token)
+credit_card.last_name      # => "Jones"
+credit_card.valid?         # => false
+
+credit_card.errors
+# Returns => [
+#      { attribute: "first_name", key: "errors.blank", message: "First name can't be blank" },
+#      { attribute: "year", key: "errors.expired", message: "Year is expired" },
+#      { attribute: "year", key: "errors.invalid", message: "Year is invalid" },
+#      { attribute: "number", key: "errors.blank", message: "Number can't be blank" }
+#    ]
+```
+
+#### Authorize and Capture
+
+``` ruby
+auth_transaction = env.authorize_on_gateway(gateway_token, payment_method_token, 250)
+
+if auth_transaction.succeeded?
+  capture_transaction = env.capture_transaction(auth_transaction.token)
+end
+```
+
+You can also specify an optional amount to capture.
+
+``` ruby
+capture_transaction = env.capture_transaction(auth_transaction.token, amount: 100)
+```
+
+
+#### Void and refund
+
+``` ruby
+transaction = env.void_transaction(transaction_token)
+
+# Refund the entire amount
+transaction = env.refund_transaction(transaction_token)
+
+# Specify an amount to be refunded
+transaction = env.refund_transaction(transaction_token, amount: 104)
+```
+
+#### Retain and redact
+
+``` ruby
+transaction = env.retain_payment_method(payment_method_token)
+
+transaction = env.redact_payment_method(payment_method_token)
+```
+
+#### Currencies
+When you instantiate an environment, you can specify a default currency code like so:
+
+``` ruby
+env = Spreedly::Environment.new(environment_key, access_secret, currency_code: 'EUR')
+```
+
+If you don't specify a default currency code, we default to 'USD'.  Calls requiring a currency code by default use the environment's currency code.  And of course, you can always override it for a particular call like so:
+
+``` ruby
+env.purchase_on_gateway(gateway_token, payment_method_token, amount, currency_code: "GBP")
+```
+
+
+#### Extra options for the basic operations
+For Purchase, Authorize, Capture, Refund, and Void calls, you can specify additional options:
+
+``` ruby
+env.purchase_on_gateway(gateway_token, payment_method_token, amount,
+                        order_id: "123",
+                        description: "The Description",
+                        ip: "192.31.123.112",
+                        merchant_name_descriptor: "SuperDuper Corp",
+                        merchant_location_descriptor: "http://super.com"
+                       )
+```
+
+#### Retain on success
+Retain a payment method automatically if the purchase or authorize transaction succeeded.  Saves you a separate call to retain:
+
+``` ruby
+env.purchase_on_gateway(gateway_token, payment_method_token, amount, retain_on_success: true)
+```
+
+#### Retrieving gateways
+
+``` ruby
+gateways = env.list_gateways
+
+# Iterate over the next chunk
+next_set = env.list_gateways(gateways.last.token)
+```
+
+#### Retrieving payment methods
+
+``` ruby
+payment_methods = env.list_payment_methods
+
+# Iterate over the next chunk
+next_set = env.list_payment_methods(payment_methods.last.token)
+```
+
+#### Retrieving transactions
+
+``` ruby
+transactions = env.list_transactions
+
+# Iterate over the next chunk
+next_set = env.list_transactions(transactions.last.token)
+```
+
+#### Retrieving transactions for a payment method
+
+``` ruby
+transactions = env.list_transactions(nil, payment_method_token)
+
+# Iterate over the next chunk
+next_set = env.list_transactions(transactions.last.token, payment_method_token)
+```
+
+#### Retrieving one gateway
+
+``` ruby
+gateway = env.find_gateway(token)
+gateway.gateway_type      # => 'paypal'
+```
+
+#### Retrieving one transaction
+
+``` ruby
+transaction = env.find_transaction(token)
+transaction.order_id      # => '30-9904-31114'
+```
+
+#### Retrieving the transcript for a transaction
+
+``` ruby
+env.find_transaction_transcript(transaction_token)
+```
+
+#### Updating a payment method
+
+``` ruby
+env.update_payment_method(payment_method_token, first_name: 'JimBob', last_name: 'Jones')
+```
+
+#### Adding other types of gateways
+
+``` ruby
+gateway = env.add_gateway(:paypal, mode: 'delegate', email: 'fred@example.com')
+gateway.token     # => "2nQEJaaY3egcVkCvg2s9qT37xrb"
+```
+
+#### Adding credit cards
+
+The primary mechanism to add a credit card is to use the transparent redirect payment form. This allows all of the sensitive information to be captured without ever touching your servers.
+
+There are times though when you may want to add a credit card in a more "manual" fashion with an API call.
+
+PLEASE NOTE: Using this API call can significantly increase your PCI compliance requirements.
+
+Here's how you can do it:
+
+``` ruby
+options = {
+email: 'perrin@wot.com', number: '5555555555554444', month: 1, year: 2019, last_name: 'Aybara', first_name: 'Perrin', data: "occupation: Blacksmith"
+}
+transaction = env.add_credit_card(options)
+
+transaction.token                 # => "2nQEJaaY3egcVkCvg2s9qT37xrb"
+transaction.card.token            # => "7rbEKaaY0egcBkCrg2sbqTo7Qrb"
+transaction.card.last_name        # => "Aybara"
+```
+
+You can also retain the card immediately like so:
+
+``` ruby
+options = {
+email: 'perrin@wot.com', number: '5555555555554444', month: 1, year: 2019, last_name: 'Aybara', first_name: 'Perrin', data: "occupation: Blacksmith", retained: true
+}
+transaction = env.add_credit_card(options)
+
+transaction.card.storage_state    # => "retained"
+```
+
+And you might want to specify a number of other details like the billing address, etc:
+
+``` ruby
+options = {
+email: 'leavenworth@free.com', number: '9555555555554444', month: 3, year: 2021, last_name: 'Smedry', first_name: 'Leavenworth', data: "talent: Late", address1: '10 Dragon Lane', address2: 'Suite 9', city: 'Tuki Tuki', state: 'Mokia', zip: '1122', country: 'Free Kingdoms', phone_number: '81Ab', retained: true
+}
+
+transaction = env.add_credit_card(options)
+
+transaction.card.last_name      # => "Smedry"
+
+```
+
+
+## Error Handling
+
+When you make a call to the API, there are times when things don't go as expected.  For the most part, when a call is made, a Transaction is created behind the scenes at Spreedly.  In general,
+you can inquire whether that transaction succeeded? or not and get it's message.  There are times when a Transaction cannot be created, and in general, an exception is raised for these cases.
+
+You can be as specific as you'd like in handling these exceptions or, you could simply rescue Spreedly::Error to handle all of them.
+
+#### Declined purchase
+
+``` ruby
+transaction = env.purchase_on_gateway(gateway_token, payment_method_token, 4432)
+
+transaction.succeeded?  # => false
+transaction.message     # => "Unable to process the purchase transaction."
+```
+
+#### Invalid payment method
+
+``` ruby
+transaction = env.purchase_on_gateway(gateway_token, payment_method_token, 4432)
+
+transaction.succeeded?  # => false
+transaction.message     # => "The payment method is invalid."
+
+transaction.payment_method.errors
+transaction.payment_method.errors
+# Returns => [
+#      { attribute: "last_name", key: "errors.blank", message: "Last name can't be blank" },
+#      { attribute: "number", key: "errors.blank", message: "Number can't be blank" }
+#    ]
+
+```
+
+#### Failure to find
+
+``` ruby
+env.find_transaction("Some Unknown Token")  # raises a Spreedly::NotFoundError
+```
+
+#### Invalid environment credentials
+
+``` ruby
+env = Spreedly::Environment.new(environment_key, "some bogus secret")
+env.purchase_on_gateway(gateway_token, payment_method_token, 4432) # Raises Spreedly::AuthenticationError
+```
+
+#### Unknown payment method trying to make a purchase
+
+``` ruby
+env.purchase_on_gateway(gateway_token, "Some Unknown Token", 4432) # Raises Spreedly::TransactionCreationError
+```
+
+#### Trying to use a non-test gateway or a non-test payment method with an inactive account
+
+You're free to use [test card data](https://core.spreedly.com/manual/test-data) and a [Test gateway](https://core.spreedly.com/manual/payment-gateways/test) to integrate Spreedly without having a
+paid Spreedly account.  If you try to use a real card or a real gateway when your account isn't yet paid for, we'll raise an exception:
+
+``` ruby
+env.purchase_on_gateway(gateway_token, "Payment Method Token for a real card", 4432) # Raises Spreedly::PaymentRequiredError
+```
+
+#### Timeout errors
+
+If Spreedly is not responding, we'll raise an exception.  Spreedly itself has a timeout so that if a gateway isn't responding, it'll reflect that in the response.  The gem has its own timeout to
+handle the case of Spreedly itself not responding.  Here's an example:
+
+``` ruby
+env.purchase_on_gateway(gateway_token, payment_method_token, 802) # Raises Spreedly::TimeoutError
+```
+
+## Sample applications using the gem
+
+There are some sample applications with source code using this gem.  You can [find them here](https://core.spreedly.com/manual/sample_applications).
+
+## Contributing
+
+We're happy to consider [pull requests](https://help.github.com/articles/using-pull-requests).
+
+There are two rake tasks to help run the tests:
+
+```
+rake test:remote  # Run remote tests that actually hit the Spreedly site
+rake test:units   # Run unit tests
+```

data/Rakefile

@@ -0,0 +1,32 @@
+require "bundler/gem_tasks"
+
+require 'rake/testtask'
+
+# Rake::TestTask.new do |t|
+#   t.libs << 'test'
+# end
+
+# desc "Run tests"
+# task :default => :test
+
+
+
+desc "Run the unit test suite"
+task :default => 'test:units'
+
+namespace :test do
+
+  Rake::TestTask.new(:units) do |t|
+    t.pattern = 'test/unit/**/*_test.rb'
+    t.libs << 'test'
+    t.verbose = true
+  end
+
+  Rake::TestTask.new(:remote) do |t|
+    t.pattern = 'test/remote/**/*_test.rb'
+    t.libs << 'test'
+    t.verbose = true
+  end
+
+end
+