Spring Boot 4 Migration on a Live Payments Platform
bankingNovember 19, 2026

Spring Boot 4 Migration on a Live Payments Platform

OpenRewrite first, AI second

Spring Boot 3.5 reached the end of its open-source support on 30 June 2026. For a payments platform, that's not a footnote: every week on an unsupported framework is a week of dependency vulnerabilities that no longer get free patches, on systems that move customers' money. The destination is also a moving target. Spring Boot 4.0 loses open-source support on 31 December 2026, and 4.1 has been available since June. So the realistic plan is to go straight to the newest 4.x line and land it without freezing feature delivery for a quarter. 

The work itself is less dramatic than the move from Boot 2 to 3, which forced the javax to jakarta rename across everything. Boot 4 has no single sweeping change. Instead there are many medium-sized ones that add up: Spring Framework 7, starters split into smaller modules, Jackson 3 as the default JSON library with new package names and different defaults, Spring Security 7, Hibernate 7, Testcontainers 2 and a list of removed deprecations. Most of that is mechanical, so let a deterministic tool do it. The part that isn't mechanical is where a payments platform's real risk sits, and it needs engineers, with AI assistants helping in a tightly bounded role. 

This is the approach we use: OpenRewrite for everything a recipe can express, AI for the remainder, and a delivery plan that keeps the main branch shippable throughout. 


Step 0: make the starting point clean 


Every migration problem you fix on 3.5 is one you don't have to untangle on 4.x. Before touching the Boot version: 

Move to the latest 3.5 patch release, and build with deprecation warnings visible. Anything deprecated in 3.x is likely to be removed in 4.0. 

Confirm the Java baseline. Boot 4 requires Java 17, but most payment platforms we see are moving to Java 21 or 25 in the same programme. Do the JDK upgrade as a separate, earlier step so the two changes can't mask each other. 

Inventory third-party dependencies that don't have a Boot 4 compatible release yet: an HSM client, a scheme SDK, an older observability agent. These, not your own code, usually set the real timeline. 


Then build the safety net the rest of the plan depends on. For a payments platform that means three things. Golden-file serialisation tests for every externally visible JSON payload: API responses, webhook bodies, messages to schemes and partners. Contract tests with your consumers, so a changed field is caught before release. And a response-comparison harness that can replay recorded traffic against two builds and diff the outputs. Jackson 3 is exactly the kind of change that compiles cleanly and alters the wire format, and these tests are what catch it. 


Step 1: let OpenRewrite do the mechanical work 

OpenRewrite's org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0 is a composite recipe. It chains the 3.5 upgrade, Spring Framework 7, Spring Security 7, property migrations, the @MockBean to @MockitoBean replacement, Hibernate 7.1, Testcontainers 2, SpringDoc 3 and the starter renames, such as spring-boot-starter-web becoming spring-boot-starter-webmvc. Jackson has its own recipe, org.openrewrite.java.jackson.UpgradeJackson_2_3, which moves packages from com.fasterxml.jackson to tools.jackson and updates group IDs. Annotations stay where they were. 


The key practice is to treat the migration as code that lives in the repository, not as a one-off command: 

 1 # rewrite.yml, committed to the repository 
 2 type: specs.openrewrite.org/v1beta/recipe 
 3 name: com.bank.payments.MigrateToBoot4 
 4 displayName: Payments platform migration to Spring Boot 4 
 5 recipeList: 
 6   - org.openrewrite.java.spring.boot4.UpgradeSpringBoot_4_0 
 7   - com.bank.payments.MigrateInternalPaymentClient   # our own recipe 
 8   - com.bank.payments.RenameLegacyMetricsProperties  # our own recipe 
 9  mvn -U org.openrewrite.maven:rewrite-maven-plugin:run \ 
10   -Drewrite.recipeArtifactCoordinates=org.openrewrite.recipe:rewrite-spring:RELEASE \ 
11   -Drewrite.activeRecipes=com.bank.payments.MigrateToBoot4 \ 
12   -Drewrite.exportDatatables=true 

Committing the recipe changes how the migration branch behaves. You don't keep a long-lived branch alive and merge main into it every week, collecting conflicts as you go. You re-run the recipe against a fresh main whenever you need a current migration branch. Feature teams keep shipping on 3.5, and the migration always reflects today's code. Your own custom recipes, for internal starters, shared payment-client libraries and company-specific properties, go into the same file. Most are short declarative YAML: a type rename, a property key change, a dependency swap. Writing them once means every service in the estate gets the same treatment. 

Keep the data tables the recipe exports. They list every change made, file by file, and they're the natural change-management record for a regulated platform: evidence of what was changed automatically, produced as a side effect. 


Step 2: land it in shippable increments 

The migration shouldn't arrive as one big release. Boot 4 provides transition aids that let you split it into steps, each deployable and each reversible: 

