checkout_sdk 2.4.0 → 2.6.0

data/lib/checkout_sdk/accounts/representative.rb

@@ -2,32 +2,93 @@
 
 module CheckoutSdk
   module Accounts
+    # A representative of the sub-entity. One class covers every shape the Accounts API defines: the v3.0
+    # person of interest (individual, roles, company_position, ownership_percentage, documents), the v3.0
+    # controlling company of EEA and GB Company Full (company, ownership_percentage), and the v2.0 company
+    # representative (the flat person fields, roles, documents and, on the US variants, identification).
     # @!attribute id
+    #   The representative's id.
+    #   [Optional]
+    #   ^rep_[a-z0-9]{26}$
+    #   30 characters
     #   @return [String]
     # @!attribute individual
+    #   Information about the individual representing the sub-entity.
+    #   [Required] for every v3.0 person of interest.
     #   @return [RepresentativeIndividual] Personal details (Accounts API v3.0).
     # @!attribute company_position
+    #   The position of the representative within the company (required for the control_person role).
+    #   [Optional] (EEA, GB and US Company Full (3.0) and US ISV Seller Company (3.0))
     #   @return [String] {CompanyPosition}
     # @!attribute ownership_percentage
+    #   The percentage ownership of the UBO or controlling company (required when over 25%).
+    #   [Optional]
+    #   min 25, max 100 on the EEA, GB and US Company Full (3.0) variants; min 0, max 100 on the US ISV
+    #   Seller variants
     #   @return [Integer]
+    # @!attribute roles
+    #   The individual's roles within the company ({EntityRoles} values). For sole traders, must be ubo only.
+    #   [Required] for every variant except EEA and US Company Lite (2.0), where it is [Optional].
+    #   @return [Array(String)] {EntityRoles}
+    # @!attribute documents
+    #   Verification documents for the individual representative. On the EEA, GB and US Company Full (3.0)
+    #   and Sole Trader Full (3.0) variants the API validates this object strictly and rejects any key the
+    #   variant does not define; the US ISV Seller (3.0) and v2.0 variants do not declare it strict. See
+    #   {RepresentativeDocuments} for the keys each variant accepts.
+    #   [Required] for the EEA, GB and US Sole Trader Full (3.0) variants and EEA Company Full (2.0);
+    #   [Optional] otherwise.
+    #   @return [RepresentativeDocuments]
+    # @!attribute company
+    #   The controlling company, when the representative is a company rather than an individual.
+    #   [Required] for a controlling company representative (EEA and GB Company Full (3.0) only).
+    #   The API reads only three attributes here, all [Required]: legal_name, trading_name and
+    #   registered_address. Leave the other {Company} attributes unset.
+    #   @return [Company]
     # @!attribute first_name
+    #   The representative's first name. Accounts API v2.0 only.
+    #   [Required] (v2.0)
+    #   min 2 characters, max 50 characters
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
+    #   @return [String]
+    # @!attribute middle_name
+    #   The representative's middle name. Required if it appears in official documents. Accounts API v2.0
+    #   only.
+    #   [Optional]
+    #   min 2 characters, max 50 characters
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [String]
     # @!attribute last_name
+    #   The representative's last name. Accounts API v2.0 only.
+    #   [Required] (v2.0)
+    #   min 2 characters, max 50 characters
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [String]
     # @!attribute address
+    #   The representative's address. Accounts API v2.0 only.
+    #   [Required] (v2.0)
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [CheckoutSdk::Common::Address]
     # @!attribute identification
+    #   The representative's identification. Accounts API v2.0 US Company variants only.
+    #   [Required] for US Company Full (2.0); [Optional] for US Company Lite (2.0).
+    #   @deprecated Not used by the Accounts API v3.0 schema.
     #   @return [Identification]
     # @!attribute phone
+    #   The representative's phone number. Accounts API v2.0 only.
+    #   [Optional]
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [Phone]
     # @!attribute date_of_birth
+    #   The date of birth of the person according to the Gregorian calendar. Accounts API v2.0 only.
+    #   [Required] for the v2.0 Full variants; [Optional] for the v2.0 Lite variants.
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [DateOfBirth]
     # @!attribute place_of_birth
