tns_payments 0.0.8 → 0.0.9

data/CHANGELOG.md

@@ -1,5 +1,11 @@
 # CHANGELOG
 
+## 0.0.9 / 2012-04-12
+
+* Error Responses get their own class in an attempt to provide consistency.
+* Added TomDoc documentation.
+* Separated concerns in Request class.
+
 ## 0.0.8 / 2012-04-11
 
 * Default open_timeout and read_timeout to something sensible.

data/lib/tns_payments.rb

@@ -1,12 +1,16 @@
 require 'tns_payments/connection'
 require 'tns_payments/request'
 require 'tns_payments/response'
+require 'tns_payments/error_response'
 require 'tns_payments/transaction'
 require 'tns_payments/version'
 
 module TNSPayments
   class SessionTokenException < Exception; end
 
+  # Public: A proxy method to Connection.new.
+  #
+  # Returns a new Connection.
   def self.new options = {}
     Connection.new options
   end

data/lib/tns_payments/connection.rb

@@ -7,6 +7,9 @@ module TNSPayments
     attr_accessor :api_key, :host, :merchant_id
     attr_writer :session_token
 
+    # Public: Request to check that the gateway is operating.
+    #
+    # Returns a boolean.
     def available?
       request(:get, '/information', :authorization => false).success?
     end
@@ -16,10 +19,17 @@ module TNSPayments
       self.host = options.fetch(:host) { 'https://secure.ap.tnspayments.com' }
     end
 
+    # Public: Payment form url that includes a session token.
+    #
+    # Returns a url.
     def payment_form_url
       "#{host}/form/#{session_token}"
     end
 
+    # Public: A single transaction to authorise the payment and transfer funds
+    #         from the cardholder's account to your account.
+    #
+    # Returns a Response object.
     def purchase transaction, token
       transaction    = Transaction.new transaction
       order_id       = transaction.order_id
@@ -28,24 +38,38 @@ module TNSPayments
         'apiOperation' => 'PAY',
         'cardDetails'  => card_details(token),
         'order'        => {'reference' => transaction.reference},
-        'transaction'  => {'amount'    => transaction.amount.to_s, 'currency' => transaction.currency, 'reference' => transaction_id.to_s}
+        'transaction'  => {
+          'amount'    => transaction.amount.to_s,
+          'currency'  => transaction.currency,
+          'reference' => transaction_id.to_s
+        }
       }
 
       request :put, "/merchant/#{merchant_id}/order/#{order_id}/transaction/#{transaction_id}", params
     end
 
+    # Public: Request to refund previously captured funds.
+    #
+    # Returns a Response object.
     def refund transaction
       transaction    = Transaction.new transaction
       order_id       = transaction.order_id.to_i
       transaction_id = transaction.transaction_id
       params         = {
         'apiOperation' => 'REFUND',
-        'transaction'  => {'amount' => transaction.amount.to_s, 'currency' => transaction.currency, 'reference' => transaction_id.to_s}
+        'transaction'  => {
+          'amount'    => transaction.amount.to_s,
+          'currency'  => transaction.currency,
+          'reference' => transaction_id.to_s
+        }
       }
 
       request :put, "/merchant/#{merchant_id}/order/#{order_id}/transaction/#{transaction_id}", params
     end
 