Boot 4 with the bridges in place. Use the classic starters (spring-boot-starter-classic, spring-boot-starter-test-classic), which restore Boot 3's broad dependency set. Keep Jackson 2 behaviour where you need it, through the spring-boot-jackson2 module or spring.jackson.use-jackson2-defaults=true. Ship this, canary it and let it run. 


Jackson 3 on the wire. Remove the Jackson 2 bridges one service at a time. Golden files and contract tests carry this step. 

Modular starters. Replace the classic starters with the specific ones each service needs. The deployable gets smaller, and it's clear what each service depends on. 

Both bridges are explicitly temporary and deprecated, so treat them as scaffolding with a removal date, not as a resting place. Each step is also small enough to roll back on its own, which matters on a platform where a bad release means failed payments rather than a broken page. 


Step 3: where the recipes stop 

After the recipes run, a residue remains, and on a payments platform it's concentrated in exactly the code that matters most: 

Custom Jackson serialisers and deserialisers for amounts, currency codes, ISO 20022 fields and partner-specific date formats. Jackson 3 changes how mappers are built: JsonMapper.builder() instead of mutating an ObjectMapper. It replaces checked exceptions with unchecked ones, and it changes defaults such as how dates are written. The package rename is mechanical. Whether your serialised payment instruction is still byte-for-byte what the scheme expects is not. 


Custom auto-configuration and internal starters that relied on Boot classes that moved or were made internal by the modularisation. 

Spring Security 7 edge cases in filter chains with mutual TLS, custom authentication providers or step-up flows. 

Third-party libraries that need a newer version, a shim or a replacement. 

Test failures whose cause isn't obvious from the stack trace. 


This is where Claude Code and GitHub Copilot earn their place, each in a different role. Claude Code works well for analysis across many files. Give it the recipe's data tables, the compiler output and the relevant section of the official migration guide, and ask it to group the remaining failures by root cause and propose a fix strategy for each group before writing any code. Copilot works well for small, reviewed changes inside one file, such as converting a serialiser to the Jackson 3 API while the engineer watches. 


The prompts that work best share three constraints: 

Context: Spring Boot 3.5 → 4.1 migration. OpenRewrite has already run; 
its changes are committed. Do not modify files outside src/main/java/ 
com/bank/payments/serialization/. 
 
Task: Migrate MoneySerializer and IsoDateTimeDeserializer to the 
Jackson 3 API (tools.jackson.*). 
 
Constraints: 
- The serialised JSON must remain byte-identical. The golden files in 
  src/test/resources/golden/ are the specification; do not edit them. 
- Amounts stay BigDecimal with scale taken from the currency; 
  never introduce double. 
- For each change, cite the Jackson 3 or Spring Boot 4 migration 
  guide section it relies on. If no section applies, say so and stop. 

The first constraint keeps the assistant's changes to a small, reviewable surface. The second makes the existing tests, not the model's judgement, the definition of correct. The third makes the reasoning auditable and stops the assistant inventing an API change that doesn't exist. AI-assisted commits stay separate from recipe commits and are labelled as such, so a reviewer always knows which changes came from a deterministic tool and which need a careful read. 


What AI should not do here is just as clear. It shouldn't "fix" a failing golden-file test by updating the golden file. It shouldn't rewrite security configuration it can't fully see. And it shouldn't resolve a dependency conflict by quietly downgrading something. Those decisions belong to the engineer who owns the service. 


Step 4: prove it before customers see it 

The response-comparison harness from Step 0 now does its main job. Replay recorded production traffic, with personal data masked, against a 3.5 build and a 4.x build of the same service and diff every response, field by field. Expect some differences, such as timestamp precision or the order of properties, and decide explicitly which ones are acceptable. Anything touching amounts, currency, account identifiers or status codes must be identical. 


From there, release the way any change to a payment service should be released: a canary with a small share of traffic, error rates and latency compared side by side with the old version, a tested rollback path, and wider rollout only once the canary has run through a full business cycle, including end-of-day batches and settlement windows. 


What this adds up to 

A Boot 4 migration on a live payments platform isn't a heroic sprint. It's a sequence of small, shippable, reversible steps. A deterministic tool does the bulk of the change. AI assistants work on the remaining edge cases under strict constraints. And tests that define correctness by the bytes on the wire, not by whether the build passes, guard every step. 


The order matters: OpenRewrite first, because its changes are repeatable, reviewable and identical across every service; AI second, because it's genuinely useful for the long tail but only safe once that tail is small and fenced in. Done that way, the platform reaches a supported framework without a delivery freeze, and the change-management record writes itself from the recipe output, the AI-assisted commits and the test evidence. That's the kind of upgrade programme we design for payments teams: routine maintenance, planned ahead of the support deadline, with no disruption for the people who depend on the platform every day.