stripe 1.27.2 → 5.33.0

data/lib/stripe/stripe_configuration.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Stripe
+  # Configurable options:
+  #
+  # =ca_bundle_path=
+  # The location of a file containing a bundle of CA certificates. By default
+  # the library will use an included bundle that can successfully validate
+  # Stripe certificates.
+  #
+  # =log_level=
+  # When set prompts the library to log some extra information to $stdout and
+  # $stderr about what it's doing. For example, it'll produce information about
+  # requests, responses, and errors that are received. Valid log levels are
+  # `debug` and `info`, with `debug` being a little more verbose in places.
+  #
+  # Use of this configuration is only useful when `.logger` is _not_ set. When
+  # it is, the decision what levels to print is entirely deferred to the logger.
+  #
+  # =logger=
+  # The logger should support the same interface as the `Logger` class that's
+  # part of Ruby's standard library (hint, anything in `Rails.logger` will
+  # likely be suitable).
+  #
+  # If `.logger` is set, the value of `.log_level` is ignored. The decision on
+  # what levels to print is entirely deferred to the logger.
+  class StripeConfiguration
+    attr_accessor :api_key
+    attr_accessor :api_version
+    attr_accessor :client_id
+    attr_accessor :enable_telemetry
+    attr_accessor :logger
+    attr_accessor :stripe_account
+
+    attr_reader :api_base
+    attr_reader :uploads_base
+    attr_reader :connect_base
+    attr_reader :ca_bundle_path
+    attr_reader :log_level
+    attr_reader :initial_network_retry_delay
+    attr_reader :max_network_retries
+    attr_reader :max_network_retry_delay
+    attr_reader :open_timeout
+    attr_reader :read_timeout
+    attr_reader :write_timeout
+    attr_reader :proxy
+    attr_reader :verify_ssl_certs
+
+    def self.setup
+      new.tap do |instance|
+        yield(instance) if block_given?
+      end
+    end
+
+    # Create a new config based off an existing one. This is useful when the
+    # caller wants to override the global configuration
+    def reverse_duplicate_merge(hash)
+      dup.tap do |instance|
+        hash.each do |option, value|
+          instance.public_send("#{option}=", value)
+        end
+      end
+    end
+
+    def initialize
+      @ca_bundle_path = Stripe::DEFAULT_CA_BUNDLE_PATH
+      @enable_telemetry = true
+      @verify_ssl_certs = true
+
+      @max_network_retries = 0
+      @initial_network_retry_delay = 0.5
+      @max_network_retry_delay = 2
+
+      @open_timeout = 30
+      @read_timeout = 80
+      @write_timeout = 30
+
+      @api_base = "https://api.stripe.com"
+      @connect_base = "https://connect.stripe.com"
+      @uploads_base = "https://files.stripe.com"
+    end
+
+    def log_level=(val)
+      # Backwards compatibility for values that we briefly allowed
+      if val == "debug"
+        val = Stripe::LEVEL_DEBUG
+      elsif val == "info"
+        val = Stripe::LEVEL_INFO
+      end
+
+      levels = [Stripe::LEVEL_INFO, Stripe::LEVEL_DEBUG, Stripe::LEVEL_ERROR]
+
+      if !val.nil? && !levels.include?(val)
+        raise ArgumentError,
+              "log_level should only be set to `nil`, `debug` or `info`"
+      end
+      @log_level = val
+    end
+
+    def max_network_retries=(val)
+      @max_network_retries = val.to_i
+    end
+
+    def max_network_retry_delay=(val)
+      @max_network_retry_delay = val.to_i
+    end
+
+    def initial_network_retry_delay=(val)
+      @initial_network_retry_delay = val.to_i
+    end
+
+    def open_timeout=(open_timeout)
+      @open_timeout = open_timeout
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def read_timeout=(read_timeout)
+      @read_timeout = read_timeout
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def write_timeout=(write_timeout)
+      unless Net::HTTP.instance_methods.include?(:write_timeout=)
+        raise NotImplementedError
+      end
+
+      @write_timeout = write_timeout
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def proxy=(proxy)
+      @proxy = proxy
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def verify_ssl_certs=(verify_ssl_certs)
+      @verify_ssl_certs = verify_ssl_certs
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def uploads_base=(uploads_base)
+      @uploads_base = uploads_base
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def connect_base=(connect_base)
+      @connect_base = connect_base
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def api_base=(api_base)
+      @api_base = api_base
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    def ca_bundle_path=(path)
+      @ca_bundle_path = path
+
+      # empty this field so a new store is initialized
+      @ca_store = nil
+
+      StripeClient.clear_all_connection_managers(config: self)
+    end
+
+    # A certificate store initialized from the the bundle in #ca_bundle_path and
+    # which is used to validate TLS on every request.
+    #
+    # This was added to the give the gem "pseudo thread safety" in that it seems
+    # when initiating many parallel requests marshaling the certificate store is
+    # the most likely point of failure (see issue #382). Any program attempting
+    # to leverage this pseudo safety should make a call to this method (i.e.
+    # `Stripe.ca_store`) in their initialization code because it marshals lazily
+    # and is itself not thread safe.
+    def ca_store
+      @ca_store ||= begin
+                      store = OpenSSL::X509::Store.new
+                      store.add_file(ca_bundle_path)
+                      store
+                    end
+    end
+
+    def enable_telemetry?
+      enable_telemetry
+    end
+
+    # Generates a deterministic key to identify configuration objects with
+    # identical configuration values.
+    def key
+      instance_variables
+        .collect { |variable| instance_variable_get(variable) }
+        .join
+    end
+  end
+end

