checkout_sdk 2.3.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 10c1640f0771e6b8ad38799a40a00322c5347fdacedce0669c6920b4a4a36199
-  data.tar.gz: 43d03c65b9a2ecfa94b50116f86db22aa5a86f1698d9bb134c2d5f49bd672d31
+  metadata.gz: 1b407e28ff0b39c99b367549f0a8936f08cdab77844dbbaae25120131b7a68fc
+  data.tar.gz: a51e29d577617ba5c4a36e288df85b6fd03e2184b0f9a7f85db86455258079a0
 SHA512:
-  metadata.gz: 43f590d48d61549fa90ade59902f394efb2c79e06a76775fe531493e275506f665168be87c6aef6947f6664e66b4a3c2c046925ca858a08bc3a5bff8c5c7ac02
-  data.tar.gz: dd687b3f02bed8008e0ae4aabe23bd948251a78274d71f48da80a657d3c2dd266fcd98eb2bc7a4bebe0dcb21844e61eb2bb222fd5b835cbc5537cca98e895b6b
+  metadata.gz: aaf583699b582fdcd33dc32e5178870074b874427ce2a032a0919ef472d8e59ae9627824affffb185a11735607a310a52dabfb5fa52bd10371a715137e128226
+  data.tar.gz: 60331bb9c0b309e98f738d1bbc140fa648c6b75c4a75ebc442f5bd406bcca6cfd343c1bbad8817d894ca6657d03c00f08da9a3f7c084a6e3c86caf1dfc8bd3a9

data/lib/checkout_sdk/api_client.rb

@@ -26,8 +26,8 @@ module CheckoutSdk
       invoke(:put, path, authorization, request, nil, params: nil, extra_headers: headers)
     end
 
-    def invoke_patch(path, authorization, request = nil)
-      invoke(:patch, path, authorization, request, nil, params: nil)
+    def invoke_patch(path, authorization, request = nil, headers = nil)
+      invoke(:patch, path, authorization, request, nil, params: nil, extra_headers: headers)
     end
 
     def invoke_delete(path, authorization)
@@ -66,18 +66,45 @@ module CheckoutSdk
         Authorization: authorization.authorization_header }
     end
 
-    # Map a typed headers container (e.g. {CheckoutSdk::Common::Headers}) onto the underlying
-    # HTTP header hash. Each attribute that's set is emitted as the corresponding
-    # canonical HTTP header.
+    # Attribute name to HTTP header name, for every typed headers container the SDK supports.
+    #
+    # The header names are case sensitive in the spec: return-encrypted-cvv is lower case where a
+    # naive conversion would produce Return-Encrypted-Cvv.
+    #
+    # The values are Strings, not Symbols, and that is load bearing. Faraday::Utils::Headers
+    # preserves a String key verbatim but rewrites a Symbol key as
+    # `key.to_s.split('_').map(&:capitalize).join('-')`, so :'return-encrypted-cvv' would reach
+    # the wire as Return-encrypted-cvv and :'Encryption-Key' as Encryption-key. Strings are the
+    # only way to send the spelling the spec asks for. As a side effect this also stops If-Match
+    # being sent as If-match, which it was before.
+    EXTRA_HEADER_NAMES = {
+      if_match: 'If-Match',
+      accept: 'Accept',
+      return_encrypted_cvv: 'return-encrypted-cvv',
+      encryption_key: 'Encryption-Key'
+    }.freeze
+    private_constant :EXTRA_HEADER_NAMES
+
+    # Map a typed headers container (e.g. {CheckoutSdk::Common::Headers},
+    # {CheckoutSdk::Issuing::CardUpdateHeaders}) onto the underlying HTTP header hash. Each
+    # attribute that is set is emitted as the corresponding HTTP header.
+    #
+    # Previously a hand-written if/return chain. That shape had a latent trap: it ended with
+    # `return unless extra_headers.respond_to?(:accept) && extra_headers.accept`, so any header
+    # handled after that point was dead code for every container without an `accept` attribute.
+    # Iterating an explicit map removes the trap and keeps the existing If-Match and Accept
+    # behaviour byte for byte.
     def apply_extra_headers(http_headers, extra_headers)
       return if extra_headers.nil?
 
