lightrail_client 1.0.0

data/lib/lightrail_client/card.rb

@@ -0,0 +1,40 @@
+module Lightrail
+  class Card < Lightrail::LightrailObject
+
+    def self.create(create_params)
+      params_for_create = Lightrail::Validator.set_params_for_card_create!(create_params)
+      response = Lightrail::Connection.send :make_post_request_and_parse_response, "cards", params_for_create
+      response['card']
+    end
+
+    def self.charge(charge_params)
+      Lightrail::Transaction.charge_card(charge_params, false)
+    end
+
+    def self.simulate_charge(charge_params)
+      params_for_simulation = Lightrail::Validator.set_nsf_for_simulate!(charge_params)
+      Lightrail::Transaction.charge_card(params_for_simulation, true)
+    end
+
+    def self.fund(fund_params)
+      Lightrail::Transaction.fund_card(fund_params)
+    end
+
+    def self.get_maximum_value(card_id)
+      card_details = self.get_details(card_id)
+      maximum_value = 0
+      card_details['valueStores'].each do |valueStore|
+        if valueStore['state'] == 'ACTIVE'
+          maximum_value += valueStore['value']
+        end
+      end
+      maximum_value
+    end
+
+    def self.get_details(card_id)
+      response = Lightrail::Connection.make_get_request_and_parse_response("cards/#{CGI::escape(card_id)}/details")
+      response['details']
+    end
+
+  end
+end

data/lib/lightrail_client/code.rb

@@ -0,0 +1,30 @@
+module Lightrail
+  class Code
+
+    def self.charge(charge_params)
+      Lightrail::Transaction.charge_code(charge_params, false)
+    end
+
+    def self.simulate_charge(charge_params)
+      params_for_simulation = Lightrail::Validator.set_nsf_for_simulate!(charge_params)
+      Lightrail::Transaction.charge_code(params_for_simulation, true)
+    end
+
+    def self.get_maximum_value(code)
+      code_details = self.get_details(code)
+      maximum_value = 0
+      code_details['valueStores'].each do |valueStore|
+        if valueStore['state'] == 'ACTIVE'
+          maximum_value += valueStore['value']
+        end
+      end
+      maximum_value
+    end
+
+    def self.get_details(code)
+      response = Lightrail::Connection.make_get_request_and_parse_response("codes/#{CGI::escape(code)}/details")
+      response['details']
+    end
+
+  end
+end

data/lib/lightrail_client/connection.rb

@@ -0,0 +1,50 @@
+module Lightrail
+  class Connection
+    def self.connection
+      conn = Faraday.new Lightrail.api_base, ssl: {version: :TLSv1_2}
+      conn.headers['Content-Type'] = 'application/json; charset=utf-8'
+      conn.headers['Authorization'] = "Bearer #{Lightrail.api_key}"
+      conn
+    end
+
+    def self.ping
+      self.make_get_request_and_parse_response('ping')
+    end
+
+    def self.make_post_request_and_parse_response (url, body)
+      resp = Lightrail::Connection.connection.post do |req|
+        req.url url
+        req.body = JSON.generate(body)
+      end
+      self.handle_response(resp)
+    end
+
+    def self.make_get_request_and_parse_response (url)
+      resp = Lightrail::Connection.connection.get {|req| req.url url}
+      self.handle_response(resp)
+    end
+
+    def self.handle_response(response)
+      body = JSON.parse(response.body) || {}
+      message = body['message'] || ''
+      case response.status
+        when 200...300
+          JSON.parse(response.body)
+        when 400
+          if (message =~ /insufficient value/i)
+            raise Lightrail::InsufficientValueError.new(message, response)
+          else
+            raise Lightrail::BadParameterError.new(message, response)
+          end
+        when 401, 403
+          raise Lightrail::AuthorizationError.new(message, response)
+        when 404
+          raise Lightrail::CouldNotFindObjectError.new(message, response)
+        when 409
+          raise Lightrail::BadParameterError.new(message, response)
+        else
+          raise LightrailError.new("Server responded with: (#{response.status}) #{message}", response)
+      end
+    end
+  end
+end

