feature/INT-1701 - Representative documents alignment

lib/checkout_sdk/accounts/accounts.rb

@@ -81,3 +81,11 @@
 require 'checkout_sdk/accounts/financial_statements'
 require 'checkout_sdk/accounts/financial_statements_type'
 require 'checkout_sdk/accounts/articles_of_association'
+require 'checkout_sdk/accounts/certified_authorised_signatory_type'
+require 'checkout_sdk/accounts/certified_authorised_signatory'
+require 'checkout_sdk/accounts/proof_of_residential_address_type'
+require 'checkout_sdk/accounts/proof_of_residential_address'
+require 'checkout_sdk/accounts/proof_of_registration_type'
+require 'checkout_sdk/accounts/proof_of_registration'
+require 'checkout_sdk/accounts/representative_documents'
+require 'checkout_sdk/accounts/file_purpose'

lib/checkout_sdk/accounts/accounts_client.rb

@@ -78,13 +78,17 @@ def retrieve_payment_instrument_details(entity_id, payment_instrument_id)
                               sdk_authorization)
       end
 
+      # Updates a payment instrument (PATCH /accounts/entities/{entityId}/payment-instruments/{id}).
+      # The API reads the ETag only from the If-Match HTTP header and answers 428 without it, so the
+      # request's headers.if_match is sent as that header.
       # @param [String] entity_id
       # @param [String] instrument_id
       # @param [Hash, UpdatePaymentInstrumentRequest] update_payment_instrument
       def update_payment_instrument(entity_id, instrument_id, update_payment_instrument)
         api_client.invoke_patch(build_path(ACCOUNTS, ENTITIES, entity_id, PAYMENT_INSTRUMENTS, instrument_id),
                                 sdk_authorization,
-                                update_payment_instrument)
+                                update_payment_instrument,
+                                payment_instrument_headers(update_payment_instrument))
       end
 
       # @param [String] entity_id
@@ -100,7 +104,10 @@ def retrieve_payout_schedule(entity_id)
         api_client.invoke_get(build_path(ACCOUNTS, ENTITIES, entity_id, PAYOUT_SCHEDULE), sdk_authorization)
       end
 
-      # @param [Hash, FileRequest] file_request
+      # Uploads a file to the Files API (POST /files on the Files host), as a multipart request. The
+      # returned ID is what document front and back attributes take.
+      # @param [Hash, FileRequest] file_request The file to upload and its {FilePurpose}.
+      # @return [Hash] The ID of the uploaded file.
       def upload_file(file_request)
         files_client.submit_file(FILES, sdk_authorization, file_request)
       end
@@ -216,20 +223,25 @@ def reinvite_sub_entity_member(entity_id, user_id, reinvite_request)
         )
       end
 
-      # Upload a file scoped to a sub-entity. Hits POST /entities/{entityId}/files.
-      # @param [String] entity_id
-      # @param [Hash, EntityFilesRequest] file_request
+      # Create a file upload scoped to a sub-entity. Hits POST /entities/{entityId}/files on the Files host
+      # with a JSON body carrying only the purpose. The file content is not part of this request: send the
+      # raw bytes with an HTTP PUT to the returned _links.upload.href.
+      # @param [String] entity_id The ID of the sub-entity.
+      # @param [Hash, EntityFilesRequest] file_request The {FilePurpose} of the file to upload.
+      # @return [Hash] The file ID, the maximum size allowed, the MIME types allowed for the purpose, and the
+      #   upload link.
       def upload_entity_file(entity_id, file_request)
