checkout_sdk 2.3.0 → 2.5.0

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,

data/lib/checkout_sdk/payments/flight_leg_details.rb

@@ -2,33 +2,59 @@
 
 module CheckoutSdk
   module Payments
+    # Contains information about a flight leg booked by the customer.
+    #
+    # Maps the inline `flight_leg_details` item on the swagger `AirlineData` and
+    # `PaymentInterfacesProcessingAirlineData` schemas, and `PaymentSetupFlightLegDetails` for
+    # payment setups. All three declare the same nine properties with the same spelling, which is
+    # why one class serves the payments and the setups paths.
+    #
     # @!attribute flight_number
-    #   @return [Integer]
+    #   @return [String] The flight number.
+    #     [Optional]
+    #     Example: "101"
     # @!attribute carrier_code
-    #   @return [String]
-    # @!attribute service_class
-    #   @return [String]
+    #   @return [String] The IATA carrier code.
+    #     [Optional]
+    #     Example: "BA"
+    # @!attribute class_of_travelling
+    #   @return [String] The fare class of the leg.
+    #     [Optional]
+    #     Example: "J"
     # @!attribute departure_date
-    #   @return [String]
+    #   @return [String] The date the flight departs.
+    #     [Optional]
+    #     Format: date (YYYY-MM-DD)
+    #     Example: "2023-06-19"
     # @!attribute departure_time
-    #   @return [String]
+    #   @return [String] The local time the flight departs.
+    #     [Optional]
+    #     Example: "15:30"
     # @!attribute departure_airport
-    #   @return [String]
+    #   @return [String] The IATA code of the departure airport.
+    #     [Optional]
+    #     Example: "LHR"
     # @!attribute arrival_airport
-    #   @return [String]
-    # @!attribute stopover_code
-    #   @return [String]
+    #   @return [String] The IATA code of the arrival airport.
+    #     [Optional]
+    #     Example: "LAX"
+    # @!attribute stop_over_code
+    #   @return [String] Whether a stopover is permitted on the leg.
+    #     [Optional]
+    #     Example: "x"
     # @!attribute fare_basis_code
-    #   @return [String]
+    #   @return [String] The fare basis code for the leg.
+    #     [Optional]
+    #     Example: "SPRSVR"
     class FlightLegDetails
       attr_accessor :flight_number,
                     :carrier_code,
-                    :service_class,
+                    :class_of_travelling,
                     :departure_date,
                     :departure_time,
                     :departure_airport,
                     :arrival_airport,
-                    :stopover_code,
+                    :stop_over_code,
                     :fare_basis_code
     end
   end

data/lib/checkout_sdk/payments/pan_processed_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The preferred type of Primary Account Number (PAN) for the payment.
+    #
+    # Named after the .NET `PanProcessedType` enum, which maps the same property.
+    module PanProcessedType
+      # Indicates a preference for using the full card number.
+      FPAN = 'fpan'
+      # Indicates a preference for using the Checkout.com Network Token.
+      DPAN = 'dpan'
+    end
+  end
+end

data/lib/checkout_sdk/payments/partner_customer_risk_data.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # A key-and-value pair with merchant-specific data for the transaction.
+    #
+    # The specification describes `partner_customer_risk_data` as "an array of key-and-value
+    # pairs" but declares it as a single inline object with `key` and `value`. The description and
+    # the declared type disagree; this class models the declared shape, which is what the gateway
+    # validates against.
+    #
+    # @!attribute key
+    #   @return [String] The key for the pair.
+    #     [Optional]
+    # @!attribute value
+    #   @return [String] The value for the pair.
+    #     [Optional]
+    class PartnerCustomerRiskData
+      attr_accessor :key,
+                    :value
+    end
+  end
+end

data/lib/checkout_sdk/payments/passenger.rb

@@ -2,17 +2,29 @@
 
 module CheckoutSdk
   module Payments
-    # Contains information about a passenger on the flight
-    # (PaymentInterfacesProcessingAirlinePassengerData).
+    # Contains information about a passenger on the flight.
+    #
+    # Maps the inline `passenger` item on the swagger `AirlineData` and
+    # `PaymentInterfacesProcessingAirlineData` schemas. See {AirlineData#passenger} for the
+    # cardinality rule: a single object is accepted on every request surface, an array only on
+    # POST /payments.
     #
     # @!attribute first_name
-    #   @return [String]
+    #   @return [String] The passenger's first name.
+    #     [Optional]
+    #     Example: "John"
     # @!attribute last_name
-    #   @return [String]
+    #   @return [String] The passenger's last name.
+    #     [Optional]
+    #     Example: "White"
     # @!attribute date_of_birth
