feature/INT-1701 - Representative documents alignment by david-ruiz-cko · Pull Request #680 · checkout/checkout-sdk-java

david-ruiz-cko · 2026-10-01T10:51:22Z

This pull request significantly improves the documentation and clarity of the Accounts API SDK by adding detailed JavaDoc comments to many classes, enums, and fields. It also introduces new document types and classes to support additional onboarding and verification requirements. The changes enhance maintainability and make the codebase much easier to understand for developers integrating with the API.

The most important changes are:

Documentation and Clarity Improvements:

Added comprehensive JavaDoc comments to most classes, enums, and fields in the com.checkout.accounts package, explaining their purpose, usage, and field requirements. This includes details on required fields, expected formats, and API variant differences. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10]

API Surface and Document Type Expansions:

Added new document types and enums to support additional onboarding requirements, such as CertifiedAuthorisedSignatory, CertifiedAuthorisedSignatoryType, and new values in AccountsFilePurpose (e.g., ADDITIONAL_DOCUMENT, ARTICLES_OF_ASSOCIATION, etc.). [1] [2] [3]
Enhanced enums with JavaDoc comments to clarify their purpose and usage, including distinctions between similar document types (e.g., FinancialStatementsType vs. FinancialVerificationType). [1] [2] [3] [4] [5]

API Method Documentation:

Added detailed JavaDoc comments to the AccountsClient interface methods (both async and sync), describing the purpose, parameters, and return values for file upload and retrieval operations. [1] [2]

Field and Requirement Clarifications:

Clarified field requirements, formats, and validation rules (e.g., regex for file IDs, phone numbers, and national ID numbers) in class-level and field-level documentation. [1] [2] [3] [4] [5]

Deprecation Notices:

Added deprecation notice to the document field in Identification, indicating it is not read by the API and will be removed in a future major version.

agent-wall-e · 2026-10-01T10:51:26Z

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

exceeds_bounded_scope:895>250

Operational gates

✅ jira_ticket (INT-1701)
✅ independent_review

Files analysed: 46

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-10-01T10:51:27Z

🔬 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
`exceeds_bounded_scope` — `895>250`	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

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 · 2026-10-01T10:51:41Z

🔵 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.

This PR adds JavaDoc across the accounts package, new document types (CertifiedAuthorisedSignatory, ProofOfResidentialAddress, ProofOfRegistration, EntityProcessingDetails), new enum values in AccountsFilePurpose, fixes two type mismatches (TaxVerification.type was CompanyVerificationType, CompanyVerification.type was TaxVerificationType), adds new fields (EntityEmailAddresses.pciComplianceContact, Representative.company, OnboardEntityDetailsResponse.processingDetails/documents), and deprecates several unused fields. The changes are structurally sound but carry API contract implications a human must verify.

For you to decide

TaxVerification.type changed from CompanyVerificationType to TaxVerificationType, and CompanyVerification.type changed from TaxVerificationType to CompanyVerificationType — these look like bug fixes for swapped types, but any callers constructing these objects with the old types will break at compile time and need to be updated.
Representative gains a new company field for the controlling-company representative shape (EEA/GB Company Full v3.0); this is a new API capability and reviewers should confirm the @SerializedName is not needed (the field serialises as 'company' by default, which matches the documented JSON key).
EntityEmailAddresses gains pciComplianceContact — if any existing deserialization tests snapshot the full JSON, they will need updating; no test changes are visible in the truncated diff.
OnboardEntityDetailsResponse gains processingDetails and documents fields — these are response-only additions and are safe for deserialization, but reviewers should confirm the field names match the API's JSON keys exactly (processingDetails would serialize as 'processingDetails' not 'processing_details' unless a @SerializedName is present, which is not shown).
OnboardSubEntityDocuments gains certifiedAuthorisedSignatory, proofOfResidentialAddress, and proofOfRegistration fields — these are new representative-level document slots; again no @SerializedName annotations are shown, and the API likely expects snake_case keys (e.g., 'certified_authorised_signatory'), so missing annotations would cause silent serialization failures.
Several fields are deprecated (Identification.document, Individual.nationalTaxId, Company.document, EntityFinancialDetails.documents, EntityFinancialDocuments) — downstream callers using these will get deprecation warnings; this is intentional but a breaking-change policy decision for SDK consumers.
The sonarqube plugin version bump from 7.3.1.8318 to 7.5.0.8588 is a minor build-tooling change and looks safe, but should be confirmed against your CI Sonar server compatibility.
The diff is truncated (7 files omitted), so the full scope of changes cannot be fully assessed — the reviewer should check those files, particularly for missing @SerializedName annotations on snake_case JSON fields.

