feature/INT-1655 - Support for negotiating Accounts API schema version via the Accept header (#351)

* New  accept header for Accounts

* Account 3.0 models

* Accounts 3.0 schema test fixes

* php doc + test completion

* Completion of schemas and tests

* doc precission fix + test examples extension

Author: david-ruiz-cko

lib/Checkout/Accounts/AccountsClient.php

@@ -25,6 +25,11 @@ class AccountsClient extends Client
     const RESERVE_RULES_PATH = "reserve-rules";
     const REQUIREMENTS_PATH = "requirements";
 
+    /**
+     * The latest Accounts API schema version, negotiated through the Accept header.
+     */
+    const DEFAULT_SCHEMA_VERSION = "3.0";
+
     private $filesApiClient;
 
     public function __construct(
@@ -36,17 +41,33 @@ public function __construct(
         $this->filesApiClient = $filesApiClient;
     }
 
+    /**
+     * Build the Accept header used to negotiate the Accounts API schema version.
+     *
+     * @param string $schemaVersion
+     * @return Headers
+     */
+    private function buildSchemaVersionHeaders($schemaVersion)
+    {
+        $headers = new Headers();
+        $headers->accept = "application/json;schema_version=" . $schemaVersion;
+        return $headers;
+    }
+
     /**
      * @param OnboardEntityRequest $entityRequest
+     * @param string $schemaVersion The Accounts API schema version to request (default: latest, 3.0)
      * @return array
      * @throws CheckoutApiException
      */
-    public function createEntity(OnboardEntityRequest $entityRequest)
+    public function createEntity(OnboardEntityRequest $entityRequest, $schemaVersion = self::DEFAULT_SCHEMA_VERSION)
     {
         return $this->apiClient->post(
             $this->buildPath(self::ACCOUNTS_PATH, self::ENTITIES_PATH),
             $entityRequest,
-            $this->sdkAuthorization()
+            $this->sdkAuthorization(),
+            null,
+            $this->buildSchemaVersionHeaders($schemaVersion)
         );
     }
 
@@ -66,29 +87,36 @@ public function retrievePaymentInstrumentDetails($entityId, $paymentInstrumentId
 
     /**
      * @param $entityId
+     * @param string $schemaVersion The Accounts API schema version to request (default: latest, 3.0)
      * @return array
      * @throws CheckoutApiException
      */
-    public function getEntity($entityId)
+    public function getEntity($entityId, $schemaVersion = self::DEFAULT_SCHEMA_VERSION)
     {
         return $this->apiClient->get(
             $this->buildPath(self::ACCOUNTS_PATH, self::ENTITIES_PATH, $entityId),
-            $this->sdkAuthorization()
+            $this->sdkAuthorization(),
+            $this->buildSchemaVersionHeaders($schemaVersion)
         );
     }
 
     /**
      * @param $entityId
      * @param OnboardEntityRequest $entityRequest
+     * @param string $schemaVersion The Accounts API schema version to request (default: latest, 3.0)
      * @return array
      * @throws CheckoutApiException
      */
-    public function updateEntity($entityId, OnboardEntityRequest $entityRequest)
-    {
+    public function updateEntity(
+        $entityId,
+        OnboardEntityRequest $entityRequest,
+        $schemaVersion = self::DEFAULT_SCHEMA_VERSION
+    ) {
         return $this->apiClient->put(
             $this->buildPath(self::ACCOUNTS_PATH, self::ENTITIES_PATH, $entityId),
             $entityRequest,
-            $this->sdkAuthorization()
+            $this->sdkAuthorization(),
+            $this->buildSchemaVersionHeaders($schemaVersion)
         );
     }
 
@@ -361,14 +389,16 @@ public function retrieveFile($entityId, $fileId)
      * Retrieve the list of pending requirements for a sub-entity.
      *
      * @param string $entityId The sub-entity's ID (Required)
+     * @param string $schemaVersion The Accounts API schema version to request (default: latest, 3.0)
      * @return array
      * @throws CheckoutApiException
      */
-    public function getEntityRequirements($entityId)
+    public function getEntityRequirements($entityId, $schemaVersion = self::DEFAULT_SCHEMA_VERSION)
     {
         return $this->apiClient->get(
             $this->buildPath(self::ACCOUNTS_PATH, self::ENTITIES_PATH, $entityId, self::REQUIREMENTS_PATH),
-            $this->sdkAuthorization()
+            $this->sdkAuthorization(),
+            $this->buildSchemaVersionHeaders($schemaVersion)
         );
     }
 

lib/Checkout/Accounts/AgreedTerms.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace Checkout\Accounts;
+
+/**
+ * The terms of service the sub-entity agreed to (Accounts API v3.0, SaaS onboarding).
+ */
+class AgreedTerms
+{
+    /**
+     * The date and time the terms were agreed.
+     * [Required]
+     * Format: date-time (RFC 3339)
+     *
+     * @var string
+     */
+    public $date;
+
+    /**
+     * The IP address from which the terms were agreed.
+     * [Required]
+     *
+     * @var string
+     */
+    public $ip_address;
+
+    /**
+     * The name of the person who agreed to the terms.
+     * [Required]
+     *
+     * @var string
+     */
+    public $name;
+
+    /**
+     * The email address of the person who agreed to the terms.
+     * [Required]
+     * Format: email
+     *
+     * @var string
+     */
+    public $email;
+
+    /**
+     * The version of the terms that were agreed.
+     * [Required]
+     *
+     * @var string
+     */
+    public $version;
+}

lib/Checkout/Accounts/BusinessType.php

@@ -4,11 +4,23 @@
 
 class BusinessType
 {
+    public static $individual_or_sole_proprietorship = "individual_or_sole_proprietorship";
     public static $general_partnership = "general_partnership";
     public static $limited_partnership = "limited_partnership";
+    public static $scottish_limited_partnership = "scottish_limited_partnership";
     public static $public_limited_company = "public_limited_company";
     public static $limited_company = "limited_company";
+    public static $limited_liability_corporation = "limited_liability_corporation";
+    public static $private_corporation = "private_corporation";
+    public static $publicly_traded_corporation = "publicly_traded_corporation";
     public static $professional_association = "professional_association";
     public static $unincorporated_association = "unincorporated_association";
     public static $auto_entrepreneur = "auto_entrepreneur";
+    public static $government_agency = "government_agency";
+    public static $non_profit_entity = "non_profit_entity";
+    public static $trust = "trust";
+    public static $club_or_society = "club_or_society";
+    public static $regulated_financial_institution = "regulated_financial_institution";
+    public static $cftc_registered_entity = "cftc_registered_entity";
+    public static $sec_registered_entity = "sec_registered_entity";
 }

lib/Checkout/Accounts/Company.php

@@ -4,49 +4,121 @@
 
 use Checkout\Common\Address;
 
+/**
+ * Information about the company represented by a sub-entity.
+ * Which fields are required depends on the sub-entity's region and onboarding variant.
+ */
 class Company
 {
     /**
+     * The company's registration number.
+     * [Required]
+     * Format: region-specific (validated by the API against the sub-entity's country)
+     *
      * @var string
      */
     public $business_registration_number;
 
     /**
+     * The company's business type.
+     * [Required]
+     * Enum: "individual_or_sole_proprietorship", "limited_company", "public_limited_company",
+     * "limited_partnership", "general_partnership", "scottish_limited_partnership",
+     * "government_agency", "non_profit_entity", "trust", "club_or_society",
+     * "unincorporated_association"
+     *
      * @var string value of BusinessType
      */
     public $business_type;
 
     /**
+     * The company's registered legal name.
+     * [Required]
+     * Length: 2 to 300 characters
+     *
      * @var string
      */
     public $legal_name;
 
     /**
+     * The name the company trades under.
+     * [Required]
+     * Length: 2 to 300 characters
+     *
      * @var string
      */
     public $trading_name;
 
     /**
+     * Additional names the company trades under.
+     * [Optional]
+     * Format: array of string (Accounts API v3.0)
+     *
+     * @var array of string
+     */
+    public $additional_trading_names;
+
+    /**
+     * Indicates whether the sub-entity is a registered legal entity.
+     * [Optional] (Accounts API v3.0)
+     *
+     * @var bool
+     */
+    public $is_registered_company;
+
+    /**
+     * The regulatory licence number of the company.
+     * [Optional]
+     * Length: max 32 characters
+     *
+     * @var string
+     */
+    public $regulatory_licence_number;
+
+    /**
+     * The date the company was incorporated.
+     * [Required] for the full onboarding variants (Accounts API v3.0)
+     *
+     * @var DateOfIncorporation
+     */
+    public $date_of_incorporation;
+
+    /**
+     * The company's principal (place of business) address.
+     * [Required]
+     *
      * @var Address
      */
     public $principal_address;
 
     /**
+     * The company's registered address.
+     * [Required]
+     *
      * @var Address
      */
     public $registered_address;
 
     /**
+     * A company verification document.
+     * [Optional]
+     *
      * @var EntityDocument
      */
     public $document;
 
     /**
+     * The company's representatives (persons of interest).
+     * [Required]
+     *
      * @var array of Representative
      */
     public $representatives;
 
     /**
+     * The company's financial details.
+     * [Optional]
+     *
      * @var EntityFinancialDetails
      */
     public $financial_details;

lib/Checkout/Accounts/CompanyPosition.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace Checkout\Accounts;
+
+class CompanyPosition
+{
+    public static $ceo = "ceo";
+    public static $cfo = "cfo";
+    public static $coo = "coo";
+    public static $managing_member = "managing_member";
+    public static $general_partner = "general_partner";
+    public static $president = "president";
+    public static $vice_president = "vice_president";
+    public static $treasurer = "treasurer";
+    public static $other_senior_management = "other_senior_management";
+    public static $other_executive_officer = "other_executive_officer";
+    public static $other_non_executive_non_senior = "other_non_executive_non_senior";
+}

lib/Checkout/Accounts/DateOfIncorporation.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace Checkout\Accounts;
+
+/**
+ * The date a company was incorporated (Accounts API v3.0).
+ */
+class DateOfIncorporation
+{
+    /**
+     * The day of the month the company was incorporated.
+     * [Optional]
+     * Range: 1 to 31
+     *
+     * @var int
+     */
+    public $day;
+
+    /**
+     * The month the company was incorporated.
+     * [Required]
+     * Range: 1 to 12
+     *
+     * @var int
+     */
+    public $month;
+
+    /**
+     * The year the company was incorporated.
+     * [Required]
+     * Range: 1500 to 2999
+     *
+     * @var int
+     */
+    public $year;
+}

lib/Checkout/Accounts/EntityRoles.php

@@ -6,4 +6,7 @@ class EntityRoles
 {
     public static $ubo = "ubo";
     public static $legal_representative = "legal_representative";
+    public static $authorised_signatory = "authorised_signatory";
+    public static $director = "director";
+    public static $control_person = "control_person";
 }

lib/Checkout/Accounts/Headers.php

@@ -5,7 +5,18 @@
 class Headers
 {
     /**
+     * Value for the If-Match header, used to identify a specific version of a
+     * reserve rule to update (for example "Y3Y9MCZydj0w"). Etag.
+     *
      * @var string
      */
     public $if_match;
+
+    /**
+     * Value for the Accept header, used to negotiate the Accounts API schema version
+     * (for example "application/json;schema_version=3.0").
+     *
+     * @var string
+     */
+    public $accept;
 }