feature/INT-1701 - Representative documents alignment

[david-ruiz-cko]

This pull request makes significant improvements to the checkout_sdk Accounts module, focusing on enhancing documentation, clarifying API usage, and adding support for new document types. The changes improve code maintainability and make the SDK easier to use and understand, especially regarding file uploads and document handling for onboarding and verification.

Documentation and API Clarity Improvements:

• Added detailed YARD documentation to many models (e.g., Company, ContactDetails, Document, BankVerification), specifying required fields, formats, and variant-specific requirements. This makes the SDK much easier to use and reduces ambiguity for integrators. [1] [2] [3] [4] [5] [6] [7] [8]
• Deprecated several fields and classes that are not part of the Accounts API schemas, and clearly marked them as such in the documentation (e.g., AdditionalInfo, EntityDocument, Company#document, EntityFinancialDetails#documents). [1] [2] [3] [4]

File Upload and Document Handling Enhancements:

• Improved file upload methods in AccountsClient, clarifying parameters, return values, and the multipart nature of requests for both general and entity-scoped file uploads. [1] [2] [3]
• Added new document types and models for certified authorised signatory, proof of residential address, and proof of registration, with corresponding enums and documentation. [1] [2] [3]

Model and Enum Additions:

• Introduced new models and enums for document types, including CertifiedAuthorisedSignatory, CertifiedAuthorisedSignatoryType, ProofOfResidentialAddress, ProofOfResidentialAddressType, ProofOfRegistration, ProofOfRegistrationType, RepresentativeDocuments, and FilePurpose. [1] [2] [3]

General Improvements:

• Improved consistency and accuracy of model attribute documentation, including regular expressions for file IDs and clearer type annotations. [1] [2] [3]

These changes collectively make the Accounts SDK more robust, self-explanatory, and easier to integrate with the Checkout.com onboarding API.

[agent-wall-e]

🟡 Risk Classification: MINOR

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

Classification reasons

• exceeds_bounded_scope:886>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 51

---

_{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 — 886>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: Looks good to me

This PR still needs a human approval — wall-e cannot auto-approve it. For what it's worth, I read the diff and found nothing I'd block on.

This PR adds documentation (YARD comments), deprecation notices, new document-type models/enums (CertifiedAuthorisedSignatory, ProofOfResidentialAddress, ProofOfRegistration, RepresentativeDocuments, FilePurpose), and fixes two attr_reader → attr_accessor bugs in FinancialVerification and ProofOfPrincipalAddress. The changes match the stated intent and no functional regressions are visible.

What I checked

• FinancialVerification and ProofOfPrincipalAddress previously used attr_reader, making those fields write-only from outside; the change to attr_accessor is a genuine bug fix.
• RepresentativeDocuments is a new class replacing OnboardSubEntityDocuments on Representative#documents, and the Representative class now has a :company accessor added — both are correct additions per the documentation.
• FilePurpose enum values align with the document-type classes added (certified_authorised_signatory, proof_of_residential_address, proof_of_registration are all present).
• The require order in accounts.rb correctly loads *_type before the corresponding class file for all six new files.
• Representative now includes :middle_name in attr_accessor, which was previously missing from v2.0 flat fields — this is a correct addition consistent with the v2.0 schema described.
• No tests appear in the diff; if there is a test suite for these models/client methods, coverage for the new classes and the attr_accessor fixes should be verified by the reviewer.

⚠️ 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:1054>250

Operational gates

• ✅ jira_ticket (INT-1701)
• ✅ independent_review

Files analysed: 65

---

_{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 — 1054>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