alpha_card 0.2.6 → 0.3.0

data/ROADMAP.md

@@ -0,0 +1,12 @@
+# TODO
+
+* Own `Attribute` class with validations and etc:
+    - default value
+    - writable: `true` / `false`
+    - presence: `true` / `false`
+    - values: `['1', '2']`
+    - coerce ?
+* Configuration with `Account` setup
+    - all objects can use global or local account
+* Add new transactions:
+    - Authorization/Credit/Validate/Offline

data/alpha_card.gemspec

@@ -4,8 +4,8 @@ require 'alpha_card/version'
 
 Gem::Specification.new do |gem|
   gem.name = 'alpha_card'
-  gem.version = AlphaCard::VERSION
-  gem.date = '2015-04-27'
+  gem.version = AlphaCard.gem_version
+  gem.date = '2016-09-22'
   gem.summary = 'Alpha Card Services API for Ruby'
   gem.description = 'Gem for creating sales with Alpha Card Services'
   gem.authors = ['Nikita Bulaj']
@@ -14,9 +14,10 @@ Gem::Specification.new do |gem|
   gem.files = `git ls-files`.split($RS)
   gem.homepage = 'http://github.com/nbulaj/alpha_card'
   gem.license = 'MIT'
-  gem.required_ruby_version = '>= 1.9.3'
+  gem.required_ruby_version = '>= 2.0.0'
 
   gem.add_runtime_dependency 'virtus', '~> 1.0', '>= 1.0.5'
+  gem.add_runtime_dependency 'rack', '~> 1.2', '>= 1.2'
 
-  gem.add_development_dependency 'rspec', '~> 3'
+  gem.add_development_dependency 'rspec', '~> 3.5'
 end

data/lib/alpha_card.rb

@@ -14,13 +14,18 @@ require 'alpha_card/alpha_card_response'
 # Errors
 require 'alpha_card/errors/alpha_card_error'
 require 'alpha_card/errors/api_connection_error'
+require 'alpha_card/errors/invalid_object_error'
 
 # Alpha Card Resources
 require 'alpha_card/objects/account'
-require 'alpha_card/objects/shipping'
 require 'alpha_card/objects/billing'
+require 'alpha_card/objects/capture'
+require 'alpha_card/objects/shipping'
 require 'alpha_card/objects/order'
+require 'alpha_card/objects/void'
+require 'alpha_card/objects/refund'
 require 'alpha_card/objects/sale'
+require 'alpha_card/objects/update'
 
 ##
 # AlphaCard is a library for processing payments with Alpha Card Services, Inc.
@@ -83,10 +88,10 @@ module AlphaCard
     #
     #   #=> AlphaCard::AlphaCardError: AlphaCard::AlphaCardError
     def request(account, params = {})
-      fail AlphaCardError, 'You must set credentials to create the sale!' unless account.filled?
+      raise AlphaCardError, 'You must set credentials to create the sale!' unless account.filled?
 
       begin
-        response = http_request(@api_base, params.merge(account.attributes))
+        response = http_post_request(@api_base, params.merge(account.attributes))
       rescue => e
         handle_connection_errors(e)
       end
@@ -121,7 +126,7 @@ module AlphaCard
     # Raises an exception if a network error occurs. It
     # could be request timeout, socket error or anything else.
     #
-    # @param [Exception]
+    # @param [StandardError]
     #   Exception object.
     #
     # @raise [AlphaCard::AlphaCardError]
@@ -141,7 +146,7 @@ module AlphaCard
         message = 'Unexpected error communicating with Alpha Card Gateway.'
       end
 
-      fail APIConnectionError, "#{message}\n\n(Network error: #{error.message})"
+      raise APIConnectionError, "#{message}\n\n(Network error: #{error.message})"
     end
 
     ##
@@ -155,7 +160,7 @@ module AlphaCard
     #
     # @return [HTTPResponse]
     #   Response of the request as HTTPResponse object
-    def http_request(url, params)
+    def http_post_request(url, params)
       uri = URI.parse(url)
 
       http = Net::HTTP.new(uri.host, uri.port)

