synapse_pay_rest 0.0.15 → 2.0.0

data/lib/synapse_pay_rest/models/node/synapse_np_node.rb

@@ -0,0 +1,22 @@
+module SynapsePayRest
+  # Represents a Synapse node allowing any user to hold Nepali Rupees.
+  class SynapseNpNode < SynapseNode
+    class << self
+      private
+
+      def payload_for_create(nickname:, **options)
+        args = {
+          type: 'SYNAPSE-NP',
+          nickname: nickname
+        }.merge(options)
+        payload = super(args)
+        # optional payload fields
+        extra = {}
+        extra['supp_id']            = options[:supp_id] if options[:supp_id]
+        extra['gateway_restricted'] = options[:gateway_restricted] if options[:gateway_restricted]
+        payload['extra'] = extra if extra.any?
+        payload
+      end
+    end
+  end
+end

data/lib/synapse_pay_rest/models/node/synapse_us_node.rb

@@ -0,0 +1,23 @@
+module SynapsePayRest
+  # Represents a Synapse node allowing any user to hold funds. You can use this
+  # node as a wallet, an escrow account or something else along those lines.
+  class SynapseUsNode < SynapseNode
+    class << self
+      private
+
+      def payload_for_create(nickname:, **options)
+        args = {
+          type: 'SYNAPSE-US',
+          nickname: nickname
+        }.merge(options)
+        payload = super(args)
+        # optional payload fields
+        extra = {}
+        extra['supp_id']            = options[:supp_id] if options[:supp_id]
+        extra['gateway_restricted'] = options[:gateway_restricted] if options[:gateway_restricted]
+        payload['extra'] = extra if extra.any?
+        payload
+      end
+    end
+  end
+end

data/lib/synapse_pay_rest/models/node/unverified_node.rb

@@ -0,0 +1,73 @@
+module SynapsePayRest
+  # Represents a node that has not yet been created due to pending bank login
+  # MFA questions.
+  class UnverifiedNode
+    # @!attribute [r] user
+    #   @return [SynapsePayRest::User] the user to whom the node belongs
+    # @!attribute [r] mfa_access_token
+    #   @return [String] access token that must be included in the response (handled automatically)
+    # @!attribute [r] mfa_message
+    #   @return [String] question or MFA prompt from bank that must be answered
+    # @!attribute [r] mfa_verified
+    #   @return [Boolean] whether the node is verified yet
+    #   @todo should be mfa_verified? in Ruby idiom
+    attr_reader :user, :mfa_access_token, :mfa_message, :mfa_verified
+
+    def initialize(user:, mfa_access_token:, mfa_message:, mfa_verified:)
+      @user             = user
+      @mfa_access_token = mfa_access_token
+      @mfa_message      = mfa_message
+      @mfa_verified     = mfa_verified
+    end
+
+    # Allows the user to submit an answer to the bank in response to mfa_message.
+    # 
+    # @param answer [String] the user's answer to the mfa_message asked by the bank
+    # 
+    # @raise [SynapsePayRest::Error] if incorrect answer
+    # 
+    # @return [Array<SynapsePayRest::AchUsNode>,SynapsePayRest::UnverifiedNode] may contain multiple nodes if successful, else self if new MFA question to answer
+    # 
+    # @todo make a new Error subclass for incorrect MFA
+    def answer_mfa(answer)
+      payload  = payload_for_answer_mfa(answer: answer)
+      response = user.client.nodes.post(payload: payload)
+      
+      handle_answer_mfa_response(response)
+    end
+
+    private
+
+    def payload_for_answer_mfa(answer:)
+      {
+        'access_token' => mfa_access_token,
+        'mfa_answer'   => answer
+      }
+    end
+
+    # Determines whether the response is successful in verifying the node, has
+    # follow-up MFA questions, or failed with an incorrect answer.
+    # 
+    # @todo Use Error#code instead of parsing the response for the code.
+    def handle_answer_mfa_response(response)
+      if response['error_code'] == '0'
+        # correct answer
+        @mfa_verified = true
+        AchUsNode.create_multiple_from_response(user, response['nodes'])
+      elsif response['error_code'] == '10' && response['mfa']['message'] == mfa_message
+        # wrong answer (mfa message the same), retry if allowed
+        args = {
+          message: 'incorrect bank login mfa answer',
+          code: response['http_code'], 
+          response: response
+        }
+        raise SynapsePayRest::Error, args
+      elsif response['error_code'] == '10'
+        # new additional MFA question. need to call #answer_mfa with new answer
+        @mfa_access_token = response['mfa']['access_token']
+        @mfa_message      = response['mfa']['message']
+        self
+      end
+    end
+  end
+end