+    #   The place of birth of the person. Accounts API v2.0 only.
+    #   [Required] for EEA Company Full (2.0); [Optional] for EEA Company Lite (2.0). Not part of the other
+    #   v2.0 variants.
+    #   @deprecated Not used by the Accounts API v3.0 schema; use individual.
     #   @return [PlaceOfBirth]
-    # @!attribute roles
-    #   @return [Array(String)]
-    # @!attribute documents
-    #   @return [OnboardSubEntityDocuments]
     class Representative
       attr_accessor :id,
                     :individual,
@@ -35,8 +96,10 @@ module CheckoutSdk
                     :ownership_percentage,
                     :roles,
                     :documents,
+                    :company,
                     # v2.0 only — deprecated; use `individual` for v3.0
                     :first_name,
+                    :middle_name,
                     :last_name,
                     :address,
                     :identification,

data/lib/checkout_sdk/accounts/representative_documents.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Verification documents for an individual representative, sent as company.representatives[].documents.
+    #
+    # On the EEA, GB and US Company Full (3.0) and the EEA, GB and US Sole Trader Full (3.0) variants the
+    # API validates this object strictly: a key it does not recognise is rejected, not ignored. The US ISV
+    # Seller variants (3.0) and the v2.0 variants do not declare it strict. These four are the only keys
+    # any variant defines, and which apply depends on the variant: EEA Sole Trader Full (3.0) requires
+    # identity_verification, proof_of_residential_address and proof_of_registration; GB and US Sole Trader
+    # Full (3.0) require identity_verification; the EEA, GB and US Company Full (3.0) variants and US ISV
+    # Seller Company (3.0) accept identity_verification and certified_authorised_signatory, both optional;
+    # US ISV Seller Sole Trader (3.0) accepts identity_verification, optional. The v2.0 company
+    # representatives use identity_verification only.
+    #
+    # Leave an attribute unset rather than assigning nil: an attribute set to nil is sent as null.
+    # Company-level documents such as bank_verification belong on {OnboardSubEntityDocuments}.
+    # @!attribute identity_verification
+    #   The document to use to confirm the individual's identity.
+    #   [Optional] (required for the sole trader full variants)
+    #   @return [Document]
+    # @!attribute certified_authorised_signatory
+    #   Certified authorised signatory document. Required when the legal representative or other role
+    #   owner is not registered on the certificate of incorporation.
+    #   [Optional] (EEA, GB and US Company Full (3.0) and US ISV Seller Company (3.0) only)
+    #   @return [CertifiedAuthorisedSignatory]
+    # @!attribute proof_of_residential_address
+    #   Proof of residential address of the representative.
+    #   [Optional] (required for EEA Sole Trader Full (3.0), and only valid there)
+    #   @return [ProofOfResidentialAddress]
+    # @!attribute proof_of_registration
+    #   Proof of the sole trader's registration, for example an extract from a trade register.
+    #   [Optional] (required for EEA Sole Trader Full (3.0), and only valid there)
+    #   @return [ProofOfRegistration]
+    class RepresentativeDocuments
+      attr_accessor :identity_verification,
+                    :certified_authorised_signatory,
+                    :proof_of_residential_address,
+                    :proof_of_registration
+    end
+  end
+end

data/lib/checkout_sdk/accounts/representative_individual.rb

@@ -2,29 +2,62 @@
 
 module CheckoutSdk
   module Accounts
-    # The personal details of a company representative ("person of interest"), as required by the
-    # Accounts API v3.0 schema.
+    # The personal details of a company representative (company.representatives[].individual), Accounts
+    # API v3.0.
     # @!attribute first_name
+    #   The representative's first name.
+    #   [Required]
+    #   min 2 characters, max 50 characters
     #   @return [String]
     # @!attribute middle_name
+    #   The representative's middle name. Required if it appears in official documents.
+    #   [Optional]
+    #   min 2 characters, max 50 characters
     #   @return [String]
     # @!attribute last_name
+    #   The representative's last name.
+    #   [Required]
+    #   min 2 characters, max 50 characters
     #   @return [String]
     # @!attribute date_of_birth
+    #   The date of birth of the person according to the Gregorian calendar.
+    #   [Required]
     #   @return [DateOfBirth]
     # @!attribute place_of_birth
