Codegen for openapi e6f9d49

lib/Checkout/Session.php

@@ -32,7 +32,7 @@
  * @property null|string $client_reference_id A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the Session with your internal systems.
  * @property null|string $currency Three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a>, in lowercase. Must be a <a href="https://stripe.com/docs/currencies">supported currency</a>.
  * @property null|string|\Stripe\Customer $customer The ID of the customer for this Session. For Checkout Sessions in <code>payment</code> or <code>subscription</code> mode, Checkout will create a new customer object based on information provided during the payment flow unless an existing customer was provided when the Session was created.
- * @property null|\Stripe\StripeObject $customer_details The customer details including the customer's tax exempt status and the customer's tax IDs.
+ * @property null|\Stripe\StripeObject $customer_details The customer details including the customer's tax exempt status and the customer's tax IDs. Only present on Sessions in <code>payment</code> or <code>subscription</code> mode.
  * @property null|string $customer_email If provided, this value will be used when the Customer object is created. If not provided, customers will be asked to enter their email address. Use this parameter to prefill customer data if you already have an email on file. To access information about the customer once the payment flow is complete, use the <code>customer</code> attribute.
  * @property \Stripe\Collection $line_items The line items purchased by the customer.
  * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.

lib/Identity/VerificationSession.php

@@ -5,27 +5,34 @@
 namespace Stripe\Identity;
 
 /**
- * A VerificationSession is the starting-point for a verification flow that will
- * collect and verify data on your users. Each VerificationSesssion has a URL which
- * provides access to Stripe’s hosted identity verification UI. When you direct
- * your users to the link, Stripe will collect personal information and verify it.
- * You can retrieve the VerificationSession later to see the status of the checks
- * performed and access any data collected from your users.
+ * 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 <a
+ * href="/docs/identity/verification-checks">verification check</a> to perform.
+ * Only create one VerificationSession for each verification in your system.
+ *
+ * A VerificationSession transitions through <a
+ * href="/docs/identity/how-sessions-work">multiple statuses</a> 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: <a href="docs/identity/verification-sessions">The Verification
+ * Sessions API</a>
  *
  * @property string $id Unique identifier for the object.
  * @property string $object String representing the object's type. Objects of the same type share the same value.
- * @property string $client_secret This string value can be passed to stripe.js to embed a verification flow directly into your app.
+ * @property null|string $client_secret The short-lived client secret used by Stripe.js to <a href="https://stripe.com/docs/js/identity/modal">show a verification modal</a> inside your app. This client secret expires after 24 hours and can only be used once. Don’t store it, log it, embed it in a URL, or expose it to anyone other than the user. Make sure that you have TLS enabled on any page that includes the client secret. Refer to our docs on <a href="https://stripe.com/docs/identity/verification-sessions#client-secret">passing the client secret to the frontend</a> to learn more.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
- * @property null|\Stripe\StripeObject $last_error Hash of details on the last error encountered in the verification process.
- * @property null|string|\Stripe\Identity\VerificationReport $last_verification_report Link to the most recent completed VerificationReport for this Session.
+ * @property null|\Stripe\StripeObject $last_error If present, this property tells you the last error encountered when processing the verification.
+ * @property null|string|\Stripe\Identity\VerificationReport $last_verification_report ID of the most recent VerificationReport. <a href="https://stripe.com/docs/identity/verification-checks">Learn more about accessing detailed verification results.</a>
  * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
  * @property \Stripe\StripeObject $metadata Set of <a href="https://stripe.com/docs/api/metadata">key-value pairs</a> that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
  * @property \Stripe\StripeObject $options
  * @property null|\Stripe\StripeObject $redaction Redaction status of this VerificationSession. If the VerificationSession is not redacted, this field will be null.
- * @property string $status Status of this VerificationSession. Read more about each <a href="https://stripe.com/docs/identity/how-sessions-work">VerificationSession status</a>.
- * @property string $type Type of report requested.
- * @property null|string $url Link to the Stripe-hosted identity verification portal that you can send a user to for verification.
- * @property null|\Stripe\StripeObject $verified_outputs Hash of verified data about this person that results from a successful verification report.
+ * @property string $status Status of this VerificationSession. <a href="https://stripe.com/docs/identity/how-sessions-work">Learn more about the lifecycle of sessions</a>.
+ * @property string $type The type of <a href="https://stripe.com/docs/identity/verification-checks">verification check</a> to be performed.
+ * @property null|string $url The short-lived URL that you use to redirect a user to Stripe to submit their identity information. This URL expires after 24 hours and can only be used once. Don’t store it, log it, send it in emails or expose it to anyone other than the user. Refer to our docs on <a href="https://stripe.com/docs/identity/verify-identity-documents?platform=web&amp;type=redirect">verifying identity documents</a> to learn how to redirect users to Stripe.
+ * @property null|\Stripe\StripeObject $verified_outputs The user’s verified data.
  */
 class VerificationSession extends \Stripe\ApiResource
 {

lib/Service/Identity/VerificationSessionService.php

@@ -7,9 +7,7 @@
 class VerificationSessionService extends \Stripe\Service\AbstractService
 {
     /**
-     * List all verification sessions. Can optionally provide a status to return only
-     * VerificationSessions with that status. Can optionally specify a query filter on
-     * created timestamp.
+     * Returns a list of VerificationSessions.
      *
      * @param null|array $params
      * @param null|array|\Stripe\Util\RequestOptions $opts
@@ -24,10 +22,12 @@ public function all($params = null, $opts = null)
     }
 
     /**
-     * Mark a VerificationSession as canceled.
+     * A VerificationSession object can be canceled when it is in
+     * <code>requires_input</code> <a
+     * href="/docs/identity/how-sessions-work">status</a>.
      *
-     * If the VerificationSession is in the <code>processing</code> state, you must
-     * wait until it finishes before cancelling it.
+     * Once canceled, future submission attempts are disabled. This cannot be undone.
+     * <a href="/docs/identity/verification-sessions#cancel">Learn more</a>.
      *
      * @param string $id
      * @param null|array $params
@@ -43,7 +43,17 @@ public function cancel($id, $params = null, $opts = null)
     }
 
     /**
-     * Create a new VerificationSession to begin the verification process.
+     * Creates a VerificationSession object.
+     *
+     * After the VerificationSession is created, display a verification modal using the
+     * session <code>client_secret</code> or send your users to the session’s
+     * <code>url</code>.
+     *
+     * If your API key is in test mode, verification checks won’t actually process,
+     * though everything else will occur as if in live mode.
+     *
+     * Related guide: <a href="/docs/identity/verify-identity-documents">Verify your
+     * users’ identity documents</a>.
      *
      * @param null|array $params
      * @param null|array|\Stripe\Util\RequestOptions $opts
@@ -58,28 +68,29 @@ public function create($params = null, $opts = null)
     }
 
     /**
-     * Redact a VerificationSession to delete all collected information from Stripe.
+     * Redact a VerificationSession to remove all collected information from Stripe.
      * This will redact the VerificationSession and all objects related to it,
-     * including VerificationReports, Events, Files, request logs, etc. This redaction
-     * process may take up to four days. When the redaction process is in progress, the
-     * VerificationSession’s <code>redaction.status</code> field will be set to
-     * <code>processing</code>; when the process is finished, it will change to
-     * <code>redacted</code>.
+     * including VerificationReports, Events, request logs, etc.
+     *
+     * A VerificationSession object can be redacted when it is in
+     * <code>requires_input</code> or <code>verified</code> <a
+     * href="/docs/identity/how-sessions-work">status</a>. Redacting a
+     * VerificationSession in <code>requires_action</code> state will automatically
+     * cancel it.
+     *
+     * The redaction process may take up to four days. When the redaction process is in
+     * progress, the VerificationSession’s <code>redaction.status</code> field will be
+     * set to <code>processing</code>; when the process is finished, it will change to
+     * <code>redacted</code> and an <code>identity.verification_session.redacted</code>
+     * event will be emitted.
      *
      * Redaction is irreversible. Redacted objects are still accessible in the Stripe
      * API, but all the fields that contain personal data will be replaced by the
      * string <code>[redacted]</code> or a similar placeholder. The
      * <code>metadata</code> field will also be erased. Redacted objects cannot be
      * updated or used for any purpose.
      *
-     * If the VerificationSession is in the <code>processing</code> state, you must
-     * wait until it finishes before redacting it. Redacting a VerificationSession in
-     * <code>requires_action</code> state will automatically <a
-     * href="/docs/api/verification_sessions/cancel">cancel</a> it.
-     *
-     * An <a
-     * href="/docs/api/events/types#event_types-identity.verification_session.redacted"><code>identity.verification_session.redacted</code></a>
-     * webhook will be sent when a VerificationSession is redacted.
+     * <a href="/docs/identity/verification-sessions#redact">Learn more</a>.
      *
      * @param string $id
      * @param null|array $params
@@ -95,12 +106,11 @@ public function redact($id, $params = null, $opts = null)
     }
 
     /**
-     * Retrieves an existing VerificationSession. When the session <code>status</code>
-     * is <code>requires_input</code>, this method guarantees that the redirect
-     * <code>url</code> is fresh: if your user has previously visited this session, a
-     * new <code>url</code> will be returned. Before redirecting your user to Stripe,
-     * ensure that you have just Created or Retrieved the VerificationSession; never
-     * cache or store the <code>url</code>.
+     * Retrieves the details of a VerificationSession that was previously created.
+     *
+     * When the session status is <code>requires_input</code>, you can use this method
+     * to retrieve a valid <code>client_secret</code> or <code>url</code> to allow
+     * re-submission.
      *
      * @param string $id
      * @param null|array $params
@@ -116,7 +126,10 @@ public function retrieve($id, $params = null, $opts = null)
     }
 
     /**
-     * Update properties on a VerificationSession.
+     * Updates a VerificationSession object.
+     *
+     * When the session status is <code>requires_input</code>, you can use this method
+     * to update the verification check and options.
      *
      * @param string $id
      * @param null|array $params