data/lib/stripe/stripe_object.rb

@@ -1,17 +1,79 @@
+# frozen_string_literal: true
+
 module Stripe
   class StripeObject
     include Enumerable
 
-    @@permanent_attributes = Set.new([:id])
+    @@permanent_attributes = Set.new([:id]) # rubocop:disable Style/ClassVars
 
     # The default :id method is deprecated and isn't useful to us
-    if method_defined?(:id)
-      undef :id
+    undef :id if method_defined?(:id)
+
+    # Sets the given parameter name to one which is known to be an additive
+    # object.
+    #
+    # Additive objects are subobjects in the API that don't have the same
+    # semantics as most subobjects, which are fully replaced when they're set.
+    # This is best illustrated by example. The `source` parameter sent when
+    # updating a subscription is *not* additive; if we set it:
+    #
+    #     source[object]=card&source[number]=123
+    #
+    # We expect the old `source` object to have been overwritten completely. If
+    # the previous source had an `address_state` key associated with it and we
+    # didn't send one this time, that value of `address_state` is gone.
+    #
+    # By contrast, additive objects are those that will have new data added to
+    # them while keeping any existing data in place. The only known case of its
+    # use is for `metadata`, but it could in theory be more general. As an
+    # example, say we have a `metadata` object that looks like this on the
+    # server side:
+    #
+    #     metadata = { old: "old_value" }
+    #
+    # If we update the object with `metadata[new]=new_value`, the server side
+    # object now has *both* fields:
+    #
+    #     metadata = { old: "old_value", new: "new_value" }
+    #
+    # This is okay in itself because usually users will want to treat it as
+    # additive:
+    #
+    #     obj.metadata[:new] = "new_value"
+    #     obj.save
+    #
+    # However, in other cases, they may want to replace the entire existing
+    # contents:
+    #
+    #     obj.metadata = { new: "new_value" }
+    #     obj.save
+    #
+    # This is where things get a little bit tricky because in order to clear
+    # any old keys that may have existed, we actually have to send an explicit
+    # empty string to the server. So the operation above would have to send
+    # this form to get the intended behavior:
+    #
+    #     metadata[old]=&metadata[new]=new_value
+    #
+    # This method allows us to track which parameters are considered additive,
+    # and lets us behave correctly where appropriate when serializing
+    # parameters to be sent.
+    def self.additive_object_param(name)
+      @additive_params ||= Set.new
+      @additive_params << name
+    end
+
+    # Returns whether the given name is an additive object parameter. See
+    # `.additive_object_param` for details.
+    def self.additive_object_param?(name)
+      @additive_params ||= Set.new
+      @additive_params.include?(name)
     end
 
-    def initialize(id=nil, opts={})
+    def initialize(id = nil, opts = {})
       id, @retrieve_params = Util.normalize_id(id)
-      @opts = opts
+      @opts = Util.normalize_opts(opts)
+      @original_values = {}
       @values = {}
       # This really belongs in APIResource, but not putting it there allows us
       # to have a unified inspect method
@@ -20,52 +82,84 @@ module Stripe
       @values[:id] = id if id
     end
 
