feature/INT-1701 - Representative documents alignment

[david-ruiz-cko]

This pull req 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]

🟡 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]

🔬 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]

🟠 Advisory review: Concerns worth a look

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

This PR adds JavaDoc, deprecations, new document types, and a handful of new fields/classes to the Accounts API SDK. The documentation is thorough and mostly consistent, but two functional changes introduce likely bugs: a type swap in CompanyVerification (TaxVerificationType → CompanyVerificationType) and a type swap in TaxVerification (CompanyVerificationType → TaxVerificationType) suggest the original code had the wrong enum types, and there is a new field added to EntityEmailAddresses (pciComplianceContact) with no corresponding test coverage visible in the diff.

Concerns

• CompanyVerification.type was previously typed as TaxVerificationType and is now CompanyVerificationType — this is a breaking change for any caller that set the field using TaxVerificationType; the reviewer should confirm this was definitely wrong before and check if any existing serialization/deserialization tests cover this field.
• TaxVerification.type was previously typed as CompanyVerificationType and is now TaxVerificationType — same concern as above: existing callers using CompanyVerificationType here will break at compile time, and the reviewer needs to verify this is an intentional bug-fix rather than an accidental swap.
• EntityEmailAddresses gains a new field pciComplianceContact with no test visible in the diff; if this field is serialized in requests it could silently appear in API calls for variants that don't accept it, and if deserialized from responses it needs coverage.
• OnboardEntityDetailsResponse gains two new response fields (processingDetails as EntityProcessingDetails, and documents as OnboardSubEntityDocuments); no deserialization tests are visible in the diff to confirm these map correctly from the API's JSON.
• EntityProcessingDetails is a new response-only class added without any test coverage visible in the diff; the Long-vs-Integer rationale in the JavaDoc is sound, but there is no test to verify it reads large integer values correctly.
• Representative gains a new company field (controlling company); no test is visible confirming the three-field constraint documented in the JavaDoc is enforced or that other Company fields are safely ignored when serialized.
• The ProofOfResidentialAddress and ProofOfRegistration classes are documented as representative-only, but they are also added as fields on OnboardSubEntityDocuments (which is also used at the top level); the JavaDoc warns about this but the class structure does not prevent misuse, which is a footgun.
• The diff is truncated (6 files omitted) so the review cannot be considered complete — there may be additional functional changes not assessed here.

⚠️ 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: 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]

🔬 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}

[agent-wall-e]

🟡 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]

🔬 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}

[agent-wall-e]

🟡 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]

🔬 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]

🟡 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]

🔬 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}

The merge-base changed after approval.

The merge-base changed after approval.

The merge-base changed after approval.

The merge-base changed after approval.

[agent-wall-e]

🟡 Risk Classification: MINOR

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

Classification reasons

• exceeds_bounded_scope:1140>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 54

---

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

[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
exceeds_bounded_scope — 1140>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]

🟡 Risk Classification: MINOR

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

Classification reasons

• exceeds_bounded_scope:1140>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 54

---

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

[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
exceeds_bounded_scope — 1140>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]

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

[armando-rodriguez-cko]

👍🏼