alpha_card 0.3.0 → 0.4.0

data/lib/alpha_card/data/credit_card_codes.yml

@@ -1,62 +1,62 @@
 "AP": 'Approved or completed successfully'
-"CALL AE": 'Refer to American Express.'
-"CALL CB": 'Refer to Carte Blanche.'
-"CALL DC": 'Refer to Diners Club.'
-"CALL DISCOVER": 'Refer to Discover.'
-"CALL JB": 'Refer to JBS.'
-"CALL ND": 'Call your Visa/MasterCard Voice Authorization Center.'
-"CALL TC": 'Refer to TeleCredit.'
-"CALL TK": 'Refer to TeleCheck.'
-"CALL WC": 'Refer to Worldcheck.'
-"CALL XXXXXXXXXX": 'Call indicated number.'
-"ISSUER UNAVAIL": 'NDC cannot contact issuing bank for authorization.'
-"INVLD MERCH ID": 'Invalid Merchant ID.'
-"PIC UP": 'Authorization declined.'
-"DECLINE": 'Authorization declined.'
-"REVERSED": 'Requested transaction reversal was successful.'
-"AP WITH ID": 'Approved with positive ID. NDC Host does not capture this transaction.'
+"CALL AE": 'Refer to American Express'
+"CALL CB": 'Refer to Carte Blanche'
+"CALL DC": 'Refer to Diners Club'
+"CALL DISCOVER": 'Refer to Discover'
+"CALL JB": 'Refer to JBS'
+"CALL ND": 'Call your Visa/MasterCard Voice Authorization Center'
+"CALL TC": 'Refer to TeleCredit'
+"CALL TK": 'Refer to TeleCheck'
+"CALL WC": 'Refer to Worldcheck'
+"CALL XXXXXXXXXX": 'Call indicated number'
+"ISSUER UNAVAIL": 'NDC cannot contact issuing bank for authorization'
+"INVLD MERCH ID": 'Invalid Merchant ID'
+"PIC UP": 'Authorization declined'
+"DECLINE": 'Authorization declined'
+"REVERSED": 'Requested transaction reversal was successful'
+"AP WITH ID": 'Approved with positive ID. NDC Host does not capture this transaction'
 "INVLD SERV ID": 'Service ID number is incorrect'
-"INVALID REQUEST": 'Administrative message contains a syntax error.'
-"INVLD TRAN CODE": 'Processing code entered is incorrect. Please refer to valid processing code.'
-"INVLD AMOUNT": 'Amount entered is not valid.'
+"INVALID REQUEST": 'Administrative message contains a syntax error'
+"INVLD TRAN CODE": 'Processing code entered is incorrect. Please refer to valid processing code'
+"INVLD AMOUNT": 'Amount entered is not valid'
 "INVLD ACCT": 'Account number does not pass issuer’s edit checks'