-    def self.construct_from(values, opts={})
-      self.new(values[:id]).refresh_from(values, opts)
+    def self.construct_from(values, opts = {})
+      values = Stripe::Util.symbolize_names(values)
+
+      # work around protected #initialize_from for now
+      new(values[:id]).send(:initialize_from, values, opts)
     end
 
-    def to_s(*args)
-      JSON.pretty_generate(@values)
+    # Determines the equality of two Stripe objects. Stripe objects are
+    # considered to be equal if they have the same set of values and each one
+    # of those values is the same.
+    def ==(other)
+      other.is_a?(StripeObject) &&
+        @values == other.instance_variable_get(:@values)
     end
 
-    def inspect
-      id_string = (self.respond_to?(:id) && !self.id.nil?) ? " id=#{self.id}" : ""
-      "#<#{self.class}:0x#{self.object_id.to_s(16)}#{id_string}> JSON: " + JSON.pretty_generate(@values)
+    # Hash equality. As with `#==`, we consider two equivalent Stripe objects
+    # equal.
+    def eql?(other)
+      # Defer to the implementation on `#==`.
+      self == other
     end
 
-    def refresh_from(values, opts, partial=false)
-      @opts = opts
-      @original_values = Marshal.load(Marshal.dump(values)) # deep copy
-      removed = partial ? Set.new : Set.new(@values.keys - values.keys)
-      added = Set.new(values.keys - @values.keys)
-      # Wipe old state before setting new.  This is useful for e.g. updating a
-      # customer, where there is no persistent card parameter.  Mark those values
-      # which don't persist as transient
+    # As with equality in `#==` and `#eql?`, we hash two Stripe objects to the
+    # same value if they're equivalent objects.
+    def hash
+      @values.hash
+    end
 
-      instance_eval do
-        remove_accessors(removed)
-        add_accessors(added)
-      end
-      removed.each do |k|
-        @values.delete(k)
-        @transient_values.add(k)
-        @unsaved_values.delete(k)
-      end
+    # Indicates whether or not the resource has been deleted on the server.
+    # Note that some, but not all, resources can indicate whether they have
+    # been deleted.
+    def deleted?
+      @values.fetch(:deleted, false)
+    end
+
+    def to_s(*_args)
+      JSON.pretty_generate(to_hash)
+    end
+
+    def inspect
+      id_string = respond_to?(:id) && !id.nil? ? " id=#{id}" : ""
+      "#<#{self.class}:0x#{object_id.to_s(16)}#{id_string}> JSON: " +
+        JSON.pretty_generate(@values)
+    end
+
+    # Mass assigns attributes on the model.
+    #
+    # This is a version of +update_attributes+ that takes some extra options
+    # for internal use.
+    #
+    # ==== Attributes
+    #
+    # * +values+ - Hash of values to use to update the current attributes of
+    #   the object. If you are on ruby 2.7 or higher make sure to wrap in curly
+    #   braces to be ruby 3 compatible.
+    # * +opts+ - Options for +StripeObject+ like an API key that will be reused
+    #   on subsequent API calls.
+    #
+    # ==== Options
+    #
+    # * +:dirty+ - Whether values should be initiated as "dirty" (unsaved) and
+    #   which applies only to new StripeObjects being initiated under this
+    #   StripeObject. Defaults to true.
+    def update_attributes(values, opts = {}, dirty: true)
       values.each do |k, v|
-        @values[k] = Util.convert_to_stripe_object(v, @opts)
-        @transient_values.delete(k)
-        @unsaved_values.delete(k)
+        add_accessors([k], values) unless metaclass.method_defined?(k.to_sym)
+        @values[k] = Util.convert_to_stripe_object(v, opts)
+        dirty_value!(@values[k]) if dirty
+        @unsaved_values.add(k)
       end
-
-      return self
     end
 
-    def [](k)
-      @values[k.to_sym]
+    def [](key)
+      @values[key.to_sym]
     end
 
-    def []=(k, v)
-      send(:"#{k}=", v)
+    def []=(key, value)
+      send(:"#{key}=", value)
     end
 
     def keys
@@ -76,18 +170,29 @@ module Stripe
       @values.values
     end
 
-    def to_json(*a)
+    def to_json(*_opts)
+      # TODO: pass opts to JSON.generate?
       JSON.generate(@values)
     end
 
-    def as_json(*a)
-      @values.as_json(*a)
+    def as_json(*opts)
+      @values.as_json(*opts)
     end
 
     def to_hash
