docs: Added docs to PaymentIntent and PaymentIntentParams classes…

… and all daughter classes

docs: Added docs to `SetupIntent` class and all daughter classes
docs: Added docs to all `Saving payment details for later use` methods on `StripeTerminal` class
docs: Added docs to all `Display information to customers` methods on `StripeTerminal` class

stripe_terminal/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 3.0.0-dev.1
+- docs: Added docs to `PaymentIntent` and `PaymentIntentParams` classes and all daughter classes
+- docs: Added docs to `SetupIntent` class and all daughter classes
+- docs: Added docs to all `Saving payment details for later use` methods on `StripeTerminal` class
+- docs: Added docs to all `Display information to customers` methods on `StripeTerminal` class
+
 ## 3.0.0-dev
 - fix(ios): Fixes incorrect checking `null` values from flutter
 - feat: added more parameters to `PaymentIntentParams` class

stripe_terminal/example/pubspec.lock

@@ -140,7 +140,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "3.0.0-dev"
+    version: "3.0.0-dev.1"
   meta:
     dependency: transitive
     description:

stripe_terminal/lib/src/models/card.dart

@@ -91,15 +91,30 @@ class ReceiptDetails with _$ReceiptDetails {
   });
 }
 
+/// Capture Method values that can be used as card-present payment method options.
 enum CardPresentCaptureMethod {
+  /// Use manual_preferred if you prefer manual capture_method for the [PaymentIntent]’s
+  /// capture_method but support falling back to automatic based on the presented payment method.
   manualPreferred,
 }
 
