stripe 5.28.0 → 8.7.0

data/lib/stripe/resources/customer.rb

@@ -2,10 +2,14 @@
 # frozen_string_literal: true
 
 module Stripe
+  # This object represents a customer of your business. It lets you create recurring charges and track payments that belong to the same customer.
+  #
+  # Related guide: [Save a card during payment](https://stripe.com/docs/payments/save-during-payment)
   class Customer < APIResource
     extend Stripe::APIOperations::Create
     include Stripe::APIOperations::Delete
     extend Stripe::APIOperations::List
+    extend Stripe::APIOperations::Search
     include Stripe::APIOperations::Save
     extend Stripe::APIOperations::NestedResource
 
@@ -13,10 +17,87 @@ module Stripe
 
     nested_resource_class_methods :balance_transaction,
                                   operations: %i[create retrieve update list]
+    nested_resource_class_methods :cash_balance_transaction,
+                                  operations: %i[retrieve list]
     nested_resource_class_methods :tax_id,
                                   operations: %i[create retrieve delete list]
 
-    custom_method :delete_discount, http_verb: :delete, http_path: "discount"
+    def create_funding_instructions(params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/customers/%<customer>s/funding_instructions", { customer: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def delete_discount(params = {}, opts = {})
+      request_stripe_object(
+        method: :delete,
+        path: format("/v1/customers/%<customer>s/discount", { customer: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def list_payment_methods(params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/customers/%<customer>s/payment_methods", { customer: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def retrieve_payment_method(payment_method, params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/customers/%<customer>s/payment_methods/%<payment_method>s", { customer: CGI.escape(self["id"]), payment_method: CGI.escape(payment_method) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.create_funding_instructions(customer, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/customers/%<customer>s/funding_instructions", { customer: CGI.escape(customer) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.delete_discount(customer, params = {}, opts = {})
+      request_stripe_object(
+        method: :delete,
+        path: format("/v1/customers/%<customer>s/discount", { customer: CGI.escape(customer) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.list_payment_methods(customer, params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/customers/%<customer>s/payment_methods", { customer: CGI.escape(customer) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.retrieve_payment_method(
+      customer,
+      payment_method,
+      params = {},
+      opts = {}
+    )
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/customers/%<customer>s/payment_methods/%<payment_method>s", { customer: CGI.escape(customer), payment_method: CGI.escape(payment_method) }),
+        params: params,
+        opts: opts
+      )
+    end
 
     save_nested_resource :source
     nested_resource_class_methods :source,
@@ -28,9 +109,56 @@ module Stripe
       alias detach_source delete_source
     end
 
-    def delete_discount
-      resp, opts = execute_resource_request(:delete, resource_url + "/discount")
-      initialize_from(resp.data, opts, true)
+    def self.search(params = {}, opts = {})
+      _search("/v1/customers/search", params, opts)
+    end
+
+    def self.search_auto_paging_each(params = {}, opts = {}, &blk)
+      search(params, opts).auto_paging_each(&blk)
+    end
+
+    def self.retrieve_cash_balance(customer, params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/customers/%<customer>s/cash_balance", { customer: CGI.escape(customer) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.update_cash_balance(customer, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/customers/%<customer>s/cash_balance", { customer: CGI.escape(customer) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def test_helpers
+      TestHelpers.new(self)
+    end
+
+    class TestHelpers < APIResourceTestHelpers
+      RESOURCE_CLASS = Customer
+
+      def self.fund_cash_balance(customer, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/test_helpers/customers/%<customer>s/fund_cash_balance", { customer: CGI.escape(customer) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def fund_cash_balance(params = {}, opts = {})
+        @resource.request_stripe_object(
+          method: :post,
+          path: format("/v1/test_helpers/customers/%<customer>s/fund_cash_balance", { customer: CGI.escape(@resource["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
     end
   end
 end

data/lib/stripe/resources/customer_balance_transaction.rb

@@ -1,6 +1,13 @@
+# File generated from our OpenAPI spec
 # frozen_string_literal: true
 
 module Stripe
+  # Each customer has a [Balance](https://stripe.com/docs/api/customers/object#customer_object-balance) value,
+  # which denotes a debit or credit that's automatically applied to their next invoice upon finalization.
+  # You may modify the value directly by using the [update customer API](https://stripe.com/docs/api/customers/update),
+  # or by creating a Customer Balance Transaction, which increments or decrements the customer's `balance` by the specified `amount`.
+  #
+  # Related guide: [Customer balance](https://stripe.com/docs/billing/customer/balance)
   class CustomerBalanceTransaction < APIResource
     extend Stripe::APIOperations::List
     include Stripe::APIOperations::Save
@@ -18,13 +25,13 @@ module Stripe
     def self.retrieve(_id, _opts = {})
       raise NotImplementedError,
             "Customer Balance Transactions cannot be retrieved without a customer ID. " \
-            "Retrieve a Customer Balance Transaction using Customer.retrieve_balance_transaction('cus_123', 'cbtxn_123')"
+            "Retrieve a Customer Balance Transaction using `Customer.retrieve_balance_transaction('cus_123', 'cbtxn_123')`"
     end
 
     def self.update(_id, _params = nil, _opts = nil)
       raise NotImplementedError,
             "Customer Balance Transactions cannot be retrieved without a customer ID. " \
-            "Update a Customer Balance Transaction using Customer.update_balance_transaction('cus_123', 'cbtxn_123', params)"
+            "Update a Customer Balance Transaction using `Customer.update_balance_transaction('cus_123', 'cbtxn_123', params)`"
     end
   end
 end

data/lib/stripe/resources/customer_cash_balance_transaction.rb

@@ -0,0 +1,14 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  # Customers with certain payments enabled have a cash balance, representing funds that were paid
+  # by the customer to a merchant, but have not yet been allocated to a payment. Cash Balance Transactions
+  # represent when funds are moved into or out of this balance. This includes funding by the customer, allocation
+  # to payments, and refunds to the customer.
+  class CustomerCashBalanceTransaction < APIResource
+    extend Stripe::APIOperations::List
+
+    OBJECT_NAME = "customer_cash_balance_transaction"
+  end
+end

data/lib/stripe/resources/discount.rb

@@ -1,6 +1,11 @@
+# File generated from our OpenAPI spec
 # frozen_string_literal: true
 
 module Stripe
+  # A discount represents the actual application of a [coupon](https://stripe.com/docs/api#coupons) or [promotion code](https://stripe.com/docs/api#promotion_codes).
+  # It contains information about when the discount began, when it will end, and what it is applied to.
+  #
+  # Related guide: [Applying discounts to subscriptions](https://stripe.com/docs/billing/subscriptions/discounts)
   class Discount < StripeObject
     OBJECT_NAME = "discount"
   end

data/lib/stripe/resources/dispute.rb

@@ -2,18 +2,32 @@
 # frozen_string_literal: true
 
 module Stripe
+  # A dispute occurs when a customer questions your charge with their card issuer.
+  # When this happens, you're given the opportunity to respond to the dispute with
+  # evidence that shows that the charge is legitimate. You can find more
+  # information about the dispute process in our [Disputes and
+  # Fraud](https://stripe.com/docs/disputes) documentation.
+  #
+  # Related guide: [Disputes and fraud](https://stripe.com/docs/disputes)
   class Dispute < APIResource
     extend Stripe::APIOperations::List
     include Stripe::APIOperations::Save
 
     OBJECT_NAME = "dispute"
 
-    custom_method :close, http_verb: :post
-
     def close(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/close",
+        path: format("/v1/disputes/%<dispute>s/close", { dispute: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.close(dispute, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/disputes/%<dispute>s/close", { dispute: CGI.escape(dispute) }),
         params: params,
         opts: opts
       )

data/lib/stripe/resources/event.rb

@@ -2,6 +2,35 @@
 # frozen_string_literal: true
 
 module Stripe
+  # Events are our way of letting you know when something interesting happens in
+  # your account. When an interesting event occurs, we create a new `Event`
+  # object. For example, when a charge succeeds, we create a `charge.succeeded`
+  # event; and when an invoice payment attempt fails, we create an
+  # `invoice.payment_failed` event. Note that many API requests may cause multiple
+  # events to be created. For example, if you create a new subscription for a
+  # customer, you will receive both a `customer.subscription.created` event and a
+  # `charge.succeeded` event.
+  #
+  # Events occur when the state of another API resource changes. The state of that
+  # resource at the time of the change is embedded in the event's data field. For
+  # example, a `charge.succeeded` event will contain a charge, and an
+  # `invoice.payment_failed` event will contain an invoice.
+  #
+  # As with other API resources, you can use endpoints to retrieve an
+  # [individual event](https://stripe.com/docs/api#retrieve_event) or a [list of events](https://stripe.com/docs/api#list_events)
+  # from the API. We also have a separate
+  # [webhooks](http://en.wikipedia.org/wiki/Webhook) system for sending the
+  # `Event` objects directly to an endpoint on your server. Webhooks are managed
+  # in your
+  # [account settings](https://dashboard.stripe.com/account/webhooks),
+  # and our [Using Webhooks](https://stripe.com/docs/webhooks) guide will help you get set up.
+  #
+  # When using [Connect](https://stripe.com/docs/connect), you can also receive notifications of
+  # events that occur in connected accounts. For these events, there will be an
+  # additional `account` attribute in the received `Event` object.
+  #
+  # **NOTE:** Right now, access to events through the [Retrieve Event API](https://stripe.com/docs/api#retrieve_event) is
+  # guaranteed only for 30 days.
   class Event < APIResource
     extend Stripe::APIOperations::List
 

data/lib/stripe/resources/exchange_rate.rb

@@ -2,6 +2,17 @@
 # frozen_string_literal: true
 
 module Stripe
+  # `Exchange Rate` objects allow you to determine the rates that Stripe is
+  # currently using to convert from one currency to another. Since this number is
+  # variable throughout the day, there are various reasons why you might want to
+  # know the current rate (for example, to dynamically price an item for a user
+  # with a default payment in a foreign currency).
+  #
+  # If you want a guarantee that the charge is made with a certain exchange rate
+  # you expect is current, you can pass in `exchange_rate` to charges endpoints.
+  # If the value is no longer up to date, the charge won't go through. Please
+  # refer to our [Exchange Rates API](https://stripe.com/docs/exchange-rates) guide for more
+  # details.
   class ExchangeRate < APIResource
     extend Stripe::APIOperations::List
 

data/lib/stripe/resources/file.rb

@@ -2,6 +2,13 @@
 # frozen_string_literal: true
 
 module Stripe
+  # This is an object representing a file hosted on Stripe's servers. The
+  # file may have been uploaded by yourself using the [create file](https://stripe.com/docs/api#create_file)
+  # request (for example, when uploading dispute evidence) or it may have
+  # been created by Stripe (for example, the results of a [Sigma scheduled
+  # query](https://stripe.com/docs/api#scheduled_queries)).
+  #
+  # Related guide: [File upload guide](https://stripe.com/docs/file-upload)
   class File < APIResource
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List
@@ -25,8 +32,9 @@ module Stripe
         end
       end
 
+      config = opts[:client]&.config || Stripe.config
       opts = {
-        api_base: Stripe.uploads_base,
+        api_base: config.uploads_base,
         content_type: MultipartEncoder::MULTIPART_FORM_DATA,
       }.merge(Util.normalize_opts(opts))
       super

data/lib/stripe/resources/file_link.rb

@@ -2,6 +2,9 @@
 # frozen_string_literal: true
 
 module Stripe
+  # To share the contents of a `File` object with non-Stripe users, you can
+  # create a `FileLink`. `FileLink`s contain a URL that can be used to
+  # retrieve the contents of the file without authentication.
   class FileLink < APIResource
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List

data/lib/stripe/resources/financial_connections/account.rb

@@ -0,0 +1,67 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  module FinancialConnections
+    # A Financial Connections Account represents an account that exists outside of Stripe, to which you have been granted some degree of access.
+    class Account < APIResource
+      extend Stripe::APIOperations::List
+
+      OBJECT_NAME = "financial_connections.account"
+
+      def disconnect(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/financial_connections/accounts/%<account>s/disconnect", { account: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def list_owners(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: format("/v1/financial_connections/accounts/%<account>s/owners", { account: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def refresh_account(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/financial_connections/accounts/%<account>s/refresh", { account: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def self.disconnect(account, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/financial_connections/accounts/%<account>s/disconnect", { account: CGI.escape(account) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def self.list_owners(account, params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: format("/v1/financial_connections/accounts/%<account>s/owners", { account: CGI.escape(account) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def self.refresh_account(account, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/financial_connections/accounts/%<account>s/refresh", { account: CGI.escape(account) }),
+          params: params,
+          opts: opts
+        )
+      end
+    end
+  end
+end

data/lib/stripe/resources/financial_connections/account_owner.rb

@@ -0,0 +1,11 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  module FinancialConnections
+    # Describes an owner of an account.
+    class AccountOwner < StripeObject
+      OBJECT_NAME = "financial_connections.account_owner"
+    end
+  end
+end

data/lib/stripe/resources/financial_connections/account_ownership.rb

@@ -0,0 +1,11 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  module FinancialConnections
+    # Describes a snapshot of the owners of an account at a particular point in time.
+    class AccountOwnership < StripeObject
+      OBJECT_NAME = "financial_connections.account_ownership"
+    end
+  end
+end

data/lib/stripe/resources/financial_connections/session.rb

@@ -0,0 +1,13 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  module FinancialConnections
+    # A Financial Connections Session is the secure way to programmatically launch the client-side Stripe.js modal that lets your users link their accounts.
+    class Session < APIResource
+      extend Stripe::APIOperations::Create
+
+      OBJECT_NAME = "financial_connections.session"
+    end
+  end
+end

data/lib/stripe/resources/funding_instructions.rb

@@ -0,0 +1,21 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  # Each customer has a [`balance`](https://stripe.com/docs/api/customers/object#customer_object-balance) that is
+  # automatically applied to future invoices and payments using the `customer_balance` payment method.
+  # Customers can fund this balance by initiating a bank transfer to any account in the
+  # `financial_addresses` field.
+  # Related guide: [Customer balance funding instructions](https://stripe.com/docs/payments/customer-balance/funding-instructions)
+  class FundingInstructions < APIResource
+    OBJECT_NAME = "funding_instructions"
+
+    def resource_url
+      if !respond_to?(:customer) || customer.nil?
+        raise NotImplementedError,
+              "FundingInstructions cannot be accessed without a customer ID."
+      end
+      "#{Customer.resource_url}/#{CGI.escape(customer)}/funding_instructions" "/#{CGI.escape(id)}"
+    end
+  end
+end

data/lib/stripe/resources/identity/verification_report.rb

@@ -0,0 +1,23 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  module Identity
+    # A VerificationReport is the result of an attempt to collect and verify data from a user.
+    # The collection of verification checks performed is determined from the `type` and `options`
+    # parameters used. You can find the result of each verification check performed in the
+    # appropriate sub-resource: `document`, `id_number`, `selfie`.
+    #
+    # Each VerificationReport contains a copy of any data collected by the user as well as
+    # reference IDs which can be used to access collected images through the [FileUpload](https://stripe.com/docs/api/files)
+    # API. To configure and create VerificationReports, use the
+    # [VerificationSession](https://stripe.com/docs/api/identity/verification_sessions) API.
+    #
+    # Related guides: [Accessing verification results](https://stripe.com/docs/identity/verification-sessions#results).
+    class VerificationReport < APIResource
+      extend Stripe::APIOperations::List
+
+      OBJECT_NAME = "identity.verification_report"
+    end
+  end
+end

data/lib/stripe/resources/identity/verification_session.rb

@@ -0,0 +1,61 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  module Identity
+    # A VerificationSession guides you through the process of collecting and verifying the identities
+    # of your users. It contains details about the type of verification, such as what [verification
+    # check](https://stripe.com/docs/identity/verification-checks) to perform. Only create one VerificationSession for
+    # each verification in your system.
+    #
+    # A VerificationSession transitions through [multiple
+    # statuses](https://stripe.com/docs/identity/how-sessions-work) throughout its lifetime as it progresses through
+    # the verification flow. The VerificationSession contains the user's verified data after
+    # verification checks are complete.
+    #
+    # Related guide: [The Verification Sessions API](https://stripe.com/docs/identity/verification-sessions)
+    class VerificationSession < APIResource
+      extend Stripe::APIOperations::Create
+      extend Stripe::APIOperations::List
+      include Stripe::APIOperations::Save
+
+      OBJECT_NAME = "identity.verification_session"
+
+      def cancel(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/identity/verification_sessions/%<session>s/cancel", { session: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def redact(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/identity/verification_sessions/%<session>s/redact", { session: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def self.cancel(session, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/identity/verification_sessions/%<session>s/cancel", { session: CGI.escape(session) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def self.redact(session, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/identity/verification_sessions/%<session>s/redact", { session: CGI.escape(session) }),
+          params: params,
+          opts: opts
+        )
+      end
+    end
+  end
+end