-      @values.inject({}) do |acc, (key, value)|
-        acc[key] = value.respond_to?(:to_hash) ? value.to_hash : value
-        acc
+      maybe_to_hash = lambda do |value|
+        return nil if value.nil?
+
+        value.respond_to?(:to_hash) ? value.to_hash : value
+      end
+
+      @values.each_with_object({}) do |(key, value), acc|
+        acc[key] = case value
+                   when Array
+                     value.map(&maybe_to_hash)
+                   else
+                     maybe_to_hash.call(value)
+                   end
       end
     end
 
@@ -95,161 +200,389 @@ module Stripe
       @values.each(&blk)
     end
 
-    def _dump(level)
-      Marshal.dump([@values, @opts])
+    # Sets all keys within the StripeObject as unsaved so that they will be
+    # included with an update when #serialize_params is called. This method is
+    # also recursive, so any StripeObjects contained as values or which are
+    # values in a tenant array are also marked as dirty.
+    def dirty!
+      @unsaved_values = Set.new(@values.keys)
+      @values.each_value do |v|
+        dirty_value!(v)
+      end
     end
 
-    def self._load(args)
-      values, opts = Marshal.load(args)
-      construct_from(values, opts)
+    # Implements custom encoding for Ruby's Marshal. The data produced by this
+    # method should be comprehendable by #marshal_load.
+    #
+    # This allows us to remove certain features that cannot or should not be
+    # serialized.
+    def marshal_dump
+      # The StripeClient instance in @opts is not serializable and is not
+      # really a property of the StripeObject, so we exclude it when
+      # dumping
+      opts = @opts.clone
+      opts.delete(:client)
+      [@values, opts]
     end
 
-    if RUBY_VERSION < '1.9.2'
-      def respond_to?(symbol)
-        @values.has_key?(symbol) || super
-      end
+    # Implements custom decoding for Ruby's Marshal. Consumes data that's
+    # produced by #marshal_dump.
+    def marshal_load(data)
+      values, opts = data
+      initialize(values[:id])
+      initialize_from(values, opts)
     end
 
-    def serialize_nested_object(key)
-      new_value = @values[key]
-      if new_value.is_a?(APIResource)
-        return {}
+    def serialize_params(options = {})
+      update_hash = {}
+
+      @values.each do |k, v|
+        # There are a few reasons that we may want to add in a parameter for
+        # update:
+        #
+        #   1. The `force` option has been set.
+        #   2. We know that it was modified.
+        #   3. Its value is a StripeObject. A StripeObject may contain modified
+        #      values within in that its parent StripeObject doesn't know about.
+        #
+        unsaved = @unsaved_values.include?(k)
+        next unless options[:force] || unsaved || v.is_a?(StripeObject)
+
+        update_hash[k.to_sym] = serialize_params_value(
+          @values[k], @original_values[k], unsaved, options[:force], key: k
+        )
       end
 
-      if @unsaved_values.include?(key)
-        # the object has been reassigned
-        # e.g. as object.key = {foo => bar}
-        update = new_value
-        new_keys = update.keys.map(&:to_sym)
-
-        # remove keys at the server, but not known locally
-        if @original_values[key]
-          keys_to_unset = @original_values[key].keys - new_keys
-          keys_to_unset.each {|key| update[key] = ''}
-        end
+      # a `nil` that makes it out of `#serialize_params_value` signals an empty
+      # value that we shouldn't appear in the serialized form of the object
+      update_hash.reject! { |_, v| v.nil? }
 
-        update
-      else
-        # can be serialized normally
-        self.class.serialize_params(new_value)
-      end
+      update_hash
     end
 