data/lib/lightrail_client/constants.rb

@@ -0,0 +1,23 @@
+module Lightrail
+  class Constants
+
+    code_keys_sym = [:code, :lightrail_code]
+    card_id_keys_sym = [:cardId, :card_id, :lightrail_card_id]
+    contact_id_keys_sym = [:contactId, :contact_id, :lightrail_contact_id]
+    shopper_id_keys_sym = [:shopperId, :shopper_id, :lightrail_shopper_id]
+    user_supplied_id_keys_sym = [:userSuppliedId, :user_supplied_id, :lightrail_user_supplied_id, :idempotency_key]
+    transaction_id_keys_sym = [:transactionId, :transaction_id, :lightrail_transaction_id]
+
+    LIGHTRAIL_CODE_KEYS = code_keys_sym + code_keys_sym.map {|code_key| code_key.to_s}
+    LIGHTRAIL_CARD_ID_KEYS = card_id_keys_sym + card_id_keys_sym.map {|card_id_key| card_id_key.to_s}
+    LIGHTRAIL_CONTACT_ID_KEYS = contact_id_keys_sym + contact_id_keys_sym.map {|contact_id_key| contact_id_key.to_s}
+    LIGHTRAIL_SHOPPER_ID_KEYS = shopper_id_keys_sym + shopper_id_keys_sym.map {|shopper_id_key| shopper_id_key.to_s}
+    LIGHTRAIL_USER_SUPPLIED_ID_KEYS = user_supplied_id_keys_sym + user_supplied_id_keys_sym.map {|user_supplied_id_key| user_supplied_id_key.to_s}
+    LIGHTRAIL_TRANSACTION_ID_KEYS = transaction_id_keys_sym + transaction_id_keys_sym.map {|transaction_id_key| transaction_id_key.to_s}
+
+    LIGHTRAIL_PAYMENT_METHODS = self::LIGHTRAIL_CODE_KEYS + self::LIGHTRAIL_CARD_ID_KEYS + self::LIGHTRAIL_CONTACT_ID_KEYS + self::LIGHTRAIL_SHOPPER_ID_KEYS
+
+    LIGHTRAIL_TRANSACTION_TYPES = [:code_drawdown, :card_id_drawdown, :code_pending, :card_id_pending, :fund_card, :refund, :capture, :void]
+
+  end
+end

data/lib/lightrail_client/contact.rb

