stripe 5.55.0 → 13.5.1

data/lib/stripe/resources/exchange_rate.rb

@@ -2,9 +2,43 @@
 # frozen_string_literal: true
 
 module Stripe
+  # `ExchangeRate` 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).
+  #
+  # Please refer to our [Exchange Rates API](https://stripe.com/docs/fx-rates) guide for more details.
+  #
+  # *[Note: this integration path is supported but no longer recommended]* Additionally,
+  # you can guarantee that a charge is made with an exchange rate that you expect is
+  # current. To do so, you must pass in the exchange_rate to charges endpoints. If the
+  # value is no longer up to date, the charge won't go through. Please refer to our
+  # [Using with charges](https://stripe.com/docs/exchange-rates) guide for more details.
+  #
+  # -----
+  #
+  #  
+  #
+  # *This Exchange Rates API is a Beta Service and is subject to Stripe's terms of service. You may use the API solely for the purpose of transacting on Stripe. For example, the API may be queried in order to:*
+  #
+  # - *localize prices for processing payments on Stripe*
+  # - *reconcile Stripe transactions*
+  # - *determine how much money to send to a connected account*
+  # - *determine app fees to charge a connected account*
+  #
+  # *Using this Exchange Rates API beta for any purpose other than to transact on Stripe is strictly prohibited and constitutes a violation of Stripe's terms of service.*
   class ExchangeRate < APIResource
     extend Stripe::APIOperations::List
 
     OBJECT_NAME = "exchange_rate"
+    def self.object_name
+      "exchange_rate"
+    end
+
+    # Returns a list of objects that contain the rates at which foreign currencies are converted to one another. Only shows the currencies for which Stripe supports.
+    def self.list(params = {}, opts = {})
+      request_stripe_object(method: :get, path: "/v1/exchange_rates", params: params, opts: opts)
+    end
   end
 end

data/lib/stripe/resources/file.rb

@@ -2,35 +2,57 @@
 # frozen_string_literal: true
 
 module Stripe
+  # This object represents files hosted on Stripe's servers. You can upload
+  # files with the [create file](https://stripe.com/docs/api#create_file) request
+  # (for example, when uploading dispute evidence). Stripe also
+  # creates files independently (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
 
     OBJECT_NAME = "file"
+    def self.object_name
+      "file"
+    end
+
+    # To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file.
+    #
+    # All of Stripe's officially supported Client libraries support sending multipart/form-data.
+    def self.create(params = {}, opts = {})
+      if params[:file] && !params[:file].is_a?(String) && !params[:file].respond_to?(:read)
+        raise ArgumentError, "file must respond to `#read`"
+      end
+
+      opts = { content_type: MultipartEncoder::MULTIPART_FORM_DATA }.merge(Util.normalize_opts(opts))
+
+      request_stripe_object(
+        method: :post,
+        path: "/v1/files",
+        params: params,
+        opts: opts,
+        base_address: :files
+      )
+    end
+
+    # Returns a list of the files that your account has access to. Stripe sorts and returns the files by their creation dates, placing the most recently created files at the top.
+    def self.list(params = {}, opts = {})
+      request_stripe_object(method: :get, path: "/v1/files", params: params, opts: opts)
+    end
 
     # This resource can have two different object names. In latter API
     # versions, only `file` is used, but since stripe-ruby may be used with
     # any API version, we need to support deserializing the older
     # `file_upload` object into the same class.
     OBJECT_NAME_ALT = "file_upload"
+    def self.object_name_alt
+      "file_upload"
+    end
 
     def self.resource_url
       "/v1/files"
     end
-
-    def self.create(params = {}, opts = {})
-      if params[:file] && !params[:file].is_a?(String)
-        unless params[:file].respond_to?(:read)
-          raise ArgumentError, "file must respond to `#read`"
-        end
-      end
-
-      config = opts[:client]&.config || Stripe.config
-      opts = {
-        api_base: config.uploads_base,
-        content_type: MultipartEncoder::MULTIPART_FORM_DATA,
-      }.merge(Util.normalize_opts(opts))
-      super
-    end
   end
 end

data/lib/stripe/resources/file_link.rb

@@ -2,11 +2,37 @@
 # 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 you can use to
+  # retrieve the contents of the file without authentication.
   class FileLink < APIResource
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List
     include Stripe::APIOperations::Save
 
     OBJECT_NAME = "file_link"
+    def self.object_name
+      "file_link"
+    end
+
+    # Creates a new file link object.
+    def self.create(params = {}, opts = {})
+      request_stripe_object(method: :post, path: "/v1/file_links", params: params, opts: opts)
+    end
+
+    # Returns a list of file links.
+    def self.list(params = {}, opts = {})
+      request_stripe_object(method: :get, path: "/v1/file_links", params: params, opts: opts)
+    end
+
+    # Updates an existing file link object. Expired links can no longer be updated.
+    def self.update(link, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/file_links/%<link>s", { link: CGI.escape(link) }),
+        params: params,
+        opts: opts
+      )
+    end
   end
 end

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

