Add documentation for the PaymentIntent resource and parameters

src/Stripe.net/Entities/PaymentIntents/PaymentIntent.cs

@@ -7,22 +7,41 @@ namespace Stripe
 
     public class PaymentIntent : StripeEntity<PaymentIntent>, IHasId, IHasMetadata, IHasObject
     {
+        /// <summary>
+        /// Unique identifier for the object.
+        /// </summary>
         [JsonProperty("id")]
         public string Id { get; set; }
 
+        /// <summary>
+        /// String representing the object’s type. Objects of the same type share the same value.
+        /// </summary>
         [JsonProperty("object")]
         public string Object { get; set; }
 
+        /// <summary>
+        /// Amount intended to be collected by this PaymentIntent.
+        /// </summary>
         [JsonProperty("amount")]
         public long? Amount { get; set; }
 
+        /// <summary>
+        /// Amount that can be captured from this PaymentIntent.
+        /// </summary>
         [JsonProperty("amount_capturable")]
         public long? AmountCapturable { get; set; }
 
+        /// <summary>
+        /// Amount that was collected by this PaymentIntent.
+        /// </summary>
         [JsonProperty("amount_received")]
         public long? AmountReceived { get; set; }
 
         #region Expandable Application
+
+        /// <summary>
+        /// ID of the Connect application that created the PaymentIntent.
+        /// </summary>
         [JsonIgnore]
         public string ApplicationId
         {
@@ -42,36 +61,93 @@ public Application Application
         internal ExpandableField<Application> InternalApplication { get; set; }
         #endregion
 
+        /// <summary>
+        /// The amount of the application fee (if any) for the resulting payment. See the
+        /// PaymentIntents <a href="https://stripe.com/docs/payments/payment-intents/use-cases#connected-accounts">
+        /// use case for connected accounts</a> for details.
+        /// </summary>
         [JsonProperty("application_fee_amount")]
         public long? ApplicationFeeAmount { get; set; }
 
+        /// <summary>
+        /// Populated when status is <c>canceled</c>, this is the time at which the PaymentIntent
+        /// was canceled. Measured in seconds since the Unix epoch.
+        /// </summary>
         [JsonProperty("canceled_at")]
         [JsonConverter(typeof(DateTimeConverter))]
         public DateTime? CanceledAt { get; set; }
 
+        /// <summary>
+        /// Reason for cancellation of this PaymentIntent, either user-provided (<c>duplicate</c>,
+        /// <c>fraudulent</c>, <c>requested_by_customer</c>, or <c>abandoned</c>) or generated by
+        /// Stripe internally (<c>failed_invoice</c>, <c>void_invoice</c>, or <c>automatic</c>).
+        /// </summary>
         [JsonProperty("cancellation_reason")]
         public string CancellationReason { get; set; }
 
+        /// <summary>
+        /// One of <c>automatic</c> (default) or <c>manual</c>.
+        /// When the capture method is <c>automatic</c>, Stripe automatically captures funds when
+        /// the customer authorizes the payment.
+        /// Change the capture method to <c>manual</c> if you wish to <a href="https://stripe.com/docs/payments/payment-intents/quickstart#automatic-confirmation-flow">
+        /// separate authorization and capture</a> for payment methods that support this.
+        /// </summary>
         [JsonProperty("capture_method")]
         public string CaptureMethod { get; set; }
 
+        /// <summary>
+        /// Charges that were created by this PaymentIntent, if any.
+        /// </summary>
         [JsonProperty("charges")]
         public StripeList<Charge> Charges { get; set; }
 
+        /// <summary>
+        /// The client secret of this PaymentIntent. Used for client-side retrieval using a
+        /// publishable key.
+        /// The client secret can be used to complete a payment from your frontend. It should not
+        /// be stored, logged, embedded in URLs, or exposed to anyone other than the customer. Make
+        /// sure that you have TLS enabled on any page that includes the client secret.
+        /// Please refer to our <a href="https://stripe.com/docs/payments/payment-intents/quickstart#automatic-confirmation-flow">
+        /// automatic confirmation quickstart guide</a> to learn about how client_secret should be
+        /// handled.
+        /// </summary>
         [JsonProperty("client_secret")]
         public string ClientSecret { get; set; }
 
+        /// <summary>
+        /// One of <c>automatic</c> (default) or <c>manual</c>.
+        /// When the confirmation method is <c>automatic</c>, a PaymentIntent can be confirmed
+        /// using a publishable key. After next actions are handled, no additional confirmation is
+        /// required to complete the payment.
+        /// When the confirmation method is <c>manual</c>, all payment attempts must be made using
+        /// a secret key. The PaymentIntent returns to the requires_confirmation state after
+        /// handling next_actions, and requires your server to initiate each payment attempt with
+        /// an explicit confirmation.
+        /// </summary>
         [JsonProperty("confirmation_method")]
         public string ConfirmationMethod { get; set; }
 
+        /// <summary>
+        /// Time at which the object was created. Measured in seconds since the Unix epoch.
+        /// </summary>
         [JsonProperty("created")]
         [JsonConverter(typeof(DateTimeConverter))]
         public DateTime? Created { get; set; }
 
+        /// <summary>
+        /// Three-letter ISO currency code, in lowercase. Must be a supported currency.
+        /// </summary>
         [JsonProperty("currency")]
         public string Currency { get; set; }
 
         #region Expandable Customer
+
+        /// <summary>
+        /// ID of the Customer this PaymentIntent belongs to, if one exists.
+        /// If present, payment methods used with this PaymentIntent can only be attached to this
+        /// Customer, and payment methods attached to other Customers cannot be used with this
+        /// PaymentIntent.
+        /// </summary>
         [JsonIgnore]
         public string CustomerId
         {
@@ -91,10 +167,17 @@ public Customer Customer
         internal ExpandableField<Customer> InternalCustomer { get; set; }
         #endregion
 
+        /// <summary>
+        /// An arbitrary string attached to the object. Often useful for displaying to users.
+        /// </summary>
         [JsonProperty("description")]
         public string Description { get; set; }
 
         #region Expandable Invoice
+
+        /// <summary>
+        /// ID of the invoice that created this PaymentIntent, if one exists.
+        /// </summary>
         [JsonIgnore]
         public string InvoiceId
         {
@@ -114,19 +197,40 @@ public Invoice Invoice
         internal ExpandableField<Invoice> InternalInvoice { get; set; }
         #endregion
 
+        /// <summary>
+        /// The payment error encountered in the previous PaymentIntent confirmation.
+        /// </summary>
         [JsonProperty("last_payment_error")]
         public StripeError LastPaymentError { get; set; }
 
+        /// <summary>
+        /// Has the value <c>true</c> if the object exists in live mode or the value
+        /// <c>false</c> if the object exists in test mode.
+        /// </summary>
         [JsonProperty("livemode")]
         public bool Livemode { get; set; }
 
+        /// <summary>
+        /// A set of key/value pairs that you can attach to an order object. It can be useful for
+        /// storing additional information about the order in a structured format.
+        /// </summary>
         [JsonProperty("metadata")]
         public Dictionary<string, string> Metadata { get; set; }
 
+        /// <summary>
+        /// If present, this property tells you what actions you need to take in order for your
+        /// customer to fulfill a payment using the provided source.
+        /// </summary>
         [JsonProperty("next_action")]
         public PaymentIntentNextAction NextAction { get; set; }
 
         #region Expandable OnBehalfOf (Account)
+
+        /// <summary>
+        /// The account (if any) for which the funds of the PaymentIntent are intended.
+        /// See the PaymentIntents <a href="https://stripe.com/docs/payments/payment-intents/use-cases#connected-accounts">
+        /// use case for connected accounts</a> for details.
+        /// </summary>
         [JsonIgnore]
         public string OnBehalfOfId
         {
@@ -147,6 +251,10 @@ public Account OnBehalfOf
         #endregion
 
         #region Expandable PaymentMethod
+
+        /// <summary>
+        /// ID of the payment method used in this PaymentIntent.
+        /// </summary>
         [JsonIgnore]
         public string PaymentMethodId
         {
@@ -166,13 +274,23 @@ public PaymentMethod PaymentMethod
         internal ExpandableField<PaymentMethod> InternalPaymentMethod { get; set; }
         #endregion
 
+        /// <summary>
+        /// The list of payment method types (e.g. card) that this PaymentIntent is allowed to use.
+        /// </summary>
         [JsonProperty("payment_method_types")]
         public List<string> PaymentMethodTypes { get; set; }
 
+        /// <summary>
+        /// Email address that the receipt for the resulting payment will be sent to.
+        /// </summary>
         [JsonProperty("receipt_email")]
         public string ReceiptEmail { get; set; }
 
         #region Expandable Review
+
+        /// <summary>
+        /// ID of the review associated with this PaymentIntent, if any.
+        /// </summary>
         [JsonIgnore]
         public string ReviewId
         {
@@ -192,13 +310,34 @@ public Review Review
         internal ExpandableField<Review> InternalReview { get; set; }
         #endregion
 
+        /// <summary>
+        /// Indicates that you intend to make future payments with this PaymentIntent’s payment
+        /// method.
+        /// If present, the payment method used with this PaymentIntent can be attached to a
+        /// Customer, even after the transaction completes.
+        /// Use <c>on_session</c> if you intend to only reuse the payment method when your customer
+        /// is present in your checkout flow. Use <c>off_session</c> if your customer may or may
+        /// not be in your checkout flow.
+        /// Stripe uses this to dynamically optimize your payment flow and comply with regional
+        /// legislation and network rules. For example, if your customer is impacted by SCA, using
+        /// <c>off_session</c> will ensure that they are authenticated while processing this
+        /// PaymentIntent. You will then be able to make later off-session payments for this
+        /// customer.
+        /// </summary>
         [JsonProperty("setup_future_usage")]
         public string SetupFutureUsage { get; set; }
 
+        /// <summary>
+        /// Shipping information for this PaymentIntent.
+        /// </summary>
         [JsonProperty("shipping")]
         public Shipping Shipping { get; set; }
 
         #region Expandable Source
+
+        /// <summary>
+        /// ID of the Source associated with this PaymentIntent, if any.
+        /// </summary>
         [JsonIgnore]
         public string SourceId
         {
@@ -218,15 +357,35 @@ public IPaymentSource Source
         internal ExpandableField<IPaymentSource> InternalSource { get; set; }
         #endregion
 
+        /// <summary>
+        /// Extra information about a PaymentIntent. This will appear on your customer’s statement
+        /// when this PaymentIntent succeeds in creating a charge
+        /// </summary>
         [JsonProperty("statement_descriptor")]
         public string StatementDescriptor { get; set; }
 
+        /// <summary>
+        /// Status of this PaymentIntent, one of <c>requires_payment_method</c>,
+        /// <c>requires_confirmation</c>, <c>requires_action</c>, <c>processing</c>,
+        /// <c>requires_capture</c>, <c>canceled</c>, or <c>succeeded</c>. Read more about each
+        /// PaymentIntent <a href="https://stripe.com/docs/payments/intents#intent-statuses">status</a>.
+        /// </summary>
         [JsonProperty("status")]
         public string Status { get; set; }
 
+        /// <summary>
+        /// The data with which to automatically create a Transfer when the payment is finalized.
+        /// See the PaymentIntents <a href="https://stripe.com/docs/payments/payment-intents/use-cases#connected-accounts">
+        /// use case for connected accounts</a> for details.
+        /// </summary>
         [JsonProperty("transfer_data")]
         public PaymentIntentTransferData TransferData { get; set; }
 
+        /// <summary>
+        /// A string that identifies the resulting payment as part of a group. See the
+        /// PaymentIntents <a href="https://stripe.com/docs/payments/payment-intents/use-cases#connected-accounts">
+        /// use case for connected accounts</a> for details.
+        /// </summary>
         [JsonProperty("transfer_group")]
         public string TransferGroup { get; set; }
 

src/Stripe.net/Entities/PaymentIntents/PaymentIntentNextAction.cs

@@ -4,9 +4,17 @@ namespace Stripe
 
     public class PaymentIntentNextAction : StripeEntity<PaymentIntentNextAction>
     {
+        /// <summary>
+        /// Contains instructions for authenticating a payment by redirecting your customer to
+        /// another page or application.
+        /// </summary>
         [JsonProperty("redirect_to_url")]
         public PaymentIntentNextActionRedirectToUrl RedirectToUrl { get; set; }
 
+        /// <summary>
+        /// Type of the next action to perform, one of <c>redirect_to_url</c> or
+        /// <c>use_stripe_sdk</c>.
+        /// </summary>
         [JsonProperty("type")]
         public string Type { get; set; }
     }

src/Stripe.net/Entities/PaymentIntents/PaymentIntentNextActionRedirectToUrl.cs

@@ -4,9 +4,16 @@ namespace Stripe
 
     public class PaymentIntentNextActionRedirectToUrl : StripeEntity<PaymentIntentNextActionRedirectToUrl>
     {
+        /// <summary>
+        /// If the customer does not exit their browser while authenticating, they will be
+        /// redirected to this specified URL after completion.
+        /// </summary>
         [JsonProperty("return_url")]
         public string ReturnUrl { get; set; }
 
+        /// <summary>
+        /// The URL you must redirect your customer to in order to authenticate the payment.
+        /// </summary>
         [JsonProperty("url")]
         public string Url { get; set; }
     }

src/Stripe.net/Entities/PaymentIntents/PaymentIntentTransferData.cs

@@ -6,7 +6,19 @@ namespace Stripe
 
     public class PaymentIntentTransferData : StripeEntity<PaymentIntentTransferData>
     {
+        /// <summary>
+        /// The amount transferred to the destination account, if specified. By default, the entire
+        /// charge amount is transferred to the destination account.
+        /// </summary>
+        [JsonProperty("amount")]
+        public long? Amount { get; set; }
+
         #region Expandable Destination (Account)
+
+        /// <summary>
+        /// ID of the account (if any) the payment will be attributed to for tax reporting, and
+        /// where funds from the payment will be transferred to upon payment success.
+        /// </summary>
         [JsonIgnore]
         public string DestinationId
         {
@@ -25,9 +37,5 @@ public Account Destination
         [JsonConverter(typeof(ExpandableFieldConverter<Account>))]
         internal ExpandableField<Account> InternalDestination { get; set; }
         #endregion
-
-        [Obsolete("Use PaymentIntent.ApplicationFeeAmount instead")]
-        [JsonProperty("amount")]
-        public long? Amount { get; set; }
     }
 }

src/Stripe.net/Services/PaymentIntents/PaymentIntentCancelOptions.cs

@@ -5,6 +5,10 @@ namespace Stripe
 
     public class PaymentIntentCancelOptions : BaseOptions
     {
+        /// <summary>
+        /// Reason for canceling this PaymentIntent. Possible values are <c>duplicate</c>,
+        /// <c>fraudulent</c>, <c>requested_by_customer</c>, or <c>abandoned</c>.
+        /// </summary>
         [JsonProperty("cancellation_reason")]
         public string CancellationReason { get; set; }
     }