-    def self.serialize_params(obj, original_value=nil)
-      case obj
-      when nil
-        ''
-      when StripeObject
-        unsaved_keys = obj.instance_variable_get(:@unsaved_values)
-        obj_values = obj.instance_variable_get(:@values)
-        update_hash = {}
-
-        unsaved_keys.each do |k|
-          update_hash[k] = serialize_params(obj_values[k])
-        end
-
-        obj_values.each do |k, v|
-          if v.is_a?(StripeObject) || v.is_a?(Hash)
-            update_hash[k] = obj.serialize_nested_object(k)
-          elsif v.is_a?(Array)
-            original_value = obj.instance_variable_get(:@original_values)[k]
-            if original_value && original_value.length > v.length
-              # url params provide no mechanism for deleting an item in an array,
-              # just overwriting the whole array or adding new items. So let's not
-              # allow deleting without a full overwrite until we have a solution.
-              raise ArgumentError.new(
-                "You cannot delete an item from an array, you must instead set a new array"
-              )
-            end
-            update_hash[k] = serialize_params(v, original_value)
-          end
-        end
-
-        update_hash
-      when Array
-        update_hash = {}
-        obj.each_with_index do |value, index|
-          update = serialize_params(value)
-          if update != {} && (!original_value || update != original_value[index])
-            update_hash[index] = update
-          end
-        end
-
-        if update_hash == {}
-          nil
-        else
-          update_hash
-        end
-      else
-        obj
-      end
+    # A protected field is one that doesn't get an accessor assigned to it
+    # (i.e. `obj.public = ...`) and one which is not allowed to be updated via
+    # the class level `Model.update(id, { ... })`.
+    def self.protected_fields
+      []
     end
 
-    protected
-
-    def metaclass
+    # When designing APIs, we now make a conscious effort server-side to avoid
+    # naming fields after important built-ins in various languages (e.g. class,
+    # method, etc.).
+    #
+    # However, a long time ago we made the mistake (either consciously or by
+    # accident) of initializing our `metadata` fields as instances of
+    # `StripeObject`, and metadata can have a wide range of different keys
+    # defined in it. This is somewhat a convenient in that it allows users to
+    # access data like `obj.metadata.my_field`, but is almost certainly not
+    # worth the cost.
+    #
+    # Naming metadata fields bad things like `class` causes `initialize_from`
+    # to produce strange results, so we ban known offenders here.
+    #
+    # In a future major version we should consider leaving `metadata` as a hash
+    # and forcing people to access it with `obj.metadata[:my_field]` because
+    # the potential for trouble is just too high. For now, reserve names.
+    RESERVED_FIELD_NAMES = [
+      :class,
+    ].freeze
+
+    protected def metaclass
       class << self; self; end
     end
 
-    def remove_accessors(keys)
+    protected def remove_accessors(keys)
+      # not available in the #instance_eval below
+      protected_fields = self.class.protected_fields
+
       metaclass.instance_eval do
         keys.each do |k|
+          next if RESERVED_FIELD_NAMES.include?(k)
+          next if protected_fields.include?(k)
           next if @@permanent_attributes.include?(k)
-          k_eq = :"#{k}="
-          remove_method(k) if method_defined?(k)
-          remove_method(k_eq) if method_defined?(k_eq)
+
+          # Remove methods for the accessor's reader and writer.
+          [k, :"#{k}=", :"#{k}?"].each do |method_name|
+            next unless method_defined?(method_name)
+
+            begin
+              remove_method(method_name)
+            rescue NameError
+              # In some cases there can be a method that's detected with
+              # `method_defined?`, but which cannot be removed with
+              # `remove_method`, even though it's on the same class. The only
+              # case so far that we've noticed this is when a class is
+              # reopened for monkey patching:
+              #
+              #     https://github.com/stripe/stripe-ruby/issues/749
+              #
+              # Here we swallow that error and issue a warning so at least
+              # the program doesn't crash.
+              warn("WARNING: Unable to remove method `#{method_name}`; " \
+                "if custom, please consider renaming to a name that doesn't " \
+                "collide with an API property name.")
+            end
+          end
         end
       end
     end
 
-    def add_accessors(keys)
+    protected def add_accessors(keys, values)
+      # not available in the #instance_eval below
+      protected_fields = self.class.protected_fields
+
       metaclass.instance_eval do
         keys.each do |k|
+          next if RESERVED_FIELD_NAMES.include?(k)
+          next if protected_fields.include?(k)
           next if @@permanent_attributes.include?(k)
-          k_eq = :"#{k}="
-          define_method(k) { @values[k] }
-          define_method(k_eq) do |v|
+
+          if k == :method
+            # Object#method is a built-in Ruby method that accepts a symbol
+            # and returns the corresponding Method object. Because the API may
+            # also use `method` as a field name, we check the arity of *args
+            # to decide whether to act as a getter or call the parent method.
+            define_method(k) { |*args| args.empty? ? @values[k] : super(*args) }
+          else
+            define_method(k) { @values[k] }
+          end
+
+          define_method(:"#{k}=") do |v|
             if v == ""