@@ -0,0 +1,93 @@
+module Lightrail
+  class Contact < Lightrail::LightrailObject
+
+    def self.create(create_params)
+      params_with_user_supplied_id = self.set_user_supplied_id_for_contact_create(create_params)
+      params_with_name_if_present = self.set_name_if_present(params_with_user_supplied_id)
+      response = Lightrail::Connection.send :make_post_request_and_parse_response, "contacts", params_with_name_if_present
+      response['contact']
+    end
+
+    def self.retrieve_by_shopper_id(shopper_id)
+      response = Lightrail::Connection.send :make_get_request_and_parse_response, "contacts?userSuppliedId=#{CGI::escape(shopper_id)}"
+      response['contacts'][0]
+    end
+
+    def self.retrieve_by_contact_id(contact_id)
+      response = Lightrail::Connection.send :make_get_request_and_parse_response, "contacts/#{CGI::escape(contact_id)}"
+      response['contact']
+    end
+
+    # Utility methods
+
+    def self.retrieve_or_create_by_shopper_id(shopper_id)
+      contact = self.retrieve_by_shopper_id(shopper_id)
+      if !contact
+        contact = self.create({shopper_id: shopper_id})
+      end
+      contact
+    end
+
+    def self.get_contact_id_from_id_or_shopper_id(charge_params)
+      if Lightrail::Validator.has_valid_contact_id?(charge_params)
+        return Lightrail::Validator.get_contact_id(charge_params)
+      end
+
+      if Lightrail::Validator.has_valid_shopper_id?(charge_params)
+        shopper_id = Lightrail::Validator.get_shopper_id(charge_params)
+        contact = self.get_by_shopper_id(shopper_id)
+        if (!contact.nil? && !contact.empty? && contact['contactId'])
+          return contact['contactId']
+        else
+          return nil
+        end
+      end
+
+      return nil
+    end
+
+    private
+
+    def self.get_contact_id_from_shopper_id(shopper_id)
+      contact = self.retrieve_by_shopper_id(shopper_id)
+      contact['contactId']
+    end
+
+    def self.set_user_supplied_id_for_contact_create(create_params)
+      params_with_user_supplied_id = create_params.clone
+      shopper_id = Lightrail::Validator.get_shopper_id(create_params) || nil
+      user_supplied_id = Lightrail::Validator.get_user_supplied_id(create_params) || nil
+
+      if !(shopper_id || user_supplied_id)
+        raise Lightrail::LightrailArgumentError.new("Must provide one of shopper_id or user_supplied_id to create new Contact")
+      elsif (shopper_id && user_supplied_id)
+        raise Lightrail::LightrailArgumentError.new("Must provide only one of shopper_id or user_supplied_id to create new Contact")
+      end
+
+      if shopper_id
+        params_with_user_supplied_id[:userSuppliedId] ||= shopper_id
+      elsif user_supplied_id
+        params_with_user_supplied_id[:userSuppliedId] ||= user_supplied_id
+      end
+
+      params_with_user_supplied_id
+    end
+
+    def self.set_name_if_present(create_params)
+      params_with_name = create_params.clone
+      params_with_name[:firstName] ||= params_with_name[:first_name]
+      params_with_name[:lastName] ||= params_with_name[:last_name]
+      params_with_name
+    end
+
+    def self.get_by_id(contact_id)
+      response = Lightrail::Connection.make_get_request_and_parse_response("contacts/#{CGI::escape(contact_id)}")
+      response['contact']
+    end
+
+    def self.get_by_shopper_id(shopper_id)
+      response = Lightrail::Connection.make_get_request_and_parse_response("contacts?userSuppliedId=#{CGI::escape(shopper_id)}")
+      response['contacts'][0]
+    end
+  end
+end

data/lib/lightrail_client/errors.rb

@@ -0,0 +1,34 @@
+module Lightrail
+  class LightrailError < StandardError
+    attr_reader :message
+    attr_accessor :response
+
+    def initialize (message='', response)
+      @message = message
+      @response = response
+    end
+  end
+
+  class AuthorizationError < LightrailError
+  end
+
+  class InsufficientValueError < LightrailError
+  end
+
+  class BadParameterError < LightrailError
+  end
+
+  class CouldNotFindObjectError < LightrailError
+  end
+
+  class IdempotencyError < LightrailError
+  end
+
+  class ThirdPartyPaymentError < LightrailError
+  end
+
+
+  class LightrailArgumentError < ArgumentError
+  end
+
+end

data/lib/lightrail_client/lightrail_object.rb

@@ -0,0 +1,10 @@
+module Lightrail
+  class LightrailObject
+
+    def initialize(hash)
+      values = Marshal.load(Marshal.dump(hash))
+      values.each {|key, value| instance_variable_set("@#{key}", value)}
+    end
+
+  end
+end

data/lib/lightrail_client/ping.rb

@@ -0,0 +1,11 @@
+module Lightrail
+  class Ping < Lightrail::LightrailObject
+    attr_accessor :username, :mode, :scopes, :roles, :effectiveScopes
+
+    def self.ping
+      response = Lightrail::Connection.ping
+      Lightrail::Validator.validate_ping_response!(response)
+      self.new(response['user'])
+    end
+  end
+end

data/lib/lightrail_client/shopper_token_factory.rb

