feat: require environment_subdomain or an explicit use_legacy_domain opt-out

[armando-rodriguez-cko]

Summary

Makes the merchant-specific subdomain (MSSD) mandatory. Callers must now call environment_subdomain(...), or explicitly opt out with the new use_legacy_domain(), which raises a DeprecationWarning from its first release. Setting both, or neither, raises CheckoutArgumentException at build time. 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

• checkout_sdk/checkout_sdk_builder.py — the subdomain is held as a string and the EnvironmentSubdomain is built when the configuration is assembled, so environment_subdomain() no longer has to be called after environment(); new use_legacy_domain(); new _validate_environment_settings() and _requires_environment_subdomain()
• checkout_sdk/environment_subdomain.py — create_url_with_subdomain raises on an invalid subdomain instead of returning the URL unchanged
• checkout_sdk/default_sdk.py, oauth_sdk.py, previous/previous_sdk.py — validate before building; Previous/ABC exempted; the duplicated with/without-subdomain branches in all three build() methods are gone
• tests/checkout_default_sdk_test.py — covers all four combinations plus an invalid subdomain
• tests/checkout_configuration_test.py — the parameterised bad-subdomain case now asserts the raise instead of the silent fallback
• tests/conftest.py + five other fixtures — every client the suite builds now chooses a domain, through configure_domain

Fixed along the way

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

The long import line in tests/payments/request_apm_payments_integration_test.py is wrapped only because pre-commit lints staged files, so touching that file surfaced a pre-existing line-too-long.

Verification

544 tests passing, 0 failing, 217 skipped. flake8 and pylint pre-commit hooks pass.

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: runtime DeprecationWarning.

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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 15

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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: Concerns worth a look

This PR needs a human approval. Before you give it, these are the things I'd want resolved.

The PR enforces mandatory merchant-specific subdomains (or an explicit legacy-domain opt-out) for Default/OAuth SDK builders, with a correct deprecation path and tests. One concrete bug exists: EnvironmentSubdomain.__init__ calls self.base_uri as an attribute but it was previously a method, and the diff removes the base_uri method entirely without replacing it, leaving the constructor broken.

Concerns

• In environment_subdomain.py, the diff removes the base_uri method (def base_uri(self) -> str: return self.base_uri) but EnvironmentSubdomain.__init__ presumably still calls create_url_with_subdomain to populate instance attributes — the old code had return self.base_uri which was a recursive bug, but the new diff removes the method entirely without showing __init__ being updated to store the results; callers such as oauth_sdk.py that reference environment_subdomain.authorization_uri and environment_subdomain.base_uri will raise AttributeError at runtime if __init__ no longer sets those attributes.
• The conftest.py default_api fixture passes os.environ.get('CHECKOUT_MERCHANT_SUBDOMAIN') directly to environment_subdomain(), which will pass None if the env var is unset, causing _validate_environment_settings() to raise CheckoutArgumentException at CI setup time — there is no fallback or skip guard, so every test that uses default_api would fail in environments without that variable set.
• The new test test_should_fail_init_authorization_invalid_credentials_and_host in oauth_integration_test.py now asserts a CheckoutArgumentException about both fields being set, but the old test was verifying a real network-level CheckoutException about connection failure — the behaviour change (raise at build time vs. at request time) is intentional but the test no longer exercises the network path it claimed to test, which silently reduces integration coverage.
• The _validate_environment_settings check for _subdomain is not None and _use_legacy_domain uses _subdomain is not None, but environment_subdomain() stores whatever the caller passes including empty string; passing environment_subdomain('') followed by use_legacy_domain() would set _subdomain = '' (not None) and trigger the conflict error, while environment_subdomain('') alone would bypass the 'neither set' check and then fail later in create_url_with_subdomain — this is technically correct but inconsistent with the documented contract that neither can be omitted.

---

_{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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 15

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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-main.yml
• security_sensitive_path:.github/workflows/build-pull-request.yml
• security_sensitive_path:.github/workflows/build-release.yml
• security_sensitive_path:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

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 — .github/workflows/build-main.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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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-main.yml
• security_sensitive_path:.github/workflows/build-pull-request.yml
• security_sensitive_path:.github/workflows/build-release.yml
• security_sensitive_path:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

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 — .github/workflows/build-main.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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 14

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 15

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 14

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 14

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 14

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 14

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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:checkout_sdk/oauth_sdk.py
• security_sensitive_path:tests/oauth_integration_test.py

Operational gates

• ✅ jira_ticket (INT-1688)
• ✅ independent_review

Files analysed: 14

---

_{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 — checkout_sdk/oauth_sdk.py	classifying	§2.1 M4/M5	Path matched a sensitive pattern (auth, secrets, crypto, PCI, migrations, network IaC).
security_sensitive_path — tests/oauth_integration_test.py	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
0 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