feature/INT-1701 - Representative documents alignment

src/main/java/com/checkout/accounts/AccountPhone.java

@@ -6,14 +6,26 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * A phone number on the Accounts API: the sub-entity's contact phone, or a representative's phone.
+ * See {@link ContactDetails} for the per-variant number format.
+ */
 @Data
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
 public final class AccountPhone {
 
+    /**
+     * The ISO 3166-1 alpha-2 country where the number is registered, not the dialling code.
+     * [Required] on Accounts API v3.0; not part of the v2.0 schemas.
+     */
     private CountryCode countryCode;
 
+    /**
+     * The phone number, without the country calling code.
+     * [Required]
+     */
     private String number;
 
 }

src/main/java/com/checkout/accounts/AccountsClient.java

@@ -18,10 +18,35 @@
 
 public interface AccountsClient {
 
+    /**
+     * Uploads a file to the Files API (POST /files on the Files host), as a multipart request. The
+     * returned ID is what document {@code front} and {@code back} fields take.
+     *
+     * @param accountsFileRequest the path to the file, its content type, and its purpose
+     * @return the ID of the uploaded file
+     */
     CompletableFuture<IdResponse> submitFile(AccountsFileRequest accountsFileRequest);
 
+    /**
+     * Creates a file upload for a sub-entity (POST /entities/{entityId}/files on the Files host).
+     * The response carries the file ID and an upload link; the file content itself is sent to that
+     * link, not in this request.
+     *
+     * @param entityId          the ID of the sub-entity
+     * @param fileUploadRequest the purpose of the file upload
+     * @return the file ID, the maximum size allowed, the MIME types allowed for the purpose, and the
+     * upload link
+     */
     CompletableFuture<FileUploadResponse> uploadFile(String entityId, FileUploadRequest fileUploadRequest);
 
+    /**
+     * Retrieves the details of a sub-entity's file (GET /entities/{entityId}/files/{fileId} on the
+     * Files host).
+     *
+     * @param entityId the ID of the sub-entity
+     * @param fileId   the ID of the file
+     * @return the file's status, size, MIME type, upload date and purpose
+     */
     CompletableFuture<FileDetailsResponse> retrieveFile(String entityId, String fileId);
 
     CompletableFuture<OnboardEntityResponse> createEntity(OnboardEntityRequest entityRequest);
@@ -99,10 +124,35 @@ CompletableFuture<ReserveRuleCreateResponse> updateReserveRule(String entityId,
     CompletableFuture<EntityRequirementUpdateResponse> resolveEntityRequirement(String entityId, String requirementId, EntityRequirementUpdateRequest updateRequest);
 
     // Synchronous methods
+    /**
+     * Uploads a file to the Files API (POST /files on the Files host), as a multipart request. The
+     * returned ID is what document {@code front} and {@code back} fields take.
+     *
+     * @param accountsFileRequest the path to the file, its content type, and its purpose
+     * @return the ID of the uploaded file
+     */
     IdResponse submitFileSync(final AccountsFileRequest accountsFileRequest);
 
+    /**
+     * Creates a file upload for a sub-entity (POST /entities/{entityId}/files on the Files host).
+     * The response carries the file ID and an upload link; the file content itself is sent to that
+     * link, not in this request.
+     *
+     * @param entityId          the ID of the sub-entity
+     * @param fileUploadRequest the purpose of the file upload
+     * @return the file ID, the maximum size allowed, the MIME types allowed for the purpose, and the
+     * upload link
+     */
     FileUploadResponse uploadFileSync(final String entityId, final FileUploadRequest fileUploadRequest);
 
+    /**
+     * Retrieves the details of a sub-entity's file (GET /entities/{entityId}/files/{fileId} on the
+     * Files host).
+     *
+     * @param entityId the ID of the sub-entity
+     * @param fileId   the ID of the file
+     * @return the file's status, size, MIME type, upload date and purpose
+     */
     FileDetailsResponse retrieveFileSync(final String entityId, final String fileId);
 
     OnboardEntityResponse createEntitySync(final OnboardEntityRequest entityRequest);

src/main/java/com/checkout/accounts/AccountsFilePurpose.java

@@ -2,14 +2,31 @@
 
 import lombok.Getter;
 
+/**
+ * The purpose of a file uploaded with {@link AccountsClient#submitFile(AccountsFileRequest)}. The
+ * values match the purposes the Accounts API accepts for onboarding documents
+ * ({@code PlatformsFileUpload}), plus the legacy {@link #IDENTIFICATION}.
+ */
 public enum AccountsFilePurpose {
 
     BANK_VERIFICATION("bank_verification"),
+    /**
+     * Legacy purpose, not among the onboarding upload purposes; use {@link #IDENTITY_VERIFICATION}.
+     */
     IDENTIFICATION("identification"),
     IDENTITY_VERIFICATION("identity_verification"),
     COMPANY_VERIFICATION("company_verification"),
     FINANCIAL_VERIFICATION("financial_verification"),
-    TAX_VERIFICATION("tax_verification");
+    TAX_VERIFICATION("tax_verification"),
+    ADDITIONAL_DOCUMENT("additional_document"),
+    ARTICLES_OF_ASSOCIATION("articles_of_association"),
+    CERTIFIED_AUTHORISED_SIGNATORY("certified_authorised_signatory"),
+    COMPANY_OWNERSHIP("company_ownership"),
+    PROOF_OF_LEGALITY("proof_of_legality"),
+    PROOF_OF_PRINCIPAL_ADDRESS("proof_of_principal_address"),
+    SHAREHOLDER_STRUCTURE("shareholder_structure"),
+    PROOF_OF_RESIDENTIAL_ADDRESS("proof_of_residential_address"),
+    PROOF_OF_REGISTRATION("proof_of_registration");
 
     @Getter
     private final String purpose;

src/main/java/com/checkout/accounts/AccountsFileRequest.java

@@ -10,14 +10,31 @@
 
 import java.io.File;
 
+/**
+ * A file to upload with {@link AccountsClient#submitFile(AccountsFileRequest)} (POST /files on the
+ * Files host), sent as a multipart request. The returned ID is what document {@code front} and
+ * {@code back} fields take.
+ */
 @Getter
 @Setter
 @EqualsAndHashCode(callSuper = true)
 @ToString(callSuper = true)
 public final class AccountsFileRequest extends AbstractFileRequest {
 
+    /**
+     * The purpose of the file upload: the onboarding document the file is for.
+     * [Required]
+     */
     private AccountsFilePurpose purpose;
 
+    /**
+     * 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
+     *                    {@code ContentType.create("application/pdf")}
+     * @param purpose     the purpose of the file upload
+     */
     @Builder
     private AccountsFileRequest(final File file,
                                    final ContentType contentType,

src/main/java/com/checkout/accounts/AdditionalDocument.java

@@ -5,12 +5,22 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * Additional space for documents to be provided when requested. Carries a file ID only; the API
+ * defines no document type for it.
+ */
 @Data
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
 public final class AdditionalDocument {
 
+    /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * 31 characters
+     */
     private String front;
 
 }

src/main/java/com/checkout/accounts/ArticlesOfAssociation.java

@@ -8,10 +8,8 @@
 /**
  * Memorandum or articles of association document, supplied when onboarding a sub-entity.
  *
- * <p>Required on the company full onboarding variants. The API expects an object carrying the
- * document type and the uploaded file ID, which is why this class exists: the field on
- * {@link OnboardSubEntityDocuments} used to be the {@link ArticlesOfAssociationType} enum, so
- * the SDK serialized a bare string and the API rejected the request.</p>
+ * <p>Required on EEA and GB Company Full (3.0); optional on US Company Full (3.0) and the US ISV
+ * Seller variants. The object carries the document type and the ID of the uploaded file.</p>
  */
 @Data
 @Builder
@@ -20,13 +18,16 @@
 public final class ArticlesOfAssociation {
 
     /**
-     * The type of document being used as the memorandum or articles of association.
+     * The type of document used.
+     * [Required]
      */
     private ArticlesOfAssociationType type;
 
     /**
-     * The ID of the front side of the document as represented within Checkout.com systems,
-     * as returned when the file was uploaded.
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * 31 characters
      */
     private String front;
 

src/main/java/com/checkout/accounts/ArticlesOfAssociationType.java

@@ -2,6 +2,9 @@
 
 import com.google.gson.annotations.SerializedName;
 
+/**
+ * The document types accepted as memorandum or articles of association.
+ */
 public enum ArticlesOfAssociationType {
 
     @SerializedName("memorandum_of_association")

src/main/java/com/checkout/accounts/BankVerification.java

@@ -5,14 +5,27 @@
 import lombok.Data;
 import lombok.NoArgsConstructor;
 
+/**
+ * A document showing transactions from the last 3 months.
+ */
 @Data
 @Builder
 @NoArgsConstructor
 @AllArgsConstructor
 public final class BankVerification {
 
+    /**
+     * The type of document being used as bank verification.
+     * [Required]
+     */
     private BankVerificationType type;
 
+    /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * 31 characters
+     */
     private String front;
 
 }

src/main/java/com/checkout/accounts/BankVerificationType.java

@@ -2,6 +2,9 @@
 
 import com.google.gson.annotations.SerializedName;
 
+/**
+ * The document type accepted as bank verification.
+ */
 public enum BankVerificationType {
 
     @SerializedName("bank_statement")

src/main/java/com/checkout/accounts/CertifiedAuthorisedSignatory.java

@@ -0,0 +1,34 @@
+package com.checkout.accounts;
+
+import lombok.AllArgsConstructor;
+import lombok.Builder;
+import lombok.Data;
+import lombok.NoArgsConstructor;
+
+/**
+ * Certified authorised signatory document. Required when the legal representative or other role
+ * owner is not registered on the certificate of incorporation. Representative documents only
+ * ({@code company.representatives[].documents}), EEA, GB and US Company Full (3.0) and US ISV
+ * Seller Company (3.0); not accepted at the top level.
+ */
+@Data
+@Builder
+@NoArgsConstructor
+@AllArgsConstructor
+public final class CertifiedAuthorisedSignatory {
+
+    /**
+     * The type of document.
+     * [Required]
+     */
+    private CertifiedAuthorisedSignatoryType type;
+
+    /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * 31 characters
+     */
+    private String front;
+
+}

src/main/java/com/checkout/accounts/CertifiedAuthorisedSignatoryType.java

@@ -0,0 +1,13 @@
+package com.checkout.accounts;
+
+import com.google.gson.annotations.SerializedName;
+
+/**
+ * The document type accepted as a representative's certified authorised signatory document.
+ */
+public enum CertifiedAuthorisedSignatoryType {
+
+    @SerializedName("power_of_attorney")
+    POWER_OF_ATTORNEY
+
+}