-"INVLD CODE ACCT": 'Valid account number matched with a transaction code for a different card type.'
-"PLEASE RETRY": 'NDC’s user tables are set up incorrectly for this account.'
-"INVLD EMP DATE": 'NDC GATEWAY requests a retry.'
-"PIN INVALID": 'Expired date entered is incorrect.'
-"UNAUTH TRANS": 'Incorrect PIN entered.'
-"MAX PIN RETRIES": 'A transaction code was used for which you are not setup on the Merchant Master File.'
-"AP DUPE": 'Maximum PIN number entry attempts exceeded.'
-"IN ACCT MATCH": 'Transaction entered is a duplicate.'
-"INV AMT MATCH": 'The account number entered during a void or adjustment transaction does not match the account number stored in the NDC Host for that item.'
-"INV ITEM NUM": 'The item number entered for a void or adjustment transaction is incorrect.'
-"ITEM VOIDED": 'An adjustment or item review was attempted on a transaction previously voided or reversed.'
-"ITEM REVERSED": 'An adjustment or item review was attempted on a transaction previously voided or reversed.'
-"MUST BALANCE NOW": 'Terminal has not been balanced within time specified in the NDC Merchant Master File for this merchant.'
-"USE DUP THEN BAL": 'Terminal has not been balanced within time specified in the NDC Merchant Master File for this merchant, but merchant is set up to perform extra transactions before balancing.'
-"NO DUP FOUND": 'Override transaction is at tempted on a non-duplicated transaction.'
-"INVALID DATA": 'Format of the transaction is incorrect.'
-"NO TRANS FOUND": 'Reversal transaction is attempted on a transaction that is not in the open batch on the host.'
+"INVLD CODE ACCT": 'Valid account number matched with a transaction code for a different card type'
+"PLEASE RETRY": 'NDC’s user tables are set up incorrectly for this account'
+"INVLD EMP DATE": 'NDC GATEWAY requests a retry'
+"PIN INVALID": 'Expired date entered is incorrect'
+"UNAUTH TRANS": 'Incorrect PIN entered'
+"MAX PIN RETRIES": 'A transaction code was used for which you are not setup on the Merchant Master File'
+"AP DUPE": 'Maximum PIN number entry attempts exceeded'
+"IN ACCT MATCH": 'Transaction entered is a duplicate'
+"INV AMT MATCH": 'The account number entered during a void or adjustment transaction does not match the account number stored in the NDC Host for that item'
+"INV ITEM NUM": 'The item number entered for a void or adjustment transaction is incorrect'
+"ITEM VOIDED": 'An adjustment or item review was attempted on a transaction previously voided or reversed'
+"ITEM REVERSED": 'An adjustment or item review was attempted on a transaction previously voided or reversed'
+"MUST BALANCE NOW": 'Terminal has not been balanced within time specified in the NDC Merchant Master File for this merchant'
+"USE DUP THEN BAL": 'Terminal has not been balanced within time specified in the NDC Merchant Master File for this merchant, but merchant is set up to perform extra transactions before balancing'
+"NO DUP FOUND": 'Override transaction is at tempted on a non-duplicated transaction'
+"INVALID DATA": 'Format of the transaction is incorrect'
+"NO TRANS FOUND": 'Reversal transaction is attempted on a transaction that is not in the open batch on the host'
 "AP NOT CAPTURED": 'Approved but not captured (applied to only credit card transactions).'
-"AP AUTH-ONLY": 'Approved but this EDC merchant is not set up to capture this card type (applies only to credit card transactions).'
-"INV BANK": 'Acquiring Bank ID entered is incorrect.'
-"TRAN TYPE INVLD": 'Transaction not supported by EFT network or EFT Group ID is incorrect.'
-"APPROVED": 'Merchant is not set up for debit on NDC Merchant Master File.'
+"AP AUTH-ONLY": 'Approved but this EDC merchant is not set up to capture this card type (applies only to credit card transactions)'
+"INV BANK": 'Acquiring Bank ID entered is incorrect'
+"TRAN TYPE INVLD": 'Transaction not supported by EFT network or EFT Group ID is incorrect'
+"APPROVED": 'Merchant is not set up for debit on NDC Merchant Master File'
 "DB UNAVAIL 02": 'NDC GATEWAY is down'
-"DB UNAVAIL 03": 'NDC GATEWAY Link ID timed out.'
-"DB UNAVAIL 04": 'NDC GATEWAY cannot contact EFT network or EFT Group ID is incorrect.'
-"UNAUTH USER": 'Merchant is not set up for debit on NDC Merchant Master File.'
-"INVALID CARD": 'Debit card not on issuer file.'
+"DB UNAVAIL 03": 'NDC GATEWAY Link ID timed out'
+"DB UNAVAIL 04": 'NDC GATEWAY cannot contact EFT network or EFT Group ID is incorrect'
+"UNAUTH USER": 'Merchant is not set up for debit on NDC Merchant Master File'
+"INVALID CARD": 'Debit card not on issuer file'
 "DB ISSUER UNAVAIL": 'EFT network cannot contact issuer'
-"INVALID POS CARD": 'Card is not eligible for POS.'
+"INVALID POS CARD": 'Card is not eligible for POS'
 "ACCT TYPE INVLD": 'Type of account entered cannot be accessed (checking, savings, etc.)'
