stripe 5.41.0 → 9.0.0

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

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

@@ -3,6 +3,17 @@
 
 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
 

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

@@ -3,6 +3,17 @@
 
 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
@@ -10,13 +21,10 @@ module Stripe
 
       OBJECT_NAME = "identity.verification_session"
 
-      custom_method :cancel, http_verb: :post
-      custom_method :redact, http_verb: :post
-
       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
         )
@@ -25,7 +33,25 @@ module Stripe
       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
+
+      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
         )

data/lib/stripe/resources/invoice.rb

@@ -2,24 +2,51 @@
 # frozen_string_literal: true
 
 module Stripe
+  # Invoices are statements of amounts owed by a customer, and are either
+  # generated one-off, or generated periodically from a subscription.
+  #
+  # They contain [invoice items](https://stripe.com/docs/api#invoiceitems), and proration adjustments
+  # that may be caused by subscription upgrades/downgrades (if necessary).
+  #
+  # If your invoice is configured to be billed through automatic charges,
+  # Stripe automatically finalizes your invoice and attempts payment. Note
+  # that finalizing the invoice,
+  # [when automatic](https://stripe.com/docs/invoicing/integration/automatic-advancement-collection), does
+  # not happen immediately as the invoice is created. Stripe waits
+  # until one hour after the last webhook was successfully sent (or the last
+  # webhook timed out after failing). If you (and the platforms you may have
+  # connected to) have no webhooks configured, Stripe waits one hour after
+  # creation to finalize the invoice.
+  #
+  # If your invoice is configured to be billed by sending an email, then based on your
+  # [email settings](https://dashboard.stripe.com/account/billing/automatic),
+  # Stripe will email the invoice to your customer and await payment. These
+  # emails can contain a link to a hosted page to pay the invoice.
+  #
+  # Stripe applies any customer credit on the account before determining the
+  # amount due for the invoice (i.e., the amount that will be actually
+  # charged). If the amount due for the invoice is less than Stripe's [minimum allowed charge
+  # per currency](https://stripe.com/docs/currencies#minimum-and-maximum-charge-amounts), the
+  # invoice is automatically marked paid, and we add the amount due to the
+  # customer's credit balance which is applied to the next invoice.
+  #
+  # More details on the customer's credit balance are
+  # [here](https://stripe.com/docs/billing/customer/balance).
+  #
+  # Related guide: [Send invoices to customers](https://stripe.com/docs/billing/invoices/sending)
   class Invoice < APIResource
     extend Stripe::APIOperations::Create
     include Stripe::APIOperations::Delete
     extend Stripe::APIOperations::List
+    extend Stripe::APIOperations::Search
     include Stripe::APIOperations::Save
 
     OBJECT_NAME = "invoice"
 
-    custom_method :finalize_invoice, http_verb: :post, http_path: "finalize"
-    custom_method :mark_uncollectible, http_verb: :post
-    custom_method :pay, http_verb: :post
-    custom_method :send_invoice, http_verb: :post, http_path: "send"
-    custom_method :void_invoice, http_verb: :post, http_path: "void"
-
     def finalize_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/finalize",
