Update Stripe Payment Intent Version to Dahlia
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.
Customer Impact
These changes will impact your integration depending on your current implementation:
- 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.
See the section breakouts below for more detailed information on each change.
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.
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. Once legacy Level 3 support is removed, requests using old field names will fail.
Current state
Legacy field names:
merchant_referenceshipping_address_zip, shipping_from_zipLine items using product_description and flat_tax_amount`
New state (Clover):
Updated field names and structure are required:
order_referenceshipping_to_postal_codeshipping_from_postal_codeLine items must use product_name and structured tax fields like total_tax_amount with optional tax_breakdowns
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.
Exact Field Mapping
| Old Field Name | New Field Name |
|---|---|
merchant_reference | order_reference |
shipping_address_zip | shipping_to_postal_code |
shipping_from_zip | shipping_from_postal_code |
Product_description and tax_amount | Line items must use product_name and structured tax fields like total_tax_amount (with optional tax_breakdowns) |
Non-breaking enhancments
Implemented by Stripe in 2026-04-22.dahlia
Optional :
- 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. - iDEAL
transaction_idin GSRF(2025-11-17) - Return iDEAL bank reference from charge PM details on the transaction response. - Automatic tax on PI(2025-11-17) — GSF to enable Stripe Tax calculation on Payment Intent create/update.
enforce_arithmetic_validationopt-out(2026-01-28) - GSF for merchants using L3 line items when Stripe strict math validation fails.transaction_purposefor US bank account(2026-02-25) - GSF for ACH complianceamount_to_confirmon PI confirm(2026-04-22) - GSF on confirm for surcharge or confirm-with-adjusted-amount flows.
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 until January 21, 2027.
- We will deploy changes ahead of the final cutoff to allow sufficient testing time.
- You can opt in early to 2026-04-22.dahlia 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 2026-04-22.dahlia until changeover.
- Once the changeover is complete you should remove the GSF
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.
Updated 12 days ago

