Merge pull request #2239 from stripe/latest-codegen-beta

Update generated code for beta

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+### Why?
+<!-- Describe why this change is being made.  Briefly include history and context, high-level what this PR does, and what the world looks like afterward. -->
+
+### What?
+<!--
+List out the key changes made in this PR, e.g.
+- implements the antimatter particle trace in the nitronium microfilament drive
+- updated tests -->
+
+### See Also
+<!-- Include any links or additional information that help explain this change. -->

CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 17.5.0 - 2024-12-18
+* [#2237](https://github.com/stripe/stripe-node/pull/2237) This release changes the pinned API version to `2024-12-18.acacia`.
+  * Change `Account.business_profile.annual_revenue` and `Account.business_profile.estimated_worker_count` to be optional
+  * Add support for `network_advice_code` and `network_decline_code` on `Charge.outcome`, `Invoice.last_finalization_error`, `PaymentIntent.last_payment_error`, `SetupAttempt.setup_error`, `SetupIntent.last_setup_error`, and `StripeError`
+  * Add support for new values `payout_minimum_balance_hold` and `payout_minimum_balance_release` on enum `BalanceTransaction.type`
+  * Add support for `credits_application_invoice_voided` on `Billing.CreditBalanceTransaction.credit`
+  * Change type of `Billing.CreditBalanceTransaction.credit.type` from `literal('credits_granted')` to `enum('credits_application_invoice_voided'|'credits_granted')`
+  * Change `BillingPortal.Configuration.features.subscription_update.schedule_at_period_end`, `Issuing.Authorization.verified_by_fraud_challenge`, `LineItem.description`, and `Payout.trace_id` to be required
+  * Add support for `allow_redisplay` on `Card` and `Source`
+  * Add support for `regulated_status` on `Card`, `Charge.payment_method_details.card`, `ConfirmationToken.payment_method_preview.card`, and `PaymentMethod.card`
+  * Add support for `funding` on `Charge.payment_method_details.amazon_pay` and `Charge.payment_method_details.revolut_pay`
+  * Add support for `network_transaction_id` on `Charge.payment_method_details.card`
+  * Add support for `reference_prefix` on `Checkout.Session.payment_method_options.bacs_debit.mandate_options`, `Checkout.Session.payment_method_options.sepa_debit.mandate_options`, `Checkout.SessionCreateParams.payment_method_options.bacs_debit.mandate_options`, `Checkout.SessionCreateParams.payment_method_options.sepa_debit.mandate_options`, `PaymentIntent.payment_method_options.bacs_debit.mandate_options`, `PaymentIntent.payment_method_options.sepa_debit.mandate_options`, `PaymentIntentConfirmParams.payment_method_options.bacs_debit.mandate_options`, `PaymentIntentConfirmParams.payment_method_options.sepa_debit.mandate_options`, `PaymentIntentCreateParams.payment_method_options.bacs_debit.mandate_options`, `PaymentIntentCreateParams.payment_method_options.sepa_debit.mandate_options`, `PaymentIntentUpdateParams.payment_method_options.bacs_debit.mandate_options`, `PaymentIntentUpdateParams.payment_method_options.sepa_debit.mandate_options`, `SetupIntent.payment_method_options.bacs_debit.mandate_options`, `SetupIntent.payment_method_options.sepa_debit.mandate_options`, `SetupIntentConfirmParams.payment_method_options.bacs_debit.mandate_options`, `SetupIntentConfirmParams.payment_method_options.sepa_debit.mandate_options`, `SetupIntentCreateParams.payment_method_options.bacs_debit.mandate_options`, `SetupIntentCreateParams.payment_method_options.sepa_debit.mandate_options`, `SetupIntentUpdateParams.payment_method_options.bacs_debit.mandate_options`, and `SetupIntentUpdateParams.payment_method_options.sepa_debit.mandate_options`
+  * Add support for new values `al_tin`, `am_tin`, `ao_tin`, `ba_tin`, `bb_tin`, `bs_tin`, `cd_nif`, `gn_nif`, `kh_tin`, `me_pib`, `mk_vat`, `mr_nif`, `np_pan`, `sn_ninea`, `sr_fin`, `tj_tin`, `ug_tin`, `zm_tin`, and `zw_tin` on enums `Checkout.Session.customer_details.tax_ids[].type`, `Invoice.customer_tax_ids[].type`, `Tax.Calculation.customer_details.tax_ids[].type`, `Tax.Transaction.customer_details.tax_ids[].type`, and `TaxId.type`
+  * Add support for new values `al_tin`, `am_tin`, `ao_tin`, `ba_tin`, `bb_tin`, `bs_tin`, `cd_nif`, `gn_nif`, `kh_tin`, `me_pib`, `mk_vat`, `mr_nif`, `np_pan`, `sn_ninea`, `sr_fin`, `tj_tin`, `ug_tin`, `zm_tin`, and `zw_tin` on enums `CustomerCreateParams.tax_id_data[].type`, `InvoiceCreatePreviewParams.customer_details.tax_ids[].type`, `InvoiceUpcomingLinesParams.customer_details.tax_ids[].type`, `InvoiceUpcomingParams.customer_details.tax_ids[].type`, `Tax.CalculationCreateParams.customer_details.tax_ids[].type`, and `TaxIdCreateParams.type`
+  * Add support for `visa_compliance` on `Dispute.evidence.enhanced_evidence`, `Dispute.evidence_details.enhanced_eligibility`, and `DisputeUpdateParams.evidence.enhanced_evidence`
+  * Add support for new value `request_signature` on enums `Forwarding.Request.replacements[]` and `Forwarding.RequestCreateParams.replacements[]`
+  * Add support for `account_holder_address` and `bank_address` on `FundingInstructions.bank_transfer.financial_addresses[].iban`, `FundingInstructions.bank_transfer.financial_addresses[].sort_code`, `FundingInstructions.bank_transfer.financial_addresses[].spei`, `FundingInstructions.bank_transfer.financial_addresses[].zengin`, `PaymentIntent.next_action.display_bank_transfer_instructions.financial_addresses[].iban`, `PaymentIntent.next_action.display_bank_transfer_instructions.financial_addresses[].sort_code`, `PaymentIntent.next_action.display_bank_transfer_instructions.financial_addresses[].spei`, and `PaymentIntent.next_action.display_bank_transfer_instructions.financial_addresses[].zengin`
+  * Add support for `account_holder_name` on `FundingInstructions.bank_transfer.financial_addresses[].spei` and `PaymentIntent.next_action.display_bank_transfer_instructions.financial_addresses[].spei`
+  * Add support for `disabled_reason` on `Invoice.automatic_tax`, `Subscription.automatic_tax`, `SubscriptionSchedule.default_settings.automatic_tax`, and `SubscriptionSchedule.phases[].automatic_tax`
+  * Add support for `tax_id` on `Issuing.Authorization.merchant_data` and `Issuing.Transaction.merchant_data`
+  * Change type of `LineItem.description` from `string` to `string | null`
+  * Add support for `trial_period_days` on `PaymentLinkUpdateParams.subscription_data`
+  * Add support for `al`, `am`, `ao`, `ba`, `bb`, `bs`, `cd`, `gn`, `kh`, `me`, `mk`, `mr`, `np`, `pe`, `sn`, `sr`, `tj`, `ug`, `uy`, `zm`, and `zw` on `Tax.Registration.country_options` and `Tax.RegistrationCreateParams.country_options`
+  * Add support for new value `2024-12-18.acacia` on enum `WebhookEndpointCreateParams.api_version`
+* [#2238](https://github.com/stripe/stripe-node/pull/2238) add missing key warning to README
+
 ## 17.5.0-beta.3 - 2024-12-12
 * [#2235](https://github.com/stripe/stripe-node/pull/2235) Update generated code for beta
   * Change `Account.business_profile.annual_revenue` and `Account.business_profile.estimated_worker_count` to be optional

OPENAPI_VERSION

@@ -1 +1 @@
-v1406
+v1437

README.md

@@ -61,6 +61,39 @@ const customer = await stripe.customers.create({
 console.log(customer.id);
 ```
 
+> [!WARNING]
+> If you're using `v17.x.x` or later and getting an error about a missing API key despite being sure it's available, it's likely you're importing the file that instantiates `Stripe` while the key isn't present (for instance, during a build step).
+> If that's the case, consider instantiating the client lazily:
+>
+> ```ts
+> import Stripe from 'stripe';
+>
+> let _stripe: Stripe | null = null;
+> const getStripe = (): Stripe => {
+>   if (!_stripe) {
+>     _stripe = new Stripe(process.env.STRIPE_SECRET_KEY as string, {
+>       // ...
+>     });
+>   }
+>   return _stripe;
+> };
+>
+> const getCustomers = () => getStripe().customers.list();
+> ```
+>
+> Alternatively, you can provide a placeholder for the real key (which will be enough to get the code through a build step):
+>
+> ```ts
+> import Stripe from 'stripe';
+>
+> export const stripe = new Stripe(
+>   process.env.STRIPE_SECRET_KEY || 'api_key_placeholder',
+>   {
+>     // ...
+>   }
+> );
+> ```
+
 ### Usage with TypeScript
 
 As of 8.0.1, Stripe maintains types for the latest [API version][api-versions].

src/resources/Treasury/FinancialAccounts.ts

@@ -20,6 +20,10 @@ export const FinancialAccounts = StripeResource.extend({
     fullPath: '/v1/treasury/financial_accounts',
     methodType: 'list',
   }),
+  close: stripeMethod({
+    method: 'POST',
+    fullPath: '/v1/treasury/financial_accounts/{financial_account}/close',
+  }),
   retrieveFeatures: stripeMethod({
     method: 'GET',
     fullPath: '/v1/treasury/financial_accounts/{financial_account}/features',

types/Accounts.d.ts

@@ -702,6 +702,11 @@ declare module 'stripe' {
          */
         directors_provided?: boolean;
 
+        /**
+         * This hash is used to attest that the director information provided to Stripe is both current and correct.
+         */
+        directorship_declaration?: Company.DirectorshipDeclaration | null;
+
         /**
          * Whether the company's executives have been provided. This Boolean will be `true` if you've manually indicated that all executives are provided via [the `executives_provided` parameter](https://stripe.com/docs/api/accounts/update#update_account-company-executives_provided), or if Stripe determined that sufficient executives were provided.
          */
@@ -742,6 +747,8 @@ declare module 'stripe' {
          */
         ownership_declaration?: Company.OwnershipDeclaration | null;
 
+        ownership_exemption_reason?: Company.OwnershipExemptionReason;
+
         /**
          * The company's phone number (used for verification).
          */
@@ -848,6 +855,23 @@ declare module 'stripe' {
           town: string | null;
         }
 
+        interface DirectorshipDeclaration {
+          /**
+           * The Unix timestamp marking when the directorship declaration attestation was made.
+           */
+          date: number | null;
+
+          /**
+           * The IP address from which the directorship declaration attestation was made.
+           */
+          ip: string | null;
+
+          /**
+           * The user-agent string from the browser where the directorship declaration attestation was made.
+           */
+          user_agent: string | null;
+        }
+
         interface OwnershipDeclaration {
           /**
            * The Unix timestamp marking when the beneficial owner attestation was made.
@@ -865,6 +889,10 @@ declare module 'stripe' {
           user_agent: string | null;
         }
 
+        type OwnershipExemptionReason =
+          | 'qualified_entity_exceeds_ownership_threshold'
+          | 'qualifies_as_financial_institution';
+
         type Structure =
           | 'free_zone_establishment'
           | 'free_zone_llc'

types/AccountsResource.d.ts

@@ -1060,6 +1060,10 @@ declare module 'stripe' {
          */
         ownership_declaration?: Company.OwnershipDeclaration;
 
+        ownership_exemption_reason?: Stripe.Emptyable<
+          Company.OwnershipExemptionReason
+        >;
+
         /**
          * The company's phone number (used for verification).
          */
@@ -1114,6 +1118,10 @@ declare module 'stripe' {
           user_agent?: string;
         }
 
+        type OwnershipExemptionReason =
+          | 'qualified_entity_exceeds_ownership_threshold'
+          | 'qualifies_as_financial_institution';
+
         type Structure =
           | 'free_zone_establishment'
           | 'free_zone_llc'
@@ -3061,6 +3069,10 @@ declare module 'stripe' {
          */
         ownership_declaration?: Company.OwnershipDeclaration;
 
+        ownership_exemption_reason?: Stripe.Emptyable<
+          Company.OwnershipExemptionReason
+        >;
+
         /**
          * The company's phone number (used for verification).
          */
@@ -3115,6 +3127,10 @@ declare module 'stripe' {
           user_agent?: string;
         }
 
+        type OwnershipExemptionReason =
+          | 'qualified_entity_exceeds_ownership_threshold'
+          | 'qualifies_as_financial_institution';
+
         type Structure =
           | 'free_zone_establishment'
           | 'free_zone_llc'

types/BillingPortal/Configurations.d.ts

@@ -181,10 +181,7 @@ declare module 'stripe' {
 
             type Mode = 'at_period_end' | 'immediately';
 
-            type ProrationBehavior =
-              | 'always_invoice'
-              | 'create_prorations'
-              | 'none';
+            type ProrationBehavior = 'create_prorations' | 'none';
           }
 
           interface SubscriptionUpdate {

types/BillingPortal/ConfigurationsResource.d.ts

@@ -168,10 +168,7 @@ declare module 'stripe' {
 
             type Mode = 'at_period_end' | 'immediately';
 
-            type ProrationBehavior =
-              | 'always_invoice'
-              | 'create_prorations'
-              | 'none';
+            type ProrationBehavior = 'create_prorations' | 'none';
           }
 
           interface SubscriptionUpdate {
@@ -430,10 +427,7 @@ declare module 'stripe' {
 
             type Mode = 'at_period_end' | 'immediately';
 
-            type ProrationBehavior =
-              | 'always_invoice'
-              | 'create_prorations'
-              | 'none';
+            type ProrationBehavior = 'create_prorations' | 'none';
           }
 
           interface SubscriptionUpdate {

types/Cards.d.ts

@@ -80,6 +80,11 @@ declare module 'stripe' {
        */
       brand: string;
 
+      /**
+       * The [product code](https://stripe.com/docs/card-product-codes) that identifies the specific program or product associated with a card. (For internal use only and not typically available in standard API requests.)
+       */
+      brand_product?: string | null;
+
       /**
        * Two-letter ISO code representing the country of the card. You could use this attribute to get a sense of the international breakdown of cards you've collected.
        */
@@ -172,7 +177,7 @@ declare module 'stripe' {
       /**
        * Status of a card based on the card issuer.
        */
-      regulated_status?: Card.RegulatedStatus | null;
+      regulated_status: Card.RegulatedStatus | null;
 
       /**
        * For external accounts that are cards, possible values are `new` and `errored`. If a payout fails, the status is set to `errored` and [scheduled payouts](https://stripe.com/docs/payouts#payout-schedule) are stopped until account details are updated.

types/Charges.d.ts

@@ -312,6 +312,11 @@ declare module 'stripe' {
       }
 
       interface Outcome {
+        /**
+         * An enumerated value providing a more detailed explanation on [how to proceed with an error](https://stripe.com/docs/declines#retrying-issuer-declines).
+         */
+        advice_code: Outcome.AdviceCode | null;
+
         /**
          * For charges declined by the network, a 2 digit code which indicates the advice returned by the network on how to proceed with an error.
          */
@@ -359,6 +364,11 @@ declare module 'stripe' {
       }
 
       namespace Outcome {
+        type AdviceCode =
+          | 'confirm_card_data'
+          | 'do_not_try_again'
+          | 'try_again_later';
+
         interface Rule {
           /**
            * The action taken on the payment.
@@ -900,7 +910,7 @@ declare module 'stripe' {
           /**
            * This is used by the financial networks to identify a transaction. Visa calls this the Transaction ID, Mastercard calls this the Trace ID, and American Express calls this the Acquirer Reference Data. The first three digits of the Trace ID is the Financial Network Code, the next 6 digits is the Banknet Reference Number, and the last 4 digits represent the date (MM/DD). This field will be available for successful Visa, Mastercard, or American Express transactions and always null for other card brands.
            */
-          network_transaction_id?: string | null;
+          network_transaction_id: string | null;
 
           overcapture?: Card.Overcapture;
 
@@ -909,7 +919,7 @@ declare module 'stripe' {
           /**
            * Status of a card based on the card issuer.
            */
-          regulated_status?: Card.RegulatedStatus | null;
+          regulated_status: Card.RegulatedStatus | null;
 
           /**
            * Populated if this transaction used 3D Secure authentication.
@@ -2064,6 +2074,11 @@ declare module 'stripe' {
         }
 
         interface Paypal {
+          /**
+           * Two-letter ISO code representing the buyer's country. Values are provided by PayPal directly (if supported) at the time of authorization or settlement. They cannot be set or mutated.
+           */
+          country: string | null;
+
           /**
            * Owner's email. Values are provided by PayPal directly
            * (if supported) at the time of authorization or settlement. They cannot be set or mutated.