+/// Parameters that will be applied to the card present PaymentIntent.
 @DataClass()
 class CardPresentParameters with _$CardPresentParameters {
+  /// Capture method of a card-present payment method option.
   final CardPresentCaptureMethod? captureMethod;
+
+  /// Using the extended authorizations feature, users in eligible categories can capture up to
+  /// 31 days later, depending on the card brand.
   final bool? requestExtendedAuthorization;
+
+  /// Allows you to increase the authorized amount on a confirmed [PaymentIntent] before you capture it.
+  /// This means you can update the amount on a payment if the estimated price changes or goods and
+  /// services are added. Before capture, each incremental authorization appears on your customer’s
+  /// credit card statement as an additional pending charge.
   final bool? requestIncrementalAuthorizationSupport;
+
+  /// Network routing priority on co-branded EMV cards supporting domestic debit and international card schemes.
   final CardPresentRouting? requestedPriority;
 
   const CardPresentParameters({
@@ -110,6 +125,7 @@ class CardPresentParameters with _$CardPresentParameters {
   });
 }
 
+/// Transaction routing priorities
 enum CardPresentRouting {
   domestic,
   international,

stripe_terminal/lib/src/models/cart.dart

@@ -2,25 +2,54 @@ import 'package:mek_data_class/mek_data_class.dart';
 
 part 'cart.g.dart';
 
+/// An [Cart] object contains information about what line items are included in the current transaction.
+/// A cart object should be created and then passed into [StripeTerminal.setReaderDisplay], which
+/// will display the cart’s contents on the reader’s screen.
+///
+/// The [Cart] only represents exactly what will be shown on the screen, and is not reflective
+/// of what the customer is actually charged. You are responsible for making sure that tax
+/// and total reflect what is in the cart.
+///
+/// These values are exactly what will be shown on the screen and do not reflect what the user is actually charged.
+///
+/// Note: Only Internet readers support setReaderDisplay functionality
 @DataClass()
 class Cart with _$Cart {
+  /// The currency of the cart.
   final String currency;
+
+  /// The displayed tax amount, provided in the currency’s smallest unit.
   final int tax;
+
+  /// The cart’s total balance, provided in the currency’s smallest unit.
   final int total;
+
+  /// The cart’s line items. Default’s to an empty array of line items.
   final List<CartLineItem> lineItems;
 
   const Cart({
     required this.currency,
-    required this.tax,
+    this.tax = 0,
     required this.total,
     required this.lineItems,
   });
 }
 
+/// Represents a single line item in an [Cart], displayed on the reader’s screen during checkout.
+///
+/// The values here will be shown on the screen as-is. Make sure you’re correctly calculating
+/// and setting the [Cart]‘s tax and total – the reader will not calculate tax or total for you.
+/// Similarly, make sure the values displayed reflect what the customer is actually charged.
 @DataClass()
 class CartLineItem with _$CartLineItem {
+  /// The description or name of the item.
   final String description;
+
+  /// The quantity of the line item being purchased.
   final int quantity;
+
+  /// The price of the item, provided in the cart’s currency’s smallest unit. The line item will
+  /// assume the currency of the parent [Cart].
   final int amount;
 
   const CartLineItem({

stripe_terminal/lib/src/models/payment_intent.dart

@@ -4,38 +4,117 @@ import 'package:meta/meta.dart';
 
 part 'payment_intent.g.dart';
 
+/// A [PaymentIntent] tracks 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 throughout its lifetime and ultimately
+/// creates at most one successful charge.
 @DataClass()
 class PaymentIntent with _$PaymentIntent {
+  /// The unique identifier for the intent.
+  //
+  // If the intent was created offline the [id] will be nil. See offlineDetails.stripeId for a unique ID to use while offline.
+  //
+  // After the payment has been forwarded the intent’s [id] will be filled in.
   final String id;
+
+  /// When the intent was created.
   final DateTime created;
+
+  /// The status of the PaymentIntent.
   final PaymentIntentStatus status;
+
+  /// The amount to be collected by this [PaymentIntent], provided in the currency’s smallest unit.
   final double amount;
+
+  /// Controls when the funds will be captured from the customer’s account.
   final String captureMethod;
+
+  /// The currency of the payment.
   final String currency;
+
+  /// Set of key-value pairs attached to the object.
   final Map<String, String> metadata;
-  // TODO: charges, paymentMethod
+  // TODO: charges, paymentMethod, amountDetails
   final String? paymentMethodId;
+
+  /// Indicates how much the user intends to tip in addition to the amount by at confirmation time.
+  /// This is only non-null in the [PaymentIntent] instance returned during collect when using
+  /// updatePaymentIntent set to true in the CollectConfiguration.
+  ///
+  /// After [StripeTerminal.confirmPaymentIntent] the amount will have this tip amount added
+  /// to it and the [amountDetails] will contain the breakdown of how much of the amount was a tip.
   final double? amountTip;
+
+  /// Extra information about a [PaymentIntent]. This will appear on your customer’s statement
+  /// when this [PaymentIntent] succeeds in creating a charge.
   final String? statementDescriptor;
+
+  /// Extra dynamic information about a [PaymentIntent]. This will appear concatenated with the
+  /// [statementDescriptor] on your customer’s statement when this [PaymentIntent] succeeds in creating a charge.
   final String? statementDescriptorSuffix;
 
-  /// Only on android
+  /// !!! ONLY ON ANDROID !!!
 
+  /// Amount that can be captured from this [PaymentIntent].
   final double? amountCapturable;
+
+  /// Amount that was collected by this [PaymentIntent].
   final double? amountReceived;
+
+  /// ID of the Connect application that created the [PaymentIntent].
+  // TODO: rename to applicationId
   final String? application;
+
+  /// The amount of the application fee for this [PaymentIntent].
   final double? applicationFeeAmount;
+
+  /// Reason for cancellation of this [PaymentIntent], either user-provided (duplicate, fraudulent,
+  /// requested_by_customer, or abandoned) or generated by Stripe internally (failed_invoice,
+  /// void_invoice, or automatic).
   final String? cancellationReason;
+
+  /// Populated when status is [PaymentIntentStatus.canceled], this is the time at which
+  /// the [PaymentIntent] was canceled.
   final DateTime? canceledAt;
+
+  /// Get the client secret returned by this intent.
   final String? clientSecret;
+
+  /// One of automatic (default) or manual. When the confirmation method is automatic, a [PaymentIntent]
+  /// can be confirmed using a publishable key. After next_actions are handled, no additional confirmation
+  /// is required to complete the payment.
+  // TODO: Convert to [CaptureMethod] type
   final String? confirmationMethod;
+
+  /// 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].
+  // TODO: rename to customerId
   final String? customer;
+
+  /// An arbitrary string attached to the [PaymentIntent]. Often useful for displaying to users.
   final String? description;
+
+  /// ID of the invoice that created this PaymentIntent, if it exists.
+  // TODO: rename to invoiceId
   final String? invoice;
+
+  /// Return the account that the PaymentIntent is on behalf of
   final String? onBehalfOf;
+
+  /// ID of the review associated with this PaymentIntent, if any.
+  // TODO: rename to reviewId
   final String? review;
+
+  /// Email address that the receipt for the resulting payment will be sent to.
   final String? receiptEmail;
+
+  /// Value of setup_future_usage associated with this [PaymentIntent], if any.
   final String? setupFutureUsage;
+
+  /// Get the transfer group of this PaymentIntent
   final String? transferGroup;
 
   @internal
@@ -70,42 +149,115 @@ class PaymentIntent with _$PaymentIntent {
   });
 }
 
+/// The possible statuses for a [PaymentIntent].
 enum PaymentIntentStatus {
+  /// The [PaymentIntent] was canceled.
   canceled,
+
+  /// The [PaymentIntent] is in the middle of full EMV processing.
   processing,
+
+  /// Next step: capture the [PaymentIntent] on your backend via the Stripe API.
   requiresCapture,
+
+  /// Next step: confirm the payment by calling [StripeTerminal.confirmPaymentIntent].
   requiresConfirmation,
+
+  /// Next step: collect a payment method by calling [StripeTerminal.collectPaymentMethod].
   requiresPaymentMethod,
+
+  /// The [PaymentIntent] succeeded.
   succeeded,
+
+  // TODO: Missing `requiredAction` value
 }
 
-// TODO: https://github.com/BreX900/mek-packages/issues/11
 @DataClass()
 class PaymentIntentParameters with _$PaymentIntentParameters {
+  /// The amount of the payment, provided in the currency’s smallest unit.
   final int amount;
+
+  /// Three-letter ISO currency code, in lowercase. Must be a supported currency.
   final String currency;
+
+  /// The capture method that this PaymentIntent should use.
   final CaptureMethod captureMethod;
+
+  /// The list of payment method types that this PaymentIntent is allowed to use.
   final List<PaymentMethodType> paymentMethodTypes;
 
+  /// Set of key-value pairs that you can attach to an object. This can be useful for storing
+  /// additional information about the object in a structured format.
   final Map<String, String> metadata;
+
+  /// An arbitrary string attached to the object. If you send a receipt email for this payment,
+  /// the email will include the description.
   final String? description;
+
+  /// A string to be displayed on your customer’s credit card statement. This may be up to 22 characters.
+  /// The statement descriptor must contain at least one letter, may not include <>"' characters,
+  /// and will appear on your customer’s statement in capital letters. Non-ASCII characters
+  /// are automatically stripped. While most banks and card issuers display this information consistently,
+  /// some may display it incorrectly or not at all.
   final String? statementDescriptor;
+
+  /// A string to specify details about the transaction so your customer can understand it clearly
+  /// on their statement. The suffix is concatenated with the statementDescriptor, the * symbol,
+  /// and a space to form the complete statement descriptor that your customer sees. Maximum 22
+  /// characters for the final concatenated descriptor.
   final String? statementDescriptorSuffix;
+
+  /// Email address that the receipt for the resulting payment will be sent to.
   final String? receiptEmail;
+
+  /// The ID of the Customer this [PaymentIntent] is for, if one exists.
   final String? customerId;
+
+  /// The amount of the application fee (if any) that will be applied to the payment and transferred
+  /// to the application owner’s Stripe account. To use an application fee, the request must be made
+  /// on behalf of another account, using the stripeAccount property or an OAuth key.
   final int? applicationFeeAmount;
+
+  /// 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.
+  ///
+  /// At capture time, use `transfer_data[amount]` to specify the amount that will be transferred
+  /// automatically when a charge succeeds.
+  ///
+  /// When [transferDataDestination] is specified, [onBehalfOf] must also be specified and must
+  /// match the destination of the transfer.
   final String? transferDataDestination;
+
+  /// A string that identifies the resulting payment as part of a group.
   final String? transferGroup;
+
+  /// The Stripe account ID for which these funds are intended.
+  ///
+  /// When [transferDataDestination] is specified, [onBehalfOf] must also be specified and
+  /// must match the destination of the transfer.
   final String? onBehalfOf;
+
+  /// Indicates that you intend to make future payments with this [PaymentIntent]’s payment method.
+  ///
+  /// Providing this parameter will attach the payment method to the [PaymentIntent]’s Customer,
+  /// after the [PaymentIntent] is confirmed and any required actions from the user are complete.
+  /// If no Customer was provided, the payment method can still be attached to a Customer after
+  /// the transaction completes.
+  ///
+  /// Possible values: “on_session”: Use “on_session” if you intend to only reuse the payment method
+  /// when your customer is present in your checkout flow. “off_session”: Use “off_session” if your
+  /// customer may or may not be present in your checkout flow.
+  // TODO: Convert to [SetupIntentUsage] type
   final String? setupFutureUsage;
 
+  /// Specific options used during the creation of the PaymentMethod.
   final PaymentMethodOptionsParameters? paymentMethodOptionsParameters;
 
   PaymentIntentParameters({
     required this.amount,
     required this.currency,
-    required this.captureMethod,
-    required this.paymentMethodTypes,
+    this.captureMethod = CaptureMethod.manual,
+    this.paymentMethodTypes = const [PaymentMethodType.cardPresent],
     this.metadata = const {},
     this.description,
     this.statementDescriptor,
@@ -121,12 +273,33 @@ class PaymentIntentParameters with _$PaymentIntentParameters {
   });
 }
 
-enum PaymentMethodType { cardPresent, card, interactPresent }
+/// An enum representing the type of payment method being handled.
+enum PaymentMethodType {
+  /// A card present payment method.
+  cardPresent,
+
+  /// A card payment method.
+  card,
+
+  /// An Interac Present payment method.
+  interactPresent
+}
+
+/// Controls when the funds will be captured from the customer’s account.
+enum CaptureMethod {
+  /// Stripe automatically captures funds when the customer authorizes the payment.
+  automatic,
 
-enum CaptureMethod { automatic, manual }
+  /// Place a hold on the funds when the customer authorizes the payment, but don’t capture
+  /// the funds until later. Will require an explicit call to capture payments.
+  /// (Not all payment methods support this.)
+  manual
+}
 
+/// The PaymentMethodOptionsParameters contains options for PaymentMethod creation.
 @DataClass()
 class PaymentMethodOptionsParameters with _$PaymentMethodOptionsParameters {
+  /// Card-present-specific configuration for this PaymentMethod.
   final CardPresentParameters cardPresentParameters;
 
   const PaymentMethodOptionsParameters({