Update Stripe Payment Intent Version to Clover

Overview

Spreedly is updating its Stripe Payment Intents integration to align with newer API versions released by Stripe.

Today, Spreedly supports Stripe API version 2025-02-24.acacia. With this update

we are aligning to 2025-10-29.clover as the new default version for Stripe Payment Intents integration.

Note, The latest API version is 2026-04-22.dahlia and Spreedly will have plans for that version at a later date after evaluating the breaking changes.

What’s Changing (Current vs New State)

1. Balance Transactions (Implemented by Stripe in 2025-03-31.basil)

Stripe has changed how balance transaction amounts and fees are calculated.

• Current state:

Balance transactions for partial captures could be based on the authorized total, not only the captured total.

• New state:

Balance transactions will reflect only the captured amount and fees will be calculated based only on the captured amount. See Stripe documentation for more details.

• Example:

If a payment is authorized for 10,000 but only 8,000 is captured, the balance transaction will now show amount = 8,000 and fees calculated on 8,000, instead of 10,000.

2. Refund Behavior (Implemented by Stripe in 2025-03-31.basil)

Stripe has changed how refunds are generated in certain payment flows.

• Current state:

Your integration can receive a Refund object in flows like partial captures or cancellations.

• New state:

Stripe will not create a Refund object for partial captures or payment cancellations. See Stripe documentation for more details.

• Example:

A workflow that previously returned a refund reference (e.g., refund ID) after a partial capture will now return no refund object at all.

3. Level 3 / Line Item Data (Implemented by Stripe in 2025-10-29.clover)

Stripe is standardizing Level 3 (enhanced line item) data and removing legacy formats.

• Current state:

Legacy field names and structures will still continue to work for the next 60 days, such as:

merchant_reference

shipping_address_zip, shipping_from_zip

Line items using product_description and flat tax_amount

• New state (Clover):

After the 60 days notice is over Updated field names and structure are required as follows:

• Example:

A line item that previously used product_description = "T-shirt" and tax_amount = 100 must now use product_name = "T-shirt" and total_tax_amount = 100, with optional tax breakdown details.

Once legacy Level 3 support is removed, requests using old field names will fail.

Customer Impact

These changes will impact your integration depending on your current implementation if you use any of the following features and take no action:

If you use balance transaction data (via GSRF), your reporting and reconciliation will change due to captured-only amounts and fees.

If your workflows depend on Refund objects, especially for partial capture or cancellation flows, those workflows will break or return incomplete data.

If you use Level 3 / line item data, requests using legacy field names or formats will fail once deprecated.

What You Need to Do

To ensure a smooth transition, we recommend the following:

Review and update any reporting or reconciliation logic to rely on captured amounts rather than authorized amounts.

Update your refund handling logic so it does not assume a Refund object will always exist.

• Migrate all Level 3 and line item fields to the new naming conventions and structure.
• Validate your integration against the updated behavior before enforcement.

Migration Strategy & Rollout Approach

We are providing a controlled migration path to minimize disruption:

By default, our integration will continue using 2025-02-24.acacia for the next 60 days.

• We will deploy changes ahead of the final cutoff to allow sufficient testing time.
• You can opt in early to 2025-10-29.clover to test and validate changes ahead of enforcement by using the “version_override” GSF.
• When ready you can change over production to continue to use version_override as 2025-10-29.clover until changeover.
• Once the changeover is complete you can remove the GSF or leave it in place.

Please note:

We will be giving notification warnings of the impending update through changelog.

• Once enforcement occurs, integrations that have not migrated will experience breaking failures
• There is no automatic synchronization—customers must actively validate and update the integration using the override.