-      if extra_headers.respond_to?(:if_match) && extra_headers.if_match
-        http_headers[:'If-Match'] = extra_headers.if_match
-      end
-      return unless extra_headers.respond_to?(:accept) && extra_headers.accept
+      EXTRA_HEADER_NAMES.each do |attribute, header_name|
+        next unless extra_headers.respond_to?(attribute)
+
+        value = extra_headers.public_send(attribute)
+        next if value.nil? || value.to_s.empty?
 
-      http_headers[:Accept] = extra_headers.accept
+        http_headers[header_name] = value
+      end
     end
 
     def append_params(path, input_params)

data/lib/checkout_sdk/checkout_api.rb

@@ -79,6 +79,8 @@ module CheckoutSdk
   #   @return [CheckoutSdk::Payments::ApplePayClient]
   # @!attribute google_pay
   #   @return [CheckoutSdk::Payments::GooglePayClient]
+  # @!attribute inventory
+  #   @return [CheckoutSdk::Inventory::InventoryClient]
   class CheckoutApi
     attr_reader :customers,
                 :disputes,
@@ -118,7 +120,8 @@ module CheckoutSdk
                 :identity_verification,
                 :face_authentication,
                 :apple_pay,
-                :google_pay
+                :google_pay,
+                :inventory
 
     # @param [CheckoutConfiguration] configuration
     def initialize(configuration)
@@ -168,6 +171,7 @@ module CheckoutSdk
         CheckoutSdk::Identities::FaceAuthentication::FaceAuthenticationClient.new(api_client, configuration)
       @apple_pay = CheckoutSdk::Payments::ApplePayClient.new(api_client, configuration)
       @google_pay = CheckoutSdk::Payments::GooglePayClient.new(api_client, configuration)
+      @inventory = CheckoutSdk::Inventory::InventoryClient.new(api_client, configuration)
     end
 
     private

data/lib/checkout_sdk/identities/address_document_verification/address_document_verification_client.rb

@@ -9,7 +9,8 @@ module CheckoutSdk
         ANONYMIZE = 'anonymize'
         ATTEMPTS = 'attempts'
         PDF_REPORT = 'pdf-report'
-        private_constant :ADDRESS_DOCUMENT_VERIFICATIONS, :ANONYMIZE, :ATTEMPTS, :PDF_REPORT
+        ASSETS = 'assets'
+        private_constant :ADDRESS_DOCUMENT_VERIFICATIONS, :ANONYMIZE, :ATTEMPTS, :PDF_REPORT, :ASSETS
 
         # @param [ApiClient] api_client
         # @param [CheckoutConfiguration] configuration
@@ -49,11 +50,19 @@ module CheckoutSdk
           )
         end
 
+        # Get the details of all attempts for a specific address document verification.
+        #
+        # Results are paginated. Beta.
+        #
         # @param [String] address_document_verification_id
-        def get_address_document_verification_attempts(address_document_verification_id)
+        # @param [Hash, CheckoutSdk::Identities::IdvAttemptsQueryFilter, nil] query pagination
+        #   query parameters; supports :skip (Integer, default: 0) and :limit (Integer, default: 10)
+        # @return [OpenStruct] the paginated attempt list
+        def get_address_document_verification_attempts(address_document_verification_id, query = nil)
           api_client.invoke_get(
             build_path(ADDRESS_DOCUMENT_VERIFICATIONS, address_document_verification_id, ATTEMPTS),
-            sdk_authorization
+            sdk_authorization,
+            query
           )
         end
 
@@ -73,6 +82,26 @@ module CheckoutSdk
             sdk_authorization
           )
         end
+
+        # Get the assets (the document image) uploaded for a address document verification attempt.
+        #
+        # Results are paginated. Beta.
+        #
+        # @param [String] address_document_verification_id
+        # @param [String] attempt_id
+        # @param [Hash, CheckoutSdk::Identities::IdvAttemptAssetsQueryFilter, nil] query pagination
+        #   query parameters; supports :skip (Integer, default: 0) and :limit (Integer, default: 10)
+        # @return [OpenStruct] the paginated asset list
+        def get_address_document_verification_attempt_assets(address_document_verification_id,
+                                                             attempt_id,
+                                                             query = nil)
+          api_client.invoke_get(
+            build_path(ADDRESS_DOCUMENT_VERIFICATIONS, address_document_verification_id,
+                       ATTEMPTS, attempt_id, ASSETS),
+            sdk_authorization,
+            query
+          )
+        end
       end
     end
   end