-"INVALID PREFIX": 'No sharing arrangement for this card.'
-"INVALID FIID NDC GATEWAY": 'Financial Institution ID not set up.'
-"VERIFY XXXXXXXXXX": 'Match on SCAN file. XXXXXXXXXX is routing/transit number on the negative file.'
-"INVALID LIC": 'The license or ID number entered during a check authorization transaction is incorrect.'
-"INVALID STATE CD": 'State code entered is incorrect.'
-"EDC UNAVAILABLE": 'EDC application down, try later.'
-"DB UNAVAIL 01": 'Problem at NDC routing transaction.'
-"SCAN UNAVAILABLE": 'SCAN application is down, try later.'
-"EXCEEDS MAX AMT": 'Exceeds withdrawal amount limit.'
+"INVALID PREFIX": 'No sharing arrangement for this card'
+"INVALID FIID NDC GATEWAY": 'Financial Institution ID not set up'
+"VERIFY XXXXXXXXXX": 'Match on SCAN file. XXXXXXXXXX is routing/transit number on the negative file'
+"INVALID LIC": 'The license or ID number entered during a check authorization transaction is incorrect'
+"INVALID STATE CD": 'State code entered is incorrect'
+"EDC UNAVAILABLE": 'EDC application down, try later'
+"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'

data/lib/alpha_card/errors/invalid_attribute_format.rb

@@ -0,0 +1,14 @@
+module AlphaCard
+  ##
+  # AlphaCard resource attributes format error
+  class InvalidAttributeFormat < StandardError
+    # Exception constructor. Returns an error with message about wrong
+    # attribute format.
+    #
+    # @param value [Object] current attribute value
+    # @param format [Regexp] required format
+    def initialize(value, format)
+      super("'#{value}' does not match the '#{format.inspect}' format")
+    end
+  end
+end

data/lib/alpha_card/errors/invalid_attribute_type.rb

@@ -0,0 +1,14 @@
+module AlphaCard
+  ##
+  # AlphaCard resource attributes value error
+  class InvalidAttributeType < StandardError
+    # Exception constructor. Returns an error with message about
+    # wrong attribute value type.
+    #
+    # @param value [Object] current attribute value
+    # @param types [Array] possible attribute types
+    def initialize(value, types)
+      super("'#{value}' must be an instance of #{types.join(', ')}")
+    end
+  end
+end

data/lib/alpha_card/errors/invalid_attribute_value.rb

@@ -0,0 +1,14 @@
+module AlphaCard
+  ##
+  # AlphaCard resource attributes value error
+  class InvalidAttributeValue < StandardError
+    # Exception constructor. Returns an error with message about wrong value
+    # and possible values.
+    #
+    # @param value [Object] current attribute value
+    # @param values [Array] possible attribute values
+    def initialize(value, values)
+      super("'#{value}' is invalid attribute value. Use one from the following: #{values.join(', ')}")
+    end
+  end
+end

data/lib/alpha_card/errors/{invalid_object_error.rb → validation_error.rb}

@@ -3,6 +3,6 @@ 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
+  class ValidationError < StandardError
   end
 end

data/lib/alpha_card/{alpha_card_object.rb → resource.rb}

@@ -1,10 +1,9 @@
 module AlphaCard
   ##
-  # Parent class for each Alpha Card Gateway object, such as
-  # Order, Billing, Sale and others.
-  class AlphaCardObject
+  # Alpha Card resource base class.
+  class Resource
     # Attributes DSL
-    include Virtus.model(nullify_blank: true)
+    include AlphaCard::Attribute
 
     ##
     # Original AlphaCard transaction variables names
@@ -14,15 +13,16 @@ module AlphaCard
     # Returns only filled attributes with the original Alpha Card Services
     # transaction variables names.
     #
-    # @param [Hash] attrs
+    # @param attrs [Hash]
     #   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)
+    #   order.attributes_for_request
     #
     #   #=> { orderid: '1', ponumber: 'PO123' }
+    #
     def attributes_for_request(attrs = filled_attributes)
       return attrs if self.class::ORIGIN_TRANSACTION_VARIABLES.empty?
 
@@ -31,22 +31,6 @@ module AlphaCard
       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
 
     ##
@@ -66,14 +50,16 @@ module AlphaCard
     end
 
     ##