-              raise ArgumentError.new(
-                "You cannot set #{k} to an empty string." \
-                "We interpret empty strings as nil in requests." \
-                "You may set #{self}.#{k} = nil to delete the property.")
+              raise ArgumentError, "You cannot set #{k} to an empty string. " \
+                "We interpret empty strings as nil in requests. " \
+                "You may set (object).#{k} = nil to delete the property."
             end
-            @values[k] = v
+            @values[k] = Util.convert_to_stripe_object(v, @opts)
+            dirty_value!(@values[k])
             @unsaved_values.add(k)
           end
+
+          if [FalseClass, TrueClass].include?(values[k].class)
+            define_method(:"#{k}?") { @values[k] }
+          end
         end
       end
     end
 
-    def method_missing(name, *args)
+    # Disabling the cop because it's confused by the fact that the methods are
+    # protected, but we do define `#respond_to_missing?` just below. Hopefully
+    # this is fixed in more recent Rubocop versions.
+    # rubocop:disable Style/MissingRespondToMissing
+    protected def method_missing(name, *args)
       # TODO: only allow setting in updateable classes.
-      if name.to_s.end_with?('=')
+      if name.to_s.end_with?("=")
         attr = name.to_s[0...-1].to_sym
-        add_accessors([attr])
+
+        # Pull out the assigned value. This is only used in the case of a
+        # boolean value to add a question mark accessor (i.e. `foo?`) for
+        # convenience.
+        val = args.first
+
+        # the second argument is only required when adding boolean accessors
+        add_accessors([attr], attr => val)
+
         begin
           mth = method(name)
         rescue NameError
-          raise NoMethodError.new("Cannot set #{attr} on this object. HINT: you can't set: #{@@permanent_attributes.to_a.join(', ')}")
+          raise NoMethodError,
+                "Cannot set #{attr} on this object. HINT: you can't set: " \
+                "#{@@permanent_attributes.to_a.join(', ')}"
         end
         return mth.call(args[0])
-      else
-        return @values[name] if @values.has_key?(name)
+      elsif @values.key?(name)
+        return @values[name]
       end
 
       begin
         super
       rescue NoMethodError => e
-        if @transient_values.include?(name)
-          raise NoMethodError.new(e.message + ".  HINT: The '#{name}' attribute was set in the past, however.  It was then wiped when refreshing the object with the result returned by Stripe's API, probably as a result of a save().  The attributes currently available on this object are: #{@values.keys.join(', ')}")
+        # If we notice the accessed name of our set of transient values we can
+        # give the user a slightly more helpful error message. If not, just
+        # raise right away.
+        raise unless @transient_values.include?(name)
+
+        raise NoMethodError,
+              e.message + ".  HINT: The '#{name}' attribute was set in the " \
+              "past, however.  It was then wiped when refreshing the object " \
+              "with the result returned by Stripe's API, probably as a " \
+              "result of a save().  The attributes currently available on " \
+              "this object are: #{@values.keys.join(', ')}"
+      end
+    end
+    # rubocop:enable Style/MissingRespondToMissing
+
+    protected def respond_to_missing?(symbol, include_private = false)
+      @values && @values.key?(symbol) || super
+    end
+
+    # Re-initializes the object based on a hash of values (usually one that's
+    # come back from an API call). Adds or removes value accessors as necessary
+    # and updates the state of internal data.
+    #
+    # Protected on purpose! Please do not expose.
+    #
+    # ==== Options
+    #
+    # * +:values:+ Hash used to update accessors and values.
+    # * +:opts:+ Options for StripeObject like an API key.
+    # * +:partial:+ Indicates that the re-initialization should not attempt to
+    #   remove accessors.
+    protected def initialize_from(values, opts, partial = false)
+      @opts = Util.normalize_opts(opts)
+
+      # the `#send` is here so that we can keep this method private
+      @original_values = self.class.send(:deep_copy, values)
+
+      removed = partial ? Set.new : Set.new(@values.keys - values.keys)
+      added = Set.new(values.keys - @values.keys)
+
+      # Wipe old state before setting new.  This is useful for e.g. updating a
+      # customer, where there is no persistent card parameter.  Mark those
+      # values which don't persist as transient
+
+      remove_accessors(removed)
+      add_accessors(added, values)
+
+      removed.each do |k|
+        @values.delete(k)
+        @transient_values.add(k)
+        @unsaved_values.delete(k)
+      end
+
+      update_attributes(values, opts, dirty: false)
+      values.each_key do |k|
+        @transient_values.delete(k)
+        @unsaved_values.delete(k)
+      end
+
+      self
+    end
+
+    protected def serialize_params_value(value, original, unsaved, force,
+                                         key: nil)
+      if value.nil?
+        ""
+
+      # The logic here is that essentially any object embedded in another
+      # object that had a `type` is actually an API resource of a different
+      # type that's been included in the response. These other resources must
+      # be updated from their proper endpoints, and therefore they are not
+      # included when serializing even if they've been modified.
+      #
+      # There are _some_ known exceptions though.
+      #
+      # For example, if the value is unsaved (meaning the user has set it), and
+      # it looks like the API resource is persisted with an ID, then we include
+      # the object so that parameters are serialized with a reference to its
+      # ID.
+      #
+      # Another example is that on save API calls it's sometimes desirable to
+      # update a customer's default source by setting a new card (or other)
+      # object with `#source=` and then saving the customer. The
+      # `#save_with_parent` flag to override the default behavior allows us to
+      # handle these exceptions.
+      #
+      # We throw an error if a property was set explicitly but we can't do
+      # anything with it because the integration is probably not working as the
+      # user intended it to.
+      elsif value.is_a?(APIResource) && !value.save_with_parent
+        if !unsaved
+          nil
+        elsif value.respond_to?(:id) && !value.id.nil?
+          value
         else
