feat: require environmentSubdomain or an explicit useLegacyDomain opt-out

[armando-rodriguez-cko]

Summary

Makes the merchant-specific subdomain (MSSD) mandatory. Callers must now call environmentSubdomain(...), or explicitly opt out with the new, already-@Deprecated useLegacyDomain(). Setting both, or neither, throws CheckoutArgumentException at client construction. MSSD is no longer beta and non-MSSD usage will be deprecated, so the previous silent fallback to api.checkout.com had to go.

Changes

• AbstractCheckoutSdkBuilder — the subdomain is held as a String and the EnvironmentSubdomain is built when the configuration is assembled, so environmentSubdomain() no longer has to be called after environment(); new useLegacyDomain() marked @Deprecated; new validateEnvironmentSettings(); new requiresEnvironmentSubdomain()
• EnvironmentSubdomain — createUrlWithSubdomain throws on an invalid subdomain instead of returning the URL unchanged
• CheckoutPreviousSdkBuilder — Previous/ABC exempted via requiresEnvironmentSubdomain()
• CheckoutSdkBuilderTest — covers all four combinations (subdomain only, legacy only, both, neither), an invalid subdomain, and the Previous exemption
• DefaultCheckoutConfigurationTest — the parameterised bad-subdomain case now asserts the throw instead of the silent fallback
• TestDomainConfiguration (new) + SandboxTestFixture and seven integration fixtures — every client the suite builds now chooses a domain

Fixed along the way

environmentSubdomain() used to build the URLs from whatever environment was set at call time, so calling it before environment() silently produced the wrong host.

API Reference

• https://api-reference.checkout.com/#section/Base-URLs
• https://www.checkout.com/docs/developer-resources/api/api-endpoints

Breaking changes

Yes, two. This needs a major release, classified and versioned when the release is cut.

1. The merchant-specific subdomain is mandatory for the Default and DefaultOAuth platforms. Code that omitted it and relied on the implicit fallback to api.checkout.com / access.checkout.com now fails at client construction. Migration: set the subdomain, or use the legacy-domain opt-out as a temporary measure. The Previous (ABC) platform is unaffected.
2. An invalid subdomain now fails instead of being silently ignored. Callers passing a malformed value keep working against the shared host today; after this change they fail fast. This one is easy to miss because it is not what the ticket asked for, so it needs its own line in the release notes.

README

Updated in this PR: a "Subdomain value" section above the Default example, the subdomain added to the configuration samples, and a "Legacy domain (emergency use only)" section at the bottom.

Notes

The suite routes every client it builds through a single helper that uses the shared hosts. Applying the merchant-specific subdomain there looked better, since it is the path merchants are being moved to, but the sandbox OAuth clients are not provisioned for it: .NET CI failed 224 integration tests with invalid_client when the token request went to {subdomain}.access.sandbox.checkout.com. Binding those OAuth clients to the subdomain is a platform task and should land before merchants are told the subdomain is mandatory.

Reference implementation: checkout-sdk-net#590. Tracked as INT-1688.

No version bump here: that happens on master when the release is cut, per the release workflow.

---

Review follow-ups (2026-08-31)

Breaking changes, complete list:

1. The merchant-specific subdomain is now required; building without it (and without the legacy opt-out) throws.
2. An invalid subdomain now throws instead of being silently ignored.

Behaviour note: host resolution is now deferred to build time, which also fixes a latent order-dependence bug where setting the subdomain before the environment produced the wrong host.

Deprecation signal: compile-time (@deprecated + Javadoc).

Option A applied (2026-08-31): an explicit OAuth authorization URI and the environment subdomain are now mutually exclusive at build time; the README OAuth example no longer sets an authorization URI, subdomain-only is the documented path.

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 19

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔵 Advisory review: Sound, but needs your judgement

This PR needs a human approval. The code itself reads as correct; whether it should land depends on context I don't have.

The change correctly enforces that callers supply either environmentSubdomain or useLegacyDomain at build time, with a clean opt-out path and Previous-platform exemption. The logic is sound, but the widespread use of useLegacyDomain() in integration tests—combined with the explicit PR note that sandbox OAuth clients are not yet provisioned for MSSD—means this PR ships a breaking API change before the platform work that would let real callers actually comply with it.