data/lib/alpha_card/alpha_card_object.rb

@@ -3,7 +3,51 @@ module AlphaCard
   # Parent class for each Alpha Card Gateway object, such as
   # Order, Billing, Sale and others.
   class AlphaCardObject
-    include Virtus.model
+    # Attributes DSL
+    include Virtus.model(nullify_blank: true)
+
+    ##
+    # Original AlphaCard transaction variables names
+    ORIGIN_TRANSACTION_VARIABLES = {}.freeze
+
+    ##
+    # Returns only filled attributes with the original Alpha Card Services
+    # transaction variables names.
+    #
+    # @param [Hash] attrs
+    #   Attributes that must be converted to AlphaCard request params/
+    #   Default value is <code>filled_attributes</code>.
+    #
+    # @example
+    #   order = AlphaCard::Order.new(id: '1', tax: nil, po_number: 'PO123')
+    #   order.send(:attributes_for_request)
+    #
+    #   #=> { orderid: '1', ponumber: 'PO123' }
+    def attributes_for_request(attrs = filled_attributes)
+      return attrs if self.class::ORIGIN_TRANSACTION_VARIABLES.empty?
+
+      attrs.each_with_object({}) do |(attr, value), request_attrs|
+        request_attrs[self.class::ORIGIN_TRANSACTION_VARIABLES.fetch(attr, attr)] = value
+      end
+    end
+
+    ##
+    # Deprecate old transaction variables names.
+    def self.deprecate_old_variables!
+      self::ORIGIN_TRANSACTION_VARIABLES.each do |new_attr, old_attr|
+        define_method "#{old_attr}=" do |value|
+          warn "[DEPRECATION] #{old_attr}= is deprecated! Please, use #{new_attr}= instead"
+          self[new_attr] = value
+        end
+
+        define_method old_attr do
+          warn "[DEPRECATION] #{old_attr} is deprecated! Please, use #{new_attr} instead"
+          self[new_attr]
+        end
+      end
+    end
+
+    protected
 
     ##
     # Returns the <code>Hash</code> with only filled attributes
@@ -13,12 +57,24 @@ module AlphaCard
     #   Filled attributes of the <code>AlphaCard::AlphaCardObject</code>.
     #
     # @example
-    #   order = AlphaCard::Order.new({orderid: '1', tax: nil, ponumber: 'PO123'})
+    #   order = AlphaCard::Order.new(id: '1', tax: nil, po_number: 'PO123')
     #   order.filled_attributes
     #
-    #   #=> {orderid: '1', ponumber: 'PO123'}
+    #   #=> { id: '1', po_number: 'PO123' }
     def filled_attributes
       attributes.select { |_, value| !value.nil? }
     end
+
+    ##
+    # Validate passed attributes for presence. Raises an exception
+    # if one of the attribute is not specified.
+    #
+    # @param [Array] attributes
+    #   array of attributes to check
+    def abort_if_attributes_blank!(*attributes)
+      attributes.each do |attr|
+        raise InvalidObjectError, "#{attr} must be present!" if self[attr].nil? || self[attr].empty?
+      end
+    end
   end
 end

data/lib/alpha_card/alpha_card_response.rb

@@ -15,6 +15,15 @@ module AlphaCard
     # Error response code
     ERROR    = '3'.freeze
 
+    # Messages for CVV response codes
+    CVV_RESPONSES = YAML.load_file(File.expand_path('../data/cvv_responses.yml', __FILE__)).freeze
+
+    # Messages for AVS response codes
+    AVS_RESPONSES = YAML.load_file(File.expand_path('../data/avs_responses.yml', __FILE__)).freeze
+
+    # AlphaCard response messages
+    RESPONSE_MESSAGES = YAML.load_file(File.expand_path('../data/response_messages.yml', __FILE__)).freeze
+
     ##
     # AlphaCardResponse constructor.
     #
@@ -32,14 +41,14 @@ module AlphaCard
     end
 
     ##
-    # The text of the Alpha Card Gateway response.
+    # Textual response of the Alpha Card Gateway.
     #
     # @return [String] text of the response
     #
     # @example
     #