data/lib/synapse_pay_rest/models/node/wire_int_node.rb

@@ -0,0 +1,23 @@
+module SynapsePayRest
+  # Represents a non-US account for wire payments.
+  class WireIntNode < WireNode
+    class << self
+      private 
+
+      def payload_for_create(nickname:, bank_name:, account_number:, swift:,
+        name_on_account:, address:, **options)
+        args = {
+          type: 'WIRE-INT',
+          nickname: nickname,
+          bank_name: bank_name,
+          account_number: account_number,
+          name_on_account: name_on_account,
+          address: address
+        }.merge(options)
+        payload = super(args)
+        payload['info']['swift'] = swift
+        payload
+      end
+    end
+  end
+end

data/lib/synapse_pay_rest/models/node/wire_node.rb

@@ -0,0 +1,38 @@
+module SynapsePayRest
+  # Parent of all Wire nodes. Should not be instantiated directly.
+  # 
+  # @todo Make this a module instead.
+  class WireNode < BaseNode
+    class << self
+      private
+
+      def payload_for_create(type:, nickname:, bank_name:, account_number:, address:,
+        name_on_account:, **options)
+        payload = {
+          'type' => type,
+          'info' => {
+            'nickname'        => nickname,
+            'name_on_account' => name_on_account,
+            'account_num'     => account_number,
+            'bank_name'       => bank_name,
+            'address'         => address,
+          }
+        }
+
+        # optional payload fields
+        payload['info']['routing_num'] = options[:routing_number] if options[:routing_number]
+        correspondent_info = {}
+        correspondent_info['routing_num'] = options[:correspondent_routing_number] if options[:correspondent_routing_number]
+        correspondent_info['bank_name']   = options[:correspondent_bank_name] if options[:correspondent_bank_name]
+        correspondent_info['address']     = options[:correspondent_address] if options[:correspondent_address]
+        correspondent_info['swift']       = options[:correspondent_swift] if options[:correspondent_swift]
+        payload['info']['correspondent_info'] = correspondent_info if correspondent_info.any?
+        extra = {}
+        extra['supp_id']            = options[:supp_id] if options[:supp_id]
+        extra['gateway_restricted'] = options[:gateway_restricted] if options[:gateway_restricted]
+        payload['extra'] = extra if extra.any?
+        payload
+      end
+    end
+  end
+end

data/lib/synapse_pay_rest/models/node/wire_us_node.rb

@@ -0,0 +1,23 @@
+module SynapsePayRest
+  # Represents a US bank account for processing wire payments.
+  class WireUsNode < WireNode
+    class << self
+      private
+
+      def payload_for_create(nickname:, bank_name:, account_number:, routing_number:,
+        name_on_account:, address:, **options)
+        args = {
+          type: 'WIRE-US',
+          nickname: nickname,
+          bank_name: bank_name,
+          account_number: account_number,
+          routing_number: routing_number,
+          name_on_account: name_on_account,
+          address: address
+        }.merge(options)
+        
+        super(args)
+      end
+    end
+  end
+end

data/lib/synapse_pay_rest/models/transaction/transaction.rb

