yp-ruby 0.1.3 → 0.1.4a

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c0e8f0cb22b7a4f03a355e460984e1ac50da242b
-  data.tar.gz: fa63594396cabc343e2699290b1223c762c903fb
+  metadata.gz: 9f28691645bfdb90373e2524028d93a1e711bb46
+  data.tar.gz: cd6b81278539fbea582bf11dca079e7131f45357
 SHA512:
-  metadata.gz: 9e96e8bfbb983d3336d1b81798087b6d81c64b1631f748488fccaa8206210aa325d1b4c5341523192a141bdb5c80d61882247fad4767a8d1e548a2145c487eff
-  data.tar.gz: 01ec3ed018db1179656697a4ea112b493e04021d3453ff58519f45041abc6d9623b6bd348fe267bb4f1206ee501c32590912cc84fae86fd7af495694740a5ac2
+  metadata.gz: 4f933e44afc37aa9a3a244e89c78f6a7ef4f75e6ca20cb8e95dbf57df2557b6fa73afe5ea6b37aa5d0cfefd84ab625bdec24f105c09d16e8e7d712873d766a97
+  data.tar.gz: 299c5520a8dd0234828004f7e5d16e1b4ad404f977deddf700010606b02fb4423e475c933c201964e9c9d36852bfe57b631e433565032dc27a80a4250468f4da

data/README.md

