Merge pull request #915 from stripe/remi/codegen-83431de

Improve PHPdocs for many classes

lib/Charge.php

@@ -20,6 +20,7 @@
  * @property null|int $application_fee_amount The amount of the application fee (if any) for the charge. <a href="https://stripe.com/docs/connect/direct-charges#collecting-fees">See the Connect documentation</a> for details.
  * @property null|string|\Stripe\BalanceTransaction $balance_transaction ID of the balance transaction that describes the impact of this charge on your account balance (not including refunds or disputes).
  * @property \Stripe\StripeObject $billing_details
+ * @property null|string $calculated_statement_descriptor The full statement descriptor that is passed to card networks, and that is displayed on your customers' credit card and bank statements. Allows you to see what the statement descriptor looks like after the static and dynamic portions are combined.
  * @property bool $captured If the charge was created without capturing, this Boolean represents whether it is still uncaptured or has since been captured.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property 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>.
@@ -38,12 +39,12 @@
  * @property null|string|\Stripe\Order $order ID of the order this charge is for if one exists.
  * @property null|\Stripe\StripeObject $outcome Details about whether the payment was accepted, and why. See <a href="https://stripe.com/docs/declines">understanding declines</a> for details.
  * @property bool $paid <code>true</code> if the charge succeeded, or was successfully authorized for later capture.
- * @property null|string $payment_intent ID of the PaymentIntent associated with this charge, if one exists.
+ * @property null|string|\Stripe\PaymentIntent $payment_intent ID of the PaymentIntent associated with this charge, if one exists.
  * @property null|string $payment_method ID of the payment method used in this charge.
  * @property null|\Stripe\StripeObject $payment_method_details Details about the payment method at the time of the transaction.
  * @property null|string $receipt_email This is the email address that the receipt for this charge was sent to.
  * @property null|string $receipt_number This is the transaction number that appears on email receipts sent for this charge. This attribute will be <code>null</code> until a receipt has been sent.
- * @property string $receipt_url This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.
+ * @property null|string $receipt_url This is the URL to view the receipt for this charge. The receipt is kept up-to-date to the latest state of the charge, including any refunds. If the charge is for an Invoice, the receipt will be stylized as an Invoice receipt.
  * @property bool $refunded Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false.
  * @property \Stripe\Collection $refunds A list of refunds that have been applied to the charge.
  * @property null|string|\Stripe\Review $review ID of the review associated with this charge if one exists.

lib/Invoice.php

@@ -98,7 +98,7 @@
  * @property \Stripe\StripeObject $threshold_reason
  * @property int $total Total after discounts and taxes.
  * @property null|\Stripe\StripeObject[] $total_tax_amounts The aggregate amounts calculated per tax rate for all line items.