@@ -0,0 +1,212 @@
+module SynapsePayRest
+  # Represents a transaction record and holds methods for constructing transaction instances
+  # from API calls. This is built on top of the SynapsePayRest::Transactions class and
+  # is intended to make it easier to use the API without knowing payload formats
+  # or knowledge of REST.
+  # 
+  # @todo use mixins to remove duplication between Node and BaseNode. May be 
+  #   better to refactor this into a mixin altogether since this shouldn't be instantiated. 
+  # @todo reduce duplicated logic between User/BaseNode/Transaction
+  class Transaction
+
+    # @!attribute [rw] node
+    #   @return [SynapsePayRest::Node] the node to which the transaction belongs
+    attr_reader :node, :id, :amount, :currency, :client_id, :client_name, :created_on,
+                :ip, :latlon, :note, :process_on, :supp_id, :webhook, :fees,
+                :recent_status, :timeline, :from, :to, :to_type, :to_id,
+                :fee_amount, :fee_note, :fee_to_id
+
+    class << self
+      # Creates a new transaction in the API belonging to the provided node and
+      # returns a transaction instance from the response data.
+      # 
+      # @param node [SynapsePayRest::BaseNode] node to which the transaction belongs
+      # @param to_id [String] node id of the receiving node
+      # @param to_type [String] node type of the receiving node
+      # @see https://docs.synapsepay.com/docs/node-resources valid node types
+      # @param amount [Float] 100.0 = $100.00 for example
+      # @param currency [String] e.g. 'USD'
+      # @param ip [String]
+      # @param note [String] (optional)
+      # @param process_in [Integer] (optional) days until processed (default/minimum 1)
+      # @param fee_amount [Float] (optional) fee amount to add to the transaction
+      # @param fee_to_id [String] (optional) node id to which to send the fee (must be SYNAPSE-US)
+      # @param fee_note [String] (optional)
+      # @param supp_id [String] (optional)
+      # 
+      # @raise [SynapsePayRest::Error] if HTTP error or invalid argument format
+      # 
+      # @return [SynapsePayRest::Transaction]
+      # 
+      # @todo allow either to_node or to_type/to_id
+      # @todo allow node to be entered as alternative to fee_to node
+      # @todo validate if fee_to node is synapse-us
+      # @todo allow multiple fees
+      def create(node:, to_type:, to_id:, amount:, currency:, ip:, **options)
+        raise ArgumentError, 'cannot create a transaction with an UnverifiedNode' if node.is_a?(UnverifiedNode)
+        raise ArgumentError, 'node must be a type of BaseNode object' unless node.is_a?(BaseNode)
+        raise ArgumentError, 'amount must be a Numeric (Integer or Float)' unless amount.is_a?(Numeric)
+        [to_type, to_id, currency, ip].each do |arg|
+          raise ArgumentError, "#{arg} must be a String" unless arg.is_a?(String)
+        end
+
+        payload = payload_for_create(node: node, to_type: to_type, to_id: to_id,
+          amount: amount, currency: currency, ip: ip, **options)
+        node.user.authenticate
+        response = node.user.client.trans.create(node_id: node.id, payload: payload)
+        create_from_response(node, response)
+      end
+
+      # Queries the API for a transaction belonging to the supplied node by transaction id
+      # and returns a Transaction instance if found.
+      # 
+      # @param node [SynapsePayRest::BaseNode] node to which the transaction belongs
+      # @param id [String] id of the transaction to find
+      # 
+      # @raise [SynapsePayRest::Error] if not found or other HTTP error
+      # 
+      # @return [SynapsePayRest::Transaction]
+      def find(node:, id:)
+        raise ArgumentError, 'node must be a type of BaseNode object' unless node.is_a?(BaseNode)
+        raise ArgumentError, 'id must be a String' unless id.is_a?(String)
+
+        node.user.authenticate
+        response = node.user.client.trans.get(node_id: node.id, trans_id: id)
+        create_from_response(node, response)
+      end
+
+      # Queries the API for all transactions belonging to the supplied node and returns
+      # them as Transaction instances.
+      # 
+      # @param node [SynapsePayRest::BaseNode] node to which the transaction belongs
+      # @param page [String,Integer] (optional) response will default to 1
+      # @param per_page [String,Integer] (optional) response will default to 20
+      # 
+      # @raise [SynapsePayRest::Error]
+      # 
+      # @return [Array<SynapsePayRest::Transaction>]
+      def all(node:, page: nil, per_page: nil)
+        raise ArgumentError, 'node must be a type of BaseNode object' unless node.is_a?(BaseNode)
+        [page, per_page].each do |arg|
+          if arg && (!arg.is_a?(Integer) || arg < 1)
+            raise ArgumentError, "#{arg} must be nil or an Integer >= 1"
+          end
+        end
+
+        node.user.authenticate
+        response = node.user.client.trans.get(node_id: node.id, page: page, per_page: per_page)
+        create_multiple_from_response(node, response['trans'])
+      end
+
+      # Creates a Transaction from a response hash.
+      # 
+      # @note Shouldn't need to call this directly.
+      # 
+      # @todo convert the nodes and users in response into User/Node objects
+      # @todo rework to handle multiple fees
+      def create_from_response(node, response)
+        args = {
+          node:          node,
+          id:            response['_id'],
+          amount:        response['amount']['amount'],
+          currency:      response['amount']['currency'],
+          client_id:     response['client']['id'],
+          client_name:   response['client']['name'],
+          created_on:    response['extra']['created_on'],
+          ip:            response['extra']['ip'],
+          latlon:        response['extra']['latlon'],
+          note:          response['extra']['note'],
+          process_on:    response['extra']['process_on'],
+          supp_id:       response['extra']['supp_id'],
+          webhook:       response['extra']['webhook'],
+          fees:          response['fees'],
+          recent_status: response['recent_status'],
+          timeline:      response['timeline'],
+          from:          response['from'],
+          to:            response['to'],
+          to_type:       response['to']['type'],
+          to_id:         response['to']['id'],
+          fee_amount:    response['fees'].last['fee'],
+          fee_note:      response['fees'].last['note'],
+          fee_to_id:     response['fees'].last['to']['id'],
+        }
+        self.new(args)
+      end
+
+      private
+
+      def payload_for_create(node:, to_type:, to_id:, amount:, currency:, ip:,
+        **options)
+        payload = {
+          'to' => {
+            'type' => to_type,
+            'id' => to_id
+          },
+          'amount' => {
+            'amount' => amount,
+            'currency' => currency
+          },
+          'extra' => {
+            'ip' => ip
+          }
+        }
+        # optional payload fields
+        payload['extra']['supp_id']    = options[:supp_id] if options[:supp_id]
+        payload['extra']['note']       = options[:note] if options[:note]
+        payload['extra']['process_on'] = options[:process_in] if options[:process_in]
+        other = {}
+        other['attachments'] = options[:attachments] if options[:attachments]
+        payload['other'] = other if other.any?
+        fees = []
+        fee = {}
+        fee['fee']  = options[:fee_amount] if options[:fee_amount]
+        fee['note'] = options[:fee_note] if options[:fee_note]
+        fee_to = {}
+        fee_to['id'] = options[:fee_to_id] if options[:fee_to_id]
+        fee['to'] = fee_to if fee_to.any?
+        fees << fee if fee.any?
+        payload['fees'] = fees if fees.any?
+        payload
+      end
+
+      def create_multiple_from_response(node, response)
+        return [] if response.empty?
+        response.map { |trans_data| create_from_response(node, trans_data) }
+      end
+    end
+
+    # @note Do not call directly. Use Transaction.create or other class
+    #   method to instantiate via API action.
+    def initialize(**options)
+      options.each { |key, value| instance_variable_set("@#{key}", value) }
+    end
+
+    # Adds a comment to the transaction's timeline/recent_status fields.
+    # 
+    # @param comment [String]
+    # 
+    # @raise [SynapsePayRest::Error]
+    # 
+    # @return [Array<SynapsePayRest::Transaction>] (self)
+    def add_comment(comment)
+      payload = {'comment': comment}
+      response = node.user.client.trans.update(node_id: node.id, trans_id: id, payload: payload)
+      self.class.create_from_response(node, response['trans'])
+    end
+
+    # Cancels this transaction if it has not already settled.
+    # 
+    # @raise [SynapsePayRest::Error]
+    # 
+    # @return [Array<SynapsePayRest::Transaction>] (self)
+    def cancel
+      response = node.user.client.trans.delete(node_id: node.id, trans_id: id)
+      self.class.create_from_response(node, response)
+    end
+
+    # Checks if two Transaction instances have same id (different instances of same record).
+    def ==(other)
+      other.instance_of?(self.class) && !id.nil? &&  id == other.id 
+    end
+  end
+end