-    # Validate passed attributes for presence. Raises an exception
+    # Validate required attributes to be filled. 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?
+    # @raise [AlphaCard::InvalidObjectError] error if required attributes not set
+    #
+    def validate_required_attributes!
+      unless required_attributes?
+        blank_attribute = required_attributes.detect { |attr| self[attr].nil? || self[attr].empty? }
+
+        raise ValidationError, "#{blank_attribute} can't be blank"
       end
     end
   end

data/lib/alpha_card/resources/billing.rb

@@ -0,0 +1,29 @@
+module AlphaCard
+  ##
+  # Implementation of Alpha Card Services order billing information.
+  # Contains all the billing information (customer name, email, email, etc).
+  class Billing < Resource
+    attribute :first_name, type: String
+    attribute :last_name, type: String
+    attribute :email, type: String
+    attribute :phone, type: String
+    attribute :company, type: String
+    attribute :address_1, type: String
+    attribute :address_2, type: String
+    attribute :city, type: String
+    attribute :state, type: String, format: /\A[A-Za-z]{2}\z/.freeze
+    attribute :zip, type: String
+    attribute :country, type: String, format: /\A[A-Za-z]{2}\z/.freeze
+    attribute :fax, type: String
+    attribute :website, type: String
+
+    ##
+    # Original AlphaCard transaction variables names
+    ORIGIN_TRANSACTION_VARIABLES = {
+      first_name: :firstname,
+      last_name: :lastname,
+      address_1: :address1,
+      address_2: :address2
+    }.freeze
+  end
+end

data/lib/alpha_card/{objects → resources}/order.rb

@@ -2,16 +2,16 @@ module AlphaCard
   ##
   # Implementation of Alpha Card Services Order object.
   # Contains all the information about order (id, description, etc).
-  class Order < AlphaCardObject
-    attribute :id, String
-    attribute :description, String
-    attribute :po_number, String
-    attribute :tax, String
+  class Order < Resource
+    attribute :id
+    attribute :description, type: String
+    attribute :po_number, type: String
+    attribute :tax, type: String
     # Format: xxx.xxx.xxx.xxx
-    attribute :ip_address, String
+    attribute :ip_address, format: /\A(?:[0-9]{1,3}\.){3}[0-9]{1,3}\z/.freeze
 
-    attribute :billing, AlphaCard::Billing
-    attribute :shipping, AlphaCard::Shipping
+    attribute :billing, type: AlphaCard::Billing
+    attribute :shipping, type: AlphaCard::Shipping
 
     ##
     # Original AlphaCard transaction variables names

data/lib/alpha_card/{objects → resources}/shipping.rb

@@ -2,17 +2,19 @@ module AlphaCard
   ##
   # Implementation of Alpha Card Services order shipping information.
   # Contains all the shipping information (address, city, zip, etc).
-  class Shipping < AlphaCardObject
-    attribute :first_name, String
-    attribute :last_name, String
-    attribute :company, String
-    attribute :address_1, String
-    attribute :address_2, String
-    attribute :city, String
-    attribute :state, String
-    attribute :zip_code, String
-    attribute :country, String
-    attribute :email, String
+  class Shipping < Resource
+    attribute :first_name, type: String
+    attribute :last_name, type: String
+    attribute :company, type: String
+    attribute :address_1, type: String
+    attribute :address_2, type: String
+    attribute :city, type: String
+    # Format: 'CC'
+    attribute :state, type: String, format: /\A[A-Za-z]{2}\z/.freeze
+    attribute :zip_code, type: String
+    # Format: 'CC'
+    attribute :country, type: String, format: /\A[A-Za-z]{2}\z/.freeze
+    attribute :email, type: String
 
     ##
     # Original AlphaCard transaction variables names
@@ -23,7 +25,7 @@ module AlphaCard
       address_2: :address2
     }.freeze
 
-    deprecate_old_variables!
+    protected
 
     ##
     # Overloaded <code>filled_attributes</code> method from
@@ -35,7 +37,7 @@ module AlphaCard
     #   Only filled attributes of Shipping resource with "shipping_" prefix.
     #
     # @example