-    #   r = AlphaCardResponse.new("response=1&responsetext=Test")
-    #   r.text
+    #   response = AlphaCardResponse.new("response=1&responsetext=Test")
+    #   response.text
     #
     #   #=> 'Test'
     def text
@@ -47,15 +56,29 @@ module AlphaCard
     end
 
     ##
-    # The ID of the transaction. Can be used to process
-    # refund operation.
+    # Response message by response code.
+    #
+    # @return [String] response message
+    #
+    # @example
+    #
+    #   response = AlphaCardResponse.new("response_code=>300")
+    #   response.message
+    #
+    #   #=> 'Transaction was rejected by gateway'
+    def message
+      RESPONSE_MESSAGES[code]
+    end
+
+    ##
+    # Payment gateway transaction ID.
     #
     # @return [String] transaction ID
     #
     # @example
     #
-    #   r = AlphaCardResponse.new("response=1&transactionid=123")
-    #   r.transaction_id
+    #   response = AlphaCardResponse.new("response=1&transactionid=123")
+    #   response.transaction_id
     #
     #   #=> '123'
     def transaction_id
@@ -63,20 +86,50 @@ module AlphaCard
     end
 
     ##
-    # The code of the Alpha Card Gateway response.
+    # The original order id passed in the transaction request.
+    #
+    # @return [String] Order ID
+    #
+    # @example
+    #
+    #   response = AlphaCardResponse.new("response=1&orderid=123")
+    #   response.order_id
+    #
+    #   #=> '123'
+    def order_id
+      @data['orderid']
+    end
+
+    ##
+    # Numeric mapping of processor responses.
     #
     # @return [String] code of the response
     #
     # @example
     #
-    #   r = AlphaCardResponse.new("response=1&response_code=100")
-    #   r.code
+    #   response = AlphaCardResponse.new("response=1&response_code=100")
+    #   response.code
     #
     #   #=> '100'
     def code
       @data['response_code']
     end
 
+    ##
+    # Transaction authorization code.
+    #
+    # @return [String] auth code
+    #
+    # @example
+    #
+    #   response = AlphaCardResponse.new("response=1&authcode=083319")
+    #   response.code
+    #
+    #   #=> '083319'
+    def auth_code
+      @data['authcode']
+    end
+
     ##
     # Indicate the state of the request to the
     # Alpha Card Gateway. Returns <i>true</i> if
@@ -86,8 +139,8 @@ module AlphaCard
     #
     # @example
     #
-    #   r = AlphaCardResponse.new("response=1")
-    #   r.success?
+    #   response = AlphaCardResponse.new("response=1")
+    #   response.success?
     #
     #   #=> true
     def success?
@@ -103,8 +156,8 @@ module AlphaCard
     #
     # @example
     #
-    #   r = AlphaCardResponse.new("response=2")
-    #   r.declined?
+    #   response = AlphaCardResponse.new("response=2")
+    #   response.declined?
     #
     #   #=> true
     def declined?
@@ -120,12 +173,42 @@ module AlphaCard
     #
     # @example
     #
-    #   r = AlphaCardResponse.new("response=3")
-    #   r.error?
+    #   response = AlphaCardResponse.new("response=3")
+    #   response.error?
     #
     #   #=> true
     def error?
       @data['response'] == ERROR
     end
+
+    ##
+    # CVV response message.
+    #
+    # @return [String] CVV response message
+    #
+    # @example
+    #
+    #   response = AlphaCardResponse.new("cvvresponse=M")
+    #   response.cvv_response
+    #
+    #   #=> 'CVV2/CVC2 match'
+    def cvv_response
+      CVV_RESPONSES[@data['cvvresponse']]
+    end
+
+    ##
+    # AVS response message.
+    #
+    # @return [String] AVS response message
+    #
+    # @example
+    #
+    #   response = AlphaCardResponse.new("avsresponse=A")
+    #   response.avs_response
+    #
+    #   #=> 'Address match only'
+    def avs_response
+      AVS_RESPONSES[@data['avsresponse']]
+    end
   end
 end

