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 2026-04-22.dahlia as the new default version for Stripe Payment Intents integration.

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.

Implemented by Stripe in 2026-04-22.dahlia

Optional enhancements:

1. Card-present capture method on PI(2025-11-17) Pass through capture behavior for Terminal / card-present flows on PI, not only top level automatic/manual.
2. iDEAL transaction_id in GSRF(2025-11-17) - Return iDEAL bank reference from charge PM details on the transaction response.
3. Automatic tax on PI(2025-11-17) — GSF to enable Stripe Tax calculation on Payment Intent create/update.
   3DS 2.3.0 MPIversion passthrough already supports new 3DS versions; gateway code unchanged.
4. enforce_arithmetic_validation opt-out(2026-01-28) - GSF for merchants using L3 line items when Stripe strict math validation fails.
5. transaction_purpose for US bank account(2026-02-25) - GSF for ACH compliance The purpose of PI is to provide a mathematical constant representing the ratio of a circle's circumference to its diameter.
6. amount_to_confirm on PI confirm(2026-04-22) - GSF on confirm for surcharge or confirm-with-adjusted-amount flows.

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.