stripe 5.28.0 → 8.7.0

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/invoice_line_item.rb

@@ -1,3 +1,4 @@
+# File generated from our OpenAPI spec
 # frozen_string_literal: true
 
 module Stripe

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

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

@@ -3,6 +3,9 @@
 
 module Stripe
   module Issuing
+    # As a [card issuer](https://stripe.com/docs/issuing), you can dispute transactions that the cardholder does not recognize, suspects to be fraudulent, or has other issues with.
+    #
+    # Related guide: [Issuing disputes](https://stripe.com/docs/issuing/purchases/disputes)
     class Dispute < APIResource
       extend Stripe::APIOperations::Create
       extend Stripe::APIOperations::List
@@ -10,12 +13,19 @@ module Stripe
 
       OBJECT_NAME = "issuing.dispute"
 
-      custom_method :submit, http_verb: :post
-
       def submit(params = {}, opts = {})
         request_stripe_object(
           method: :post,
-          path: resource_url + "/submit",
+          path: format("/v1/issuing/disputes/%<dispute>s/submit", { dispute: CGI.escape(self["id"]) }),
+          params: params,
+          opts: opts
+        )
+      end
+
+      def self.submit(dispute, params = {}, opts = {})
+        request_stripe_object(
+          method: :post,
+          path: format("/v1/issuing/disputes/%<dispute>s/submit", { dispute: CGI.escape(dispute) }),
           params: params,
           opts: opts
         )

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

@@ -3,6 +3,11 @@
 
 module Stripe
   module Issuing
+    # Any use of an [issued card](https://stripe.com/docs/issuing) that results in funds entering or leaving
+    # your Stripe account, such as a completed purchase or refund, is represented by an Issuing
+    # `Transaction` object.
+    #
+    # Related guide: [Issued card transactions](https://stripe.com/docs/issuing/purchases/transactions)
     class Transaction < APIResource
       extend Stripe::APIOperations::List
       include Stripe::APIOperations::Save

data/lib/stripe/resources/line_item.rb

@@ -1,6 +1,8 @@
+# File generated from our OpenAPI spec
 # frozen_string_literal: true
 
 module Stripe
+  # A line item.
   class LineItem < APIResource
     OBJECT_NAME = "item"
   end

data/lib/stripe/resources/login_link.rb

@@ -1,6 +1,8 @@
+# File generated from our OpenAPI spec
 # frozen_string_literal: true
 
 module Stripe
+  # Login Links are single-use login link for an Express account to access their Stripe dashboard.
   class LoginLink < APIResource
     OBJECT_NAME = "login_link"
 

data/lib/stripe/resources/mandate.rb

@@ -2,6 +2,7 @@
 # frozen_string_literal: true
 
 module Stripe
+  # A Mandate is a record of the permission a customer has given you to debit their payment method.
   class Mandate < APIResource
     OBJECT_NAME = "mandate"
   end

data/lib/stripe/resources/payment_intent.rb

@@ -2,21 +2,38 @@
 # frozen_string_literal: true
 
 module Stripe
+  # A PaymentIntent guides you through the process of collecting a payment from your customer.
+  # We recommend that you create exactly one PaymentIntent for each order or
+  # customer session in your system. You can reference the PaymentIntent later to
+  # see the history of payment attempts for a particular session.
+  #
+  # A PaymentIntent transitions through
+  # [multiple statuses](https://stripe.com/docs/payments/intents#intent-statuses)
+  # throughout its lifetime as it interfaces with Stripe.js to perform
+  # authentication flows and ultimately creates at most one successful charge.
+  #
+  # Related guide: [Payment Intents API](https://stripe.com/docs/payments/payment-intents)
   class PaymentIntent < APIResource
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List
+    extend Stripe::APIOperations::Search
     include Stripe::APIOperations::Save
 
     OBJECT_NAME = "payment_intent"
 