⚠️ 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}

+        final IdResponse identityFile = submitAccountsFile(checkoutApi, AccountsFilePurpose.IDENTITY_VERIFICATION);
+        final IdResponse signatoryFile = submitAccountsFile(checkoutApi, AccountsFilePurpose.CERTIFIED_AUTHORISED_SIGNATORY);
+
+        final OnboardEntityRequest request = buildCompanyEntityV3(RandomStringUtils.random(15, true, true));


agent-wall-e · 2026-10-01T11:34:01Z

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

exceeds_bounded_scope:1068>250

Operational gates

✅ jira_ticket (INT-1701)
✅ independent_review

Files analysed: 50

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-10-01T11:34:02Z

🔬 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
`exceeds_bounded_scope` — `1068>250`	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

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}

+    /**
+     * Creates a file upload request.
+     *
+     * @param file        the file to upload (JPEG, PNG or PDF)


+     * Creates a file upload request.
+     *
+     * @param file        the file to upload (JPEG, PNG or PDF)
+     * @param contentType the file's content type; for PDF use


+     * @param file        the file to upload (JPEG, PNG or PDF)
+     * @param contentType the file's content type; for PDF use
+     *                    {@code ContentType.create("application/pdf")}
+     * @param purpose     the purpose of the file upload


agent-wall-e · 2026-10-01T12:19:33Z

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

exceeds_bounded_scope:1125>250

Operational gates

✅ jira_ticket (INT-1701)
✅ independent_review

Files analysed: 53

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-10-01T12:19:34Z

🔬 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
`exceeds_bounded_scope` — `1125>250`	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

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}

…ut-sdk-java into feature/INT-1701

agent-wall-e · 2026-10-02T13:19:25Z

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

exceeds_bounded_scope:1127>250

Operational gates

✅ jira_ticket (INT-1701)
✅ independent_review

Files analysed: 54

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-10-02T13:19:25Z

🔬 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
`exceeds_bounded_scope` — `1127>250`	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

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 · 2026-10-05T11:56:36Z

🟡 Risk Classification: MINOR

Approval route: AI Review + Human Approval
Rollback controls: Staged rollout + rollback

Classification reasons

exceeds_bounded_scope:1142>250

Operational gates

✅ jira_ticket (INT-1701)
✅ independent_review

Files analysed: 55

_{wall-e 2026.06.19-02 · policy 6b4ce2b3b45a…}

agent-wall-e · 2026-10-05T11:56:37Z

🔬 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
`exceeds_bounded_scope` — `1142>250`	classifying	§2.1 M8	More than 250 non-test, non-doc, non-lockfile lines changed.

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 · 2026-10-05T11:57:14Z

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

+        final Representative representative = Representative.builder()
+                .id("rep_r2y49v5j1skna5zx0swaprf2he")
+                .firstName("John")
+                .middleName("Paul")
+                .lastName("Doe")
+                .dateOfBirth(DateOfBirth.builder().day(5).month(6).year(1995).build())
+                .phone(AccountPhone.builder().number("2072345678").build())
+                .address(Address.builder()
+                        .addressLine1("90 Tottenham Court Road")
+                        .city("London")
+                        .zip("W1T 4TJ")
+                        .country(CountryCode.GB)
+                        .build())
+                .placeOfBirth(PlaceOfBirth.builder().country(CountryCode.FR).build())
+                .identification(Identification.builder().nationalIdNumber("AB123456C").build())


+        final Representative representative = Representative.builder()
+                .id("rep_r2y49v5j1skna5zx0swaprf2he")
+                .firstName("John")
+                .middleName("Paul")
+                .lastName("Doe")
+                .dateOfBirth(DateOfBirth.builder().day(5).month(6).year(1995).build())
+                .phone(AccountPhone.builder().number("2072345678").build())
+                .address(Address.builder()
+                        .addressLine1("90 Tottenham Court Road")
+                        .city("London")
+                        .zip("W1T 4TJ")
+                        .country(CountryCode.GB)
+                        .build())
+                .placeOfBirth(PlaceOfBirth.builder().country(CountryCode.FR).build())


+        final Representative representative = Representative.builder()
+                .id("rep_r2y49v5j1skna5zx0swaprf2he")
+                .firstName("John")
+                .middleName("Paul")
+                .lastName("Doe")
+                .dateOfBirth(DateOfBirth.builder().day(5).month(6).year(1995).build())
+                .phone(AccountPhone.builder().number("2072345678").build())
+                .address(Address.builder()
+                        .addressLine1("90 Tottenham Court Road")
+                        .city("London")
+                        .zip("W1T 4TJ")
+                        .country(CountryCode.GB)
+                        .build())


+        final Representative representative = Representative.builder()
+                .id("rep_r2y49v5j1skna5zx0swaprf2he")
+                .firstName("John")
+                .middleName("Paul")
+                .lastName("Doe")
+                .dateOfBirth(DateOfBirth.builder().day(5).month(6).year(1995).build())
+                .phone(AccountPhone.builder().number("2072345678").build())


+        final Representative representative = Representative.builder()
+                .id("rep_r2y49v5j1skna5zx0swaprf2he")
+                .firstName("John")
+                .middleName("Paul")
+                .lastName("Doe")
+                .dateOfBirth(DateOfBirth.builder().day(5).month(6).year(1995).build())


+        final Representative representative = Representative.builder()
+                .id("rep_r2y49v5j1skna5zx0swaprf2he")
+                .firstName("John")
+                .middleName("Paul")
+                .lastName("Doe")


+        final Representative representative = Representative.builder()
+                .id("rep_r2y49v5j1skna5zx0swaprf2he")
+                .firstName("John")
+                .middleName("Paul")


+        final Representative representative = Representative.builder()
+                .id("rep_r2y49v5j1skna5zx0swaprf2he")
+                .firstName("John")


Representative documents alignment

8c4bbe8

david-ruiz-cko requested a review from a team October 1, 2026 10:51

github-advanced-security Bot found potential problems Oct 1, 2026

View reviewed changes

Docs and fixes

cf7d5b8

github-advanced-security Bot found potential problems Oct 1, 2026

View reviewed changes

Docs extended + obsolete schemas identified

2635a29

david-ruiz-cko added 5 commits October 2, 2026 15:17

Bouncy Castle dependabot alert fix (#682)

7335acf

Representative documents alignment

6aa2d61

Docs and fixes

fbf0f62

Docs extended + obsolete schemas identified

c93fb9a

Merge branch 'feature/INT-1701' of https://github.com/checkout/checko…

23c88d9

…ut-sdk-java into feature/INT-1701

V3 schema adjustments + test fine tune

a50cae8

github-advanced-security Bot found potential problems Oct 5, 2026

View reviewed changes

Navigation Menu

feature/INT-1701 - Representative documents alignment - #680

feature/INT-1701 - Representative documents alignment#680
david-ruiz-cko wants to merge 9 commits into
masterfrom
feature/INT-1701

david-ruiz-cko commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026 •

edited

Loading

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 2, 2026

Uh oh!

agent-wall-e Bot commented Oct 2, 2026

Uh oh!

agent-wall-e Bot commented Oct 5, 2026

Uh oh!

agent-wall-e Bot commented Oct 5, 2026

Uh oh!

sonarqubecloud Bot commented Oct 5, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Conversation

david-ruiz-cko commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

🟡 Risk Classification: MINOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🔵 Advisory review: Sound, but needs your judgement

For you to decide

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

🟡 Risk Classification: MINOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

🟡 Risk Classification: MINOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 1, 2026

Uh oh!

agent-wall-e Bot commented Oct 2, 2026

🟡 Risk Classification: MINOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 2, 2026

Uh oh!

agent-wall-e Bot commented Oct 5, 2026

🟡 Risk Classification: MINOR

Classification reasons

Operational gates

Uh oh!

agent-wall-e Bot commented Oct 5, 2026

Uh oh!

sonarqubecloud Bot commented Oct 5, 2026

Quality Gate passed

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

agent-wall-e Bot commented Oct 1, 2026 •

edited

Loading