data/lib/alpha_card/data/avs_responses.yml

@@ -0,0 +1,20 @@
+"X": 'Exact match, 9-character numeric ZIP'
+"Y": 'Exact match, 5-character numeric ZIP'
+"D": 'Exact match, 5-character numeric ZIP'
+"M": 'Exact match, 5-character numeric ZIP'
+"A": 'Address match only'
+"B": 'Address match only'
+"W": '9-character numeric ZIP match only'
+"Z": '5-character ZIP match only'
+"P": '5-character ZIP match only'
+"L": '5-character ZIP match only'
+"N": 'No address or ZIP match only'
+"C": 'No address or ZIP match only'
+"U": 'Address unavailable'
+"G": 'Non-U.S. issuer does not participate'
+"I": 'Non-U.S. issuer does not participate'
+"R": 'Issuer system unavailable'
+"E": 'Not a mail/phone order'
+"S": 'Service not supported'
+"O": 'AVS not available'
+"B": 'AVS not available'

data/lib/alpha_card/data/credit_card_codes.yml

@@ -59,4 +59,4 @@
 "DB UNAVAIL 01": 'Problem at NDC routing transaction.'
 "SCAN UNAVAILABLE": 'SCAN application is down, try later.'
 "EXCEEDS MAX AMT": 'Exceeds withdrawal amount limit.'
-"EXCEEDS MAX USES": 'Exceeds withdrawal frequency limit'
+"EXCEEDS MAX USES": 'Exceeds withdrawal frequency limit'

data/lib/alpha_card/data/cvv_responses.yml

@@ -0,0 +1,5 @@
+"M": 'CVV2/CVC2 match'
+"N": 'CVV2/CVC2 no match'
+"P": 'Not processed'
+"S": 'Merchant has indicated that CVV2/CVC2 is not present on card'
+"U": 'Issuer is not certified and/or has not provided Visa encryption keys'

data/lib/alpha_card/data/response_messages.yml

@@ -0,0 +1,33 @@
+"100": 'Transaction was approved'
+"200": 'Transaction was declined by processor'
+"201": 'Do not honor'
+"202": 'Insufficient funds'
+"203": 'Over limit'
+"204": 'Transaction not allowed'
+"220": 'Incorrect payment information'
+"221": 'No such card issuer'
+"222": 'No card number on file with issuer'
+"223": 'Expired card'
+"224": 'Invalid expiration date'
+"225": 'Invalid card security code'
+"240": 'Call issuer for further information'
+"250": 'Pick up card'
+"251": 'Lost card'
+"252": 'Stolen card'
+"253": 'Fraudulent card'
+"260": 'Declined with further instructions available'
+"261": 'Declined-Stop all recurring payments'
+"262": 'Declined-Stop this recurring program'
+"263": 'Declined-Update cardholder data available'
+"264": 'Declined-Retry in a few days'
+"300": 'Transaction was rejected by gateway'
+"400": 'Transaction error returned by processor'
+"410": 'Invalid merchant configuration'
+"411": 'Merchant account is inactive'
+"420": 'Communication error'
+"421": 'Communication error with issuer'
+"430": 'Duplicate transaction at processor'
+"440": 'Processor format error'
+"441": 'Invalid transaction information'
+"460": 'Processor feature not available'
+"461": 'Unsupported card type'

data/lib/alpha_card/errors/alpha_card_error.rb

@@ -12,7 +12,7 @@ module AlphaCard
     ##
     # <code>AlphaCard::AlphaCardError</code> constructor.
     #
-    # @param [String] response
+    # @param [String] message
     #   Error message
     # @param [AlphaCard::AlphaCardResponse] response
     #   AlphaCard Gateway response

data/lib/alpha_card/errors/invalid_object_error.rb

@@ -0,0 +1,8 @@
+module AlphaCard
+  ##
+  # Exception class for invalid Alpha Card objects.
+  # Raises when some of the object doesn't have all
+  # the necessary attributes.
+  class InvalidObjectError < StandardError
+  end
+end