data/lib/synapse_pay_rest/models/user/base_document.rb

@@ -0,0 +1,346 @@
+module SynapsePayRest
+  # Stores info on the base document portion (personal/business info) of the CIP
+  # document and also manages physical/social/virtual documents.
+  class BaseDocument
+    # @!attribute [rw] user
+    #   @return [SynapsePayRest::User] the user to whom the transaction belongs
+    # @!attribute [r] permission_scope
+    #   @return [String] https://docs.synapsepay.com/docs/user-resources#section-document-permission-scope
+    attr_accessor :user, :email, :phone_number, :ip, :name, :aka, :entity_type,
+                  :entity_scope, :birth_day, :birth_month, :birth_year,
+                  :address_street, :address_city, :address_subdivision,
+                  :address_postal_code, :address_country_code, 
+                  :physical_documents, :social_documents, :virtual_documents
+    attr_reader :id, :permission_scope
+
+    class << self
+      # Creates a new base document in the API belonging to the provided user and
+      # returns a base document instance from the response data.
+      # 
+      # @param user [SynapsePayRest::User] the user to whom the base document belongs
+      # @param email [String]
+      # @param phone_number [String]
+      # @param ip [String]
+      # @param name [String]
+      # @param aka [String] corresponds to 'alias' in docs, use name if no alias
+      # @param entity_type [String] consult your organization's CIP for valid options
+      # @see https://docs.synapsepay.com/docs/user-resources#section-supported-entity-types all supported entity_type values
+      # @param entity_scope [String] consult your organization's CIP for valid options
+      # @see https://docs.synapsepay.com/docs/user-resources#section-supported-entity-scope all entity_scope options
+      # @param birth_day [Integer]
+      # @param birth_month [Integer]
+      # @param birth_year [Integer]
+      # @param address_street [String]
+      # @param address_city [String]
+      # @param address_subdivision [String]
+      # @param address_postal_code [String]
+      # @param address_country_code [String]
+      # @param physical_documents [Array<SynapsePayRest::PhysicalDocument>] (optional)
+      # @param social_documents [Array<SynapsePayRest::SocialDocument>] (optional)
+      # @param virtual_documents [Array<SynapsePayRest::VirtualDocument>] (optional)
+      # 
+      # @raise [SynapsePayRest::Error]
+      # 
+      # @return [SynapsePayRest::BaseDocument] new instance with updated info
+      def create(user:, email:, phone_number:, ip:, name:,
+        aka:, entity_type:, entity_scope:, birth_day:, birth_month:, birth_year:,
+        address_street:, address_city:, address_subdivision:, address_postal_code:,
+        address_country_code:, physical_documents: [], social_documents: [],
+        virtual_documents: [])
+        raise ArgumentError, 'user must be a User object' unless user.is_a?(User)
+        [email, phone_number, ip, name, aka, entity_type, entity_scope, 
+         address_street, address_city, address_subdivision, address_postal_code,
+         address_country_code].each do |arg|
+           raise ArgumentError, "#{arg} must be a String" unless arg.is_a?(String)
+        end
+        [physical_documents, social_documents, virtual_documents].each do |arg|
+          raise ArgumentError, "#{arg} must be an Array" unless arg.is_a?(Array)
+        end
+        unless physical_documents.empty? || physical_documents.first.is_a?(PhysicalDocument)
+          raise ArgumentError, 'physical_documents be empty or contain PhysicalDocument(s)'
+        end
+        unless social_documents.empty? || social_documents.first.is_a?(SocialDocument)
+          raise ArgumentError, 'social_documents be empty or contain SocialDocument(s)'
+        end
+        unless virtual_documents.empty? || virtual_documents.first.is_a?(VirtualDocument)
+          raise ArgumentError, 'virtual_documents be empty or contain VirtualDocument(s)'
+        end
+
+        base_document = BaseDocument.new(
+          user: user, 
+          email: email, 
+          phone_number: phone_number,
+          ip: ip, 
+          name: name, 
+          aka: aka, 
+          entity_type: entity_type,
+          entity_scope: entity_scope, 
+          birth_day: birth_day, 
+          birth_month: birth_month, 
+          birth_year: birth_year, 
+          address_street: address_street, 
+          address_city: address_city,
+          address_subdivision: address_subdivision, 
+          address_postal_code:  address_postal_code,
+          address_country_code: address_country_code, 
+          physical_documents: physical_documents,
+          social_documents: social_documents, 
+          virtual_documents: virtual_documents
+        )
+
+        base_document.submit
+      end
+
+      # Parses multiple base_documents from response
+      # @note Do not call directly (it's automatic).
+      def create_from_response(user, response)
+        base_documents_data = response['documents']
+        base_documents_data.map do |base_document_data|
+          physical_docs = base_document_data['physical_docs'].map do |data|
+            doc = PhysicalDocument.create_from_response(data)
+            doc.base_document = self
+            doc
+          end
+          social_docs = base_document_data['social_docs'].map do |data|
+            doc = SocialDocument.create_from_response(data)
+            doc.base_document = self
+            doc
+          end
+          virtual_docs = base_document_data['virtual_docs'].map do |data|
+            doc = VirtualDocument.create_from_response(data)
+            doc.base_document = self
+            doc
+          end
+
+          args = {
+            user:               user,
+            id:                 base_document_data['id'],
+            name:               base_document_data['name'],
+            permission_scope:   base_document_data['permission_scope'],
+            physical_documents: physical_docs,
+            social_documents:   social_docs,
+            virtual_documents:  virtual_docs
+          }
+
+          base_doc = self.new(args)
+          [physical_docs, social_docs, virtual_docs].flatten.each do |doc|
+            doc.base_document = base_doc
+          end
+
+          base_doc
+        end
+      end
+    end
+
+    # @note It should not be necessary to call this method directly.
+    def initialize(**args)
+      @id                   = args[:id]
+      @permission_scope     = args[:permission_scope]
+      @user                 = args[:user]
+      @email                = args[:email]
+      @phone_number         = args[:phone_number]
+      @ip                   = args[:ip]
+      @name                 = args[:name]
+      @aka                  = args[:aka]
+      @entity_type          = args[:entity_type]
+      @entity_scope         = args[:entity_scope]
+      @birth_day            = args[:birth_day]
+      @birth_month          = args[:birth_month]
+      @birth_year           = args[:birth_year]
+      @address_street       = args[:address_street]
+      @address_city         = args[:address_city]
+      @address_subdivision  = args[:address_subdivision]
+      @address_postal_code  = args[:address_postal_code]
+      @address_country_code = args[:address_country_code]
+      @physical_documents   = args[:physical_documents]
+      @social_documents     = args[:social_documents]
+      @virtual_documents    = args[:virtual_documents]
+    end
+
+    # Submits the base document to the API.
+    # @note It should not be necessary to call this method directly.
+    # 
+    # @raise [SynapsePayRest::Error]
+    # 
+    # @return [SynapsePayRest::BaseDocument] new instance with updated info (id will be different if email or phone changed)
+    def submit
+      user.authenticate
+      response = user.client.users.update(payload: payload_for_submit)
+      @user    = User.create_from_response(user.client, response)
+
+      if id
+        # return updated version of self
+        user.base_documents.find { |doc| doc.id == id }
+      else
+        # first time submission, assume last doc is updated version of self
+        require 'pry'; 
+        user.base_documents.last
+      end
+    end
+
+    # Updates the supplied fields in the base document. See #create for valid
+    # 
+    # @param email [String] (optional)
+    # @param phone_number [String] (optional)
+    # @param ip [String] (optional)
+    # @param name [String] (optional)
+    # @param aka [String] (optional) corresponds to 'alias' in docs, use name if no alias
+    # @param entity_type [String] (optional) consult your organization's CIP for valid options
+    # @see https://docs.synapsepay.com/docs/user-resources#section-supported-entity-types all supported entity_type values
+    # @param entity_scope [String] (optional) consult your organization's CIP for valid options
+    # @see https://docs.synapsepay.com/docs/user-resources#section-supported-entity-scope all entity_scope options
+    # @param birth_day [Integer] (optional)
+    # @param birth_month [Integer] (optional)
+    # @param birth_year [Integer] (optional)
+    # @param address_street [String] (optional)
+    # @param address_city [String] (optional)
+    # @param address_subdivision [String] (optional)
+    # @param address_postal_code [String] (optional)
+    # @param address_country_code [String] (optional)
+    # @param physical_documents [Array<SynapsePayRest::PhysicalDocument>] (optional)
+    # @param social_documents [Array<SynapsePayRest::SocialDocument>] (optional)
+    # @param virtual_documents [Array<SynapsePayRest::VirtualDocument>] (optional)
+    # 
+    # @raise [SynapsePayRest::Error]
+    # 
+    # @return [SynapsePayRest::BaseDocument] new instance with updated info 
+    # 
+    # @todo validate changes are valid fields in base_document
+    #   (or make other methods more like this)
+    def update(**changes)
+      if changes.empty?
+        raise ArgumentError, 'must provide some key-value pairs to update'
+      end
+      user.authenticate
+      payload  = payload_for_update(changes)
+      response = user.client.users.update(payload: payload)
+      @user    = User.create_from_response(user.client, response)
+
+      if id
+        # return updated version of self
+        return user.base_documents.find { |doc| doc.id == id }
+      else
+        # first time submission, assume last doc is updated version of self
+        return user.base_documents.last
+      end
+    end
+
+    # Adds one or more physical documents to the base document and submits
+    # them to the API using KYC 2.0 endpoints.
+    # 
+    # @param documents [Array<SynapsePayRest::PhysicalDocument>]
+    # 
+    # @raise [SynapsePayRest::Error]
+    # 
+    # @return [SynapsePayRest::BaseDocument] new instance with updated info
+    def add_physical_documents(documents)
+      raise ArgumentError, 'must be an Array' unless documents.is_a?(Array)
+      unless documents.first.is_a?(PhysicalDocument)
+        raise ArgumentError, 'must contain a PhysicalDocument'
+      end
+
+      update(physical_documents: documents)
+    end
+
+    # Adds one or more social documents to the base document and submits
+    # them to the API using KYC 2.0 endpoints.
+    # 
+    # @param documents [Array<SynapsePayRest::SocialDocument>]
+    # 
+    # @raise [SynapsePayRest::Error]
+    # 
+    # @return [SynapsePayRest::BaseDocument] new instance with updated info
+    def add_social_documents(documents)
+      raise ArgumentError, 'must be an Array' unless documents.is_a?(Array)
+      unless documents.first.is_a?(SocialDocument)
+        raise ArgumentError, 'must contain a SocialDocument'
+      end
+
+      update(social_documents: documents)
+    end
+
+    # Adds one or more virtual documents to the base document and submits
+    # them to the API using KYC 2.0 endpoints.
+    # 
+    # @param documents [Array<SynapsePayRest::VirtualDocument>]
+    # 
+    # @raise [SynapsePayRest::Error]
+    # 
+    # @return [SynapsePayRest::BaseDocument] new instance with updated info
+    def add_virtual_documents(documents)
+      raise ArgumentError, 'must be an Array' unless documents.is_a?(Array)
+      unless documents.first.is_a?(VirtualDocument)
+        raise ArgumentError, 'must contain a VirtualDocument'
+      end
+
+      update(virtual_documents: documents)
+    end
+
+    # Checks if two BaseDocument instances have same id (different instances of same record).
+    def ==(other)
+      other.instance_of?(self.class) && !id.nil? &&  id == other.id 
+    end
+
+    private
+
+    def payload_for_submit
+      payload = {
+        'documents' => [{
+          'email'                => email,
+          'phone_number'         => phone_number,
+          'ip'                   => ip,
+          'name'                 => name,
+          'alias'                => aka,
+          'entity_type'          => entity_type,
+          'entity_scope'         => entity_scope,
+          'day'                  => birth_day,
+          'month'                => birth_month,
+          'year'                 => birth_year,
+          'address_street'       => address_street,
+          'address_city'         => address_city,
+          'address_subdivision'  => address_subdivision,
+          'address_postal_code'  => address_postal_code,
+          'address_country_code' => address_country_code
+        }]
+      }
+
+      unless physical_documents.empty?
+        payload['documents'].first['physical_docs'] = physical_documents.map(&:to_hash)
+      end
+
+      unless social_documents.empty?
+        payload['documents'].first['social_docs'] = social_documents.map(&:to_hash)
+      end
+
+      unless virtual_documents.empty?
+        payload['documents'].first['virtual_docs'] = virtual_documents.map(&:to_hash)
+      end
+
+      payload
+    end
+
+    def payload_for_update(changes)
+      payload = {
+        'documents' => [{
+         'id' => id
+        }]
+      }
+
+      changes.each do |field, new_value|
+        # convert docs to their hash format for payload
+        if field == :physical_documents
+          payload['documents'].first['physical_docs'] = new_value.map(&:to_hash)
+        elsif field == :social_documents
+          payload['documents'].first['social_docs'] = new_value.map(&:to_hash)
+        elsif field == :virtual_documents
+          payload['documents'].first['virtual_docs'] = new_value.map(&:to_hash)
+        else
+          # insert non-document fields into payload
+          payload['documents'].first[field.to_s] = new_value
+        end
+      end
+
+      payload
+    end
+  end
+end