-        files_client.submit_file(
+        files_client.invoke_post(
           build_path(ENTITIES, entity_id, FILES),
           sdk_authorization,
           file_request
         )
       end
 
-      # Retrieve a file scoped to a sub-entity. Hits GET /entities/{entityId}/files/{fileId}.
-      # @param [String] entity_id
-      # @param [String] file_id
+      # Retrieve a file scoped to a sub-entity. Hits GET /entities/{entityId}/files/{fileId} on the Files host.
+      # @param [String] entity_id The ID of the sub-entity.
+      # @param [String] file_id The ID of the file.
+      # @return [Hash] The file's status, size, MIME type, upload date and purpose.
       def get_entity_file(entity_id, file_id)
         files_client.invoke_get(
           build_path(ENTITIES, entity_id, FILES, file_id),
@@ -239,6 +251,20 @@ def get_entity_file(entity_id, file_id)
 
       private
 
+      # The If-Match header of a payment instrument update, from an UpdatePaymentInstrumentRequest or
+      # a Hash. Returns nil when no ETag was given.
+      def payment_instrument_headers(request)
+        headers = request.is_a?(Hash) ? (request[:headers] || request['headers']) : request&.headers
+        return headers unless headers.is_a?(Hash)
+
+        etag = headers[:if_match] || headers['if_match'] || headers['if-match']
+        return nil if etag.nil?
+
+        http_headers = CheckoutSdk::Common::Headers.new
+        http_headers.if_match = etag
+        http_headers
+      end
+
       # Builds the versioned Accept header for Accounts onboarding operations.
       # @param [String] schema_version
       # @return [CheckoutSdk::Common::Headers]

lib/checkout_sdk/accounts/additional_document.rb

@@ -2,7 +2,13 @@
 
 module CheckoutSdk
   module Accounts
+    # Additional space for documents to be provided when requested. Carries a file ID only; the API defines
+    # no document type for it.
     # @!attribute front
+    #   The ID of the front side of the document as represented within Checkout.com systems.
+    #   [Required]
+    #   ^file_[a-z2-7]{26}$
+    #   31 characters
     #   @return [String]
     class AdditionalDocument
       attr_accessor :front

lib/checkout_sdk/accounts/additional_info.rb

@@ -2,11 +2,16 @@
 
 module CheckoutSdk
   module Accounts
+    # Not defined by any Accounts API schema.
+    # @deprecated Not part of any Accounts API schema; the API does not read it.
     # @!attribute field1
+    #   @deprecated Not defined by any Accounts API schema.
     #   @return [String]
     # @!attribute field2
+    #   @deprecated Not defined by any Accounts API schema.
     #   @return [String]
     # @!attribute field3
+    #   @deprecated Not defined by any Accounts API schema.
     #   @return [String]
     class AdditionalInfo
       attr_accessor :field1,

lib/checkout_sdk/accounts/agreed_terms.rb

@@ -2,16 +2,29 @@
 
 module CheckoutSdk
   module Accounts
-    # The terms of service the sub-entity agreed to (Accounts API v3.0, SaaS onboarding).
+    # Evidence of consent to Checkout.com onboarding: the person who agreed to the terms and conditions
+    # (US ISV Seller variants).
     # @!attribute date
+    #   Date and time the terms were agreed, in RFC 3339 or ISO 8601 format.
+    #   [Required]
+    #   Format: date-time
     #   @return [String] Date and time the terms were agreed (RFC 3339 / ISO 8601).
     # @!attribute ip_address
+    #   IP address (IPv4 or IPv6) of the person at the time they agreed the terms.
+    #   [Required]
     #   @return [String] IP address (IPv4 or IPv6) of the person at the time they agreed.
     # @!attribute name
+    #   First and last name of the person who agreed to the terms.
+    #   [Required]
     #   @return [String] First and last name of the person who agreed to the terms.
     # @!attribute email
+    #   Email address of the person who agreed to the terms.
+    #   [Required]
+    #   Format: email
     #   @return [String] Email address of the person who agreed to the terms.
     # @!attribute version
+    #   Identifier of the terms version that was agreed.
+    #   [Required]
     #   @return [String] Identifier of the terms version that was agreed.
     class AgreedTerms
       attr_accessor :date,

lib/checkout_sdk/accounts/articles_of_association.rb

@@ -2,9 +2,16 @@
 
 module CheckoutSdk
   module Accounts
+    # Memorandum or Articles of Association document.
     # @!attribute type
-    #   @return [ArticlesOfAssociationType]
+    #   The type of document used.
+    #   [Required]
+    #   @return [String] {ArticlesOfAssociationType}
     # @!attribute front
+    #   The ID of the front side of the document as represented within Checkout.com systems.
+    #   [Required]
+    #   ^file_[a-z2-7]{26}$
+    #   31 characters
     #   @return [String]
     class ArticlesOfAssociation
       attr_accessor :type,

lib/checkout_sdk/accounts/articles_of_association_type.rb

@@ -2,6 +2,7 @@
 
 module CheckoutSdk
   module Accounts
+    # The document types accepted as memorandum or articles of association.
     module ArticlesOfAssociationType
       MEMORANDUM_OF_ASSOCIATION = 'memorandum_of_association'
       ARTICLES_OF_ASSOCIATION = 'articles_of_association'

lib/checkout_sdk/accounts/bank_verification.rb

@@ -2,9 +2,16 @@
 
 module CheckoutSdk
   module Accounts
+    # A document showing transactions from the last 3 months.
     # @!attribute type
-    #   @return [BankVerificationType]
+    #   The type of document being used as bank verification.
+    #   [Required]
+    #   @return [String] {BankVerificationType}
     # @!attribute front
+    #   The ID of the front side of the document as represented within Checkout.com systems.
+    #   [Required]
+    #   ^file_[a-z2-7]{26}$
+    #   31 characters
     #   @return [String]
     class BankVerification
       attr_accessor :type,

lib/checkout_sdk/accounts/bank_verification_type.rb

@@ -2,6 +2,7 @@
 
 module CheckoutSdk
   module Accounts
+    # The document type accepted as bank verification.
     module BankVerificationType
       BANK_STATEMENT = 'bank_statement'
     end

lib/checkout_sdk/accounts/business_type.rb

@@ -2,6 +2,8 @@
 
 module CheckoutSdk
   module Accounts
+    # The legal type of the company. Must be INDIVIDUAL_OR_SOLE_PROPRIETORSHIP for the sole trader variants;
+    # which other values a variant accepts depends on the variant.
     module BusinessType
       INDIVIDUAL_OR_SOLE_PROPRIETORSHIP = 'individual_or_sole_proprietorship'
       GENERAL_PARTNERSHIP = 'general_partnership'

lib/checkout_sdk/accounts/certified_authorised_signatory.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Certified authorised signatory document. Required when the legal representative or other role owner
+    # is not registered on the certificate of incorporation. Representative documents only
+    # (company.representatives[].documents), EEA, GB and US Company Full (3.0) and US ISV Seller Company
+    # (3.0).
+    # @!attribute type
+    #   The type of document.
+    #   [Required]
+    #   @return [String] {CertifiedAuthorisedSignatoryType}
+    # @!attribute front
+    #   The ID of the front side of the document as represented within Checkout.com systems.
+    #   [Required]
+    #   ^file_[a-z2-7]{26}$
+    #   31 characters
+    #   @return [String]
+    class CertifiedAuthorisedSignatory
+      attr_accessor :type,
+                    :front
+    end
+  end
+end

lib/checkout_sdk/accounts/certified_authorised_signatory_type.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # The document type accepted as a representative's certified authorised signatory document.
+    module CertifiedAuthorisedSignatoryType
+      POWER_OF_ATTORNEY = 'power_of_attorney'
+    end
+  end
+end

lib/checkout_sdk/accounts/citizenship.rb

@@ -2,10 +2,15 @@
 
 module CheckoutSdk
   module Accounts
-    # A citizenship or legal status held by a company representative (Accounts API v3.0).
+    # A citizenship or legal-status record of a representative (US ISV Seller variants).
     # @!attribute type
+    #   The type of citizenship or legal status (for example citizenship or residency).
+    #   [Optional]
     #   @return [String] The type of citizenship or legal status (e.g. `citizenship`, `residency`).
     # @!attribute country
+    #   The two-letter ISO 3166-1 alpha-2 country code.
+    #   [Required]
+    #   Format: iso-3166-1-alpha-2
     #   @return [String] {CheckoutSdk::Common::Country} two-letter ISO 3166-1 alpha-2 code.
     class Citizenship
       attr_accessor :type,

lib/checkout_sdk/accounts/company.rb

@@ -2,31 +2,84 @@
 
 module CheckoutSdk
   module Accounts
+    # Information about the company represented by the sub-entity: on every company and v3.0 sole trader
+    # variant, and as the controlling company of a {Representative} (where only legal_name, trading_name
+    # and registered_address apply).
     # @!attribute business_registration_number
+    #   The sub-entity's business registration number: a Commercial Registration or Ministry of Commerce
+    #   certificate number, or an equivalent registration number.
+    #   [Required] for the Full variants and US ISV Seller Company (3.0); [Optional] for the Lite (2.0)
+    #   variants. Not part of the sole trader variants.
+    #   The format depends on the variant:
+    #     EEA: min 2 characters, max 39 characters; a SIRET number for sub-entities based in France.
+    #     GB (3.0): a Companies House number, 8 characters, matching one of the three alternatives of the
+    #     spec's pattern, ^(A|B|C)$:
+    #     A: ((AC|CE|CS|FC|FE|GE|GS|IC|LP|NC|NF|NI|NL|NO|NP|OC|OE|PC|R0|RC|SA|SC|SE|SF|SG|SI|SL|SO|SR|SZ|ZC|\d{2})\d{6})
+    #     B: ((IP|SP|RS)[A-Z\d]{6})
+    #     C: (SL\d{5}[\dA])
+    #     GB (2.0) accepts the same pattern case-insensitively.
+    #     US: an Employer Identification Number (EIN), ^[0-9]{9}$, 9 characters; US ISV Seller Company (3.0)
+    #     also accepts the hyphenated form, ^[0-9]{2}-?[0-9]{7}$, min 9 characters, max 11.
     #   @return [String]
     # @!attribute business_type
+    #   The legal type of the company ({BusinessType} values). Must be individual_or_sole_proprietorship for
+    #   the sole trader variants.
+    #   [Required], except on EEA and US Company Lite (2.0) where it is [Optional]. Not part of GB Company
+    #   Full and Lite (2.0).
     #   @return [String] {BusinessType}
     # @!attribute legal_name
+    #   The legal name of the sub-entity.
+    #   [Required] for every company variant and the controlling company; not part of the sole trader
+    #   variants.
+    #   min 2 characters, max 300 characters
     #   @return [String]
     # @!attribute trading_name
+    #   The trading name of the sub-entity, also referred to as 'doing business as'.
+    #   [Required]
+    #   min 2 characters, max 300 characters
     #   @return [String]
     # @!attribute additional_trading_names
+    #   The collection of additional trading names for the sub-entity.
+    #   [Optional] (US ISV Seller variants only)
     #   @return [Array(String)]
     # @!attribute is_registered_company
+    #   Whether the sub-entity is a registered legal entity. Must be false for US ISV Seller Sole Trader
+    #   (3.0).
+    #   [Required] for US ISV Seller Sole Trader (3.0); not part of the other variants.
     #   @return [Boolean]
     # @!attribute date_of_incorporation
+    #   The date the company was incorporated, or the date the sole trader started trading.
+    #   [Required] for every v3.0 variant; [Optional] for EEA, GB and US Company Full (2.0).
     #   @return [DateOfIncorporation]
     # @!attribute regulatory_licence_number
+    #   The regulatory licence number of the company.
+    #   [Optional] (EEA Company Full (3.0) only)
+    #   ^[a-zA-Z0-9\-]+$
+    #   min 4 characters, max 32 characters
     #   @return [String]
     # @!attribute principal_address
+    #   The primary location where business is performed.
+    #   [Required] for every company and v3.0 sole trader variant.
     #   @return [CheckoutSdk::Common::Address]
     # @!attribute registered_address
+    #   The registered address of the company.
+    #   [Required] for every company variant and the controlling company; not part of the sole trader
+    #   variants.
     #   @return [CheckoutSdk::Common::Address]
     # @!attribute representatives
-    #   @return [Array(EntityRepresentative)]
+    #   Information about the representatives of this company.
+    #   [Required]
+    #   min 1 item; max 1 item for the sole trader variants (the individual themselves, with roles [ubo]),
+    #   max 5 on v2.0, max 25 on EEA, GB and US Company Full (3.0), no maximum on US ISV Seller Company
+    #   (3.0)
+    #   @return [Array(Representative)]
     # @!attribute document
+    #   @deprecated Not defined by any Accounts API company schema; the API does not read it.
     #   @return [EntityDocument]
     # @!attribute financial_details
+    #   Seller financial questions.
+    #   [Required] for EEA and US Company Full (2.0); [Optional] for EEA and US Company Lite (2.0). Not part
+    #   of the other variants.
     #   @return [EntityFinancialDetails]
     class Company
       attr_accessor :business_registration_number,

lib/checkout_sdk/accounts/company_position.rb

@@ -2,6 +2,7 @@
 
 module CheckoutSdk
   module Accounts
+    # The position of a representative within the company (required for the control_person role).
     module CompanyPosition
       CEO = 'ceo'
       CFO = 'cfo'

lib/checkout_sdk/accounts/company_verification.rb

@@ -2,9 +2,18 @@
 
 module CheckoutSdk
   module Accounts
+    # The document to use to confirm the company's identity (certified by a power of attorney within the
+    # last 3 months).
     # @!attribute type
+    #   The type of document used for company verification. articles_of_association is accepted on the US
+    #   Company (2.0) variants only.
+    #   [Required]
     #   @return [String] {CompanyVerificationType}
     # @!attribute front
+    #   The ID of the front side of the document as represented within Checkout.com systems.
+    #   [Required]
+    #   ^file_[a-z2-7]{26}$
+    #   31 characters
     #   @return [String]
     class CompanyVerification
       attr_accessor :type,

lib/checkout_sdk/accounts/company_verification_type.rb

@@ -2,6 +2,9 @@
 
 module CheckoutSdk
   module Accounts
+    # The document types accepted as company verification. ARTICLES_OF_ASSOCIATION is accepted on the US
+    # Company (2.0) variants only; articles of association sent as their own document use
+    # {ArticlesOfAssociationType} instead.
     module CompanyVerificationType
       INCORPORATION_DOCUMENT = 'incorporation_document'
       ARTICLES_OF_ASSOCIATION = 'articles_of_association'