@@ -3,25 +3,120 @@
 
 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
-      OBJECT_NAME = "financial_connections.account"
+      extend Stripe::APIOperations::List
 
-      custom_method :disconnect, http_verb: :post
-      custom_method :refresh, http_verb: :post
+      OBJECT_NAME = "financial_connections.account"
+      def self.object_name
+        "financial_connections.account"
+      end
 
+      # Disables your access to a Financial Connections Account. You will no longer be able to access data associated with the account (e.g. balances, transactions).
       def disconnect(params = {}, opts = {})
         request_stripe_object(
           method: :post,
-          path: resource_url + "/disconnect",
+          path: format("/v1/financial_connections/accounts/%<account>s/disconnect", { account: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Disables your access to a Financial Connections Account. You will no longer be able to access data associated with the account (e.g. balances, transactions).
+      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
+
+      # Returns a list of Financial Connections Account objects.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/financial_connections/accounts",
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Lists all owners for a given Account
+      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
+
+      # Lists all owners for a given Account
+      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
+
+      # Refreshes the data associated with a Financial Connections Account.
+      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
+
+      # Refreshes the data associated with a Financial Connections Account.
+      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
+
+      # Subscribes to periodic refreshes of data associated with a Financial Connections Account.
+      def subscribe(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/financial_connections/accounts/%<account>s/subscribe", { account: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Subscribes to periodic refreshes of data associated with a Financial Connections Account.
+      def self.subscribe(account, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/financial_connections/accounts/%<account>s/subscribe", { account: CGI.escape(account) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Unsubscribes from periodic refreshes of data associated with a Financial Connections Account.
+      def unsubscribe(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/financial_connections/accounts/%<account>s/unsubscribe", { account: CGI.escape(self["id"]) }),
           params: params,
           opts: opts
         )
       end
 
-      def refresh(params = {}, opts = {})
+      # Unsubscribes from periodic refreshes of data associated with a Financial Connections Account.
+      def self.unsubscribe(account, params = {}, opts = {})
         request_stripe_object(
           method: :post,
-          path: resource_url + "/refresh",
+          path: format("/v1/financial_connections/accounts/%<account>s/unsubscribe", { account: CGI.escape(account) }),
           params: params,
           opts: opts
         )

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

@@ -3,8 +3,12 @@
 
 module Stripe
   module FinancialConnections
+    # Describes an owner of an account.
     class AccountOwner < StripeObject
       OBJECT_NAME = "financial_connections.account_owner"
+      def self.object_name
+        "financial_connections.account_owner"
+      end
     end
   end
 end

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

@@ -3,8 +3,12 @@
 
 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"
+      def self.object_name
+        "financial_connections.account_ownership"
+      end
     end
   end
 end

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

@@ -3,10 +3,24 @@
 
 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"
+      def self.object_name
+        "financial_connections.session"
+      end
+
+      # To launch the Financial Connections authorization flow, create a Session. The session's client_secret can be used to launch the flow using Stripe.js.
+      def self.create(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: "/v1/financial_connections/sessions",
+          params: params,
+          opts: opts
+        )
+      end
     end
   end
 end

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

@@ -0,0 +1,26 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  module FinancialConnections
+    # A Transaction represents a real transaction that affects a Financial Connections Account balance.
+    class Transaction < APIResource
+      extend Stripe::APIOperations::List
+
+      OBJECT_NAME = "financial_connections.transaction"
+      def self.object_name
+        "financial_connections.transaction"
+      end
+
+      # Returns a list of Financial Connections Transaction objects.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/financial_connections/transactions",
+          params: params,
+          opts: opts
+        )
+      end
+    end
+  end
+end

data/lib/stripe/resources/forwarding/request.rb

@@ -0,0 +1,52 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  module Forwarding
+    # Instructs Stripe to make a request on your behalf using the destination URL. The destination URL
+    # is activated by Stripe at the time of onboarding. Stripe verifies requests with your credentials
+    # provided during onboarding, and injects card details from the payment_method into the request.
+    #
+    # Stripe redacts all sensitive fields and headers, including authentication credentials and card numbers,
+    # before storing the request and response data in the forwarding Request object, which are subject to a
+    # 30-day retention period.
+    #
+    # You can provide a Stripe idempotency key to make sure that requests with the same key result in only one
+    # outbound request. The Stripe idempotency key provided should be unique and different from any idempotency
+    # keys provided on the underlying third-party request.
+    #
+    # Forwarding Requests are synchronous requests that return a response or time out according to
+    # Stripe's limits.
+    #
+    # Related guide: [Forward card details to third-party API endpoints](https://docs.stripe.com/payments/forwarding).
+    class Request < APIResource
+      extend Stripe::APIOperations::Create
+      extend Stripe::APIOperations::List
+
+      OBJECT_NAME = "forwarding.request"
+      def self.object_name
+        "forwarding.request"
+      end
+
+      # Creates a ForwardingRequest object.
+      def self.create(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: "/v1/forwarding/requests",
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Lists all ForwardingRequest objects.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/forwarding/requests",
+          params: params,
+          opts: opts
+        )
+      end
+    end
+  end
+end

data/lib/stripe/resources/funding_instructions.rb

@@ -2,8 +2,16 @@
 # 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 self.object_name
+      "funding_instructions"
+    end
 
     def resource_url
       if !respond_to?(:customer) || customer.nil?

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

@@ -3,10 +3,34 @@
 
 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 guide: [Accessing verification results](https://stripe.com/docs/identity/verification-sessions#results).
     class VerificationReport < APIResource
       extend Stripe::APIOperations::List
 
       OBJECT_NAME = "identity.verification_report"
+      def self.object_name
+        "identity.verification_report"
+      end
+
+      # List all verification reports.
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/identity/verification_reports",
+          params: params,
+          opts: opts
+        )
+      end
     end
   end
 end

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

@@ -3,29 +3,141 @@
 
 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 self.object_name
+        "identity.verification_session"
+      end
 
-      custom_method :cancel, http_verb: :post
-      custom_method :redact, http_verb: :post
-
+      # A VerificationSession object can be canceled when it is in requires_input [status](https://stripe.com/docs/identity/how-sessions-work).
+      #
+      # Once canceled, future submission attempts are disabled. This cannot be undone. [Learn more](https://stripe.com/docs/identity/verification-sessions#cancel).
       def cancel(params = {}, opts = {})
         request_stripe_object(
           method: :post,
-          path: resource_url + "/cancel",
+          path: format("/v1/identity/verification_sessions/%<session>s/cancel", { session: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # A VerificationSession object can be canceled when it is in requires_input [status](https://stripe.com/docs/identity/how-sessions-work).
+      #
+      # Once canceled, future submission attempts are disabled. This cannot be undone. [Learn more](https://stripe.com/docs/identity/verification-sessions#cancel).
+      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
+
+      # Creates a VerificationSession object.
+      #
+      # After the VerificationSession is created, display a verification modal using the session client_secret or send your users to the session's url.
+      #
+      # If your API key is in test mode, verification checks won't actually process, though everything else will occur as if in live mode.
+      #
+      # Related guide: [Verify your users' identity documents](https://stripe.com/docs/identity/verify-identity-documents)
+      def self.create(params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: "/v1/identity/verification_sessions",
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Returns a list of VerificationSessions
+      def self.list(params = {}, opts = {})
+        request_stripe_object(
+          method: :get,
+          path: "/v1/identity/verification_sessions",
           params: params,
           opts: opts
         )
       end
 
+      # Redact a VerificationSession to remove all collected information from Stripe. This will redact
+      # the VerificationSession and all objects related to it, including VerificationReports, Events,
+      # request logs, etc.
+      #
+      # A VerificationSession object can be redacted when it is in requires_input or verified
+      # [status](https://stripe.com/docs/identity/how-sessions-work). Redacting a VerificationSession in requires_action
+      # state will automatically cancel it.
+      #
+      # The redaction process may take up to four days. When the redaction process is in progress, the
+      # VerificationSession's redaction.status field will be set to processing; when the process is
+      # finished, it will change to redacted and an identity.verification_session.redacted event
+      # will be emitted.
+      #
+      # Redaction is irreversible. Redacted objects are still accessible in the Stripe API, but all the
+      # fields that contain personal data will be replaced by the string [redacted] or a similar
+      # placeholder. The metadata field will also be erased. Redacted objects cannot be updated or
+      # used for any purpose.
+      #
+      # [Learn more](https://stripe.com/docs/identity/verification-sessions#redact).
       def redact(params = {}, opts = {})
         request_stripe_object(
           method: :post,
-          path: resource_url + "/redact",
+          path: format("/v1/identity/verification_sessions/%<session>s/redact", { session: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      # Redact a VerificationSession to remove all collected information from Stripe. This will redact
+      # the VerificationSession and all objects related to it, including VerificationReports, Events,
+      # request logs, etc.
+      #
+      # A VerificationSession object can be redacted when it is in requires_input or verified
+      # [status](https://stripe.com/docs/identity/how-sessions-work). Redacting a VerificationSession in requires_action
+      # state will automatically cancel it.
+      #
+      # The redaction process may take up to four days. When the redaction process is in progress, the
+      # VerificationSession's redaction.status field will be set to processing; when the process is
+      # finished, it will change to redacted and an identity.verification_session.redacted event
+      # will be emitted.
+      #
+      # Redaction is irreversible. Redacted objects are still accessible in the Stripe API, but all the
+      # fields that contain personal data will be replaced by the string [redacted] or a similar
+      # placeholder. The metadata field will also be erased. Redacted objects cannot be updated or
+      # used for any purpose.
+      #
+      # [Learn more](https://stripe.com/docs/identity/verification-sessions#redact).
+      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
+
+      # Updates a VerificationSession object.
+      #
+      # When the session status is requires_input, you can use this method to update the
+      # verification check and options.
+      def self.update(session, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/identity/verification_sessions/%<session>s", { session: CGI.escape(session) }),
           params: params,
           opts: opts
         )