+    # Public: Request to store a card for later retrieval via token.
+    #
+    # Returns a Response object.
     def create_credit_card_token token
       params = {
         'cardDetails' => card_details(token)
@@ -54,28 +78,56 @@ module TNSPayments
       request :post, "/merchant/#{merchant_id}/token", params
     end
 
+    # Public:
+    #
+    # Returns a Response object.
     def delete_credit_card_token token
       request :delete, "/merchant/#{merchant_id}/token/#{token}"
     end
 
+    # Public: Request to create a Form Session. A Form Session is used by the
+    #         Hosted Payment Form service to temporarily store card details so
+    #         that the merchant does not need to handle these details directly.
+    #
+    # Returns a Response object.
     def session_token
       @session_token ||= begin
         response = request :post, "/merchant/#{merchant_id}/session"
-        response.response.fetch('session') { raise(SessionTokenException.new, response.message) }
+        if response.success?
+          response.response.fetch('session')
+        else
+          raise SessionTokenException.new, response.explanation
+        end
       end
     end
 
+    # Public: Request to check a cardholder's enrollment in the 3DSecure scheme.
+    #
+    # Returns a Response object.
     def check_enrollment transaction, token, postback_url
       params = {
-        '3DSecure'     => {'authenticationRedirect' => {'pageGenerationMode' => 'CUSTOMIZED', 'responseUrl' => postback_url}},
+        '3DSecure'     => {
+          'authenticationRedirect' => {
+            'pageGenerationMode'   => 'CUSTOMIZED',
+            'responseUrl'          => postback_url
+          }
+        },
         'apiOperation' => 'CHECK_3DS_ENROLLMENT',
         'cardDetails'  => card_details(token),
-        'transaction'  => {'amount' => transaction.amount.to_s, 'currency' => transaction.currency}
+        'transaction'  => {
+          'amount'   => transaction.amount.to_s,
+          'currency' => transaction.currency
+        }
       }
 
       request :put, "/merchant/#{merchant_id}/3DSecureId/#{transaction.three_domain_id}", params
     end
 
+    # Public: Interprets the authentication response returned from the card
+    #         Issuer's Access Control Server (ACS) after the cardholder
+    #         completes the authentication process.
+    #
+    # Returns a Response object.
     def process_acs_result three_domain_id, pa_res
       params = {
         '3DSecure'     => {'paRes' => pa_res},

data/lib/tns_payments/error_response.rb

@@ -0,0 +1,92 @@
+module TNSPayments
+  class ErrorResponse < Response
+    # Public: Check if the request was rejected because it did not conform to
+    #         the API protocol.
+    #
+    # Returns booelan.
+    def invalid_request?
+      cause == 'INVALID_REQUEST'
+    end
+
+    # Public: Check if the server did not have enough resources to process the
+    #         request at the moment.
+    #
+    # Returns booelan.
+    def server_busy?
+      cause == 'SERVER_BUSY'
+    end
+
+    # Public: Check if the request was rejected due to security reasons such as
+    #         firewall rules, expired certificate, etc.
+    #
+    # Returns booelan.
+    def request_rejected?
+      cause == 'REQUEST_REJECTED'
+    end
+
+    # Public: Check if there was an internal system failure.
+    #
+    # Returns booelan.
+    def server_failed?
+      cause == 'SERVER_FAILED'
+    end
+
+    # Public: Check if the request timed out.
+    #
+    # Returns boolean.
+    def timedout?
+      cause == 'REQUEST_TIMEDOUT'
+    end
+
+    # Public: Broadly categorizes the cause of the error.
+    #
+    # Returns string.
+    def cause
+      response['error']['cause']
+    end
+
+    # Pubic: Textual description of the error based on the cause.
+    #
+    # Returns string.
+    def explanation
+      if invalid_request? || server_busy?
+        response['error']['explanation']
+      else
+        "No explanation available for #{cause}"
+      end
+    end
+
+    # Public: Indicates the name of the field that failed validation.
+    #
+    # Returns name of invalid field.
+    def field
+      response['error']['field'] if invalid_request?
+    end
+
+    # Public: Indicates the code that helps the support team to quickly
+    #         identify the exact cause of the error.
+    #
+    # Returns a support code.
+    def support_code
+      if server_failed? || request_rejected?
+        response['error']['supportCode']
+      else
+        "No support code for #{cause}"
+      end
+    end
+
+    # Public: Determine if the request was successful.
+    #
+    # Returns false.
+    def success?
+      false
+    end
+
+    # Public: A system-generated high level overall result of the operation.
+    #
+    # Returns string.
+    def result
+      response['result']
+    end
+  end
+end

data/lib/tns_payments/request.rb

@@ -6,16 +6,27 @@ module TNSPayments
     attr_accessor :connection, :method, :path, :payload
 
     def initialize connection, method, path, payload = {}
-      self.connection, self.method, self.path, self.payload = connection, method, path, payload
+      self.connection = connection
+      self.method     = method
+      self.path       = path
+      self.payload    = payload
     end
 
-    def perform
-      authorization = payload.fetch(:authorization) { true }
-      url           = "#{connection.host}/api/rest/version/4#{path}"
-      auth_headers  = {:Authorization => encode_credentials}
-      headers       = {:content_type => 'Application/json;charset=UTF-8', :accept => '*/*'}
-      headers.merge! auth_headers if authorization
+    # Public: A hash representing the headers for the request.
+    #
+    # Returns a hash of headers.
+    def headers
+      headers = {}
+      headers[:accept]        = '*/*'
+      headers[:content_type]  = 'Application/json;charset=UTF-8'
+      headers[:Authorization] = encode_credentials if authorization
+      headers
+    end
 
+    # Public: Execute the request.
+    #
+    # Returns a response object.
+    def perform
       args = {
         :method       => method,
         :url          => url,
@@ -27,13 +38,27 @@ module TNSPayments
 
       Response.new RestClient::Request.execute(args)
     rescue RestClient::Exception => e
-      Response.new({:result => e.message.upcase, :response => JSON.parse(e.response || '{}')}.to_json)
+      response = e.response
+
+      if response.message == 'Request Timeout'
+        response = JSON.generate({:error => {:cause => 'REQUEST_TIMEDOUT'}})
+      end
+
+      ErrorResponse.new response
     end
 
   private
 
+    def authorization
+      payload.fetch(:authorization) { true }
+    end
+
     def encode_credentials
       'Basic ' + Base64.encode64(":#{connection.api_key}")
     end
+
+    def url
+      "#{connection.host}/api/rest/version/4#{path}"
+    end
   end
 end

data/lib/tns_payments/response.rb

@@ -6,20 +6,41 @@ module TNSPayments
       @raw_response = response
     end
 
+    # Public: The parsed response.
+    #
+    # Returns a hash of the parsed response.
     def response
       @response ||= JSON.parse(raw_response)
     end
 
+    # Public: The result of the request.
+    #
+    # Returns a string.
+    def result
+      if response.has_key?('status')
+        response['status'] == 'OPERATING' ? 'SUCCESS' : 'ERROR'
+      elsif response.has_key?('3DSecure')
+        'SUCCESS'
+      else
+        response['result']
+      end
+    end
+
+    # Public: Check if the request was successful.
+    #
+    # Returns boolean.
     def success?
-      %w[SUCCESS OPERATING].include? response['result'] || response['status']
+      result == 'SUCCESS'
     end
 
+    # Public: Unuseful message.
+    #
+    # Returns a string.
     def message
-      result = response['response'].fetch('result') { 'SUCCESS' }
-      if result == 'ERROR'
-        response['response']['error']['explanation']
-      else
+      if success?
         'Successful request'
+      else
+        ErrorResponse.new(raw_response).explanation
       end
     end
   end

data/lib/tns_payments/transaction.rb

@@ -7,10 +7,17 @@ module TNSPayments
       super
     end
 
+    # Public: TNS require a minimum order_id of 10000000000 for what I can only
+    #         assume is legacy requirements.
+    #
+    # Returns a minimum order_id.
     def minimum_order_id
       @minimum_order_id ||= 10000000000
     end
 
+    # Public: TNS require an order_id to be sent with each transaction.
+    #
+    # Returns the order_id.
     def order_id
       minimum_order_id + @transaction.order_id.to_i
     end

data/lib/tns_payments/version.rb

@@ -1,3 +1,3 @@
 module TNSPayments
-  VERSION = "0.0.8"
+  VERSION = "0.0.9"
 end

data/test/unit/conntection_test.rb

@@ -94,7 +94,7 @@ class TNSPayments::ConnectionTest < MiniTest::Unit::TestCase
   end
 
   def test_unsuccessful_session_token_request_raises_an_exception
-    stub_session_token_request.to_return(:status => 400, :body => '{}')
+    stub_session_token_request.to_return(:status => 400, :body => '{"error":{"cause":"Invalid merchant_id"}}')
     assert_raises SessionTokenException do
       @gateway.session_token
     end

data/test/unit/error_response_test.rb

@@ -0,0 +1,102 @@
+require 'helper'
+
+class TNSPayments::ErrorResponseTest < MiniTest::Unit::TestCase
+  def test_cause_exists
+    json = JSON.generate({'error' => {'cause' => 'foo'}})
+    assert_equal 'foo', TNSPayments::ErrorResponse.new(json).cause
+  end
+
+  def test_invalid_request_is_true
+    json = JSON.generate({'error' => {'cause' => 'INVALID_REQUEST'}})
+    assert TNSPayments::ErrorResponse.new(json).invalid_request?
+  end
+
+  def test_invalid_request_is_false
+    json = JSON.generate({'error' => {'cause' => 'SERVER_BUSY'}})
+    refute TNSPayments::ErrorResponse.new(json).invalid_request?
+  end
+
+  def test_server_busy_is_true
+    json = JSON.generate({'error' => {'cause' => 'SERVER_BUSY'}})
+    assert TNSPayments::ErrorResponse.new(json).server_busy?
+  end
+
+  def test_server_busy_is_false
+    json = JSON.generate({'error' => {'cause' => 'INVALID_REQUEST'}})
+    refute TNSPayments::ErrorResponse.new(json).server_busy?
+  end
+
+  def test_request_rejected_is_true
+    json = JSON.generate({'error' => {'cause' => 'REQUEST_REJECTED'}})
+    assert TNSPayments::ErrorResponse.new(json).request_rejected?
+  end
+
+  def test_request_rejected_is_false
+    json = JSON.generate({'error' => {'cause' => 'SERVER_BUSY'}})
+    refute TNSPayments::ErrorResponse.new(json).request_rejected?
+  end
+
+  def test_server_failed_is_true
+    json = JSON.generate({'error' => {'cause' => 'SERVER_FAILED'}})
+    assert TNSPayments::ErrorResponse.new(json).server_failed?
+  end
+
+  def test_server_failed_is_false
+    json = JSON.generate({'error' => {'cause' => 'REQUEST_REJECTED'}})
+    refute TNSPayments::ErrorResponse.new(json).server_failed?
+  end
+
+  def test_explanation_when_invalid_request
+    json = JSON.generate({'error' => {'cause' => 'INVALID_REQUEST', 'explanation' => 'Damn'}})
+    assert_equal 'Damn', TNSPayments::ErrorResponse.new(json).explanation
+  end
+
+  def test_explanation_when_server_busy
+    json = JSON.generate({'error' => {'cause' => 'SERVER_BUSY', 'explanation' => 'Damn'}})
+    assert_equal 'Damn', TNSPayments::ErrorResponse.new(json).explanation
+  end
+
+  def test_explanation_when_anything_else
+    json = JSON.generate({'error' => {'cause' => 'SERVER_FAILED', 'explanation' => 'Damn'}})
+    assert_equal 'No explanation available for SERVER_FAILED', TNSPayments::ErrorResponse.new(json).explanation
+  end
+
+  def test_field_when_invalid_request
+    json = JSON.generate({'error' => {'cause' => 'INVALID_REQUEST', 'field' => 'foo'}})
+    assert_equal 'foo', TNSPayments::ErrorResponse.new(json).field
+  end
+
+  def test_field_when_anything_else
+    json = JSON.generate({'error' => {'cause' => 'SERVER_FAILED', 'field' => 'foo'}})
+    assert_nil TNSPayments::ErrorResponse.new(json).field
+  end
+
+  def test_support_code_when_server_failed
+    json = JSON.generate({'error' => {'cause' => 'SERVER_FAILED', 'supportCode' => 'foo'}})
+    assert_equal 'foo', TNSPayments::ErrorResponse.new(json).support_code
+  end
+
+  def test_support_code_when_request_rejected
+    json = JSON.generate({'error' => {'cause' => 'REQUEST_REJECTED', 'supportCode' => 'foo'}})
+    assert_equal 'foo', TNSPayments::ErrorResponse.new(json).support_code
+  end
+
+  def test_support_code_when_anything_else
+    json = JSON.generate({'error' => {'cause' => 'INVALID_REQUEST', 'supportCode' => 'foo'}})
+    assert_equal 'No support code for INVALID_REQUEST', TNSPayments::ErrorResponse.new(json).support_code
+  end
+
+  def test_timedout
+    json = JSON.generate({'error' => {'cause' => 'REQUEST_TIMEDOUT'}})
+    assert TNSPayments::ErrorResponse.new(json).timedout?
+  end
+
+  def test_success_is_false
+    refute TNSPayments::ErrorResponse.new('{}').success?
+  end
+
+  def test_result
+    json = JSON.generate({'result' => 'ERROR'})
+    assert_equal 'ERROR', TNSPayments::ErrorResponse.new(json).result
+  end
+end

data/test/unit/response_test.rb

@@ -2,7 +2,7 @@ require 'helper'
 
 class TNSPayments::ResponseTest < MiniTest::Unit::TestCase
   def test_success_when_operating
-    assert Response.new({:result => 'OPERATING'}.to_json).success?
+    assert Response.new({:status => 'OPERATING'}.to_json).success?
   end
 
   def test_success_when_success
@@ -14,7 +14,7 @@ class TNSPayments::ResponseTest < MiniTest::Unit::TestCase
   end
 
   def test_message_when_error_request
-    response = "{\"result\":\"401 UNAUTHORIZED\",\"response\":{\"error\":{\"cause\":\"INVALID_REQUEST\",\"explanation\":\"Invalid credentials.\"},\"result\":\"ERROR\"}}"
+    response = "{\"result\":\"401 UNAUTHORIZED\",\"error\":{\"cause\":\"INVALID_REQUEST\",\"explanation\":\"Invalid credentials.\"},\"result\":\"ERROR\"}"
     assert_equal 'Invalid credentials.', Response.new(response).message
   end
 

metadata

@@ -1,154 +1,128 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: tns_payments
-version: !ruby/object:Gem::Version 
-  hash: 15
+version: !ruby/object:Gem::Version
+  version: 0.0.9
   prerelease: 
-  segments: 
-  - 0
-  - 0
-  - 8
-  version: 0.0.8
 platform: ruby
-authors: 
+authors:
 - Tim Cooper
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2012-04-11 00:00:00 +10:00
-default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  prerelease: false
-  type: :runtime
+date: 2012-04-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
   name: json
-  version_requirements: &id001 !ruby/object:Gem::Requirement 
+  requirement: &70254632443040 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  requirement: *id001
-- !ruby/object:Gem::Dependency 
-  prerelease: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :runtime
+  prerelease: false
+  version_requirements: *70254632443040
+- !ruby/object:Gem::Dependency
   name: rest-client
-  version_requirements: &id002 !ruby/object:Gem::Requirement 
+  requirement: &70254632442580 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  requirement: *id002
-- !ruby/object:Gem::Dependency 
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
   prerelease: false
-  type: :development
+  version_requirements: *70254632442580
+- !ruby/object:Gem::Dependency
   name: minitest
-  version_requirements: &id003 !ruby/object:Gem::Requirement 
+  requirement: &70254632442000 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  requirement: *id003
-- !ruby/object:Gem::Dependency 
-  prerelease: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
+  prerelease: false
+  version_requirements: *70254632442000
+- !ruby/object:Gem::Dependency
   name: rake
-  version_requirements: &id004 !ruby/object:Gem::Requirement 
+  requirement: &70254632441520 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  requirement: *id004
-- !ruby/object:Gem::Dependency 
-  prerelease: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
   type: :development
+  prerelease: false
+  version_requirements: *70254632441520
+- !ruby/object:Gem::Dependency
   name: webmock
-  version_requirements: &id005 !ruby/object:Gem::Requirement 
+  requirement: &70254632441040 !ruby/object:Gem::Requirement
     none: false
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        hash: 3
-        segments: 
-        - 0
-        version: "0"
-  requirement: *id005
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: *70254632441040
 description: Integration with TNS Payments Gateway
-email: 
+email:
 - coop@latrobest.com
 executables: []
-
 extensions: []
-
 extra_rdoc_files: []
-
-files: 
+files:
 - .gitignore
 - CHANGELOG.md
 - Gemfile
 - Rakefile
 - lib/tns_payments.rb
 - lib/tns_payments/connection.rb
+- lib/tns_payments/error_response.rb
 - lib/tns_payments/request.rb
 - lib/tns_payments/response.rb
 - lib/tns_payments/transaction.rb
 - lib/tns_payments/version.rb
 - test/helper.rb
 - test/unit/conntection_test.rb
+- test/unit/error_response_test.rb
 - test/unit/response_test.rb
 - test/unit/transaction_test.rb
 - tns_payments.gemspec
-has_rdoc: true
-homepage: ""
+homepage: ''
 licenses: []
-
 post_install_message: 
 rdoc_options: []
-
-require_paths: 
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+      hash: -4303212720216238171
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      hash: 3
-      segments: 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
       - 0
-      version: "0"
+      hash: -4303212720216238171
 requirements: []
-
 rubyforge_project: 
-rubygems_version: 1.6.2
+rubygems_version: 1.8.11
 signing_key: 
 specification_version: 3
 summary: Integration with TNS Payments Gateway
-test_files: 
+test_files:
 - test/helper.rb
 - test/unit/conntection_test.rb
+- test/unit/error_response_test.rb
 - test/unit/response_test.rb
 - test/unit/transaction_test.rb