data/lib/checkout_sdk/identities/address_document_verification/address_document_verification_request.rb

@@ -6,11 +6,21 @@ module CheckoutSdk
       # Request body for POST /address-document-verifications.
       #
       # @!attribute applicant_id
-      #   @return [String] The applicant's unique identifier. [Required] Pattern: ^aplt_\w+$
+      #   The applicant's unique identifier.
+      #   [Required]
+      #   ^aplt_\w+$
+      #   @return [String]
       # @!attribute user_journey_id
-      #   @return [String] Your configuration ID. [Required] Pattern: ^usj_[a-z2-7]{26}$
+      #   Your configuration ID.
+      #   [Required]
+      #   ^usj_[a-z2-7]{26}$
+      #   @return [String]
       # @!attribute declared_data
-      #   @return [IdvDeclaredData, Hash] The personal details provided by the applicant. [Optional]
+      #   The personal details provided by the applicant. The address document verification
+      #   request takes the narrower two field IdvDeclaredData shape, not the identity
+      #   verification one.
+      #   [Optional]
+      #   @return [CheckoutSdk::Identities::IdentityVerification::IdvDeclaredData]
       class AddressDocumentVerificationRequest
         attr_accessor :applicant_id,
                       :user_journey_id,

data/lib/checkout_sdk/identities/face_authentication/face_authentication_attempt_request.rb

@@ -6,11 +6,22 @@ module CheckoutSdk
       # Request body for POST /face-authentications/{id}/attempts.
       #
       # @!attribute redirect_url
-      #   @return [String] URL to redirect the applicant after the attempt.
+      #   The URL to redirect the applicant to after the attempt.
+      #   [Required]
+      #   Format: uri
+      #   @return [String]
+      # @!attribute phone_number
+      #   The applicant's mobile phone number, if sharing the attempt URL via SMS.
+      #   [Optional]
+      #   @return [CheckoutSdk::Identities::IdvPhoneNumber]
       # @!attribute client_information
+      #   The applicant's details. The face authentication attempt takes the narrower
+      #   FavClientInformation shape, which declares neither document field, so this is
+      #   deliberately the parent class and not IdvIdentityClientInformation.
+      #   [Optional]
       #   @return [CheckoutSdk::Identities::IdentityVerification::IdvClientInformation]
       class FaceAuthenticationAttemptRequest
-        attr_accessor :redirect_url, :client_information
+        attr_accessor :redirect_url, :phone_number, :client_information
       end
     end
   end

data/lib/checkout_sdk/identities/face_authentication/face_authentication_client.rb

@@ -47,11 +47,19 @@ module CheckoutSdk
           )
         end
 
+        # Get the details of all attempts for a specific face authentication.
+        #
+        # Results are paginated. Beta.
+        #
         # @param [String] face_authentication_id
-        def get_face_authentication_attempts(face_authentication_id)
+        # @param [Hash, CheckoutSdk::Identities::IdvAttemptsQueryFilter, nil] query pagination
+        #   query parameters; supports :skip (Integer, default: 0) and :limit (Integer, default: 10)
+        # @return [OpenStruct] the paginated attempt list
+        def get_face_authentication_attempts(face_authentication_id, query = nil)
           api_client.invoke_get(
             build_path(FACE_AUTHENTICATIONS, face_authentication_id, ATTEMPTS),
-            sdk_authorization
+            sdk_authorization,
+            query
           )
         end
 
@@ -67,8 +75,8 @@ module CheckoutSdk
         # Retrieve the assets (face images and videos) captured during a face authentication attempt.
         # @param [String] face_authentication_id
         # @param [String] attempt_id