+    #   The place of birth of the person.
+    #   [Required]
     #   @return [PlaceOfBirth]
     # @!attribute citizenships
+    #   The list of citizenships or legal statuses for the representative.
+    #   [Required] for the US ISV Seller variants only; not part of the other v3.0 schemas, leave unset for
+    #   them.
     #   @return [Array(Citizenship)]
     # @!attribute national_id_type
+    #   The classification of the national identification number provided.
+    #   [Required] for the US ISV Seller variants only; not part of the other v3.0 schemas, leave unset for
+    #   them.
     #   @return [String] {NationalIdType}
     # @!attribute national_id_number
+    #   The representative's national identification number.
+    #   [Required] for the US ISV Seller variants; [Optional] for the other v3.0 variants.
+    #   The format depends on the variant:
+    #     US ISV Seller: the number for the national_id_type given. ^[a-zA-Z0-9\-]+$, min 5 characters, max
+    #     16 characters.
+    #     Other v3.0 variants: a Social Security Number (SSN) or Individual Taxpayer Identification Number
+    #     (ITIN), US residents only. ^\d{9}$, 9 characters.
     #   @return [String]
     # @!attribute email_address
+    #   The representative's personal email address.
+    #   [Required] for the US ISV Seller variants; [Optional] for the other v3.0 variants.
+    #   Format: email
     #   @return [String]
     # @!attribute phone
+    #   The representative's phone number.
+    #   [Required] for the US ISV Seller variants; [Optional] for the other v3.0 variants.
     #   @return [Phone]
     # @!attribute address
+    #   The representative's address.
+    #   [Required]
     #   @return [CheckoutSdk::Common::Address]
     class RepresentativeIndividual
       attr_accessor :first_name,

data/lib/checkout_sdk/accounts/shareholder_structure.rb

@@ -2,9 +2,17 @@
 
 module CheckoutSdk
   module Accounts
+    # Shareholder structure chart (including % of shares) certified by a competent authority individual and
+    # dated within the last 3 months.
     # @!attribute type
-    #   @return [ShareholderStructureType]
+    #   The type of document.
+    #   [Required]
+    #   @return [String] {ShareholderStructureType}
     # @!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 ShareholderStructure
       attr_accessor :type,

data/lib/checkout_sdk/accounts/shareholder_structure_type.rb

@@ -2,6 +2,7 @@
 
 module CheckoutSdk
   module Accounts
+    # The document type accepted as a certified shareholder structure.
     module ShareholderStructureType
       CERTIFIED_SHAREHOLDER_STRUCTURE = 'certified_shareholder_structure'
     end

data/lib/checkout_sdk/accounts/submitter.rb

@@ -2,10 +2,11 @@
 
 module CheckoutSdk
   module Accounts
-    # Captures evidence of the end-user's consent to onboarding.
-    #
+    # Not defined by any Accounts API onboarding schema.
+    # @deprecated Not part of any Accounts API onboarding schema; the API does not read it.
     # @!attribute ip_address
-    #   @return [String] IP address of the end-user submitting the onboarding request.
+    #   @deprecated Not defined by any Accounts API onboarding schema.
+    #   @return [String]
     class Submitter
       attr_accessor :ip_address
     end

data/lib/checkout_sdk/accounts/tax_verification.rb

@@ -2,9 +2,17 @@
 
 module CheckoutSdk
   module Accounts
+    # IRS-issued Employer Identification Number document used to verify the entity's tax identification
+    # (US variants).
     # @!attribute type
+    #   The type of IRS-issued document used for tax verification.
+    #   [Required]
     #   @return [String] {TaxVerificationType}
     # @!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 TaxVerification
       attr_accessor :type,

data/lib/checkout_sdk/accounts/tax_verification_type.rb

@@ -2,6 +2,7 @@
 
 module CheckoutSdk
   module Accounts
+    # The document type accepted as tax verification: an IRS-issued Employer Identification Number letter.
     module TaxVerificationType
       EIN_LETTER = 'ein_letter'
     end

data/lib/checkout_sdk/accounts/update_payment_instrument_request.rb

@@ -2,12 +2,24 @@
 
 module CheckoutSdk
   module Accounts
+    # Request for PATCH /accounts/entities/{entityId}/payment-instruments/{id}
+    # (PlatformsPaymentInstrumentUpdate).
     # @!attribute label