For you to decide

• AbstractCheckoutSdkBuilder.environmentSubdomain(null) silently stores null and then fails at build time with 'environmentSubdomain is required' rather than the more intuitive 'subdomain must be specified'; this is a deliberate design choice (null == unset) but a reviewer should confirm this is the intended UX.
• The integration test suite (SandboxTestFixture, OAuthTestIT, AccountsTestIT, BaseIssuingTestIT, AccountsPayoutSchedulesIT, RequestApmPaymentsIT) adds .useLegacyDomain() to every OAuth client because sandbox OAuth clients are not yet provisioned for MSSD; the PR notes this but it means the 'required' enforcement in production code ships before the corresponding platform provisioning, which is a deployment-sequencing risk the reviewer must accept.
• CheckoutSdkTelemetryIntegrationTest and CardMetadataIT use the hard-coded subdomain '1234doma' and System.getenv('CHECKOUT_MERCHANT_SUBDOMAIN') respectively; if CHECKOUT_MERCHANT_SUBDOMAIN is unset in CI the card-metadata test will throw NullPointerException at build time, not a clear error message.
• The mutually exclusive authorizationUri + environmentSubdomain check in CheckoutSdkBuilder.getSdkCredentials() is evaluated after the subdomain is retrieved via getEnvironmentSubdomain(), which constructs an EnvironmentSubdomain (and validates the pattern) before the conflict check fires; a reviewer should confirm the desired exception order is 'conflict first' vs 'invalid subdomain first'.
• SUBDOMAIN_PATTERN (^(?:pl-)?[a-z0-9]+$) has no upper-length bound; a reviewer should confirm whether arbitrarily long subdomains should be accepted or whether an 8-char (or pl- + 8-char) constraint belongs here.
• The README 'Legacy domain' section says 'Exactly one of environmentSubdomain(...) or useLegacyDomain() must be set'; this is accurate, but the README Default and OAuth examples use the placeholder string 'subdomain' rather than the actual 8-character format described in the new 'Subdomain value' section—minor accuracy concern worth noting.
• The breaking-change note in the PR is explicit and correctly identifies two distinct breaks; a reviewer must decide whether the release-versioning process (major bump deferred to cut time) is appropriate for their workflow before approving.

⚠️ The diff was too large to read in full, so this review covers only part of the change.

---

_{This is not an approval. wall-e cannot auto-approve this PR — it is an opinion to help whoever does. Advisory review · us.anthropic.claude-sonnet-4-6 · wall-e 2026.06.19-02}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 19

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 19

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:.github/workflows/build-master.yml
• security_sensitive_path:.github/workflows/build-pull-request.yml
• security_sensitive_path:.github/workflows/build-release.yml
• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 22

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — .github/workflows/build-master.yml	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — .github/workflows/build-pull-request.yml	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — .github/workflows/build-release.yml	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:.github/workflows/build-master.yml
• security_sensitive_path:.github/workflows/build-pull-request.yml
• security_sensitive_path:.github/workflows/build-release.yml
• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 21

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — .github/workflows/build-master.yml	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — .github/workflows/build-pull-request.yml	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — .github/workflows/build-release.yml	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 17

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 18

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 17

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 18

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 17

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 17

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 18

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

Fixed

[agent-wall-e]

🔴 Risk Classification: MAJOR

Approval route: AI Review + Human Approval Required
Rollback controls: Change-freeze window + documented rollback plan

Classification reasons

• security_sensitive_path:src/test/java/com/checkout/OAuthTestIT.java

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 18

---

_{wall-e 2026.06.19-02 · policy 376219bc71e6…}

[agent-wall-e]

🔬 Debug — why this classification?

Each reason code emitted by the classifier, its source clause in the AI in SDLC Control Framework, and what it means.

Reason code	Kind	Clause	Meaning
security_sensitive_path — src/test/java/com/checkout/OAuthTestIT.java	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).

Kinds:

• classifying — this rule contributed to the chosen tier.
• informational — context only; did not by itself decide the tier.

See issue #3 for the proposal to formalise this map as Appendix A of the standards doc.

_{wall-e 2026.06.19-02 · debug}

[sonarqubecloud]

Quality Gate passed

Issues
46 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud