stripe 10.5.0.pre.beta.1 → 10.6.0.pre.beta.1

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

@@ -14,6 +14,8 @@ module Stripe
 
       OBJECT_NAME = "issuing.authorization"
 
+      # [Deprecated] Approves a pending Issuing Authorization object. This request should be made within the timeout window of the [real-time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to approve an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def approve(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -23,6 +25,8 @@ module Stripe
         )
       end
 
+      # [Deprecated] Declines a pending Issuing Authorization object. This request should be made within the timeout window of the [real time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to decline an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def decline(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -32,6 +36,8 @@ module Stripe
         )
       end
 
+      # [Deprecated] Approves a pending Issuing Authorization object. This request should be made within the timeout window of the [real-time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to approve an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def self.approve(authorization, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -41,6 +47,8 @@ module Stripe
         )
       end
 
+      # [Deprecated] Declines a pending Issuing Authorization object. This request should be made within the timeout window of the [real time authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations) flow.
+      # This method is deprecated. Instead, [respond directly to the webhook request to decline an authorization](https://stripe.com/docs/issuing/controls/real-time-authorizations#authorization-handling).
       def self.decline(authorization, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -57,6 +65,7 @@ module Stripe
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Authorization
 
+        # Capture a test-mode authorization.
         def self.capture(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -66,6 +75,7 @@ module Stripe
           )
         end
 
+        # Create a test-mode authorization.
         def self.create(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -75,6 +85,7 @@ module Stripe
           )
         end
 
+        # Expire a test-mode Authorization.
         def self.expire(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -84,6 +95,7 @@ module Stripe
           )
         end
 
+        # Increment a test-mode Authorization.
         def self.increment(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -93,6 +105,7 @@ module Stripe
           )
         end
 
+        # Reverse a test-mode Authorization.
         def self.reverse(authorization, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -102,6 +115,7 @@ module Stripe
           )
         end
 
+        # Capture a test-mode authorization.
         def capture(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -111,6 +125,7 @@ module Stripe
           )
         end
 
+        # Expire a test-mode Authorization.
         def expire(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -120,6 +135,7 @@ module Stripe
           )
         end
 
+        # Increment a test-mode Authorization.
         def increment(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -129,6 +145,7 @@ module Stripe
           )
         end
 
+        # Reverse a test-mode Authorization.
         def reverse(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,

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

@@ -18,6 +18,7 @@ module Stripe
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Card
 
+        # Updates the shipping status of the specified Issuing Card object to delivered.
         def self.deliver_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -27,6 +28,7 @@ module Stripe
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to failure.
         def self.fail_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -36,6 +38,7 @@ module Stripe
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to returned.
         def self.return_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -45,6 +48,7 @@ module Stripe
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to shipped.
         def self.ship_card(card, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -54,6 +58,7 @@ module Stripe
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to delivered.
         def deliver_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -63,6 +68,7 @@ module Stripe
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to failure.
         def fail_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -72,6 +78,7 @@ module Stripe
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to returned.
         def return_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -81,6 +88,7 @@ module Stripe
           )
         end
 
+        # Updates the shipping status of the specified Issuing Card object to shipped.
         def ship_card(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,

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

@@ -11,6 +11,7 @@ module Stripe
 
       OBJECT_NAME = "issuing.credit_underwriting_record"
 
+      # Update a CreditUnderwritingRecord object to correct mistakes.
       def correct(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -20,6 +21,7 @@ module Stripe
         )
       end
 
+      # Update a CreditUnderwritingRecord object from a decision made on a credit application.
       def report_decision(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -29,6 +31,7 @@ module Stripe
         )
       end
 
+      # Update a CreditUnderwritingRecord object to correct mistakes.
       def self.correct(credit_underwriting_record, params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -38,6 +41,7 @@ module Stripe
         )
       end
 
+      # Creates a CreditUnderwritingRecord object with information about a credit application submission.
       def self.create_from_application(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -47,6 +51,7 @@ module Stripe
         )
       end
 
+      # Creates a CreditUnderwritingRecord object from an underwriting decision coming from a proactive review of an existing accountholder.
       def self.create_from_proactive_review(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -56,6 +61,7 @@ module Stripe
         )
       end
 
+      # Update a CreditUnderwritingRecord object from a decision made on a credit application.
       def self.report_decision(credit_underwriting_record, params = {}, opts = {})
         request_stripe_object(
           method: :post,

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

@@ -13,6 +13,7 @@ module Stripe
 
       OBJECT_NAME = "issuing.dispute"
 
+      # Submits an Issuing Dispute to the card network. Stripe validates that all evidence fields required for the dispute's reason are present. For more details, see [Dispute reasons and evidence](https://stripe.com/docs/issuing/purchases/disputes#dispute-reasons-and-evidence).
       def submit(params = {}, opts = {})
         request_stripe_object(
           method: :post,
@@ -22,6 +23,7 @@ module Stripe
         )
       end
 
+      # Submits an Issuing Dispute to the card network. Stripe validates that all evidence fields required for the dispute's reason are present. For more details, see [Dispute reasons and evidence](https://stripe.com/docs/issuing/purchases/disputes#dispute-reasons-and-evidence).
       def self.submit(dispute, params = {}, opts = {})
         request_stripe_object(
           method: :post,

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

@@ -18,6 +18,7 @@ module Stripe
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = PersonalizationDesign
 
+        # Updates the status of the specified testmode personalization design object to active.
         def self.activate(personalization_design, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -27,6 +28,7 @@ module Stripe
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to inactive.
         def self.deactivate(personalization_design, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -36,6 +38,7 @@ module Stripe
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to rejected.
         def self.reject(personalization_design, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -45,6 +48,7 @@ module Stripe
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to active.
         def activate(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -54,6 +58,7 @@ module Stripe
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to inactive.
         def deactivate(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,
@@ -63,6 +68,7 @@ module Stripe
           )
         end
 
+        # Updates the status of the specified testmode personalization design object to rejected.
         def reject(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,

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

@@ -21,6 +21,7 @@ module Stripe
       class TestHelpers < APIResourceTestHelpers
         RESOURCE_CLASS = Transaction
 
+        # Allows the user to capture an arbitrary amount, also known as a forced capture.
         def self.create_force_capture(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -30,6 +31,7 @@ module Stripe
           )
         end
 
+        # Allows the user to refund an arbitrary amount, also known as a unlinked refund.
         def self.create_unlinked_refund(params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -39,6 +41,7 @@ module Stripe
           )
         end
 
+        # Refund a test-mode Transaction.
         def self.refund(transaction, params = {}, opts = {})
           request_stripe_object(
             method: :post,
@@ -48,6 +51,7 @@ module Stripe
           )
         end
 
+        # Refund a test-mode Transaction.
         def refund(params = {}, opts = {})
           @resource.request_stripe_object(
             method: :post,

data/lib/stripe/resources/order.rb

@@ -14,6 +14,7 @@ module Stripe
 
     OBJECT_NAME = "order"
 
+    # Cancels the order as well as the payment intent if one is attached.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +24,7 @@ module Stripe
       )
     end
 
+    # When retrieving an order, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def list_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -32,6 +34,7 @@ module Stripe
       )
     end
 
+    # Reopens a submitted order.
     def reopen(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -41,6 +44,7 @@ module Stripe
       )
     end
 
+    # Submitting an Order transitions the status to processing and creates a PaymentIntent object so the order can be paid. If the Order has an amount_total of 0, no PaymentIntent object will be created. Once the order is submitted, its contents cannot be changed, unless the [reopen](https://stripe.com/docs/api#reopen_order) method is called.
     def submit(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -50,6 +54,7 @@ module Stripe
       )
     end
 
+    # Cancels the order as well as the payment intent if one is attached.
     def self.cancel(id, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -59,6 +64,7 @@ module Stripe
       )
     end
 
+    # When retrieving an order, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_line_items(id, params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -68,6 +74,7 @@ module Stripe
       )
     end
 
+    # Reopens a submitted order.
     def self.reopen(id, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -77,6 +84,7 @@ module Stripe
       )
     end
 
+    # Submitting an Order transitions the status to processing and creates a PaymentIntent object so the order can be paid. If the Order has an amount_total of 0, no PaymentIntent object will be created. Once the order is submitted, its contents cannot be changed, unless the [reopen](https://stripe.com/docs/api#reopen_order) method is called.
     def self.submit(id, params = {}, opts = {})
       request_stripe_object(
         method: :post,

data/lib/stripe/resources/payment_intent.rb

@@ -21,6 +21,7 @@ module Stripe
 
     OBJECT_NAME = "payment_intent"
 
+    # Manually reconcile the remaining amount for a customer_balance PaymentIntent.
     def apply_customer_balance(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -30,6 +31,11 @@ module Stripe
       )
     end
 
+    # You can cancel a PaymentIntent object when it's in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action or, [in rare cases](https://stripe.com/docs/payments/intents), processing.
+    #
+    # After it's canceled, no additional charges are made by the PaymentIntent and any operations on the PaymentIntent fail with an error. For PaymentIntents with a status of requires_capture, the remaining amount_capturable is automatically refunded.
+    #
+    # You can't cancel the PaymentIntent for a Checkout Session. [Expire the Checkout Session](https://stripe.com/docs/api/checkout/sessions/expire) instead.
     def cancel(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -39,6 +45,11 @@ module Stripe
       )
     end
 
+    # Capture the funds of an existing uncaptured PaymentIntent when its status is requires_capture.
+    #
+    # Uncaptured PaymentIntents are cancelled a set number of days (7 by default) after their creation.
+    #
+    # Learn more about [separate authorization and capture](https://stripe.com/docs/payments/capture-later).
     def capture(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -48,6 +59,29 @@ module Stripe
       )
     end
 
+    # Confirm that your customer intends to pay with current or provided
+    # payment method. Upon confirmation, the PaymentIntent will attempt to initiate
+    # a payment.
+    # If the selected payment method requires additional authentication steps, the
+    # PaymentIntent will transition to the requires_action status and
+    # suggest additional actions via next_action. If payment fails,
+    # the PaymentIntent transitions to the requires_payment_method status or the
+    # canceled status if the confirmation limit is reached. If
+    # payment succeeds, the PaymentIntent will transition to the succeeded
+    # status (or requires_capture, if capture_method is set to manual).
+    # If the confirmation_method is automatic, payment may be attempted
+    # using our [client SDKs](https://stripe.com/docs/stripe-js/reference#stripe-handle-card-payment)
+    # and the PaymentIntent's [client_secret](https://stripe.com/docs/api#payment_intent_object-client_secret).
+    # After next_actions are handled by the client, no additional
+    # confirmation is required to complete the payment.
+    # If the confirmation_method is manual, all payment attempts must be
+    # initiated using a secret key.
+    # If any actions are required for the payment, the PaymentIntent will
+    # return to the requires_confirmation state
+    # after those actions are completed. Your server needs to then
+    # explicitly re-confirm the PaymentIntent to initiate the next payment
+    # attempt. Read the [expanded documentation](https://stripe.com/docs/payments/payment-intents/web-manual)
+    # to learn more about manual confirmation.
     def confirm(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -57,6 +91,30 @@ module Stripe
       )
     end
 
+    # Perform an incremental authorization on an eligible
+    # [PaymentIntent](https://stripe.com/docs/api/payment_intents/object). To be eligible, the
+    # PaymentIntent's status must be requires_capture and
+    # [incremental_authorization_supported](https://stripe.com/docs/api/charges/object#charge_object-payment_method_details-card_present-incremental_authorization_supported)
+    # must be true.
+    #
+    # Incremental authorizations attempt to increase the authorized amount on
+    # your customer's card to the new, higher amount provided. Similar to the
+    # initial authorization, incremental authorizations can be declined. A
+    # single PaymentIntent can call this endpoint multiple times to further
+    # increase the authorized amount.
+    #
+    # If the incremental authorization succeeds, the PaymentIntent object
+    # returns with the updated
+    # [amount](https://stripe.com/docs/api/payment_intents/object#payment_intent_object-amount).
+    # If the incremental authorization fails, a
+    # [card_declined](https://stripe.com/docs/error-codes#card-declined) error returns, and no other
+    # fields on the PaymentIntent or Charge update. The PaymentIntent
+    # object remains capturable for the previously authorized amount.
+    #
+    # Each PaymentIntent can have a maximum of 10 incremental authorization attempts, including declines.
+    # After it's captured, a PaymentIntent can no longer be incremented.
+    #
+    # Learn more about [incremental authorizations](https://stripe.com/docs/terminal/features/incremental-authorizations).
     def increment_authorization(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -66,6 +124,7 @@ module Stripe
       )
     end
 
+    # Verifies microdeposits on a PaymentIntent object.
     def verify_microdeposits(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -75,6 +134,7 @@ module Stripe
       )
     end
 
+    # Manually reconcile the remaining amount for a customer_balance PaymentIntent.
     def self.apply_customer_balance(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -84,6 +144,11 @@ module Stripe
       )
     end
 
+    # You can cancel a PaymentIntent object when it's in one of these statuses: requires_payment_method, requires_capture, requires_confirmation, requires_action or, [in rare cases](https://stripe.com/docs/payments/intents), processing.
+    #
+    # After it's canceled, no additional charges are made by the PaymentIntent and any operations on the PaymentIntent fail with an error. For PaymentIntents with a status of requires_capture, the remaining amount_capturable is automatically refunded.
+    #
+    # You can't cancel the PaymentIntent for a Checkout Session. [Expire the Checkout Session](https://stripe.com/docs/api/checkout/sessions/expire) instead.
     def self.cancel(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -93,6 +158,11 @@ module Stripe
       )
     end
 
+    # Capture the funds of an existing uncaptured PaymentIntent when its status is requires_capture.
+    #
+    # Uncaptured PaymentIntents are cancelled a set number of days (7 by default) after their creation.
+    #
+    # Learn more about [separate authorization and capture](https://stripe.com/docs/payments/capture-later).
     def self.capture(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -102,6 +172,29 @@ module Stripe
       )
     end
 
+    # Confirm that your customer intends to pay with current or provided
+    # payment method. Upon confirmation, the PaymentIntent will attempt to initiate
+    # a payment.
+    # If the selected payment method requires additional authentication steps, the
+    # PaymentIntent will transition to the requires_action status and
+    # suggest additional actions via next_action. If payment fails,
+    # the PaymentIntent transitions to the requires_payment_method status or the
+    # canceled status if the confirmation limit is reached. If
+    # payment succeeds, the PaymentIntent will transition to the succeeded
+    # status (or requires_capture, if capture_method is set to manual).
+    # If the confirmation_method is automatic, payment may be attempted
+    # using our [client SDKs](https://stripe.com/docs/stripe-js/reference#stripe-handle-card-payment)
+    # and the PaymentIntent's [client_secret](https://stripe.com/docs/api#payment_intent_object-client_secret).
+    # After next_actions are handled by the client, no additional
+    # confirmation is required to complete the payment.
+    # If the confirmation_method is manual, all payment attempts must be
+    # initiated using a secret key.
+    # If any actions are required for the payment, the PaymentIntent will
+    # return to the requires_confirmation state
+    # after those actions are completed. Your server needs to then
+    # explicitly re-confirm the PaymentIntent to initiate the next payment
+    # attempt. Read the [expanded documentation](https://stripe.com/docs/payments/payment-intents/web-manual)
+    # to learn more about manual confirmation.
     def self.confirm(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -111,6 +204,30 @@ module Stripe
       )
     end
 
+    # Perform an incremental authorization on an eligible
+    # [PaymentIntent](https://stripe.com/docs/api/payment_intents/object). To be eligible, the
+    # PaymentIntent's status must be requires_capture and
+    # [incremental_authorization_supported](https://stripe.com/docs/api/charges/object#charge_object-payment_method_details-card_present-incremental_authorization_supported)
+    # must be true.
+    #
+    # Incremental authorizations attempt to increase the authorized amount on
+    # your customer's card to the new, higher amount provided. Similar to the
+    # initial authorization, incremental authorizations can be declined. A
+    # single PaymentIntent can call this endpoint multiple times to further
+    # increase the authorized amount.
+    #
+    # If the incremental authorization succeeds, the PaymentIntent object
+    # returns with the updated
+    # [amount](https://stripe.com/docs/api/payment_intents/object#payment_intent_object-amount).
+    # If the incremental authorization fails, a
+    # [card_declined](https://stripe.com/docs/error-codes#card-declined) error returns, and no other
+    # fields on the PaymentIntent or Charge update. The PaymentIntent
+    # object remains capturable for the previously authorized amount.
+    #
+    # Each PaymentIntent can have a maximum of 10 incremental authorization attempts, including declines.
+    # After it's captured, a PaymentIntent can no longer be incremented.
+    #
+    # Learn more about [incremental authorizations](https://stripe.com/docs/terminal/features/incremental-authorizations).
     def self.increment_authorization(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -120,6 +237,7 @@ module Stripe
       )
     end
 
+    # Verifies microdeposits on a PaymentIntent object.
     def self.verify_microdeposits(intent, params = {}, opts = {})
       request_stripe_object(
         method: :post,

data/lib/stripe/resources/payment_link.rb

@@ -14,6 +14,7 @@ module Stripe
 
     OBJECT_NAME = "payment_link"
 
+    # When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def list_line_items(params = {}, opts = {})
       request_stripe_object(
         method: :get,
@@ -23,6 +24,7 @@ module Stripe
       )
     end
 
+    # When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
     def self.list_line_items(payment_link, params = {}, opts = {})
       request_stripe_object(
         method: :get,

data/lib/stripe/resources/payment_method.rb

@@ -14,6 +14,19 @@ module Stripe
 
     OBJECT_NAME = "payment_method"
 
+    # Attaches a PaymentMethod object to a Customer.
+    #
+    # To attach a new PaymentMethod to a customer for future payments, we recommend you use a [SetupIntent](https://stripe.com/docs/api/setup_intents)
+    # or a PaymentIntent with [setup_future_usage](https://stripe.com/docs/api/payment_intents/create#create_payment_intent-setup_future_usage).
+    # These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach
+    # endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for
+    # future use, which makes later declines and payment friction more likely.
+    # See [Optimizing cards for future payments](https://stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up
+    # future payments.
+    #
+    # To use this PaymentMethod as the default for invoice or subscription payments,
+    # set [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method),
+    # on the Customer to the PaymentMethod's ID.
     def attach(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -23,6 +36,7 @@ module Stripe
       )
     end
 
+    # Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.
     def detach(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -32,6 +46,19 @@ module Stripe
       )
     end
 
+    # Attaches a PaymentMethod object to a Customer.
+    #
+    # To attach a new PaymentMethod to a customer for future payments, we recommend you use a [SetupIntent](https://stripe.com/docs/api/setup_intents)
+    # or a PaymentIntent with [setup_future_usage](https://stripe.com/docs/api/payment_intents/create#create_payment_intent-setup_future_usage).
+    # These approaches will perform any necessary steps to set up the PaymentMethod for future payments. Using the /v1/payment_methods/:id/attach
+    # endpoint without first using a SetupIntent or PaymentIntent with setup_future_usage does not optimize the PaymentMethod for
+    # future use, which makes later declines and payment friction more likely.
+    # See [Optimizing cards for future payments](https://stripe.com/docs/payments/payment-intents#future-usage) for more information about setting up
+    # future payments.
+    #
+    # To use this PaymentMethod as the default for invoice or subscription payments,
+    # set [invoice_settings.default_payment_method](https://stripe.com/docs/api/customers/update#update_customer-invoice_settings-default_payment_method),
+    # on the Customer to the PaymentMethod's ID.
     def self.attach(payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -41,6 +68,7 @@ module Stripe
       )
     end
 
+    # Detaches a PaymentMethod object from a Customer. After a PaymentMethod is detached, it can no longer be used for a payment or re-attached to a Customer.
     def self.detach(payment_method, params = {}, opts = {})
       request_stripe_object(
         method: :post,

data/lib/stripe/resources/payment_method_domain.rb

@@ -13,6 +13,12 @@ module Stripe
 
     OBJECT_NAME = "payment_method_domain"
 
+    # Some payment methods such as Apple Pay require additional steps to verify a domain. If the requirements weren't satisfied when the domain was created, the payment method will be inactive on the domain.
+    # The payment method doesn't appear in Elements for this domain until it is active.
+    #
+    # To activate a payment method on an existing payment method domain, complete the required validation steps specific to the payment method, and then validate the payment method domain with this endpoint.
+    #
+    # Related guides: [Payment method domains](https://stripe.com/docs/payments/payment-methods/pmd-registration).
     def validate(params = {}, opts = {})
       request_stripe_object(
         method: :post,
@@ -22,6 +28,12 @@ module Stripe
       )
     end
 
+    # Some payment methods such as Apple Pay require additional steps to verify a domain. If the requirements weren't satisfied when the domain was created, the payment method will be inactive on the domain.
+    # The payment method doesn't appear in Elements for this domain until it is active.
+    #
+    # To activate a payment method on an existing payment method domain, complete the required validation steps specific to the payment method, and then validate the payment method domain with this endpoint.
+    #
+    # Related guides: [Payment method domains](https://stripe.com/docs/payments/payment-methods/pmd-registration).
     def self.validate(payment_method_domain, params = {}, opts = {})
       request_stripe_object(
         method: :post,