- * @property null|int $webhooks_delivered_at The time at which webhooks for this invoice were successfully delivered (if the invoice had no webhooks to deliver, this will match <code>created</code>). Invoice payment is delayed until webhooks are delivered, or until all webhook delivery attempts have been exhausted.
+ * @property null|int $webhooks_delivered_at Invoices are automatically paid or sent 1 hour after webhooks are delivered, or until all webhook delivery attempts have <a href="https://stripe.com/docs/billing/webhooks#understand">been exhausted</a>. This field tracks the time when webhooks for this invoice were successfully delivered. If the invoice had no webhooks to deliver, this will be set while the invoice is being created.
  */
 class Invoice extends ApiResource
 {

lib/Issuing/Authorization.php

@@ -14,27 +14,27 @@
  *
  * @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 int $amount The total amount in the card's currency that was authorized or rejected.
+ * @property int $amount The total amount that was authorized or rejected. This amount is in the card's currency and in the <a href="https://stripe.com/docs/currencies#zero-decimal">smallest currency unit</a>.
  * @property bool $approved Whether the authorization has been approved.
  * @property string $authorization_method How the card details were provided.
- * @property int $authorized_amount The amount that has been authorized. This will be <code>0</code> when the object is created, and increase after it has been approved.
- * @property string $authorized_currency The currency that was presented to the cardholder for the authorization. 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 int $authorized_amount [DEPRECATED] The amount that has been authorized. This will be <code>0</code> when the object is created, and increase after it has been approved.
+ * @property string $authorized_currency [DEPRECATED] The currency that was presented to the cardholder for the authorization. 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 \Stripe\BalanceTransaction[] $balance_transactions List of balance transactions associated with this authorization.
  * @property \Stripe\Issuing\Card $card You can <a href="https://stripe.com/docs/issuing/cards">create physical or virtual cards</a> that are issued to cardholders.
  * @property null|string|\Stripe\Issuing\Cardholder $cardholder The cardholder to whom this authorization belongs.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property 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 int $held_amount The amount the authorization is expected to be in <code>held_currency</code>. When Stripe holds funds from you, this is the amount reserved for the authorization. This will be <code>0</code> when the object is created, and increase after it has been approved. For multi-currency transactions, <code>held_amount</code> can be used to determine the expected exchange rate.
- * @property string $held_currency The currency of the <a href="https://stripe.com/docs/api#issuing_authorization_object-held_amount">held amount</a>. This will always be the card currency.
- * @property bool $is_held_amount_controllable If set <code>true</code>, you may provide <a href="https://stripe.com/docs/api/issuing/authorizations/approve#approve_issuing_authorization-held_amount">held_amount</a> to control how much to hold for the authorization.
+ * @property int $held_amount [DEPRECATED] The amount the authorization is expected to be in <code>held_currency</code>. When Stripe holds funds from you, this is the amount reserved for the authorization. This will be <code>0</code> when the object is created, and increase after it has been approved. For multi-currency transactions, <code>held_amount</code> can be used to determine the expected exchange rate.
+ * @property string $held_currency [DEPRECATED] The currency of the <a href="https://stripe.com/docs/api#issuing_authorization_object-held_amount">held amount</a>. This will always be the card currency.
+ * @property bool $is_held_amount_controllable [DEPRECATED] If set <code>true</code>, you may provide <a href="https://stripe.com/docs/api/issuing/authorizations/approve#approve_issuing_authorization-held_amount">held_amount</a> to control how much to hold for the authorization.
  * @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 int $merchant_amount The total amount that was authorized or rejected in the local merchant_currency.
+ * @property int $merchant_amount The total amount that was authorized or rejected. This amount is in the <code>merchant_currency</code> and in the <a href="https://stripe.com/docs/currencies#zero-decimal">smallest currency unit</a>.
  * @property string $merchant_currency The currency that was presented to the cardholder for the authorization. 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 \Stripe\StripeObject $merchant_data
  * @property \Stripe\StripeObject $metadata 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.
- * @property int $pending_authorized_amount The amount the user is requesting to be authorized. This field will only be non-zero during an <code>issuing.authorization.request</code> webhook.
- * @property int $pending_held_amount The additional amount Stripe will hold if the authorization is approved. This field will only be non-zero during an <code>issuing.authorization.request</code> webhook.
- * @property null|\Stripe\StripeObject $pending_request The pending authorization request. This field will only be non-null during an <code>issuing.authorization.request</code> webhook.
+ * @property int $pending_authorized_amount [DEPRECATED] The amount the user is requesting to be authorized. This field will only be non-zero during an <code>issuing_authorization.request</code> webhook.
+ * @property int $pending_held_amount [DEPRECATED] The additional amount Stripe will hold if the authorization is approved. This field will only be non-zero during an <code>issuing_authorization.request</code> webhook.
+ * @property null|\Stripe\StripeObject $pending_request The pending authorization request. This field will only be non-null during an <code>issuing_authorization.request</code> webhook.
  * @property \Stripe\StripeObject[] $request_history History of every time the authorization was approved/denied (whether approved/denied by you directly, or by Stripe based on your authorization_controls). If the merchant changes the authorization by performing an <a href="https://stripe.com/docs/issuing/purchases/authorizations">incremental authorization or partial capture</a>, you can look at request_history to see the previous states of the authorization.
  * @property string $status The current status of the authorization in its lifecycle.
  * @property \Stripe\Issuing\Transaction[] $transactions List of <a href="https://stripe.com/docs/api/issuing/transactions">transactions</a> associated with this authorization.

lib/Issuing/Card.php

@@ -10,20 +10,22 @@
  * @property string $object String representing the object's type. Objects of the same type share the same value.
  * @property \Stripe\StripeObject $authorization_controls
  * @property string $brand The brand of the card.
- * @property null|\Stripe\Issuing\Cardholder $cardholder The <a href="https://stripe.com/docs/api#issuing_cardholder_object">Cardholder</a> object to which the card belongs.
+ * @property null|string $cancellation_reason The reason why the card was canceled.
+ * @property \Stripe\Issuing\Cardholder $cardholder <p>An Issuing <code>Cardholder</code> object represents an individual or business entity who is <a href="https://stripe.com/docs/issuing">issued</a> cards.</p><p>Related guide: <a href="https://stripe.com/docs/issuing/cards#create-cardholder">How to create a Cardholder</a></p>
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property 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 int $exp_month The expiration month of the card.
  * @property int $exp_year The expiration year of the card.
  * @property string $last4 The last 4 digits of the card number.
  * @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 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.
- * @property string $name The name of the cardholder, printed on the card.
+ * @property string $name [DEPRECATED] The name of the cardholder, printed on the card. Refer to <code>cardholder.name</code> instead.
  * @property null|\Stripe\StripeObject $pin Metadata about the PIN on the card.
  * @property null|string|\Stripe\Issuing\Card $replaced_by The latest card that replaces this card, if any.
  * @property null|string|\Stripe\Issuing\Card $replacement_for The card this card replaces, if any.
  * @property null|string $replacement_reason The reason why the previous card needed to be replaced.
  * @property null|\Stripe\StripeObject $shipping Where and how the card will be shipped.
+ * @property \Stripe\StripeObject $spending_controls
  * @property string $status Whether authorizations can be approved on this card.
  * @property string $type The type of the card.
  */

lib/Issuing/Cardholder.php

@@ -12,7 +12,7 @@
  *
  * @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 null|\Stripe\StripeObject $authorization_controls Spending rules that give you some control over how this cardholder's cards can be used. Refer to our <a href="https://stripe.com/docs/issuing/purchases/authorizations">authorizations</a> documentation for more details.
+ * @property null|\Stripe\StripeObject $authorization_controls [DEPRECATED] Spending rules that give you some control over how this cardholder's cards can be used. Refer to our <a href="https://stripe.com/docs/issuing/purchases/authorizations">authorizations</a> documentation for more details.
  * @property \Stripe\StripeObject $billing
  * @property null|\Stripe\StripeObject $company Additional information about a <code>company</code> cardholder.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
@@ -24,6 +24,7 @@
  * @property string $name The cardholder's name. This will be printed on cards issued to them.
  * @property null|string $phone_number The cardholder's phone number.
  * @property \Stripe\StripeObject $requirements
+ * @property null|\Stripe\StripeObject $spending_controls Spending rules that give you some control over how this cardholder's cards can be used. Refer to our <a href="https://stripe.com/docs/issuing/purchases/authorizations">authorizations</a> documentation for more details.
  * @property string $status Specifies whether to permit authorizations on this cardholder's cards.
  * @property string $type One of <code>individual</code> or <code>company</code>.
  */

lib/Issuing/Transaction.php

@@ -14,16 +14,16 @@
  *
  * @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 int $amount The amount of this transaction in your currency. This is the amount that your balance will be updated by.
+ * @property int $amount The transaction amount, which will be reflected in your balance. This amount is in your currency and in the <a href="https://stripe.com/docs/currencies#zero-decimal">smallest currency unit</a>.
  * @property null|string|\Stripe\Issuing\Authorization $authorization The <code>Authorization</code> object that led to this transaction.
  * @property null|string|\Stripe\BalanceTransaction $balance_transaction ID of the <a href="https://stripe.com/docs/api/balance_transactions">balance transaction</a> associated with this transaction.
  * @property string|\Stripe\Issuing\Card $card The card used to make this transaction.
  * @property null|string|\Stripe\Issuing\Cardholder $cardholder The cardholder to whom this transaction belongs.
  * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property 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\Issuing\Dispute $dispute If you've disputed the transaction, the ID of the <a href="https://stripe.com/docs/api/issuing/disputes/object">dispute object</a>.
+ * @property null|string|\Stripe\Issuing\Dispute $dispute If you've disputed the transaction, the ID of the dispute.
  * @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 int $merchant_amount The amount that the merchant will receive, denominated in <code>merchant_currency</code>. It will be different from <code>amount</code> if the merchant is taking payment in a different currency.
+ * @property int $merchant_amount The amount that the merchant will receive, denominated in <code>merchant_currency</code> and in the <a href="https://stripe.com/docs/currencies#zero-decimal">smallest currency unit</a>. It will be different from <code>amount</code> if the merchant is taking payment in a different currency.
  * @property string $merchant_currency The currency with which the merchant is taking payment.
  * @property \Stripe\StripeObject $merchant_data
  * @property \Stripe\StripeObject $metadata 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.

lib/Mandate.php

@@ -14,8 +14,8 @@
  * @property string|\Stripe\PaymentMethod $payment_method ID of the payment method associated with this mandate.
  * @property \Stripe\StripeObject $payment_method_details
  * @property \Stripe\StripeObject $single_use
- * @property string $status The status of the Mandate, one of <code>pending</code>, <code>inactive</code>, or <code>active</code>. The Mandate can be used to initiate a payment only if status=active.
- * @property string $type The type of the mandate, one of <code>single_use</code> or <code>multi_use</code>
+ * @property string $status The status of the mandate, which indicates whether it can be used to initiate a payment.
+ * @property string $type The type of the mandate.
  */
 class Mandate extends ApiResource
 {