-    custom_method :cancel, http_verb: :post
-    custom_method :capture, http_verb: :post
-    custom_method :confirm, http_verb: :post
+    def apply_customer_balance(params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/apply_customer_balance", { intent: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
 
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/cancel",
+        path: format("/v1/payment_intents/%<intent>s/cancel", { intent: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
@@ -25,7 +42,7 @@ module Stripe
     def capture(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/capture",
+        path: format("/v1/payment_intents/%<intent>s/capture", { intent: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
@@ -34,10 +51,90 @@ module Stripe
     def confirm(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/confirm",
+        path: format("/v1/payment_intents/%<intent>s/confirm", { intent: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def increment_authorization(params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/increment_authorization", { intent: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def verify_microdeposits(params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/verify_microdeposits", { intent: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.apply_customer_balance(intent, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/apply_customer_balance", { intent: CGI.escape(intent) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.cancel(intent, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/cancel", { intent: CGI.escape(intent) }),
         params: params,
         opts: opts
       )
     end
+
+    def self.capture(intent, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/capture", { intent: CGI.escape(intent) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.confirm(intent, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/confirm", { intent: CGI.escape(intent) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.increment_authorization(intent, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/increment_authorization", { intent: CGI.escape(intent) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.verify_microdeposits(intent, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_intents/%<intent>s/verify_microdeposits", { intent: CGI.escape(intent) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.search(params = {}, opts = {})
+      _search("/v1/payment_intents/search", params, opts)
+    end
+
+    def self.search_auto_paging_each(params = {}, opts = {}, &blk)
+      search(params, opts).auto_paging_each(&blk)
+    end
   end
 end

data/lib/stripe/resources/payment_link.rb

@@ -0,0 +1,35 @@
+# File generated from our OpenAPI spec
+# frozen_string_literal: true
+
+module Stripe
+  # A payment link is a shareable URL that will take your customers to a hosted payment page. A payment link can be shared and used multiple times.
+  #
+  # When a customer opens a payment link it will open a new [checkout session](https://stripe.com/docs/api/checkout/sessions) to render the payment page. You can use [checkout session events](https://stripe.com/docs/api/events/types#event_types-checkout.session.completed) to track payments through payment links.
+  #
+  # Related guide: [Payment Links API](https://stripe.com/docs/payment-links)
+  class PaymentLink < APIResource
+    extend Stripe::APIOperations::Create
+    extend Stripe::APIOperations::List
+    include Stripe::APIOperations::Save
+
+    OBJECT_NAME = "payment_link"
+
+    def list_line_items(params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/payment_links/%<payment_link>s/line_items", { payment_link: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.list_line_items(payment_link, params = {}, opts = {})
+      request_stripe_object(
+        method: :get,
+        path: format("/v1/payment_links/%<payment_link>s/line_items", { payment_link: CGI.escape(payment_link) }),
+        params: params,
+        opts: opts
+      )
+    end
+  end
+end

data/lib/stripe/resources/payment_method.rb

@@ -2,6 +2,11 @@
 # frozen_string_literal: true
 
 module Stripe
+  # PaymentMethod objects represent your customer's payment instruments.
+  # You can use them with [PaymentIntents](https://stripe.com/docs/payments/payment-intents) to collect payments or save them to
+  # Customer objects to store instrument details for future payments.
+  #
+  # Related guides: [Payment Methods](https://stripe.com/docs/payments/payment-methods) and [More Payment Scenarios](https://stripe.com/docs/payments/more-payment-scenarios).
   class PaymentMethod < APIResource
     extend Stripe::APIOperations::Create
     extend Stripe::APIOperations::List
@@ -9,13 +14,10 @@ module Stripe
 
     OBJECT_NAME = "payment_method"
 
-    custom_method :attach, http_verb: :post
-    custom_method :detach, http_verb: :post
-
     def attach(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/attach",
+        path: format("/v1/payment_methods/%<payment_method>s/attach", { payment_method: CGI.escape(self["id"]) }),
         params: params,
         opts: opts
       )
@@ -24,7 +26,25 @@ module Stripe
     def detach(params = {}, opts = {})
       request_stripe_object(
         method: :post,
-        path: resource_url + "/detach",
+        path: format("/v1/payment_methods/%<payment_method>s/detach", { payment_method: CGI.escape(self["id"]) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.attach(payment_method, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_methods/%<payment_method>s/attach", { payment_method: CGI.escape(payment_method) }),
+        params: params,
+        opts: opts
+      )
+    end
+
+    def self.detach(payment_method, params = {}, opts = {})
+      request_stripe_object(
+        method: :post,
+        path: format("/v1/payment_methods/%<payment_method>s/detach", { payment_method: CGI.escape(payment_method) }),
         params: params,
         opts: opts
       )