@@ -0,0 +1,41 @@
+module Lightrail
+  class ShopperTokenFactory
+    def self.generate (contact, validity_in_seconds=nil)
+      raise Lightrail::BadParameterError.new("Lightrail::api_key is not set") unless Lightrail::api_key
+      raise Lightrail::BadParameterError.new("Lightrail::shared_secret is not set") unless Lightrail::shared_secret
+
+      raise Lightrail::BadParameterError.new("Must provide a contact with one of shopper_id, contact_id or user_supplied_id to generate a shopper token") unless (Lightrail::Validator.has_valid_or_empty_shopper_id?(contact) ||
+          Lightrail::Validator.has_valid_contact_id?(contact) ||
+          Lightrail::Validator.has_valid_user_supplied_id?(contact))
+
+      g = {}
+      if (Lightrail::Validator.has_valid_or_empty_shopper_id?(contact))
+        g['shi'] = Lightrail::Validator.get_shopper_id(contact)
+      elsif (Lightrail::Validator.has_valid_contact_id?(contact))
+        g['coi'] = Lightrail::Validator.get_contact_id(contact)
+      elsif (Lightrail::Validator.has_valid_user_supplied_id?(contact))
+        g['cui'] = Lightrail::Validator.get_user_supplied_id(contact)
+      end
+
+
+      payload = Lightrail::api_key.split('.')
+      payload = JSON.parse(Base64.decode64(payload[1]))
+
+      g['gui'] = payload['g']['gui']
+      g['gmi'] = payload['g']['gmi']
+
+      iat = Time.now.to_i
+      payload = {
+          g: g,
+          iat: iat,
+          iss: "MERCHANT"
+      }
+
+      if validity_in_seconds
+        payload['exp'] = iat + validity_in_seconds
+      end
+
+      JWT.encode(payload, Lightrail::shared_secret, 'HS256')
+    end
+  end
+end

data/lib/lightrail_client/transaction.rb

@@ -0,0 +1,77 @@
+module Lightrail
+  class Transaction < Lightrail::LightrailObject
+    attr_accessor :transactionId, :value, :userSuppliedId, :dateCreated, :transactionType, :transactionAccessMethod, :giftbitUserId, :cardId, :currency, :codeLastFour, :metadata, :parentTransactionId
+
+    def self.charge_code(transaction_params, simulate)
+      transaction_type = transaction_params[:pending] ? :code_pending : :code_drawdown
+      self.create(transaction_params, transaction_type, simulate)
+    end
+
+    def self.charge_card(transaction_params, simulate)
+      transaction_type = transaction_params[:pending] ? :card_id_pending : :card_id_drawdown
+      self.create(transaction_params, transaction_type, simulate)
+    end
+
+    def self.fund_card(transaction_params)
+      self.create(transaction_params, :card_id_fund, false)
+    end
+
+
+    def self.refund (original_transaction_info, new_request_body={})
+      handle_transaction(original_transaction_info, 'refund', new_request_body)
+    end
+
+    def self.void (original_transaction_info, new_request_body={})
+      handle_transaction(original_transaction_info, 'void', new_request_body)
+    end
+
+    def self.capture (original_transaction_info, new_request_body={})
+      handle_transaction(original_transaction_info, 'capture', new_request_body)
+    end
+
+    private
+
+    # def self.simulate(transaction_params, transaction_type)
+    #   transaction_params_for_lightrail = Lightrail::Validator.send("set_params_for_#{transaction_type}!", transaction_params)
+    #   response = self.post_transaction(transaction_params_for_lightrail, true)
+    # end
+
+    def self.create(transaction_params, transaction_type, simulate)
+      transaction_params_for_lightrail = Lightrail::Validator.send("set_params_for_#{transaction_type}!", transaction_params)
+      response = self.post_transaction(transaction_params_for_lightrail, simulate)
+    end
+
+    def self.handle_transaction (original_transaction_info, action, new_request_body={})
+      transaction_params_for_lightrail = Lightrail::Validator.set_params_for_acting_on_existing_transaction!(original_transaction_info, new_request_body)
+      response = self.act_on_transaction(transaction_params_for_lightrail, action)
+    end
+
+    def self.post_transaction(transaction_params, simulate)
+      dry_run = simulate ? '/dryRun' : ''
+      response = {}
+      if (transaction_params[:code])
+        code = transaction_params.delete(:code)
+        response = Lightrail::Connection.send :make_post_request_and_parse_response, "codes/#{CGI::escape(code)}/transactions#{dry_run}", transaction_params
+      elsif (transaction_params[:cardId])
+        card_id = transaction_params.delete(:cardId)
+        response = Lightrail::Connection.send :make_post_request_and_parse_response, "cards/#{CGI::escape(card_id)}/transactions#{dry_run}", transaction_params
+      else
+        raise Lightrail::LightrailArgumentError.new("Lightrail code or cardId required to post a transaction: #{transaction_params.inspect}")
+      end
+      response['transaction']
+    end
+
+    def self.act_on_transaction(transaction_params, action)
+      response = {}
+      if (transaction_params[:cardId])
+        card_id = transaction_params.delete(:cardId)
+        transaction_id = transaction_params.delete(:transactionId)
+        response = Lightrail::Connection.send :make_post_request_and_parse_response, "cards/#{CGI::escape(card_id)}/transactions/#{CGI::escape(transaction_id)}/#{action}", transaction_params
+      else
+        raise Lightrail::LightrailArgumentError.new("Lightrail cardId required to act on an existing transaction: #{transaction_params.inspect}")
+      end
+      response['transaction']
+    end
+
+  end
+end