+    #   A reference that you can use to identify the payment instrument.
+    #   [Optional]
+    #   min 1 character, max 50 characters
     #   @return [String]
     # @!attribute default
+    #   Deprecated by the API: for scheduled payouts the first payment instrument created for a currency
+    #   is used; to change it, update the payout schedule.
+    #   [Optional]
     #   @return [TrueClass, FalseClass]
     # @!attribute headers
-    #   @return [Headers]
+    #   The payment instrument ETag, as returned in the ETag header of the GET, in headers.if_match.
+    #   {AccountsClient#update_payment_instrument} sends it as the If-Match HTTP header; the API
+    #   answers 428 without it and 412 when it does not match.
+    #   [Required] by the API.
+    #   @return [CheckoutSdk::Common::Headers]
     class UpdatePaymentInstrumentRequest
       attr_accessor :label,
                     :default,

data/lib/checkout_sdk/issuing/issuing_client.rb

@@ -93,7 +93,10 @@ module CheckoutSdk
       # @param [CardUpdateHeaders, nil] headers the optional return-encrypted-cvv and
       #   Encryption-Key HTTP headers. Setting return_encrypted_cvv without encryption_key returns
       #   a 422 with error code encryption_key_required.
-      # @return [OpenStruct] the update response, carrying encrypted_cvv when requested
+      # @return [OpenStruct] the update response, carrying encrypted_cvv when requested. For a
+      #   virtual card the response may also carry is_single_use (boolean, default false),
+      #   specifying whether the card is set to expire after a single use. Physical cards never
+      #   send it.
       def update_card(card_id, update_card_request, headers = nil)
         api_client.invoke_patch(
           build_path(ISSUING, CARDS, card_id),

data/lib/checkout_sdk/issuing/update_card_request.rb

@@ -39,14 +39,21 @@ module CheckoutSdk
     #   Example: 2026-06-01T10:00Z
     #   @return [String]
     # @!attribute revocation_date
-    #   Date scheduling the card's automatic revocation.
-    #   [Optional]
-    #   Format: yyyy-MM-dd (time is midnight UTC)
-    #   Example: 2027-03-12
-    #   @return [String]
+    #   @return [String] Date for the card to be automatically revoked, in the form `yyyy-mm-dd`.
+    #     Must be after the current date. Maps swagger `IssuingRevocationDate`.
+    #   @deprecated Use {#scheduled_revocation_date} instead.
+    # @!attribute scheduled_revocation_date
+    #   @return [String] Date for the card to be automatically revoked, in the form `yyyy-mm-dd`.
+    #     Overrides the deprecated {#revocation_date} when both are given. Maps swagger
+    #     `IssuingScheduledRevocationDate`.
+    # @!attribute status
+    #   @return [String] Set to `active` to reactivate an `inactive` or `suspended` card.
+    #     Mutually exclusive with `scheduled_activation_date`: submitting both returns a
+    #     `scheduled_activation_date_conflicts_with_activation` error. The only supported
+    #     value is `active`.
     class UpdateCardRequest
       attr_accessor :reference, :metadata, :expiry_month, :expiry_year,
-                    :scheduled_activation_date, :revocation_date
+                    :scheduled_activation_date, :revocation_date, :scheduled_revocation_date, :status
     end
   end
 end

data/lib/checkout_sdk/payments/accommodation_data.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Contains information about the accommodation booked by the customer.
+    #
+    # Maps the swagger `AccommodationData` schema, which `POST /payments`, the
+    # `GET /payments/{id}` response and `PaymentContextProcessing` all resolve to.
+    #
+    # `property_phone` and `customer_service_phone` are declared on `AccommodationData` only.
+    # The `PaymentInterfacesProcessingAccommodationData` schema used by hosted payments, payment
+    # links and payment sessions carries the other eleven properties but neither phone array, so
+    # those two are read on `POST /payments` and payment contexts and ignored elsewhere.
+    #
+    # @!attribute name
+    #   @return [String] The name of the accommodation.
+    #     [Optional]
+    #     Example: "The Sea View Hotel"
+    # @!attribute booking_reference
+    #   @return [String] The booking reference for the stay.
+    #     [Optional]
+    #     Example: "HOTEL123"
+    # @!attribute check_in_date
+    #   @return [String] The date the customer checks in.
+    #     [Optional]
+    #     Format: date (YYYY-MM-DD)
+    #     Example: "2023-06-20"
+    # @!attribute check_out_date
+    #   @return [String] The date the customer checks out.
+    #     [Optional]
+    #     Format: date (YYYY-MM-DD)
+    #     Example: "2023-06-23"
+    # @!attribute address
+    #   @return [AccommodationAddress] The address of the accommodation.
+    #     [Optional]
+    # @!attribute state
+    #   @return [String] The state or region the accommodation is in.
+    #     [Optional]
+    #     A plain string, not a country code. Example: "FL"
+    # @!attribute country
+    #   @return [String] The country the accommodation is in.
+    #     [Optional]
+    #     A plain string, not an ISO 3166-1 alpha-2 code: the specification's own example is the
+    #     three-letter "USA", which no alpha-2 enum can hold. Example: "USA"
+    # @!attribute city
+    #   @return [String] The city the accommodation is in.
+    #     [Optional]
+    #     Example: "Los Angeles"
+    # @!attribute number_of_rooms
+    #   @return [Integer] The number of rooms booked.
+    #     [Optional]
+    #     Example: 2
+    # @!attribute guests
+    #   @return [Array(AccommodationGuest)] The guests staying at the accommodation.
+    #     [Optional]
+    # @!attribute room
+    #   @return [Array(AccommodationRoom)] The rooms booked by the customer.
+    #     [Optional]
+    #     Named `room` in the singular by the specification, and it is an array.
+    # @!attribute property_phone
+    #   @return [Array(AccommodationPhone)] Phone numbers for the property.
+    #     [Optional]
+    #     Declared on `AccommodationData` only.
+    # @!attribute customer_service_phone
+    #   @return [Array(AccommodationPhone)] Customer service phone numbers for the property.
+    #     [Optional]
+    #     Declared on `AccommodationData` only.
+    class AccommodationData
+      attr_accessor :name,
+                    :booking_reference,
+                    :check_in_date,
+                    :check_out_date,
+                    :address,
+                    :state,
+                    :country,
+                    :city,
+                    :number_of_rooms,
+                    :guests,
+                    :room,
+                    :property_phone,
+                    :customer_service_phone
+    end
+
+    # Partial address information for an accommodation.
+    #
+    # The specification declares exactly these two properties, so this is deliberately not the
+    # wide {CheckoutSdk::Common::Address}.
+    #
+    # @!attribute address_line1
+    #   @return [String] The first line of the address.
+    #     [Optional]
+    #     Example: "123 Beach Road"
+    # @!attribute zip
+    #   @return [String] The postal code of the address.
+    #     [Optional]
+    #     Example: "10001"
+    class AccommodationAddress
+      attr_accessor :address_line1,
+                    :zip
+    end
+
+    # A guest staying at the accommodation.
+    #
+    # @!attribute first_name
+    #   @return [String] The guest's first name.
+    #     [Optional]
+    #     Example: "Jane"
+    # @!attribute last_name
+    #   @return [String] The guest's last name.
+    #     [Optional]
+    #     Example: "Doe"
+    # @!attribute date_of_birth
+    #   @return [String] The guest's date of birth.
+    #     [Optional]
+    #     Format: date (YYYY-MM-DD)
+    #     Example: "1985-07-14"
+    class AccommodationGuest
+      attr_accessor :first_name,
+                    :last_name,
+                    :date_of_birth
+    end
+
+    # A room booked at the accommodation.
+    #
+    # Both properties are strings in this schema. The payment setups equivalent,
+    # {PaymentSetupAccommodationRoom}, declares a numeric `rate` and an integer
+    # `number_of_nights` instead, so the two are not interchangeable.
+    #
+    # @!attribute rate
+    #   @return [String] The nightly rate for the room.
+    #     [Optional]
+    #     A string, not a number. Example: "70"
+    # @!attribute number_of_nights_at_room_rate
+    #   @return [String] The number of nights booked at that rate.
+    #     [Optional]
+    #     A string, not an integer. Example: "3"
+    class AccommodationRoom
+      attr_accessor :rate,
+                    :number_of_nights_at_room_rate
+    end
+
+    # A phone number for an accommodation property.
+    #
+    # The specification declares exactly these two properties, so this is deliberately not the
+    # wide {CheckoutSdk::Common::Phone}.
+    #
+    # @!attribute country_code
+    #   @return [String] The international dialling code.
+    #     [Optional]
+    #     Example: "44"
+    # @!attribute number
+    #   @return [String] The phone number.
+    #     [Optional]
+    #     Example: "7123456789"
+    class AccommodationPhone
+      attr_accessor :country_code,
+                    :number
+    end
+  end
+end

data/lib/checkout_sdk/payments/ach_service_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Which ACH service to use for the payment, when `source.type` is `ach`.
+    #
+    # Named after the .NET `AchServiceType` enum and the PHP doc reference, which map the same
+    # property.
+    module AchServiceType
+      SAME_DAY = 'same_day'
+      STANDARD = 'standard'
+    end
+  end
+end

data/lib/checkout_sdk/payments/aggregator.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Information about the payment aggregator.
+    #
+    # Maps the swagger `Aggregator` schema. Named after the schema, unlike .NET which calls its
+    # equivalent `ProcessingAggregator`; Ruby has no name collision here.
+    #
+    # @!attribute sub_merchant_id
+    #   @return [String] The sub-merchant ID.
+    #     [Optional]
+    #     Example: "9cf70789ba90123"
+    # @!attribute aggregator_id_visa
+    #   @return [String] The Visa identifier for the payment aggregator.
+    #     [Optional]
+    #     Example: "10012345"
+    # @!attribute aggregator_id_mc
+    #   @return [String] The Mastercard identifier for the payment aggregator.
+    #     [Optional]
+    #     Example: "00000123456"
+    class Aggregator
+      attr_accessor :sub_merchant_id,
+                    :aggregator_id_visa,
+                    :aggregator_id_mc
+    end
+  end
+end

data/lib/checkout_sdk/payments/airline_data.rb

@@ -2,12 +2,46 @@
 
 module CheckoutSdk
   module Payments
+    # Contains information about the airline ticket and flights booked by the customer.
+    #
+    # Maps the swagger `AirlineData` schema, which `POST /payments`, the `GET /payments/{id}`
+    # response and `PaymentContextProcessing` all resolve to, and the
+    # `PaymentInterfacesProcessingAirlineData` schema used by hosted payments, payment links and
+    # payment sessions. The two declare the same three properties.
+    #
     # @!attribute ticket
-    #   @return [Ticket]
+    #   @return [Ticket] Contains information about the airline ticket.
+    #     [Optional]
+    #     A single object, not a collection.
     # @!attribute passenger
-    #   @return [Passenger]
+    #   @return [Passenger, Array(Passenger)] Contains information about the passenger or
+    #     passengers on the flight.
+    #     [Optional]
+    #
+    #     Accepts either a single {Passenger} or an array of them, and the choice is not
+    #     cosmetic. Verified against the sandbox on 2026-09-25:
+    #
+    #       | Surface                  | object | array |
+    #       |--------------------------|--------|-------|
+    #       | POST /payments           | 201    | 201   |
+    #       | POST /hosted-payments    | 201    | 422   |
+    #       | POST /payment-links      | 201    | 422   |
+    #       | POST /payment-contexts   | 201    | 422   |
+    #
+    #     So assign a single {Passenger} for one passenger: that is accepted on every request
+    #     surface. Assign an array only for two or more, and only on `POST /payments`, which is
+    #     the sole surface that takes it. Leave the attribute unset when there are no passengers:
+    #     an empty array and an explicit null are both rejected with
+    #     `processing_airline_data_0_passenger_invalid`.
+    #
+    #     This inverts the specification, which declares the property array-only on `AirlineData`
+    #     and `oneOf[array, object]` on `PaymentInterfacesProcessingAirlineData`. The array branch
+    #     does not exist in practice on three of the four surfaces. Responses may carry either
+    #     shape, so read defensively.
     # @!attribute flight_leg_details
-    #   @return [Array(FlightLegDetails)]
+    #   @return [Array(FlightLegDetails)] Contains information about the flight legs booked by the
+    #     customer.
+    #     [Optional]
     class AirlineData
       attr_accessor :ticket,
                     :passenger,