-          raise
+          raise ArgumentError, "Cannot save property `#{key}` containing " \
+            "an API resource. It doesn't appear to be persisted and is " \
+            "not marked as `save_with_parent`."
         end
+
+      elsif value.is_a?(Array)
+        update = value.map { |v| serialize_params_value(v, nil, true, force) }
+
+        # This prevents an array that's unchanged from being resent.
+        update if update != serialize_params_value(original, nil, true, force)
+
+      # Handle a Hash for now, but in the long run we should be able to
+      # eliminate all places where hashes are stored as values internally by
+      # making sure any time one is set, we convert it to a StripeObject. This
+      # will simplify our model by making data within an object more
+      # consistent.
+      #
+      # For now, you can still run into a hash if someone appends one to an
+      # existing array being held by a StripeObject. This could happen for
+      # example by appending a new hash onto `additional_owners` for an
+      # account.
+      elsif value.is_a?(Hash)
+        Util.convert_to_stripe_object(value, @opts).serialize_params
+
+      elsif value.is_a?(StripeObject)
+        update = value.serialize_params(force: force)
+
+        # If the entire object was replaced and this is an additive object,
+        # then we need blank each field of the old object that held a value
+        # because otherwise the update to the keys of the object will be
+        # additive instead of a full replacement. The new serialized values
+        # will override any of these empty values.
+        if original && unsaved && key && self.class.additive_object_param?(key)
+          update = empty_values(original).merge(update)
+        end
+
+        update
+
+      else
+        value
       end
     end
 
-    def respond_to_missing?(symbol, include_private = false)
-      @values && @values.has_key?(symbol) || super
+    # Produces a deep copy of the given object including support for arrays,
+    # hashes, and StripeObjects.
+    private_class_method def self.deep_copy(obj)
+      case obj
+      when Array
+        obj.map { |e| deep_copy(e) }
+      when Hash
+        obj.each_with_object({}) do |(k, v), copy|
+          copy[k] = deep_copy(v)
+          copy
+        end
+      when StripeObject
+        obj.class.construct_from(
+          deep_copy(obj.instance_variable_get(:@values)),
+          obj.instance_variable_get(:@opts).select do |k, _v|
+            Util::OPTS_COPYABLE.include?(k)
+          end
+        )
+      else
+        obj
+      end
+    end
+
+    private def dirty_value!(value)
+      case value
+      when Array
+        value.map { |v| dirty_value!(v) }
+      when StripeObject
+        value.dirty!
+      end
+    end
+
+    # Returns a hash of empty values for all the values that are in the given
+    # StripeObject.
+    private def empty_values(obj)
+      values = case obj
+               when Hash         then obj
+               when StripeObject then obj.instance_variable_get(:@values)
+               else
+                 raise ArgumentError,
+                       "#empty_values got unexpected object type: " \
+                       "#{obj.class.name}"
+               end
+
+      values.each_with_object({}) do |(k, _), update|
+        update[k] = ""
+      end
     end
   end
 end