data/lib/lightrail_client/validator.rb

@@ -0,0 +1,317 @@
+module Lightrail
+  class Validator
+    def self.set_params_for_code_drawdown!(charge_params)
+      validated_params = charge_params.clone
+      begin
+        return validated_params if ((validated_params.is_a? Hash) &&
+            self.set_code!(validated_params, validated_params) &&
+            self.validate_amount!(validated_params[:amount] || validated_params[:value]) &&
+            self.validate_currency!(validated_params[:currency]) &&
+            self.get_or_set_userSuppliedId!(validated_params))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid charge_params for set_params_for_code_drawdown!: #{charge_params.inspect}")
+    end
+
+    def self.set_params_for_code_pending!(charge_params)
+      begin
+        validated_params = self.set_params_for_code_drawdown!(charge_params)
+        validated_params[:pending] = true
+        return validated_params
+      rescue Lightrail::LightrailError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid charge_params for set_params_for_code_pending!: #{charge_params.inspect}")
+    end
+
+    def self.set_params_for_card_id_drawdown!(charge_params)
+      validated_params = charge_params.clone
+      begin
+        return validated_params if ((validated_params.is_a? Hash) &&
+            (self.set_cardId!(validated_params, validated_params) ||
+                Lightrail::Account.replace_contact_id_or_shopper_id_with_card_id(validated_params)) &&
+            self.validate_amount!(validated_params[:amount] || validated_params[:value]) &&
+            self.validate_currency!(validated_params[:currency]) &&
+            self.get_or_set_userSuppliedId!(validated_params))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid charge_params for set_params_for_card_id_drawdown!: #{charge_params.inspect}")
+    end
+
+    def self.set_params_for_card_id_fund!(fund_params)
+      validated_params = fund_params.clone
+      begin
+        return validated_params if ((validated_params.is_a? Hash) &&
+            (self.set_cardId!(validated_params, validated_params) ||
+                Lightrail::Account.replace_contact_id_or_shopper_id_with_card_id(validated_params)) &&
+            self.validate_amount!(validated_params[:amount] || validated_params[:value]) &&
+            self.validate_currency!(validated_params[:currency]) &&
+            self.get_or_set_userSuppliedId!(validated_params))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid fund_params for set_params_for_card_id_fund!: #{fund_params.inspect}")
+    end
+
+    def self.set_params_for_card_create!(create_params)
+      validated_params = create_params.clone
+      begin
+        return validated_params if ((validated_params.is_a? Hash) &&
+            self.validate_currency!(validated_params[:currency]) &&
+            self.has_valid_user_supplied_id?(validated_params) &&
+            validated_params[:userSuppliedId] ||= self.get_user_supplied_id(create_params))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid create_params for set_params_for_card_create!!: #{create_params.inspect}")
+    end
+
+    def self.set_params_for_account_create!(create_account_params)
+      validated_params = create_account_params.clone
+
+      begin
+        return validated_params if ((validated_params.is_a? Hash) &&
+            self.set_userSuppliedId_from_existing!(validated_params, validated_params) &&
+            (self.has_valid_shopper_id?(validated_params) || self.has_valid_contact_id?(validated_params)) &&
+            self.validate_currency!(validated_params[:currency]) &&
+            Lightrail::Account.set_account_card_type(validated_params))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid create_account_params for set_params_for_account_create!: #{create_account_params.inspect}")
+    end
+
+    def self.set_nsf_for_simulate!(charge_params)
+      params_for_simulate = charge_params.clone
+      if (!params_for_simulate.key?([:nsf]) && !params_for_simulate.key?(['nsf']))
+        params_for_simulate[:nsf] = false
+      end
+      params_for_simulate
+    end
+
+    def self.set_params_for_card_id_pending!(charge_params)
+      begin
+        validated_params = self.set_params_for_card_id_drawdown!(charge_params)
+        validated_params[:pending] = true
+        return validated_params
+      rescue Lightrail::LightrailError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid charge_params for set_params_for_card_id_pending!!: #{charge_params.inspect}")
+    end
+
+    def self.set_params_for_acting_on_existing_transaction!(original_transaction, new_request_body={})
+      validated_params = new_request_body.clone
+      validated_params[:original_transaction] = original_transaction
+      begin
+        return validated_params if ((validated_params.is_a? Hash) &&
+            (validated_params[:original_transaction].is_a? Hash) &&
+            self.set_cardId!(validated_params, validated_params[:original_transaction]) &&
+            self.set_transactionId!(validated_params, validated_params[:original_transaction]) &&
+            self.get_or_set_userSuppliedId!(validated_params))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid params for set_params_for_acting_on_existing_transaction!: original_transaction: #{original_transaction.inspect}; new_request_body: #{new_request_body.inspect}")
+    end
+
+
+    def self.validate_charge_object! (charge_params)
+      begin
+        return true if (self.set_params_for_code_drawdown!(charge_params) if self.has_valid_code?(charge_params)) ||
+            (self.set_params_for_card_id_drawdown!(charge_params) if (self.has_valid_card_id?(charge_params) || self.has_valid_contact_id?(charge_params) || self.has_valid_shopper_id?(charge_params)))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid charge_params: #{charge_params.inspect}")
+    end
+
+    def self.validate_transaction_response! (transaction_response)
+      begin
+        return true if (transaction_response.is_a? Hash) &&
+            self.has_valid_transaction_id?(transaction_response) &&
+            self.has_valid_card_id?(transaction_response)
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid transaction_response: #{transaction_response.inspect}")
+    end
+
+    def self.validate_fund_object! (fund_params)
+      begin
+        return true if (self.set_params_for_card_id_fund!(fund_params) if (self.has_valid_card_id?(fund_params) ||
+            self.has_valid_contact_id?(fund_params) || self.has_valid_shopper_id?(fund_params)))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid fund_params: #{fund_params.inspect}")
+    end
+
+    def self.validate_ping_response! (ping_response)
+      begin
+        return true if ((ping_response.is_a? Hash) &&
+            (ping_response['user'].is_a? Hash) &&
+            !ping_response['user'].empty? &&
+            self.validate_username!(ping_response['user']['username']))
+      rescue Lightrail::LightrailArgumentError
+      end
+      raise Lightrail::LightrailArgumentError.new("Invalid ping_response: #{ping_response.inspect}")
+    end
+
+
+    def self.validate_card_id! (card_id)
+      return true if ((card_id.is_a? String) && ((/\A[A-Z0-9\-]+\z/i =~ card_id).is_a? Integer))
+      raise Lightrail::LightrailArgumentError.new("Invalid card_id: #{card_id.inspect}")
+    end
+
+    def self.validate_code! (code)
+      return true if ((code.is_a? String) && ((/\A[A-Z0-9\-]+\z/i =~ code).is_a? Integer))
+      raise Lightrail::LightrailArgumentError.new("Invalid code: #{code.inspect}")
+    end
+
+    def self.validate_contact_id! (contact_id)
+      return true if ((contact_id.is_a? String) && ((/\A[A-Z0-9\-]+\z/i =~ contact_id).is_a? Integer))
+      raise Lightrail::LightrailArgumentError.new("Invalid contact_id: #{contact_id.inspect}")
+    end
+
+    def self.validate_shopper_id! (shopper_id)
+      return true if ((shopper_id.is_a? String) && ((/\A[A-Z0-9\-]+\z/i =~ shopper_id).is_a? Integer))
+      raise Lightrail::LightrailArgumentError.new("Invalid shopper_id: #{shopper_id.inspect}")
+    end
+
+    def self.validate_user_supplied_id! (user_supplied_id)
+      return true if (user_supplied_id.is_a? String)
+      raise Lightrail::LightrailArgumentError.new("Invalid user_supplied_id (must be a String): #{user_supplied_id.inspect} ")
+    end
+
+    def self.validate_transaction_id! (transaction_id)
+      return true if ((transaction_id.is_a? String) && !transaction_id.empty?)
+      raise Lightrail::LightrailArgumentError.new("Invalid transaction_id: #{transaction_id.inspect}")
+    end
+
+    def self.validate_amount! (amount)
+      return true if (amount.is_a? Integer)
+      raise Lightrail::LightrailArgumentError.new("Invalid amount: #{amount.inspect}")
+    end
+
+    def self.validate_currency! (currency)
+      return true if (/\A[A-Z]{3}\z/ === currency)
+      raise Lightrail::LightrailArgumentError.new("Invalid currency: #{currency.inspect}")
+    end
+
+    def self.validate_username!(username)
+      return true if ((username.is_a? String) && !username.empty?)
+      raise Lightrail::LightrailArgumentError.new("Invalid username: #{username.inspect}")
+    end
+
+    private
+
+    def self.set_code!(destination_params, source_params)
+      destination_params[:code] ||= self.has_valid_code?(source_params) ? self.get_code(source_params) : nil
+    end
+
+    def self.set_cardId!(destination_params, source_params)
+      destination_params[:cardId] ||= self.has_valid_card_id?(source_params) ? self.get_card_id(source_params) : nil
+    end
+
+    def self.set_transactionId!(destination_params, source_params)
+      destination_params[:transactionId] = self.has_valid_transaction_id?(source_params) ? self.get_transaction_id(source_params) : nil
+    end
+
+    def self.set_contactId_from_contact_or_shopper_id!(destination_params, source_params)
+      contact_id = Lightrail::Validator.has_valid_contact_id?(source_params) ? Lightrail::Validator.get_contact_id(source_params) : nil
+      shopper_id = Lightrail::Validator.has_valid_shopper_id?(source_params) ? Lightrail::Validator.get_shopper_id(source_params) : nil
+
+      raise Lightrail::LightrailArgumentError.new("Must set one of shopper_id or contact_id in #{source_params.inspect}.") unless shopper_id || contact_id
+
+      contact_id_from_shopper_id = shopper_id ? Lightrail::Contact.get_contact_id_from_shopper_id(shopper_id) : nil
+
+      if contact_id && contact_id_from_shopper_id && (contact_id != contact_id_from_shopper_id)
+        raise Lightrail::LightrailArgumentError.new("Error from set_contactId_from_contact_or_shopper_id!: received shopper_id #{shopper_id} and contact_id #{contact_id} which do not belong to the same contact.")
+      end
+
+      destination_params[:contactId] = contact_id || contact_id_from_shopper_id
+    end
+
+    def self.set_userSuppliedId_from_existing!(destination_params, source_params)
+      destination_params[:userSuppliedId] ||= self.has_valid_user_supplied_id?(source_params) ? self.get_user_supplied_id(source_params) : nil
+    end
+
+    def self.get_or_set_userSuppliedId!(charge_params)
+      charge_params[:userSuppliedId] ||= self.get_or_create_user_supplied_id(charge_params)
+    end
+
+
+    def self.has_valid_code?(charge_params)
+      code = (charge_params.respond_to? :keys) ? self.get_code(charge_params) : false
+      code && self.validate_code!(code)
+    end
+
+    def self.has_valid_card_id?(charge_params)
+      cardId = (charge_params.respond_to? :keys) ? self.get_card_id(charge_params) : false
+      cardId && self.validate_card_id!(cardId)
+    end
+
+    def self.has_valid_contact_id?(charge_params)
+      contactId = (charge_params.respond_to? :keys) ? self.get_contact_id(charge_params) : false
+      contactId && self.validate_contact_id!(contactId)
+    end
+
+    def self.has_valid_shopper_id?(charge_params)
+      shopperId = (charge_params.respond_to? :keys) ? self.get_shopper_id(charge_params) : false
+      shopperId && self.validate_shopper_id!(shopperId)
+    end
+
+    def self.has_valid_or_empty_shopper_id?(charge_params)
+      shopperId = (charge_params.respond_to? :keys) ? self.get_shopper_id(charge_params) : false
+      shopperId && (shopperId === '' || self.validate_shopper_id!(shopperId))
+    end
+
+    def self.has_valid_user_supplied_id?(params)
+      userSuppliedId = (params.respond_to? :keys) ? self.get_user_supplied_id(params) : false
+      userSuppliedId && self.validate_user_supplied_id!(userSuppliedId)
+    end
+
+    def self.has_valid_transaction_id?(charge_params)
+      transactionId = (charge_params.respond_to? :keys) ? self.get_transaction_id(charge_params) : false
+      transactionId && self.validate_transaction_id!(transactionId)
+    end
+
+
+    def self.get_card_id(charge_params)
+      card_id_key = (charge_params.keys & Lightrail::Constants::LIGHTRAIL_CARD_ID_KEYS).first
+      charge_params[card_id_key]
+    end
+
+    def self.get_code(charge_params)
+      code_key = (charge_params.keys & Lightrail::Constants::LIGHTRAIL_CODE_KEYS).first
+      charge_params[code_key]
+    end
+
+    def self.get_contact_id(charge_params)
+      contact_id_key = (charge_params.keys & Lightrail::Constants::LIGHTRAIL_CONTACT_ID_KEYS).first
+      charge_params[contact_id_key]
+    end
+
+    def self.get_shopper_id(charge_params)
+      shopper_id_key = (charge_params.keys & Lightrail::Constants::LIGHTRAIL_SHOPPER_ID_KEYS).first
+      charge_params[shopper_id_key]
+    end
+
+    def self.get_transaction_id(charge_params)
+      transaction_id_key = (charge_params.keys & Lightrail::Constants::LIGHTRAIL_TRANSACTION_ID_KEYS).first
+      charge_params[transaction_id_key]
+    end
+
+    def self.get_code_or_card_id_key(charge_params)
+      (charge_params.keys & Lightrail::Constants::LIGHTRAIL_PAYMENT_METHODS).first
+    end
+
+    def self.get_user_supplied_id(params)
+      user_supplied_id_key = (params.keys & Lightrail::Constants::LIGHTRAIL_USER_SUPPLIED_ID_KEYS).first
+      params[user_supplied_id_key]
+    end
+
+    def self.get_or_create_user_supplied_id(charge_params)
+      user_supplied_id_key = (charge_params.keys & Lightrail::Constants::LIGHTRAIL_USER_SUPPLIED_ID_KEYS).first
+      charge_params[user_supplied_id_key] || SecureRandom::uuid
+    end
+
+    def self.get_or_create_user_supplied_id_with_action_suffix(charge_params, new_user_supplied_id_base, action_suffix)
+      user_supplied_id_key = (charge_params.keys & Lightrail::Constants::LIGHTRAIL_USER_SUPPLIED_ID_KEYS).first
+      charge_params[user_supplied_id_key] || "#{new_user_supplied_id_base}-#{action_suffix}"
+    end
+
+  end
+end