@@ -20,7 +20,86 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Different classes are available for the Gateway actions:
+
+ - Yp::Sale
+ - Yp::Preauth
+ - Yp::Verify
+ 
+If you need support for more actions, please [open an issue](https://github.com/andytango/yp-ruby/issues)!
+
+### Authentication and params
+ 
+You will need to pass in the correct parameters according to the Yorkshire Payments integration guide:
+
+```ruby
+
+signature_key = 'Engine0Milk12Next'
+
+params = {
+  merchantID: '101381',
+  countryCode: 826,
+  currencyCode:  826,
+  cardNumber:  '4012001037141112',
+  cardExpiryMonth:  12,
+  cardExpiryYear:  15,
+  cardCVV:  '083',
+  customerName:  'Yorkshire Payments',
+  customerEmail:  'support@yorkshirepayments.com',
+  customerAddress:  '16 Test Street',
+  customerPostCode:  'TE15 5ST',
+  orderRef:  'Test purchase'
+}
+
+transaction = Yp::Sale.new(signature, params)
+
+```
+
+The library will *not* validate your parameters before sending. This feature is coming soon.
+
+You pass in a callback method as a block, or access the response after the transaction is sent:
+
+```ruby
+
+transaction.send! do |response|
+  puts response.state # --> 'captured'
+end
+
+# OR:
+
+response = transaction.send!
+puts response.state # --> 'captured'
+
+```
+
+### Error Handling
+
+The client will raise a number of different types of errors:
+
+#### Validation Errors
+
+These occur if we could not perform any validation. This means the response is 
+malformed and can arise if you did not correctly sign your request:
+
+ - Yp::Response::InvalidSignatureError (potentially malicious)
+ - Yp::Response::MissingSignatureError
+ - Yp::Response::MissingResponseCodeError
+ 
+#### Gateway Errors
+
+These occur if, during validation, we found a Gateway error code. These come in 
+three different flavours:
+
+ - Yp::Response::MissingFieldError: _a field was missing in your request_
+ - Yp::Response::InvalidFieldError: _a field value was invalid in your request_
+ - Yp::Response::GatewayError: _the error could not be classified. The gateway's
+ error message will be supplied_
+ 
+#### Transaction Declined Error
+
+This occurs if the transaction has entered the **Declined** state:
+     
+  - Yp::Response::DeclinedError
 
 ## Development
 
@@ -30,7 +109,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/yp-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+Bug reports and pull requests are welcome on GitHub at https://github.com/andytango/yp-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
 
 
 ## License

data/data/gateway_responses.yml

@@ -0,0 +1,69 @@
+missing_field:
+  66048: 'request'
+  66049: 'merchantID'
+  66055: 'action'
+  66056: 'amount'
+  66057: 'currencyCode'
+  66058: 'cardNumber'
+  66059: 'cardExpiryMonth'
+  66060: 'cardExpiryYear'
+  66064: 'cardCVV'
+  66065: 'customerName'
+  66066: 'customerAddress'
+  66067: 'customerPostCode'
+  66068: 'customerEmail'
+  66070: 'countyCode'
+  66087: 'signature'
+  66092: 'threeDSPaRes'
+  66093: 'threeDSECI'
+  66094: 'threeDSCAVV'
+  66095: 'threeDSXID'
+  66096: 'threeDSEnrolled'
+  66097: 'threeDSAuthenticated'
+  66098: 'threeDSCheckPref'
+  66099: 'cv2CheckPref'
+  66100: 'addressCheckPref'
+  66101: 'postcodeCheckPref'
+  66102: 'captureDelay'
+  66103: 'orderDate'
+  66104: 'grossAmount'
+  66105: 'netAmount'
+  66016: 'taxRate'
+  66016: 'taxReason'
+  66160: 'cardExpiryDate'
+  66161: 'cardStartDate'
+
+invalid_field:
+  66304: 'request'
+  66305: 'merchantID'
+  66311: 'action'
+  66312: 'amount'
+  66313: 'currencyCode'
+  66314: 'cardNumber'
+  66315: 'cardExpiryMonth'
+  66316: 'cardExpiryYear'
+  66317: 'cardCVV'
+  66332: 'customerName'
+  66322: 'customerAddress'
+  66323: 'customerPostCode'
+  66324: 'customerEmail'
+  66326: 'countyCode'
+  66343: 'signature'
+  66348: 'threeDSPaRes'
+  66349: 'threeDSECI'
+  66350: 'threeDSCAVV'
+  66351: 'threeDSXID'
+  66352: 'threeDSEnrolled'
+  66353: 'threeDSAuthenticated'
+  66354: 'threeDSCheckPref'
+  66355: 'cv2CheckPref'
+  66356: 'addressCheckPref'
+  66357: 'postcodeCheckPref'
+  66358: 'captureDelay'
+  66359: 'orderDate'
+  66360: 'grossAmount'
+  66361: 'netAmount'
+  66362: 'taxRate'
+  66363: 'taxReason'
+  66416: 'cardExpiryDate'
+  66417: 'cardStartDate'

data/lib/base.rb

@@ -1,4 +1,6 @@
 require 'transaction_logger'
+require 'signing_hash_creator'
+require 'response'
 
 module Yp
   class Base
@@ -15,24 +17,13 @@ module Yp
       @signature_key = signature_key
     end
 
-    def body
-      @params.clone.tap do |params|
-        params[:signature] = create_signing_hash
-        TransactionLogger.log_request(params)
-      end
-    end
-
-    def create_signing_hash
-      self.class.digest(self.class.serialize_params(@params) + @signature_key)
-    end
-
-    def send
+    def send!
       if block_given?
         RestClient.post(URL, body) do |response|
-          yield(self.class.parse response)
+          yield(parse_and_validate response)
         end
       else
-        self.class.parse(RestClient.post(URL, body))
+        parse_and_validate(RestClient.post(URL, body))
       end
     end
 
@@ -59,42 +50,22 @@ module Yp
       { type: TYPE[type] }
     end
 
-    class << self
-
-      def digest(str_params)
-        Digest::SHA512.hexdigest str_params
-      end
-
-      def serialize_params(params)
-        uri_string_from_hash(params)
-      end
-
-      def parse(response)
-        ruby_hash_from_response(CGI::parse(response)).tap do |parsed|
-          TransactionLogger.log_response(parsed)
-        end
-      end
-
-      private
-
-      def uri_string_from_hash(hash)
-        hash.map { |key, value| uri_query_param(key, value) }.sort.join '&'
-      end
-
-      def uri_query_param(key, value)
-        encode_url_component(key) + '=' + encode_url_component(value)
-      end
-
-      def encode_url_component(key)
-        ERB::Util::url_encode(key).gsub(/%20/, '+')
+    def body
+      @params.clone.tap do |params|
+        params[:signature] = create_signing_hash
+        TransactionLogger.log_request(params)
       end
+    end
 
-      def ruby_hash_from_response(hash)
-        hash.reduce({}) do |memo, (key, value)|
-          memo.merge({key.to_sym => value.first})
-        end
-      end
+    def create_signing_hash
+      SigningHashCreator.new(@params, @signature_key).create
+    end
 
+    def parse_and_validate(response)
+      Response
+          .new(@signature_key, response, TransactionLogger)
+          .parse_and_validate
     end
+
   end
 end

data/lib/response.rb

@@ -0,0 +1,36 @@
+require 'response/parser'
+require 'response/error'
+require 'response/validator'
+require 'response/error_logger'
+
+module Yp
+  class Response
+    def initialize(signature, params, logger)
+      @signature = signature
+      @params = params
+      @logger = logger
+    end
+
+    def parse_and_validate
+      validate!
+      parsed
+    end
+
+    private
+
+    def validate!
+      ErrorLogger.new(@logger).log do
+        Validator.new(parsed, @signature).validate!
+      end
+    end
+
+    def parsed
+      @parsed ||= parse_params
+    end
+
+    def parse_params
+      Parser.new(@params).parse.tap { |parsed| @logger.log_response(parsed) }
+    end
+
+  end
+end

data/lib/response/error.rb

@@ -0,0 +1,16 @@
+module Yp
+  class Response
+    class ValidationError < StandardError
+      def initialize
+        super('Gateway response could not be validated.')
+      end
+    end
+
+    class InvalidSignatureError < ValidationError; end
+    class MissingSignatureError < ValidationError; end
+    class MissingResponseCodeError < ValidationError; end
+    class MissingResponseMessageError < ValidationError; end
+
+    class DeclinedError < StandardError; end
+  end
+end

data/lib/response/error_logger.rb

@@ -0,0 +1,53 @@
+module Yp
+  class Response
+    class ErrorLogger
+      extend Forwardable
+
+      def_delegators :@logger, :fatal, :error
+
+      def initialize(logger)
+        @logger = logger
+      end
+
+      def log
+        begin
+          yield
+        rescue InvalidSignatureError => e
+          log_fatal 'An invalid signature was received', e
+        rescue MissingSignatureError => e
+          log_not_found 'Signature', e
+        rescue MissingResponseCodeError => e
+          log_not_found 'Response Code', e
+        rescue MissingResponseMessageError => e
+          log_not_found 'Response Message', e
+        rescue DeclinedError => e
+          log_error 'Transaction was declined by the acquirer', e
+        rescue MissingFieldError => e
+          log_error 'Gateway responded with missing field', e
+        rescue InvalidFieldError => e
+          log_error 'Gateway responded with invalid field', e
+        rescue GatewayError => e
+          log_error 'Gateway responded with error', e
+        end
+      end
+
+      private
+
+      def log_not_found(thing, e)
+        log_fatal("#{thing} was not found in the response", e)
+      end
+
+      def log_fatal(str, e)
+        fatal(str)
+        raise e
+      end
+
+      def log_error(str, e)
+        error("#{str} (#{e})")
+        raise e
+      end
+
+
+    end
+  end
+end

data/lib/response/gateway_error.rb

@@ -0,0 +1,68 @@
+require 'yaml'
+
+module Yp
+  class Response
+    class GatewayError < StandardError
+
+      def self.from_response_code(code, message)
+        Factory.new(code, message).error
+      end
+
+      class Factory
+
+        class << self
+          def error_map
+            @error_map ||= load_error_map
+          end
+
+          private
+
+          def load_error_map
+            YAML.load(File.read('data/gateway_responses.yml'))
+          end
+        end
+
+        def initialize(code, message)
+          @code = code
+          @message = message
+        end
+
+        def error
+          if is_missing_field?
+            MissingFieldError.new(missing_field)
+          elsif is_invalid_field?
+            InvalidFieldError.new(invalid_field)
+          else
+            GatewayError.new(@message)
+          end
+        end
+
+        private
+
+        def is_missing_field?
+          !missing_field.nil?
+        end
+
+        def missing_field
+          @missing_field ||= mapped_error(:missing_field)
+        end
+
+        def is_invalid_field?
+          !invalid_field.nil?
+        end
+
+        def invalid_field
+          @invalid_field ||= mapped_error(:invalid_field)
+        end
+
+        def mapped_error(sym)
+          Factory.error_map[sym.to_s][@code.to_i]
+        end
+
+      end
+    end
+
+    class MissingFieldError < GatewayError; end
+    class InvalidFieldError < GatewayError; end
+  end
+end

data/lib/response/parser.rb

@@ -0,0 +1,27 @@
+module Yp
+  class Response
+    class Parser
+
+      def initialize(params)
+        @params = params
+      end
+
+      def parse
+        ruby_hash_from_response(parse_string)
+      end
+
+      private
+
+      def parse_string
+        CGI::parse(@params)
+      end
+
+      def ruby_hash_from_response(hash)
+        hash.reduce({}) do |memo, (key, value)|
+          memo.merge({key.to_sym => value.first})
+        end
+      end
+
+    end
+  end
+end

data/lib/response/validator.rb

@@ -0,0 +1,21 @@
+require_relative 'validator/signing_key'
+require_relative 'validator/gateway'
+require_relative 'validator/acquirer'
+
+module Yp
+  class Response
+    class Validator
+      def initialize(params, signature)
+        @params = params
+        @signature = signature
+      end
+
+      def validate!
+        SigningKey.new(@params, @signature).validate!
+        Gateway.new(@params).validate!
+        Acquirer.new(@params).validate!
+      end
+
+    end
+  end
+end

data/lib/response/validator/acquirer.rb

@@ -0,0 +1,27 @@
+module Yp
+  class Response
+    class Validator
+      class Acquirer
+
+        def initialize(params)
+          @params = params
+        end
+
+        def validate!
+          !declined? || (raise DeclinedError)
+        end
+
+        private
+
+        def declined?
+          response_code == 4 || response_code == 5
+        end
+
+        def response_code
+          @response_code ||= @params[:responseCode].to_i
+        end
+
+      end
+    end
+  end
+end

data/lib/response/validator/gateway.rb

@@ -0,0 +1,41 @@
+require_relative '../gateway_error'
+
+module Yp
+  class Response
+    class Validator
+      class Gateway
+
+        def initialize(params)
+          @params = params
+        end
+
+        def validate!
+          is_valid_response_code? || (raise error_from_response)
+        end
+
+        private
+
+        def is_valid_response_code?
+          response_code.to_i <= 5
+        end
+
+        def error_from_response
+          GatewayError.from_response_code(response_code, response_message)
+        end
+
+        def response_code
+          @response_code ||= find_response_code
+        end
+
+        def find_response_code
+          @params[:responseCode] || (raise MissingResponseCodeError)
+        end
+
+        def response_message
+          @params[:responseMessage] || (raise MissingResponseMessageError)
+        end
+
+      end
+    end
+  end
+end

data/lib/response/validator/signing_key.rb

@@ -0,0 +1,38 @@
+require 'signing_hash_creator'
+
+module Yp
+  class Response
+    class Validator
+      class SigningKey
+
+        def initialize(params, signature)
+          @params = params
+          @signature = signature
+        end
+
+        def validate!
+          has_valid_signing_key? || (raise InvalidSignatureError)
+        end
+
+        private
+
+        def has_valid_signing_key?
+          their_signing_key == our_signing_key
+        end
+
+        def their_signing_key
+          @params[:signature] || (raise MissingSignatureError)
+        end
+
+        def our_signing_key
+          SigningHashCreator.new(signing_key_params, @signature).create
+        end
+
+        def signing_key_params
+          @params.reject { |k, _| k == :signature }
+        end
+
+      end
+    end
+  end
+end

data/lib/signing_hash_creator.rb

@@ -0,0 +1,32 @@
+module Yp
+  class SigningHashCreator
+    def initialize(params, signature_key)
+      @params = params
+      @signature_key = signature_key
+    end
+
+    def create
+      self.class.digest(self.class.serialize_params(@params) + @signature_key)
+    end
+
+    class << self
+
+      def digest(str_params)
+        Digest::SHA512.hexdigest str_params
+      end
+
+      def serialize_params(params)
+        params.map { |key, value| uri_query_param(key, value) }.sort.join('&')
+      end
+
+      def uri_query_param(key, value)
+        encode_url_component(key) + '=' + encode_url_component(value)
+      end
+
+      def encode_url_component(key)
+        ERB::Util::url_encode(key).gsub(/%20/, '+')
+      end
+
+    end
+  end
+end

data/lib/transaction_logger.rb

@@ -12,10 +12,22 @@ module Yp
         info 'Response received', params
       end
 
+      def info(str, params=nil)
+        Yp.logger.info(format(str, params))
+      end
+
+      def error(str)
+        Yp.logger.error(format_message(str))
+      end
+
+      def fatal(str)
+        Yp.logger.fatal(format_message(str))
+      end
+
       private
 
-      def info(str, params=nil)
-        Yp.logger.info("#{format_message(str)} #{format_params(params)}")
+      def format(str, params)
+        "#{format_message(str)} #{format_params(params)}"
       end
 
       def format_message(str)
@@ -23,7 +35,7 @@ module Yp
       end
 
       def format_params(params)
-        " with params #{filter_card_params(params).to_s}"
+        " with params #{filter_card_params(params).to_s}" unless params.nil?
       end
 
       def filter_card_params(hash)

data/lib/version.rb

@@ -1,3 +1,3 @@
 module Yp
-    VERSION = "0.1.3"
+    VERSION = "0.1.4a"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: yp-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.1.4a
 platform: ruby
 authors:
 - Andrew Hall
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-01-21 00:00:00.000000000 Z
+date: 2017-03-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
@@ -133,12 +133,23 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- data/gateway_responses.yml
 - exe/yp-ruby
 - lib/base.rb
 - lib/factory.rb
 - lib/nil_logger.rb
 - lib/preauth.rb
+- lib/response.rb
+- lib/response/error.rb
+- lib/response/error_logger.rb
+- lib/response/gateway_error.rb
+- lib/response/parser.rb
+- lib/response/validator.rb
+- lib/response/validator/acquirer.rb
+- lib/response/validator/gateway.rb
+- lib/response/validator/signing_key.rb
 - lib/sale.rb
+- lib/signing_hash_creator.rb
 - lib/transaction_logger.rb
 - lib/verify.rb
 - lib/version.rb
@@ -160,9 +171,9 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
 rubyforge_project: 
 rubygems_version: 2.5.2