-        # @param [Hash, nil] query pagination query parameters; supports :skip (Integer, default: 0)
-        #   and :limit (Integer, default: 10)
+        # @param [Hash, CheckoutSdk::Identities::IdvAttemptAssetsQueryFilter, nil] query pagination
+        #   query parameters; supports :skip (Integer, default: 0) and :limit (Integer, default: 10)
         def get_face_authentication_attempt_assets(face_authentication_id, attempt_id, query = nil)
           api_client.invoke_get(
             build_path(FACE_AUTHENTICATIONS, face_authentication_id, ATTEMPTS, attempt_id, ASSETS),

data/lib/checkout_sdk/identities/face_authentication/face_authentication_request.rb

@@ -5,14 +5,33 @@ module CheckoutSdk
     module FaceAuthentication
       # Request body for POST /face-authentications.
       #
+      # Realigned with the spec on 2026-09-21. This class omitted user_journey_id, which
+      # FavFaceAuthentication declares and requires, and declared external_reference and
+      # redirect_url, which it does not. The two invented attributes are retained rather than
+      # removed, so no caller breaks, and are scheduled for removal in a future major; the API
+      # ignores them.
+      #
       # @!attribute applicant_id
+      #   The applicant's unique identifier.
+      #   [Required]
+      #   ^aplt_\w+$
+      #   @return [String]
+      # @!attribute user_journey_id
+      #   Your configuration ID.
+      #   [Required]
+      #   ^usj_[a-z2-7]{26}$
       #   @return [String]
       # @!attribute external_reference
+      #   @deprecated Not declared by FavFaceAuthentication. Never sent by the API and ignored if
+      #     supplied. Scheduled for removal in a future major.
       #   @return [String]
       # @!attribute redirect_url
+      #   @deprecated Not declared by FavFaceAuthentication. The redirect URL belongs on the
+      #     attempt request, not the face authentication. Scheduled for removal in a future major.
       #   @return [String]
       class FaceAuthenticationRequest
         attr_accessor :applicant_id,
+                      :user_journey_id,
                       :external_reference,
                       :redirect_url
       end

data/lib/checkout_sdk/identities/id_document_verification/id_document_verification_client.rb

@@ -9,7 +9,8 @@ module CheckoutSdk
         ANONYMIZE = 'anonymize'
         ATTEMPTS = 'attempts'
         PDF_REPORT = 'pdf-report'
-        private_constant :ID_DOCUMENT_VERIFICATIONS, :ANONYMIZE, :ATTEMPTS, :PDF_REPORT
+        ASSETS = 'assets'
+        private_constant :ID_DOCUMENT_VERIFICATIONS, :ANONYMIZE, :ATTEMPTS, :PDF_REPORT, :ASSETS
 
         # @param [ApiClient] api_client
         # @param [CheckoutConfiguration] configuration
@@ -47,11 +48,19 @@ module CheckoutSdk
           )
         end
 
+        # Get the details of all attempts for a specific ID document verification.
+        #
+        # Results are paginated. Beta.
+        #
         # @param [String] id_document_verification_id
-        def get_id_document_verification_attempts(id_document_verification_id)
+        # @param [Hash, CheckoutSdk::Identities::IdvAttemptsQueryFilter, nil] query pagination
+        #   query parameters; supports :skip (Integer, default: 0) and :limit (Integer, default: 10)
+        # @return [OpenStruct] the paginated attempt list
+        def get_id_document_verification_attempts(id_document_verification_id, query = nil)
           api_client.invoke_get(
             build_path(ID_DOCUMENT_VERIFICATIONS, id_document_verification_id, ATTEMPTS),
-            sdk_authorization
+            sdk_authorization,
+            query
           )
         end
 
@@ -71,6 +80,27 @@ module CheckoutSdk
             sdk_authorization
           )
         end
+
+        # Get the assets (the front and back images of the document) uploaded for an ID document
+        # verification attempt.
+        #
+        # Results are paginated. Beta.
+        #
+        # @param [String] id_document_verification_id
+        # @param [String] attempt_id
+        # @param [Hash, CheckoutSdk::Identities::IdvAttemptAssetsQueryFilter, nil] query pagination
+        #   query parameters; supports :skip (Integer, default: 0) and :limit (Integer, default: 10)
+        # @return [OpenStruct] the paginated asset list
+        def get_id_document_verification_attempt_assets(id_document_verification_id,
+                                                        attempt_id,
+                                                        query = nil)
+          api_client.invoke_get(
+            build_path(ID_DOCUMENT_VERIFICATIONS, id_document_verification_id,
+                       ATTEMPTS, attempt_id, ASSETS),
+            sdk_authorization,
+            query
+          )
+        end
       end
     end
   end

data/lib/checkout_sdk/identities/id_document_verification/id_document_verification_request.rb

@@ -5,18 +5,48 @@ module CheckoutSdk
     module IdDocumentVerification
       # Request body for POST /id-document-verifications.
       #
