Feature/INT-1702 - Airline and accommodation sub-tree model alignment

lib/Checkout/Payments/AccommodationAddress.php

@@ -2,6 +2,9 @@
 
 namespace Checkout\Payments;
 
+/**
+ * The address details of the accommodation.
+ */
 class AccommodationAddress
 {
     /**

lib/Checkout/Payments/AccommodationData.php

@@ -5,6 +5,9 @@
 use DateTime;
 use Checkout\Common\DateOnly;
 
+/**
+ * Contains information about the accommodation booked by the customer.
+ */
 class AccommodationData
 {
     /**
@@ -67,13 +70,31 @@
 
     /**
      * The list of guests staying at the accommodation.
-     * @var array of AccommodationGuest
+     * @var AccommodationGuest[]
      */
     public $guests;
 
     /**
      * The room details and rates.
-     * @var array of AccommodationRoom
+     * [Optional]
+     *
+     * @var AccommodationRoom[]
      */
     public $room;
+
+    /**
+     * The property's phone information.
+     * [Optional]
+     *
+     * @var AccommodationPhone[]
+     */
+    public $property_phone;
+
+    /**
+     * The customer service phone information.
+     * [Optional]
+     *
+     * @var AccommodationPhone[]
+     */
+    public $customer_service_phone;
 }

lib/Checkout/Payments/AccommodationGuest.php

@@ -5,6 +5,9 @@
 use DateTime;
 use Checkout\Common\DateOnly;
 
+/**
+ * Contains information about a guest staying at the accommodation.
+ */
 class AccommodationGuest
 {
     /**

lib/Checkout/Payments/AccommodationPhone.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace Checkout\Payments;
+
+/**
+ * Phone contact information for an accommodation property.
+ */
+class AccommodationPhone
+{
+    /**
+     * The phone country code.
+     * [Optional]
+     *
+     * @var string
+     */
+    public $country_code;
+
+    /**
+     * The phone number.
+     * [Optional]
+     *
+     * @var string
+     */
+    public $number;
+}

lib/Checkout/Payments/AccommodationRoom.php

@@ -2,6 +2,9 @@
 
 namespace Checkout\Payments;
 
+/**
+ * Contains information about a room booked by the customer.
+ */
 class AccommodationRoom
 {
     /**

lib/Checkout/Payments/AirlineData.php

@@ -2,20 +2,50 @@
 
 namespace Checkout\Payments;
 
+/**
+ * Contains information about the airline ticket and flights booked by the customer.
+ */
 class AirlineData
 {
     /**
+     * Contains information about the airline ticket.
+     * [Optional]
+     *
      * @var Ticket
      */
     public $ticket;
 
     /**
-     * @var array of Passenger
+     * Contains information about the passenger(s) on the flight.
+     * [Optional]
+     *
+     * Assign a single Passenger for one passenger, not a one-element array. Verified against the
+     * sandbox on 2026-09-25 with a complete airline_data block:
+     *
+     *   surface                  passenger: object   passenger: array
+     *   POST /payments           201                 201
+     *   POST /hosted-payments    accepted            422 processing_airline_data_0_passenger_invalid
+     *   POST /payment-links      accepted            422 processing_airline_data_0_passenger_invalid
+     *   POST /payment-contexts   201                 422 passenger_required
+     *
+     * A single object is accepted on every request surface; an array only on POST /payments.
+     * The specification declares the opposite, and ProcessingSettings is shared by POST /payments,
+     * hosted payments and payment links, so an array is not a safe default. An empty array and a
+     * null are both rejected, so leave the property unset when there are no passengers: the
+     * serializer omits nulls.
+     *
+     * Several passengers can only be expressed as an array, which only POST /payments accepts.
+     * That is an API limitation, not an SDK choice. Recorded in the plan under P1.
+     *
+     * @var Passenger|Passenger[]
      */
     public $passenger;
 
     /**
-     * @var array of FlightLegDetails
+     * Contains information about the flight leg(s) booked by the customer.
+     * [Optional]
+     *
+     * @var FlightLegDetails[]
      */
     public $flight_leg_details;
 }

lib/Checkout/Payments/Contexts/PaymentContextsAirlineData.php

@@ -2,20 +2,46 @@
 
 namespace Checkout\Payments\Contexts;
 
+/**
+ * Contains information about the airline ticket and flights booked by the customer.
+ */
 class PaymentContextsAirlineData
 {
     /**
-     * @var array of Checkout\Payments\Contexts\PaymentContextsTicket
+     * Contains information about the airline ticket.
+     * [Optional]
+     *
+     * The specification declares this as a single object. It was previously named $tickets and
+     * documented as an array, so the SDK sent an array under the key "tickets", which the API
+     * does not define: the value never reached the gateway.
+     *
+     * @var PaymentContextsTicket
      */
-    public $tickets;
+    public $ticket;
 
     /**
-     * @var array of Checkout\Payments\Contexts\PaymentContextsPassenger
+     * Contains information about the passenger(s) on the flight.
+     * [Optional]
+     *
+     * It was previously named $passengers, so the SDK sent the key "passengers", which the API
+     * does not define: the value never reached the gateway.
+     *
+     * Assign a single PaymentContextsPassenger, not an array. Verified against the sandbox on
+     * 2026-09-25: POST /payment-contexts rejects the array form with 422 passenger_required and
+     * accepts a single object. A single object is accepted on every request surface, while an
+     * array is accepted only on POST /payments. This is the opposite of what the specification
+     * declares, and is recorded in the plan under P1. An array of two or more is the only way to
+     * express several passengers, and only POST /payments accepts it.
+     *
+     * @var PaymentContextsPassenger|PaymentContextsPassenger[]
      */
-    public $passengers;
+    public $passenger;
 
     /**
-     * @var array of Checkout\Payments\Contexts\PaymentContextsFlightLegDetails
+     * Contains information about the flight leg(s) booked by the customer.
+     * [Optional]
+     *
+     * @var PaymentContextsFlightLegDetails[]
      */
     public $flight_leg_details;
 }

lib/Checkout/Payments/Contexts/PaymentContextsFlightLegDetails.php

@@ -4,6 +4,9 @@
 
 use Checkout\Common\DateOnly;
 
+/**
+ * Contains information about a flight leg booked by the customer.
+ */
 class PaymentContextsFlightLegDetails
 {
     /**

lib/Checkout/Payments/Contexts/PaymentContextsPartnerCustomerRiskData.php

@@ -2,6 +2,14 @@
 
 namespace Checkout\Payments\Contexts;
 
+/**
+ * A key-and-value pair with merchant-specific data for the transaction.
+ *
+ * @deprecated Duplicates Checkout\Payments\PartnerCustomerRiskData, which maps the same
+ * specification shape and is what PaymentContextsProcessing now uses. Maintaining two identical
+ * classes for one schema invited drift. Retained for backwards compatibility and will be removed
+ * in a future version.
+ */
 class PaymentContextsPartnerCustomerRiskData
 {
     /**

lib/Checkout/Payments/Contexts/PaymentContextsPassenger.php

@@ -5,6 +5,9 @@
 use Checkout\Common\Address;
 use Checkout\Common\DateOnly;
 
+/**
+ * Contains information about a passenger on the flight.
+ */
 class PaymentContextsPassenger
 {
     /**

lib/Checkout/Payments/Contexts/PaymentContextsProcessing.php

@@ -2,50 +2,138 @@
 
 namespace Checkout\Payments\Contexts;
 
+use Checkout\Payments\AccommodationData;
+use Checkout\Payments\BillingPlan;
+use Checkout\Payments\PartnerCustomerRiskData;
+
+/**
+ * Settings that control how the payment context is processed.
+ */
 class PaymentContextsProcessing
 {
     /**
-     * @var string value of BillingPlan
+     * The plan details for a recurring payment with PayPal.
+     * Required when payment_type is recurring.
+     * [Optional]
+     *
+     * Previously named $billing_plan, so the SDK sent the key "billing_plan"; the specification
+     * declares this property as "plan", so the value never reached the gateway.
+     *
+     * @var BillingPlan
+     */
+    public $plan;
+
+    /**
+     * The discount amount the merchant applied to the transaction.
+     * [Optional]
+     * minimum 0
+     *
+     * @var float
      */
-    public $billing_plan;
+    public $discount_amount;
 
     /**
-     * @var int
+     * The total freight or shipping and handling charges for the transaction.
+     * [Optional]
+     *
+     * @var float
      */
     public $shipping_amount;
 
     /**
+     * The total tax amount for the transaction, in the minor currency unit.
+     * [Optional]
+     *
+     * @var float
+     */
+    public $tax_amount;
+
+    /**
+     * Invoice ID number.
+     * [Optional]
+     *
      * @var string
      */
     public $invoice_id;
 
     /**
+     * The label that overrides the business name in the PayPal account on the PayPal pages.
+     * [Optional]
+     *
      * @var string
      */
     public $brand_name;
 
     /**
+     * The language and region of the customer in ISO 639-2 language code; the value consists of
+     * language-country.
+     * [Optional]
+     *
      * @var string
      */
     public $locale;
 
     /**
+     * Shipping preference.
+     * [Optional]
+     * One of: no_shipping, set_provided_address, get_from_file
+     *
      * @var string value of ShippingPreference
      */
     public $shipping_preference;
 
     /**
+     * Property required by PayPal to have an appropriate payment flow.
+     * [Optional]
+     * One of: pay_now, continue
+     *
      * @var string value of UserAction
      */
     public $user_action;
 
     /**
-     * @var array of PaymentContextsPartnerCustomerRiskData
+     * Key-and-value pairs with merchant-specific data for the transaction.
+     * [Optional]
+     *
+     * Uses the shared Checkout\Payments\PartnerCustomerRiskData: payment contexts and the
+     * payments request schemas resolve partner_customer_risk_data to the same specification
+     * shape, and maintaining two identical classes for it invited drift.
+     *
+     * A single object, not a collection. The specification declares it as one object with
+     * `key` and `value`, even though its description calls it "an array of key-and-value
+     * pairs". The sandbox accepts both shapes; this follows the declared one, which Java,
+     * .NET, Go and Ruby also use.
+     *
+     * @var PartnerCustomerRiskData
      */
     public $partner_customer_risk_data;
 
     /**
-     * @var array of PaymentContextsAirlineData
+     * Promo codes. They define which of the configured payment options within a payment category
+     * (pay_later, pay_over_time, and so on) are shown for this purchase.
+     * [Optional]
+     *
+     * @var string[]
+     */
+    public $custom_payment_method_ids;
+
+    /**
+     * Contains information about the airline ticket and flights booked by the customer.
+     * [Optional]
+     *
+     * @var PaymentContextsAirlineData[]
      */
     public $airline_data;
+
+    /**
+     * Contains information about the accommodation booked by the customer.
+     * [Optional]
+     *
+     * Uses the shared AccommodationData: payment contexts, POST /payments and the
+     * GET /payments/{id} response all resolve accommodation_data to the same specification
+     * schema.
+     *
+     * @var AccommodationData[]
+     */
+    public $accommodation_data;
 }

lib/Checkout/Payments/Contexts/PaymentContextsTicket.php

@@ -4,6 +4,9 @@
 
 use Checkout\Common\DateOnly;
 
+/**
+ * Contains information about the airline ticket.
+ */
 class PaymentContextsTicket
 {
     /**