+        path: format("/v1/invoices/%<invoice>s/finalize", { invoice: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
@@ -28,7 +55,7 @@ module Stripe
     def mark_uncollectible(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/mark_uncollectible",
+        path: format("/v1/invoices/%<invoice>s/mark_uncollectible", { invoice: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
@@ -37,7 +64,7 @@ module Stripe
     def pay(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/pay",
+        path: format("/v1/invoices/%<invoice>s/pay", { invoice: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
@@ -46,7 +73,7 @@ module Stripe
     def send_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/send",
+        path: format("/v1/invoices/%<invoice>s/send", { invoice: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
@@ -55,20 +82,81 @@ module Stripe
     def void_invoice(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/void",
+        path: format("/v1/invoices/%<invoice>s/void", { invoice: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.finalize_invoice(invoice, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/invoices/%<invoice>s/finalize", { invoice: CGI.escape(invoice) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.list_upcoming_line_items(params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: "/v1/invoices/upcoming/lines",
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.mark_uncollectible(invoice, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/invoices/%<invoice>s/mark_uncollectible", { invoice: CGI.escape(invoice) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.pay(invoice, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/invoices/%<invoice>s/pay", { invoice: CGI.escape(invoice) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.send_invoice(invoice, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/invoices/%<invoice>s/send", { invoice: CGI.escape(invoice) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.upcoming(params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: "/v1/invoices/upcoming",
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.void_invoice(invoice, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/invoices/%<invoice>s/void", { invoice: CGI.escape(invoice) }),
         params: params,
         opts: opts
       )
     end
 
-    def self.upcoming(params, opts = {})
-      resp, opts = execute_resource_request(:get, resource_url + "/upcoming", params, opts)
-      Util.convert_to_stripe_object(resp.data, opts)
+    def self.search(params = {}, opts = {})
+      _search("/v1/invoices/search", params, opts)
     end
 
-    def self.list_upcoming_line_items(params, opts = {})
-      resp, opts = execute_resource_request(:get, resource_url + "/upcoming/lines", params, opts)
-      Util.convert_to_stripe_object(resp.data, opts)
+    def self.search_auto_paging_each(params = {}, opts = {}, &blk)
+      search(params, opts).auto_paging_each(&blk)
     end
   end
 end

data/lib/stripe/resources/invoice_item.rb

@@ -2,6 +2,17 @@
 # frozen_string_literal: true
 
 module Stripe
+  # Invoice Items represent the component lines of an [invoice](https://stripe.com/docs/api/invoices). An invoice item is added to an
+  # invoice by creating or updating it with an `invoice` field, at which point it will be included as
+  # [an invoice line item](https://stripe.com/docs/api/invoices/line_item) within
+  # [invoice.lines](https://stripe.com/docs/api/invoices/object#invoice_object-lines).
+  #
+  # Invoice Items can be created before you are ready to actually send the invoice. This can be particularly useful when combined
+  # with a [subscription](https://stripe.com/docs/api/subscriptions). Sometimes you want to add a charge or credit to a customer, but actually charge
+  # or credit the customer's card only at the end of a regular billing cycle. This is useful for combining several charges
+  # (to minimize per-transaction fees), or for having Stripe tabulate your usage-based billing totals.
+  #
+  # Related guides: [Integrate with the Invoicing API](https://stripe.com/docs/invoicing/integration), [Subscription Invoices](https://stripe.com/docs/billing/invoices/subscription#adding-upcoming-invoice-items).
   class InvoiceItem < APIResource
     extend Stripe::APIOperations::Create
     include Stripe::APIOperations::Delete

data/lib/stripe/resources/issuing/authorization.rb

@@ -3,19 +3,21 @@
 
 module Stripe
   module Issuing
+    # When an [issued card](https://stripe.com/docs/issuing) is used to make a purchase, an Issuing `Authorization`
+    # object is created. [Authorizations](https://stripe.com/docs/issuing/purchases/authorizations) must be approved for the
+    # purchase to be completed successfully.
+    #
+    # Related guide: [Issued card authorizations](https://stripe.com/docs/issuing/purchases/authorizations)
     class Authorization < APIResource
       extend Stripe::APIOperations::List
       include Stripe::APIOperations::Save
 
       OBJECT_NAME = "issuing.authorization"
 
-      custom_method :approve, http_verb: :post
-      custom_method :decline, http_verb: :post
-
       def approve(params = {}, opts = {})
         request_stripe_object(
           method: :post,
-          path: resource_url + "/approve",
+          path: format("/v1/issuing/authorizations/%<authorization>s/approve", { authorization: CGI.escape(self["id"]) }),
           params: params,
           opts: opts
         )
@@ -24,7 +26,25 @@ module Stripe
       def decline(params = {}, opts = {})
         request_stripe_object(
           method: :post,
-          path: resource_url + "/decline",
+          path: format("/v1/issuing/authorizations/%<authorization>s/decline", { authorization: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def self.approve(authorization, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/issuing/authorizations/%<authorization>s/approve", { authorization: CGI.escape(authorization) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def self.decline(authorization, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/issuing/authorizations/%<authorization>s/decline", { authorization: CGI.escape(authorization) }),
           params: params,
           opts: opts
         )

data/lib/stripe/resources/issuing/card.rb

@@ -3,6 +3,7 @@
 
 module Stripe
   module Issuing
+    # You can [create physical or virtual cards](https://stripe.com/docs/issuing/cards) that are issued to cardholders.
     class Card < APIResource
       extend Stripe::APIOperations::Create
       extend Stripe::APIOperations::List
@@ -10,15 +11,84 @@ module Stripe
 
       OBJECT_NAME = "issuing.card"
 
-      custom_method :details, http_verb: :get
+      def test_helpers
+        TestHelpers.new(self)
+      end
+
+      class TestHelpers < APIResourceTestHelpers
+        RESOURCE_CLASS = Card
+
+        def self.deliver_card(card, params = {}, opts = {})
+          request_stripe_object(
+            method: :post,
+            path: format("/v1/test_helpers/issuing/cards/%<card>s/shipping/deliver", { card: CGI.escape(card) }),
+            params: params,
+            opts: opts
+          )
+        end
+
+        def self.fail_card(card, params = {}, opts = {})
+          request_stripe_object(
+            method: :post,
+            path: format("/v1/test_helpers/issuing/cards/%<card>s/shipping/fail", { card: CGI.escape(card) }),
+            params: params,
+            opts: opts
+          )
+        end
+
+        def self.return_card(card, params = {}, opts = {})
+          request_stripe_object(
+            method: :post,
+            path: format("/v1/test_helpers/issuing/cards/%<card>s/shipping/return", { card: CGI.escape(card) }),
+            params: params,
+            opts: opts
+          )
+        end
+
+        def self.ship_card(card, params = {}, opts = {})
+          request_stripe_object(
+            method: :post,
+            path: format("/v1/test_helpers/issuing/cards/%<card>s/shipping/ship", { card: CGI.escape(card) }),
+            params: params,
+            opts: opts
+          )
+        end
+
+        def deliver_card(params = {}, opts = {})
+          @resource.request_stripe_object(
+            method: :post,
+            path: format("/v1/test_helpers/issuing/cards/%<card>s/shipping/deliver", { card: CGI.escape(@resource["id"]) }),
+            params: params,
+            opts: opts
+          )
+        end
+
+        def fail_card(params = {}, opts = {})
+          @resource.request_stripe_object(
+            method: :post,
+            path: format("/v1/test_helpers/issuing/cards/%<card>s/shipping/fail", { card: CGI.escape(@resource["id"]) }),
+            params: params,
+            opts: opts
+          )
+        end
+
+        def return_card(params = {}, opts = {})
+          @resource.request_stripe_object(
+            method: :post,
+            path: format("/v1/test_helpers/issuing/cards/%<card>s/shipping/return", { card: CGI.escape(@resource["id"]) }),
+            params: params,
+            opts: opts
+          )
+        end
 
-      def details(params = {}, opts = {})
-        request_stripe_object(
-          method: :get,
-          path: resource_url + "/details",
-          params: params,
-          opts: opts
-        )
+        def ship_card(params = {}, opts = {})
+          @resource.request_stripe_object(
+            method: :post,
+            path: format("/v1/test_helpers/issuing/cards/%<card>s/shipping/ship", { card: CGI.escape(@resource["id"]) }),
+            params: params,
+            opts: opts
+          )
+        end
       end
     end
   end

data/lib/stripe/resources/issuing/cardholder.rb

@@ -3,6 +3,9 @@
 
 module Stripe
   module Issuing
+    # An Issuing `Cardholder` object represents an individual or business entity who is [issued](https://stripe.com/docs/issuing) cards.
+    #
+    # Related guide: [How to create a cardholder](https://stripe.com/docs/issuing/cards#create-cardholder)
     class Cardholder < APIResource
       extend Stripe::APIOperations::Create
       extend Stripe::APIOperations::List