-    #   shipping = AlphaCard::Shipping.new(firstname: 'John', state: 'NY')
+    #   shipping = AlphaCard::Shipping.new(first_name: 'John', state: 'NY')
     #   shipping.filled_attributes
     #
     #   #=> { shipping_firstname: 'John', shipping_state: 'NY' }

data/lib/alpha_card/{alpha_card_response.rb → response.rb}

@@ -3,7 +3,7 @@ module AlphaCard
   # Implementation of Alpha Card Services response.
   # Contains all the data, that Alpha Card Gateway
   # returned for the request.
-  class AlphaCardResponse
+  class Response
     # Alpha Card Gateway response as a <code>Hash</code>.
     # @attr_reader [Hash] data
     attr_reader :data
@@ -25,17 +25,17 @@ module AlphaCard
     RESPONSE_MESSAGES = YAML.load_file(File.expand_path('../data/response_messages.yml', __FILE__)).freeze
 
     ##
-    # AlphaCardResponse constructor.
+    # Alpha Card Response constructor.
     #
-    # @param [String] response_body
+    # @param response_body [String]
     #   Alpha Card Gateway response body text
     #
-    # @return [AlphaCardResponse] AlphaCardResponse object
+    # @return [Response] Alpha Card Response object
     #
     # @example
-    #   AlphaCard::AlphaCardResponse.new('response=1&responsetext=Test')
+    #   AlphaCard::Response.new('response=1&responsetext=Test')
     #
-    #   #=> #<AlphaCard::AlphaCardResponse:0x00000003f2b568 @data={"response"=>"1", "responsetext"=>"Test"}>
+    #   #=> #<AlphaCard::Response:0x00000003f2b568 @data={"response"=>"1", "responsetext"=>"Test"}>
     def initialize(response_body)
       @data = Rack::Utils.parse_query(response_body)
     end
@@ -130,6 +130,21 @@ module AlphaCard
       @data['authcode']
     end
 
+    # Credit Card Authorization Message based on returned code in accordance with
+    # the Global Payment Systems Credit Card Authorization Codes (codes.yml).
+    #
+    # @return [String] auth message
+    #
+    # @example
+    #
+    #   response = AlphaCardResponse.new("response_text=AP")
+    #   response.credit_card_auth_message
+    #
+    #   #=> 'Approved or completed successfully'
+    def credit_card_auth_message
+      AlphaCard::CREDIT_CARD_CODES[text]
+    end
+
     ##
     # Indicate the state of the request to the
     # Alpha Card Gateway. Returns <i>true</i> if

data/lib/alpha_card/transaction.rb

@@ -0,0 +1,30 @@
+module AlphaCard
+  ##
+  # Base Alpha Card transaction object.
+  class Transaction < Resource
+    ##
+    # Creates transaction.
+    #
+    # @param credentials [Hash]
+    #   Alpha Card merchant account credentials.
+    #
+    # @return [AlphaCard::Response]
+    #   AlphaCard Gateway response with all the information about transaction.
+    #
+    # @raise [AlphaCard::InvalidObjectError]
+    #   Exception if one of required attributes doesn't specified.
+    #
+    # @example
+    #   void = AlphaCard::Void.new(transaction_id: '981562')
+    #   void.create
+    #
+    #   #=> #<AlphaCard::Response:0x1a0fda ...>
+    def process(credentials = Account.credentials)
+      validate_required_attributes!
+
+      AlphaCard.request(attributes_for_request, credentials)
+    end
+
+    alias_method :create, :process
+  end
+end

data/lib/alpha_card/transactions/auth.rb

@@ -0,0 +1,18 @@
+module AlphaCard
+  ##
+  # Implementation of Alpha Card Services Authorization transaction.
+  #
+  # @example
+  #   auth = AlphaCard::Auth.new(card_expiration_date: '0117', card_number: '4111111111111111', amount: '1.00')
+  #   auth.create(order)
+  #
+  #   #=> #<AlphaCard::Response:0x1a0fda ...>
+  #
+  class Auth < Sale
+    ##
+    # Transaction type (default is 'auth')
+    #
+    # @attribute [r] type
+    attribute :type, default: 'auth', writable: false
+  end
+end