feature/INT-1701 - Representative documents alignment

lib/Checkout/Accounts/AccountsClient.php

@@ -163,10 +163,13 @@ public function updateBankPaymentInstrumentDetails(
         $instrumentId,
         UpdatePaymentInstrumentRequest $instrumentRequest
     ) {
+        // The API reads the ETag only from the If-Match HTTP header and answers 428 without it, so the
+        // request's headers are sent as HTTP headers.
         return $this->apiClient->patch(
             $this->buildPath(self::ACCOUNTS_PATH, self::ENTITIES_PATH, $entityId, self::PAYMENT_INSTRUMENTS_PATH, $instrumentId),
             $instrumentRequest,
-            $this->sdkAuthorization()
+            $this->sdkAuthorization(),
+            $instrumentRequest->headers
         );
     }
 

lib/Checkout/Accounts/AdditionalDocument.php

@@ -0,0 +1,20 @@
+<?php
+
+namespace Checkout\Accounts;
+
+/**
+ * Additional space for documents to be provided when requested. Carries a file ID only; the API
+ * defines no document type for it.
+ */
+class AdditionalDocument
+{
+    /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * Length: 31 characters
+     *
+     * @var string
+     */
+    public $front;
+}

lib/Checkout/Accounts/ArticlesOfAssociation.php

@@ -3,17 +3,26 @@
 namespace Checkout\Accounts;
 
 /**
- * Memorandum or articles of association document.
+ * Memorandum or Articles of Association document.
  */
 class ArticlesOfAssociation
 {
     /**
+     * The type of document used.
+     * [Required]
+     * Enum: "memorandum_of_association", "articles_of_association"
+     *
      * @var string value of ArticlesOfAssociationType
      */
     public $type;
 
     /**
-     * @var string the ID of the front side of the document, 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}$
+     * Length: 31 characters
+     *
+     * @var string
      */
     public $front;
 }

lib/Checkout/Accounts/BankVerification.php

@@ -8,12 +8,21 @@
 class BankVerification
 {
     /**
+     * The type of document being used as bank verification.
+     * [Required]
+     * Enum: "bank_statement"
+     *
      * @var string value of BankVerificationType
      */
     public $type;
 
     /**
-     * @var string the ID of the front side of the document, 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}$
+     * Length: 31 characters
+     *
+     * @var string
      */
     public $front;
 }

lib/Checkout/Accounts/CertifiedAuthorisedSignatory.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace Checkout\Accounts;
+
+/**
+ * Certified authorised signatory document. Required when the legal representative or other role
+ * owner is not registered on the certificate of incorporation.
+ *
+ * Belongs on company.representatives[].documents (see RepresentativeDocuments), never on the
+ * top-level request documents. Used by the EEA, GB and US company variants.
+ */
+class CertifiedAuthorisedSignatory
+{
+    /**
+     * The type of document.
+     * [Required]
+     * Enum: "power_of_attorney"
+     *
+     * @var string value of CertifiedAuthorisedSignatoryType
+     */
+    public $type;
+
+    /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * Length: 31 characters
+     *
+     * @var string
+     */
+    public $front;
+}

lib/Checkout/Accounts/CertifiedAuthorisedSignatoryType.php

@@ -0,0 +1,12 @@
+<?php
+
+namespace Checkout\Accounts;
+
+/**
+ * The document type accepted as a representative's certified authorised signatory document when
+ * onboarding a sub-entity (EEA, GB and US company variants, Accounts API v3.0).
+ */
+class CertifiedAuthorisedSignatoryType
+{
+    public static $power_of_attorney = "power_of_attorney";
+}

lib/Checkout/Accounts/CompanyVerification.php

@@ -2,13 +2,28 @@
 
 namespace Checkout\Accounts;
 