+      # Realigned with the spec on 2026-09-21. This class previously declared
+      # external_reference, document_type, country and redirect_url, none of which
+      # IddvIdDocumentVerification declares, and omitted user_journey_id and declared_data, which
+      # it does. The four invented attributes are retained rather than removed, so no caller
+      # breaks, and are scheduled for removal in a future major; the API ignores them.
+      #
       # @!attribute applicant_id
+      #   The applicant's unique identifier.
+      #   [Required]
+      #   ^aplt_\w+$
+      #   @return [String]
+      # @!attribute user_journey_id
+      #   Your configuration ID.
+      #   [Optional]
+      #   ^usj_[a-z2-7]{26}$
       #   @return [String]
+      # @!attribute declared_data
+      #   The personal details provided by the applicant. The ID document verification request
+      #   takes the narrower two field IdvDeclaredData shape.
+      #   [Optional]
+      #   @return [CheckoutSdk::Identities::IdentityVerification::IdvDeclaredData]
       # @!attribute external_reference
+      #   @deprecated Not declared by IddvIdDocumentVerification. Never sent by the API and
+      #     ignored if supplied. Scheduled for removal in a future major.
       #   @return [String]
       # @!attribute document_type
+      #   @deprecated Not declared by IddvIdDocumentVerification. The document type is chosen by
+      #     the applicant during the attempt and returned on the response, not sent on the
+      #     request. Scheduled for removal in a future major.
       #   @return [String]
       # @!attribute country
+      #   @deprecated Not declared by IddvIdDocumentVerification. Scheduled for removal in a
+      #     future major.
       #   @return [String]
       # @!attribute redirect_url
+      #   @deprecated Not declared by IddvIdDocumentVerification. The redirect URL belongs on the
+      #     attempt request, not the verification. Scheduled for removal in a future major.
       #   @return [String]
       class IdDocumentVerificationRequest
         attr_accessor :applicant_id,
+                      :user_journey_id,
+                      :declared_data,
                       :external_reference,
                       :document_type,
                       :country,

data/lib/checkout_sdk/identities/identities.rb

@@ -1,5 +1,11 @@
 # frozen_string_literal: true
 
+# Shared identities types
+require 'checkout_sdk/identities/idv_phone_number'
+require 'checkout_sdk/identities/idv_address'
+require 'checkout_sdk/identities/idv_attempts_query_filter'
+require 'checkout_sdk/identities/idv_attempt_assets_query_filter'
+
 # Applicants
 require 'checkout_sdk/identities/applicants/create_applicant_request'
 require 'checkout_sdk/identities/applicants/update_applicant_request'
@@ -21,7 +27,9 @@ require 'checkout_sdk/identities/address_document_verification/address_document_
 
 # Identity Verification
 require 'checkout_sdk/identities/identity_verification/idv_declared_data'
+require 'checkout_sdk/identities/identity_verification/idv_identity_declared_data'
 require 'checkout_sdk/identities/identity_verification/idv_client_information'
+require 'checkout_sdk/identities/identity_verification/idv_identity_client_information'
 require 'checkout_sdk/identities/identity_verification/identity_verification_attempt_request'
 require 'checkout_sdk/identities/identity_verification/identity_verification_request'
 require 'checkout_sdk/identities/identity_verification/identity_verification_client'

data/lib/checkout_sdk/identities/identity_verification/identity_verification_attempt_request.rb

@@ -6,11 +6,21 @@ module CheckoutSdk
       # Request body for POST /identity-verifications/{id}/attempts.
       #
       # @!attribute redirect_url
-      #   @return [String] URL to redirect the applicant after the attempt.
+      #   The URL to redirect the applicant to after the attempt.
+      #   [Required]
+      #   Format: uri
+      #   @return [String]
+      # @!attribute phone_number
+      #   The applicant's mobile phone number, if sharing the attempt URL via SMS.
+      #   [Optional]
+      #   @return [CheckoutSdk::Identities::IdvPhoneNumber]
       # @!attribute client_information
-      #   @return [IdvClientInformation]
+      #   The applicant's details. The identity verification attempt accepts the wider
+      #   IdvClientInformation shape, unlike the face authentication attempt.
+      #   [Optional]
+      #   @return [IdvIdentityClientInformation]
       class IdentityVerificationAttemptRequest