-    #   @return [String] Format: YYYY-MM-DD
+    #   @return [String] The passenger's date of birth.
+    #     [Optional]
+    #     Format: date (YYYY-MM-DD)
+    #     Example: "1990-05-26"
     # @!attribute address
-    #   @return [PassengerAddress]
+    #   @return [PassengerAddress] Contains information about the passenger's address.
+    #     [Optional]
     class Passenger
       attr_accessor :first_name,
                     :last_name,
@@ -22,8 +34,13 @@ module CheckoutSdk
 
     # Partial address information for an airline passenger.
     #
+    # The specification declares exactly one property here, so this is deliberately not the wide
+    # {CheckoutSdk::Common::Address}.
+    #
     # @!attribute country
-    #   @return [String] {CheckoutSdk::Common::Country}
+    #   @return [String] The two-letter ISO country code of the passenger's country residence.
+    #     [Optional]
+    #     Example: "US"
     class PassengerAddress
       attr_accessor :country
     end

data/lib/checkout_sdk/payments/payments.rb

@@ -26,6 +26,13 @@ require 'checkout_sdk/payments/capture_type'
 require 'checkout_sdk/payments/payment_type'
 require 'checkout_sdk/payments/merchant_initiated_reason'
 require 'checkout_sdk/payments/preferred_schema'
+require 'checkout_sdk/payments/ticket'
+require 'checkout_sdk/payments/accommodation_data'
+require 'checkout_sdk/payments/aggregator'
+require 'checkout_sdk/payments/partner_customer_risk_data'
+require 'checkout_sdk/payments/pan_processed_type'
+require 'checkout_sdk/payments/ach_service_type'
+require 'checkout_sdk/payments/processing_card_type'
 require 'checkout_sdk/payments/airline_data'
 require 'checkout_sdk/payments/risk_request'
 require 'checkout_sdk/payments/billing_descriptor'
@@ -126,7 +133,6 @@ require 'checkout_sdk/payments/sender/government_sender'
 require 'checkout_sdk/payments/sender/individual_sender'
 require 'checkout_sdk/payments/sender/corporate_sender'
 require 'checkout_sdk/payments/sender/instrument_sender'
-require 'checkout_sdk/payments/sender/ticket'
 require 'checkout_sdk/payments/sender/sender_information'
 
 # Destination

data/lib/checkout_sdk/payments/processing_card_type.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Whether to process the payment as a credit or debit transaction, when a combo card is used.
+    #
+    # Deliberately NOT named `CardType`. The specification's values here are lowercase
+    # `credit` and `debit`, while every generic card-type enum across the SDK family uses
+    # `Credit`/`Debit` or `CREDIT`/`DEBIT`. .NET types this property as its generic `CardType`,
+    # whose values are `Credit` and `Debit`, so it sends the wrong casing. Go avoided that by
+    # adding a dedicated `ProcessingCardType`; this follows Go.
+    module ProcessingCardType
+      CREDIT = 'credit'
+      DEBIT = 'debit'
+    end
+  end
+end

data/lib/checkout_sdk/payments/processing_data.rb

@@ -34,7 +34,7 @@ module CheckoutSdk
     # @!attribute partner_transaction_id
     #   @return [String] [Optional] Unique transaction identification provided by partner.
     # @!attribute partner_error_codes
-    #   @return [Array<String>] [Optional] The list of error codes that led the payment to fail or
+    #   @return [Array(String)] [Optional] The list of error codes that led the payment to fail or
     #     be declined, as given by the payment provider.
     # @!attribute partner_error_message
     #   @return [String] [Optional] Error description provided by partner.
@@ -51,7 +51,7 @@ module CheckoutSdk
     #     additional information about the transaction. For declined transactions it also
     #     indicates whether the payment can be retried and how long to wait.
     # @!attribute custom_payment_method_ids
-    #   @return [Array<String>] [Optional] An array defining which of the configured payment
+    #   @return [Array(String)] [Optional] An array defining which of the configured payment
     #     options within a payment category (for example, pay_later or pay_over_time) should be
     #     displayed for this purchase.
     # @!attribute aft
@@ -84,10 +84,10 @@ module CheckoutSdk
     #     differ from the card's scheme used for the payment if the card is co-badged and the
     #     payment was authorized on a different network. Read-only.
     # @!attribute accommodation_data
-    #   @return [Array<AccommodationData>] [Optional] Contains information about the accommodation
+    #   @return [Array(AccommodationData)] [Optional] Contains information about the accommodation
     #     booked by the customer.
     # @!attribute airline_data
-    #   @return [Array<AirlineData>] [Optional] Contains information about the airline ticket and
+    #   @return [Array(AirlineData)] [Optional] Contains information about the airline ticket and
     #     flights booked by the customer.
     # @!attribute scheme_transaction_link_id
     #   @return [String] [Optional] The scheme transaction link identifier. Returned for