+/**
+ * The document to use to confirm the company's identity (certified by a power of attorney within
+ * the last 3 months).
+ */
 class CompanyVerification
 {
     /**
+     * The type of document used for company verification.
+     * [Required]
+     * Enum: "incorporation_document", "articles_of_association"
+     * (articles_of_association is accepted on the US Company (2.0) variants only)
+     *
      * @var string value of CompanyVerificationType
      */
     public $type;
+
     /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * Length: 31 characters
+     *
      * @var string
      */
     public $front;

lib/Checkout/Accounts/CompanyVerificationType.php

@@ -2,6 +2,13 @@
 
 namespace Checkout\Accounts;
 
+/**
+ * The document types accepted as company verification when onboarding a sub-entity.
+ *
+ * incorporation_document is accepted on every variant that takes company_verification;
+ * articles_of_association only on the US Company (2.0) variants. The articles of association
+ * sent as their own document use ArticlesOfAssociationType instead.
+ */
 class CompanyVerificationType
 {
     public static $incorporation_document = "incorporation_document";

lib/Checkout/Accounts/ContactDetails.php

@@ -4,15 +4,37 @@
 
 use Checkout\Common\Phone;
 
+/**
+ * Contact details of the sub-entity.
+ */
 class ContactDetails
 {
     /**
+     * The phone number of the sub-entity.
+     * [Required] for every Accounts API v2.0 variant and the US ISV Seller variants; [Optional]
+     * for the other v3.0 variants.
+     * On v3.0, country_code is required and is the ISO 3166-1 alpha-2 country where the number is
+     * registered (for example "FR"), not the dialling code. v2.0 takes number only.
+     *
      * @var Phone
      */
     public $phone;
 
     /**
+     * Email addresses for this sub-entity.
+     * [Required] for every Accounts API v2.0 variant and the US ISV Seller variants; [Optional]
+     * for the other v3.0 variants.
+     *
      * @var EntityEmailAddresses
      */
     public $email_addresses;
+
+    /**
+     * The details of the user responsible for onboarding the sub-entity.
+     * [Required] in the hosted onboarding invite request; [Optional] in the full and lite onboarding
+     * variants; not part of the US ISV Seller variants.
+     *
+     * @var Invitee
+     */
+    public $invitee;
 }

lib/Checkout/Accounts/Document.php

@@ -2,19 +2,38 @@
 
 namespace Checkout\Accounts;
 
+/**
+ * An identity document, as used for identity_verification on the representative (Accounts API
+ * v3.0) or on the top-level documents of the sole trader variants (Accounts API v2.0).
+ */
 class Document
 {
     /**
-     * @var string value of DocumentType
+     * The type of document used for identity verification.
+     * [Required]
+     * Enum: "passport", "national_identity_card", "driving_license", "citizen_card",
+     * "residence_permit", "electoral_id"
+     *
+     * @var string value of \Checkout\Common\DocumentType
      */
     public $type;
 
     /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * Length: 31 characters
+     *
      * @var string
      */
     public $front;
 
     /**
+     * The ID of the back side of the document as represented within Checkout.com systems.
+     * [Optional]
+     * ^file_[a-z2-7]{26}$
+     * Length: 31 characters
+     *
      * @var string
      */
     public $back;

lib/Checkout/Accounts/EntityEmailAddresses.php

@@ -2,10 +2,27 @@
 
 namespace Checkout\Accounts;
 
+/**
+ * Email addresses for this sub-entity, sent as contact_details.email_addresses.
+ */
 class EntityEmailAddresses
 {
     /**
+     * The main email address for this sub-entity.
+     * [Required]
+     * Format: email
+     *
      * @var string
      */
     public $primary;
+
+    /**
+     * The email address of the person responsible for PCI compliance at this sub-entity.
+     * [Required] for the US ISV Seller Company (3.0) and US ISV Seller Sole Trader (3.0) variants,
+     * together with primary; not part of the other variants.
+     * Format: email
+     *
+     * @var string
+     */
+    public $pci_compliance_contact;
 }

lib/Checkout/Accounts/FinancialStatements.php

@@ -2,14 +2,29 @@
 
 namespace Checkout\Accounts;
 
+/**
+ * Audited or management-prepared financial statements (when applicable). US ISV Seller variants.
+ *
+ * Not the same document as FinancialVerification, whose type is the singular
+ * financial_statement.
+ */
 class FinancialStatements
 {
     /**
+     * The type of document.
+     * [Required]
+     * Enum: "financial_statements"
+     *
      * @var string value of FinancialStatementsType
      */
     public $type;
 
     /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * Length: 31 characters
+     *
      * @var string
      */
     public $front;

lib/Checkout/Accounts/FinancialStatementsType.php

@@ -2,6 +2,13 @@
 
 namespace Checkout\Accounts;
 
+/**
+ * The document type accepted as financial statements when onboarding a sub-entity (US ISV Seller
+ * variants).
+ *
+ * Note the plural financial_statements. It is a different enum from FinancialVerificationType,
+ * whose value is the singular financial_statement and which belongs to a different document.
+ */
 class FinancialStatementsType
 {
     public static $financial_statements = "financial_statements";

lib/Checkout/Accounts/FinancialVerification.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Checkout\Accounts;
+
+/**
+ * Financial statement document. Becomes mandatory depending on the answer provided for
+ * annual_processing_volume; the sub-entity's status changes to requirements_due when it is
+ * needed.
+ */
+class FinancialVerification
+{
+    /**
+     * The type of the file.
+     * [Required]
+     * Enum: "financial_statement"
+     *
+     * @var string value of FinancialVerificationType
+     */
+    public $type;
+
+    /**
+     * The ID of the front side of the document as represented within Checkout.com systems.
+     * [Required]
+     * ^file_[a-z2-7]{26}$
+     * Length: 31 characters
+     *
+     * @var string
+     */
+    public $front;
+}

lib/Checkout/Accounts/FinancialVerificationType.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace Checkout\Accounts;
+
+/**
+ * The document type accepted as financial verification when onboarding a sub-entity (EEA Company,
+ * Accounts API v2.0).
+ *
+ * Note the singular financial_statement. It is a different enum from FinancialStatementsType,
+ * whose value is the plural financial_statements and which belongs to a different document.
+ */
+class FinancialVerificationType
+{
+    public static $financial_statement = "financial_statement";
+}

lib/Checkout/Accounts/Headers.php

@@ -5,8 +5,8 @@
 class Headers
 {
     /**
-     * Value for the If-Match header, used to identify a specific version of a
-     * reserve rule to update (for example "Y3Y9MCZydj0w"). Etag.
+     * Value for the If-Match header: the ETag of the reserve rule or payment instrument to update
+     * (for example "Y3Y9MCZydj0w"), sent as the If-Match HTTP header.
      *
      * @var string
      */