-        attr_accessor :redirect_url, :client_information
+        attr_accessor :redirect_url, :phone_number, :client_information
       end
     end
   end

data/lib/checkout_sdk/identities/identity_verification/identity_verification_client.rb

@@ -55,11 +55,19 @@ module CheckoutSdk
           )
         end
 
+        # Get the details of all attempts for a specific identity verification.
+        #
+        # Results are paginated. Beta.
+        #
         # @param [String] identity_verification_id
-        def get_identity_verification_attempts(identity_verification_id)
+        # @param [Hash, CheckoutSdk::Identities::IdvAttemptsQueryFilter, nil] query pagination
+        #   query parameters; supports :skip (Integer, default: 0) and :limit (Integer, default: 10)
+        # @return [OpenStruct] the paginated attempt list
+        def get_identity_verification_attempts(identity_verification_id, query = nil)
           api_client.invoke_get(
             build_path(IDENTITY_VERIFICATIONS, identity_verification_id, ATTEMPTS),
-            sdk_authorization
+            sdk_authorization,
+            query
           )
         end
 
@@ -84,8 +92,8 @@ module CheckoutSdk
         # identity verification attempt.
         # @param [String] identity_verification_id
         # @param [String] attempt_id
-        # @param [Hash, nil] query pagination query parameters; supports :skip (Integer, default: 0)
-        #   and :limit (Integer, default: 10)
+        # @param [Hash, CheckoutSdk::Identities::IdvAttemptAssetsQueryFilter, nil] query pagination
+        #   query parameters; supports :skip (Integer, default: 0) and :limit (Integer, default: 10)
         def get_identity_verification_attempt_assets(identity_verification_id, attempt_id, query = nil)
           api_client.invoke_get(
             build_path(IDENTITY_VERIFICATIONS, identity_verification_id, ATTEMPTS, attempt_id, ASSETS),

data/lib/checkout_sdk/identities/identity_verification/identity_verification_request.rb

@@ -6,15 +6,36 @@ module CheckoutSdk
       # Request body for POST /identity-verifications and POST /create-and-open-idv.
       #
       # @!attribute applicant_id
-      #   @return [String] The applicant's unique identifier (e.g. "aplt_...").
+      #   The applicant's unique identifier.
+      #   [Required]
+      #   ^aplt_\w+$
+      #   @return [String]
       # @!attribute user_journey_id
-      #   @return [String] Your configuration ID (e.g. "usj_...").
+      #   Your configuration ID.
+      #   [Optional]
+      #   ^usj_[a-z2-7]{26}$
+      #   @return [String]
       # @!attribute declared_data
-      #   @return [IdvDeclaredData]
+      #   The personal details provided by the applicant. The identity verification requests take
+      #   the five field IdvIdentityDeclaredData shape.
+      #   [Required]
+      #   @return [IdvIdentityDeclaredData]
       # @!attribute risk_labels
+      #   One or more codes that provide more information about risks associated with the
+      #   verification.
+      #
+      #   The request schema declares this readOnly field, so carrying it here is spec faithful.
+      #   It cannot be sent and will be ignored by the API; read it from the response instead.
+      #   [Optional]
       #   @return [Array<String>]
+      # @!attribute redirect_url
+      #   The URL to redirect the applicant to after the attempt. Accepted by
+      #   POST /create-and-open-idv only, which opens the first attempt in the same call.
+      #   [Optional]
+      #   Format: uri
+      #   @return [String]
       class IdentityVerificationRequest
-        attr_accessor :applicant_id, :user_journey_id, :declared_data, :risk_labels
+        attr_accessor :applicant_id, :user_journey_id, :declared_data, :risk_labels, :redirect_url
       end
     end
   end

data/lib/checkout_sdk/identities/identity_verification/idv_client_information.rb

@@ -3,12 +3,26 @@
 module CheckoutSdk
   module Identities
     module IdentityVerification
-      # Pre-populated client information for an identity-verification attempt.
+      # The applicant's details for a face authentication attempt.
+      #
+      # Maps FavClientInformation. Deliberately smaller than
+      # {IdvIdentityClientInformation}, which adds the two fields only the identity verification
+      # attempt accepts. Shared with the face authentication attempt, so do not add IDV only
+      # fields here.
       #
       # @!attribute pre_selected_residence_country
-      #   @return [String] ISO alpha-2 country code.
+      #   The applicant's residence country.
+      #   [Optional]
+      #   Standard: ISO 3166-1 alpha-2 country code
+      #   ^[A-Z]{2}
+      #   Example: FR
+      #   @return [String] a value of {CheckoutSdk::Common::Country}
       # @!attribute pre_selected_language
-      #   @return [String] IETF BCP 47 language tag.
+      #   The language you want to use for the user interface.
+      #   [Optional]
+      #   Format: IETF BCP 47 language tag
+      #   Example: en-US
+      #   @return [String]
       class IdvClientInformation
         attr_accessor :pre_selected_residence_country, :pre_selected_language
       end

data/lib/checkout_sdk/identities/identity_verification/idv_declared_data.rb

@@ -3,12 +3,25 @@
 module CheckoutSdk
   module Identities
     module IdentityVerification
-      # The personal details provided by the applicant for an identity verification.
+      # The personal details provided by the applicant.
+      #
+      # Maps IdvDeclaredData, the shape the address document and ID document verification requests
+      # accept. The identity verification requests take the larger {IdvIdentityDeclaredData}.
       #
       # @!attribute name
-      #   @return [String] The applicant's name (max 255 characters).
+      #   The applicant's name.
+      #   [Required]
+      #   min 2 characters, max 255 characters
+      #   Example: Hannah Bret
+      #   @return [String]
+      # @!attribute birth_date
+      #   The applicant's birth date.
+      #   [Optional]
+      #   Format: yyyy-MM-dd
+      #   Example: 1994-10-15
+      #   @return [String]
       class IdvDeclaredData
-        attr_accessor :name
+        attr_accessor :name, :birth_date
       end
     end
   end

data/lib/checkout_sdk/identities/identity_verification/idv_identity_client_information.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Identities
+    module IdentityVerification
+      # The applicant's details for an identity verification attempt.
+      #
+      # Maps IdvClientInformation, a strict superset of FavClientInformation, so it inherits from
+      # {IdvClientInformation}. The face authentication attempt must keep using the parent: its
+      # schema declares neither document field, so sending them there would be a request the API
+      # rejects.
+      #
+      # @!attribute pre_selected_document_issuing_country
+      #   The country that issued the applicant's identity document.
+      #   [Optional]
+      #   Standard: ISO 3166-1 alpha-2 country code
+      #   ^[A-Z]{2}
+      #   Example: FR
+      #   @return [String] a value of {CheckoutSdk::Common::Country}
+      # @!attribute pre_selected_document_type
+      #   The type of identity document the applicant uses for the attempt.
+      #   [Optional]
+      #   Enum: "Driving licence" "ID" "Other" "Passport" "Residence Permit" "Travel Document" "Visa"
+      #   @return [String]
+      class IdvIdentityClientInformation < IdvClientInformation
+        attr_accessor :pre_selected_document_issuing_country, :pre_selected_document_type
+      end
+    end
+  end
+end

data/lib/checkout_sdk/identities/identity_verification/idv_identity_declared_data.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Identities
+    module IdentityVerification
+      # The personal details provided by the applicant for an identity verification.
+      #
+      # Maps IdvIdentityDeclaredData, a strict superset of IdvDeclaredData, so it inherits from it.
+      # The address document and ID document verification requests take the smaller
+      # {IdvDeclaredData} shape instead: sending these three extra fields there would be a request
+      # the API rejects.
+      #
+      # @!attribute phone_number
+      #   The applicant's mobile phone number, if sharing the attempt URL via SMS.
+      #   [Optional]
+      #   @return [CheckoutSdk::Identities::IdvPhoneNumber]
+      # @!attribute email
+      #   The applicant's email address. Explicitly nullable in the spec, so the API may return
+      #   null for it rather than omitting it.
+      #   [Optional]
+      #   Format: email
+      #   Nullable: true
+      #   Example: hannah.bret@example.com
+      #   @return [String]
+      # @!attribute address
+      #   The applicant's address.
+      #   [Optional]
+      #   @return [CheckoutSdk::Identities::IdvAddress]
+      class IdvIdentityDeclaredData < IdvDeclaredData
+        attr_accessor :phone_number, :email, :address
+      end
+    end
+  end
+end