From 92c07b26edf0d43a7eec1b1c8c108b0e6accd708 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Armando=20Rodr=C3=ADguez?=
 <127134616+armando-rodriguez-cko@users.noreply.github.com>
Date: Tue, 27 Oct 2026 12:00:19 +0100
Subject: [PATCH 1/4] fix(payments): load retry types and add customer_retry to
 sessions

PaymentRetryRequest was never required by the gem, misspelled
end_after_days and had no dunning or downtime. DunningRetryRequest and
DowntimeRetryRequest are added, CustomerRetry moves to Common (the
Accounts constant remains as a deprecated alias), and payment sessions
gain customer_retry while the off-spec retry attribute is deprecated.
---
 lib/checkout_sdk/common/customer_retry.rb     | 16 +++-
 .../payments/downtime_retry_request.rb        | 14 +++
 .../payments/dunning_retry_request.rb         | 22 +++++
 .../hosted/hosted_payments_session.rb         |  3 +-
 .../payments/links/payment_link.rb            |  3 +-
 lib/checkout_sdk/payments/payment_request.rb  |  2 +-
 .../payments/payment_retry_request.rb         | 20 +++-
 lib/checkout_sdk/payments/payments.rb         |  3 +
 .../sessions/payment_sessions_request.rb      |  8 ++
 .../hosted_payments_integration_spec.rb       |  2 +-
 .../retry_request_serialization_spec.rb       | 91 +++++++++++++++++++
 11 files changed, 177 insertions(+), 7 deletions(-)
 create mode 100644 lib/checkout_sdk/payments/downtime_retry_request.rb
 create mode 100644 lib/checkout_sdk/payments/dunning_retry_request.rb
 create mode 100644 spec/checkout_sdk/payments/retry_request_serialization_spec.rb

diff --git a/lib/checkout_sdk/common/customer_retry.rb b/lib/checkout_sdk/common/customer_retry.rb
index ef5f253..d1a4270 100644
--- a/lib/checkout_sdk/common/customer_retry.rb
+++ b/lib/checkout_sdk/common/customer_retry.rb
@@ -1,11 +1,23 @@
 # frozen_string_literal: true
 
 module CheckoutSdk
-  module Accounts
+  module Common
+    # Configures the parameters for customer retries. A customer retry is a payment attempt
+    # performed by the customer on the checkout page, used by hosted payments, payment links
+    # and payment sessions.
+    #
     # @!attribute max_attempts
-    #   @return [Integer]
+    #   @return [Integer] [Optional] The maximum number of customer retry attempts, excluding the
+    #     initial payment attempt. Minimum 0, maximum 5. Default 5.
+    #     Required when used in a payment sessions request.
     class CustomerRetry
       attr_accessor :max_attempts
     end
   end
+
+  module Accounts
+    # @deprecated Please use {CheckoutSdk::Common::CustomerRetry} instead. This alias will be
+    #   removed in the next major version.
+    CustomerRetry = CheckoutSdk::Common::CustomerRetry
+  end
 end
diff --git a/lib/checkout_sdk/payments/downtime_retry_request.rb b/lib/checkout_sdk/payments/downtime_retry_request.rb
new file mode 100644
index 0000000..1735c1a
--- /dev/null
+++ b/lib/checkout_sdk/payments/downtime_retry_request.rb
@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Configuration of Downtime retries.
+    #
+    # @!attribute enabled
+    #   @return [TrueClass, FalseClass] [Required] Indicates if Checkout.com retries the payment when it's declined
+    #     due to issuer or acquirer downtime.
+    class DowntimeRetryRequest
+      attr_accessor :enabled
+    end
+  end
+end
diff --git a/lib/checkout_sdk/payments/dunning_retry_request.rb b/lib/checkout_sdk/payments/dunning_retry_request.rb
new file mode 100644
index 0000000..1be7456
--- /dev/null
+++ b/lib/checkout_sdk/payments/dunning_retry_request.rb
@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Configuration of Dunning retries.
+    #
+    # @!attribute enabled
+    #   @return [TrueClass, FalseClass] [Required] Indicates if Checkout.com retries the payment when it's declined
+    #     with a supported decline code.
+    # @!attribute max_attempts
+    #   @return [Integer] [Optional] The maximum number of authorization retry attempts, excluding the initial
+    #     authorization. Minimum 1, maximum 15. Default 6.
+    # @!attribute end_after_days
+    #   @return [Integer] [Optional] The maximum number of days between the initial request and the final retry
+    #     attempt. Minimum 1, maximum 60. Default 30.
+    class DunningRetryRequest
+      attr_accessor :enabled,
+                    :max_attempts,
+                    :end_after_days
+    end
+  end
+end
diff --git a/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb b/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
index f319295..abbc61b 100644
--- a/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
+++ b/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
@@ -49,7 +49,8 @@ module Payments
     # @!attribute risk
     #   @return [RiskRequest]
     # @!attribute customer_retry
-    #   @return [PaymentRetryRequest]
+    #   @return [CheckoutSdk::Common::CustomerRetry] [Optional] Configures the parameters for customer retries
+    #     performed by the customer on the checkout page.
     # @!attribute sender
     #   @return [CheckoutSdk::Payments::Sender]
     # @!attribute metadata
diff --git a/lib/checkout_sdk/payments/links/payment_link.rb b/lib/checkout_sdk/payments/links/payment_link.rb
index 3679a28..ed4bb50 100644
--- a/lib/checkout_sdk/payments/links/payment_link.rb
+++ b/lib/checkout_sdk/payments/links/payment_link.rb
@@ -49,7 +49,8 @@ module Payments
     # @!attribute risk
     #   @return [RiskRequest]
     # @!attribute customer_retry
-    #   @return [CheckoutSdk::Common::CustomerRetry]
+    #   @return [CheckoutSdk::Common::CustomerRetry] [Optional] Configures the parameters for customer retries
+    #     performed by the customer on the checkout page.
     # @!attribute sender
     #   @return [CheckoutSdk::Payments::Sender]
     # @!attribute return_url
diff --git a/lib/checkout_sdk/payments/payment_request.rb b/lib/checkout_sdk/payments/payment_request.rb
index 9ce278b..b3a9a77 100644
--- a/lib/checkout_sdk/payments/payment_request.rb
+++ b/lib/checkout_sdk/payments/payment_request.rb
@@ -62,7 +62,7 @@ module Payments
     # @!attribute items
     #   @return [Array(Product)]
     # @!attribute retry
-    #   @return [PaymentRetryRequest]
+    #   @return [PaymentRetryRequest] [Optional] Configuration of asynchronous retries.
     # @!attribute metadata
     #   @return [Hash{String => Object}]
     # @!attribute instruction
diff --git a/lib/checkout_sdk/payments/payment_retry_request.rb b/lib/checkout_sdk/payments/payment_retry_request.rb
index b8fb06e..eb6ac59 100644
--- a/lib/checkout_sdk/payments/payment_retry_request.rb
+++ b/lib/checkout_sdk/payments/payment_retry_request.rb
@@ -2,15 +2,33 @@
 
 module CheckoutSdk
   module Payments
+    # Configuration of asynchronous retries (POST /payments).
+    #
     # @!attribute enabled
-    #   @return [TrueClass, FalseClass]
+    #   @return [TrueClass, FalseClass] [Required] Indicates whether asynchronous retries are enabled for the payment.
+    # @!attribute dunning
+    #   @return [DunningRetryRequest] [Optional] Configuration of asynchronous Dunning retries.
+    # @!attribute downtime
+    #   @return [DowntimeRetryRequest] [Optional] Configuration of asynchronous Downtime retries.
     # @!attribute max_attempts
     #   @return [Integer]
+    #   @deprecated Please use {DunningRetryRequest#max_attempts} via {#dunning} instead. This attribute
+    #     will be removed in the next major version.
     # @!attribute end_after_days
     #   @return [Integer]
+    #   @deprecated Please use {DunningRetryRequest#end_after_days} via {#dunning} instead. This attribute
+    #     will be removed in the next major version.
+    # @!attribute end_after_day
+    #   @return [Integer]
+    #   @deprecated Misspelled attribute that serialized as "end_after_day", which the API does not accept.
+    #     Please use {DunningRetryRequest#end_after_days} via {#dunning} instead. This attribute will be
+    #     removed in the next major version.
     class PaymentRetryRequest
       attr_accessor :enabled,
+                    :dunning,
+                    :downtime,
                     :max_attempts,
+                    :end_after_days,
                     :end_after_day
     end
   end
diff --git a/lib/checkout_sdk/payments/payments.rb b/lib/checkout_sdk/payments/payments.rb
index 6b7b907..021c41c 100644
--- a/lib/checkout_sdk/payments/payments.rb
+++ b/lib/checkout_sdk/payments/payments.rb
@@ -42,6 +42,9 @@
 require 'checkout_sdk/payments/exemption'
 require 'checkout_sdk/payments/three_ds_flow_type'
 require 'checkout_sdk/payments/void_request'
+require 'checkout_sdk/payments/dunning_retry_request'
+require 'checkout_sdk/payments/downtime_retry_request'
+require 'checkout_sdk/payments/payment_retry_request'
 require 'checkout_sdk/payments/payment_request'
 require 'checkout_sdk/payments/processing_settings'
 require 'checkout_sdk/payments/processing_data'
diff --git a/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb b/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
index fa1ac45..449f1f4 100644
--- a/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
+++ b/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
@@ -42,6 +42,13 @@ module Payments
     #   @return [RiskRequest]
     # @!attribute retry
     #   @return [PaymentRetryRequest]
+    #   @deprecated Not part of the payment sessions specification. Please use {#customer_retry} instead.
+    #     This attribute will be removed in the next major version.
+    # @!attribute customer_retry
+    #   @return [CheckoutSdk::Common::CustomerRetry] [Optional] Configures the parameters for customer retries
+    #     performed by the customer on the checkout page. max_attempts is the maximum number of customer retry
+    #     attempts, excluding the initial payment attempt (minimum 0, maximum 5, default 5); it is required
+    #     when customer_retry is set.
     # @!attribute display_name
     #   @return [String]
     # @!attribute success_url
@@ -90,6 +97,7 @@ class PaymentSessionsRequest
                     :amount_allocations,
                     :risk,
                     :retry,
+                    :customer_retry,
                     :display_name,
                     :success_url,
                     :failure_url,
diff --git a/spec/checkout_sdk/payments/hosted/hosted_payments_integration_spec.rb b/spec/checkout_sdk/payments/hosted/hosted_payments_integration_spec.rb
index 7cd6ff5..33052d5 100644
--- a/spec/checkout_sdk/payments/hosted/hosted_payments_integration_spec.rb
+++ b/spec/checkout_sdk/payments/hosted/hosted_payments_integration_spec.rb
@@ -78,7 +78,7 @@ def create_hosted_payments_request
   billing_descriptor.name = "The Jewelry Shop"
   billing_descriptor.reference = "ORD-123A"
 
-  customer_retry = CheckoutSdk::Payments::PaymentRetryRequest.new
+  customer_retry = CheckoutSdk::Common::CustomerRetry.new
   customer_retry.max_attempts = 2
 
   sender = CheckoutSdk::Payments::InstrumentSender.new
diff --git a/spec/checkout_sdk/payments/retry_request_serialization_spec.rb b/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
new file mode 100644
index 0000000..581504e
--- /dev/null
+++ b/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+def retry_to_json_hash(obj)
+  JSON.parse(CheckoutSdk::JsonSerializer.to_custom_hash(obj).to_json)
+end
+
+def build_full_retry_request
+  dunning = CheckoutSdk::Payments::DunningRetryRequest.new
+  dunning.enabled = true
+  dunning.max_attempts = 6
+  dunning.end_after_days = 30
+  downtime = CheckoutSdk::Payments::DowntimeRetryRequest.new
+  downtime.enabled = false
+  request = CheckoutSdk::Payments::PaymentRetryRequest.new
+  request.enabled = true
+  request.dunning = dunning
+  request.downtime = downtime
+  request
+end
+
+RSpec.describe CheckoutSdk::Payments::PaymentRetryRequest do
+  it 'serializes all properties to the expected JSON' do
+    expected = JSON.parse('{"enabled":true,"dunning":{"enabled":true,"max_attempts":6,"end_after_days":30},' \
+                          '"downtime":{"enabled":false}}')
+    expect(retry_to_json_hash(build_full_retry_request)).to eq(expected)
+  end
+
+  it 'serializes enabled false' do
+    request = described_class.new
+    request.enabled = false
+    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":false}'))
+  end
+
+  it 'serializes deprecated max_attempts and end_after_days with the spec names' do
+    request = described_class.new
+    request.enabled = true
+    request.max_attempts = 3
+    request.end_after_days = 10
+    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":true,"max_attempts":3,"end_after_days":10}'))
+  end
+
+  it 'keeps the deprecated end_after_day accessor, serialized under its own key' do
+    request = described_class.new
+    request.end_after_day = 7
+    expect(request.end_after_day).to eq(7)
+    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"end_after_day":7}'))
+  end
+end
+
+RSpec.describe CheckoutSdk::Payments::DunningRetryRequest do
+  it 'serializes all properties with enabled false' do
+    request = described_class.new
+    request.enabled = false
+    request.max_attempts = 15
+    request.end_after_days = 60
+    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":false,"max_attempts":15,"end_after_days":60}'))
+  end
+end
+
+RSpec.describe CheckoutSdk::Payments::DowntimeRetryRequest do
+  it 'serializes enabled false' do
+    request = described_class.new
+    request.enabled = false
+    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":false}'))
+  end
+end
+
+RSpec.describe CheckoutSdk::Common::CustomerRetry do
+  it 'serializes the swagger example' do
+    expect(retry_to_json_hash(described_class.new.tap { |c| c.max_attempts = 2 }))
+      .to eq(JSON.parse('{"max_attempts":2}'))
+  end
+
+  it 'serializes max_attempts 0' do
+    expect(retry_to_json_hash(described_class.new.tap { |c| c.max_attempts = 0 }))
+      .to eq(JSON.parse('{"max_attempts":0}'))
+  end
+
+  it 'keeps the deprecated Accounts alias pointing to the same class' do
+    expect(CheckoutSdk::Accounts::CustomerRetry).to equal(described_class)
+  end
+
+  it 'is used by hosted payments, payment links and payment sessions' do
+    [CheckoutSdk::Payments::HostedPaymentsSession, CheckoutSdk::Payments::PaymentLink,
+     CheckoutSdk::Payments::PaymentSessionsRequest].each do |klass|
+      request = klass.new
+      request.customer_retry = described_class.new.tap { |c| c.max_attempts = 2 }
+      expect(retry_to_json_hash(request)['customer_retry']).to eq(JSON.parse('{"max_attempts":2}'))
+    end
+  end
+end

From 24ddd3839cc412cfaf173522eb91f206682efafa Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Armando=20Rodr=C3=ADguez?=
 <127134616+armando-rodriguez-cko@users.noreply.github.com>
Date: Wed, 28 Oct 2026 21:21:19 +0100
Subject: [PATCH 2/4] fix(payments): drop non-existent retry end_after_days,
 complete docs

---
 .../hosted/hosted_payments_session.rb         | 68 ++++++++++--------
 .../payments/links/payment_link.rb            | 58 ++++++++-------
 .../payments/payment_retry_request.rb         | 10 +--
 .../sessions/payment_sessions_request.rb      | 70 +++++++++++--------
 .../retry_request_serialization_spec.rb       |  5 +-
 5 files changed, 115 insertions(+), 96 deletions(-)

diff --git a/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb b/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
index abbc61b..81ff36a 100644
--- a/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
+++ b/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
@@ -5,68 +5,76 @@
 module CheckoutSdk
   module Payments
     # @!attribute currency
-    #   @return [String] {CheckoutSdk::Common::Currency}
+    #   @return [String] {CheckoutSdk::Common::Currency} [Required] The three-letter ISO currency code of the payment
     # @!attribute billing
-    #   @return [BillingInformation]
+    #   @return [BillingInformation] [Required] The billing details
     # @!attribute success_url
-    #   @return [String]
+    #   @return [String] [Required] For redirect payment methods, this overrides the default success redirect URL
+    #     configured on your account
     # @!attribute cancel_url
-    #   @return [String]
+    #   @return [String] [Required] The URL to which the customer should be directed if they cancel the payment
     # @!attribute failure_url
-    #   @return [String]
+    #   @return [String] [Required] For redirect payment methods, this overrides the default failure redirect URL
+    #     configured on your account
     # @!attribute amount
-    #   @return [Integer]
+    #   @return [Integer] [Optional] The payment amount.
     # @!attribute payment_type
-    #   @return [String] {PaymentType}
+    #   @return [String] {PaymentType} [Optional] This must be specified for card payments where the cardholder is not
+    #     present (i.e., recurring or mail order / telephone order)
     # @!attribute payment_ip
-    #   @return [String]
+    #   @return [String] [Optional] The Customers IP address.
     # @!attribute billing_descriptor
-    #   @return [BillingDescriptor]
+    #   @return [BillingDescriptor] [Optional] An optional description that is displayed on the customer's statement
+    #     identifying a purchase
     # @!attribute reference
-    #   @return [String]
+    #   @return [String] [Optional] A reference you can use to identify the payment.
     # @!attribute description
-    #   @return [String]
+    #   @return [String] [Optional] A description of the payment
     # @!attribute display_name
-    #   @return [String]
+    #   @return [String] [Optional] The merchant name to display to customers on the checkout page.
     # @!attribute processing_channel_id
-    #   @return [String]
+    #   @return [String] [Optional] The processing channel to be used for the payment
     # @!attribute amount_allocations
-    #   @return [Array(CheckoutSdk::Common::AmountAllocations)]
+    #   @return [Array(CheckoutSdk::Common::AmountAllocations)] [Optional] The sub-entities that the payment is being
+    #     processed on behalf of
     # @!attribute customer
-    #   @return [CheckoutSdk::Common::CustomerRequest]
+    #   @return [CheckoutSdk::Common::CustomerRequest] [Optional] The customer's details
     # @!attribute shipping
-    #   @return [ShippingDetails]
+    #   @return [ShippingDetails] [Optional] The address any products are being sent to.
     # @!attribute recipient
-    #   @return [PaymentRecipient]
+    #   @return [PaymentRecipient] [Optional] Information about the recipient of the payment's funds.
     # @!attribute processing
-    #   @return [ProcessingSettings]
+    #   @return [ProcessingSettings] [Optional] Use the processing object to influence or override the data sent
+    #     during card processing
     # @!attribute allow_payment_methods
-    #   @return [Array(CheckoutSdk::Common::PaymentSourceType)]
+    #   @return [Array(CheckoutSdk::Common::PaymentSourceType)] [Optional] Specifies which payment method options to
+    #     present to the customer.
     # @!attribute disabled_payment_methods
-    #   @return [Array(CheckoutSdk::Common::PaymentSourceType)]
+    #   @return [Array(CheckoutSdk::Common::PaymentSourceType)] [Optional] Specifies which payment method options to
+    #     not present to the customer.
     # @!attribute products
-    #   @return [Array(CheckoutSdk::Common::Product)]
+    #   @return [Array(CheckoutSdk::Common::Product)] [Optional] Contains details about the products in the order.
     # @!attribute risk
-    #   @return [RiskRequest]
+    #   @return [RiskRequest] [Optional] Configures the risk assessment performed during payment processing.
     # @!attribute customer_retry
     #   @return [CheckoutSdk::Common::CustomerRetry] [Optional] Configures the parameters for customer retries
     #     performed by the customer on the checkout page.
     # @!attribute sender
-    #   @return [CheckoutSdk::Payments::Sender]
+    #   @return [CheckoutSdk::Payments::Sender] [Optional] The sender of the payment.
     # @!attribute metadata
-    #   @return [Hash(String=>Object)]
+    #   @return [Hash(String=>Object)] [Optional] Allows you to store additional information about the transaction.
     # @!attribute locale
-    #   @return [String] {LocaleType}
+    #   @return [String] {LocaleType} [Optional] Creates a translated version of the page in the specified language
     # @!attribute three_ds
-    #   @return [ThreeDSRequest]
+    #   @return [ThreeDSRequest] [Optional] Information required for 3D Secure payments
     # @!attribute capture
-    #   @return [TrueClass, FalseClass]
+    #   @return [TrueClass, FalseClass] [Optional] Whether to capture the payment (if applicable).
     # @!attribute capture_on
-    #   @return [Time]
+    #   @return [Time] [Optional] A timestamp (ISO 8601 code) that determines when the payment should be captured.
     # @!attribute instruction
-    #   @return [HostedPaymentInstruction]
+    #   @return [HostedPaymentInstruction] [Optional] Details about the payment instruction.
     # @!attribute payment_method_configuration
-    #   @return [PaymentMethodConfiguration]
+    #   @return [PaymentMethodConfiguration] [Optional] Configuration options for specific payment methods.
     # @!attribute payment_plan
     #   @return [PaymentPlan] [Optional] The information to process a recurring payment request.
     #     To be used when the payment_type is Recurring.
diff --git a/lib/checkout_sdk/payments/links/payment_link.rb b/lib/checkout_sdk/payments/links/payment_link.rb
index ed4bb50..cfa1a31 100644
--- a/lib/checkout_sdk/payments/links/payment_link.rb
+++ b/lib/checkout_sdk/payments/links/payment_link.rb
@@ -5,62 +5,70 @@
 module CheckoutSdk
   module Payments
     # @!attribute amount
-    #   @return [Integer]
+    #   @return [Integer] [Required] The payment amount.
     # @!attribute currency
-    #   @return [String] {CheckoutSdk::Common::Currency}
+    #   @return [String] {CheckoutSdk::Common::Currency} [Required] The three-letter ISO currency code of the
+    #     payment.The `currency` and `billing.address.country` fields determine which payment methods are shown on the
+    #     payment page.
     # @!attribute payment_type
-    #   @return [String] {PaymentType}
+    #   @return [String] {PaymentType} [Optional] This must be specified for card payments where the cardholder is not
+    #     present (i.e., recurring or mail order / telephone order)
     # @!attribute payment_ip
-    #   @return [String]
+    #   @return [String] [Optional] The Customers IP address.
     # @!attribute billing_descriptor
-    #   @return [BillingDescriptor]
+    #   @return [BillingDescriptor] [Optional] An optional description that is displayed on the customer's statement
+    #     identifying a purchase
     # @!attribute reference
-    #   @return [String]
+    #   @return [String] [Optional] A reference you can use to identify the payment.
     # @!attribute description
-    #   @return [String]
+    #   @return [String] [Optional] A description of the payment.
     # @!attribute display_name
-    #   @return [String]
+    #   @return [String] [Optional] The merchant name to display to customers on the checkout page.
     # @!attribute processing_channel_id
     #   @return [String] - Not available on Previous.
     # @!attribute amount_allocations
     #   @return [Array(CheckoutSdk::Common::AmountAllocations)] - Not available on Previous.
     # @!attribute expires_in
-    #   @return [Integer]
+    #   @return [Integer] [Optional] The time for which the link remains valid, in seconds.
     # @!attribute customer
-    #   @return [CheckoutSdk::Common::CustomerRequest]
+    #   @return [CheckoutSdk::Common::CustomerRequest] [Optional] The customer's details
     # @!attribute shipping
-    #   @return [ShippingDetails]
+    #   @return [ShippingDetails] [Optional] The address any products are being sent to.
     # @!attribute billing
-    #   @return [BillingInformation]
+    #   @return [BillingInformation] [Required] The billing details.
     # @!attribute recipient
-    #   @return [PaymentRecipient]
+    #   @return [PaymentRecipient] [Optional] Information about the recipient of the payment's funds.
     # @!attribute processing
-    #   @return [ProcessingSettings]
+    #   @return [ProcessingSettings] [Optional] Use the processing object to influence or override the data sent
+    #     during card processing
     # @!attribute allow_payment_methods
-    #   @return [Array(CheckoutSdk::Common::PaymentSourceType)]
+    #   @return [Array(CheckoutSdk::Common::PaymentSourceType)] [Optional] Specifies which payment method options to
+    #     present to the customer.
     # @!attribute disabled_payment_methods
-    #   @return [Array(CheckoutSdk::Common::PaymentSourceType)]
+    #   @return [Array(CheckoutSdk::Common::PaymentSourceType)] [Optional] Specifies which payment method options to
+    #     not present to the customer.
     # @!attribute products
-    #   @return [Array(CheckoutSdk::Common::Product)]
+    #   @return [Array(CheckoutSdk::Common::Product)] [Optional] Contains details about the products in the order.
     # @!attribute metadata
-    #   @return [Hash(String=>Object)]
+    #   @return [Hash(String=>Object)] [Optional] Allows you to store additional information about the transaction.
     # @!attribute three_ds
-    #   @return [ThreeDSRequest]
+    #   @return [ThreeDSRequest] [Optional] Information required for 3D Secure payments.
     # @!attribute risk
-    #   @return [RiskRequest]
+    #   @return [RiskRequest] [Optional] Configures the risk assessment performed during payment processing.
     # @!attribute customer_retry
     #   @return [CheckoutSdk::Common::CustomerRetry] [Optional] Configures the parameters for customer retries
     #     performed by the customer on the checkout page.
     # @!attribute sender
-    #   @return [CheckoutSdk::Payments::Sender]
+    #   @return [CheckoutSdk::Payments::Sender] [Optional] The sender of the payment.
     # @!attribute return_url
-    #   @return [String]
+    #   @return [String] [Optional] If provided, the success page will include a button that redirects your customer
+    #     to the provided URL.
     # @!attribute locale
-    #   @return [String]
+    #   @return [String] [Optional] Creates a translated version of the page in the specified language
     # @!attribute capture
-    #   @return [TrueClass, FalseClass]
+    #   @return [TrueClass, FalseClass] [Optional] Whether to capture the payment (if applicable).
     # @!attribute capture_on
-    #   @return [Time]
+    #   @return [Time] [Optional] A timestamp (ISO 8601 code) that determines when the payment should be captured.
     # @!attribute payment_plan
     #   @return [PaymentPlan] [Optional] The information to process a recurring payment request.
     #     To be used when the payment_type is Recurring.
diff --git a/lib/checkout_sdk/payments/payment_retry_request.rb b/lib/checkout_sdk/payments/payment_retry_request.rb
index eb6ac59..1d8d41e 100644
--- a/lib/checkout_sdk/payments/payment_retry_request.rb
+++ b/lib/checkout_sdk/payments/payment_retry_request.rb
@@ -12,12 +12,9 @@ module Payments
     #   @return [DowntimeRetryRequest] [Optional] Configuration of asynchronous Downtime retries.
     # @!attribute max_attempts
     #   @return [Integer]
-    #   @deprecated Please use {DunningRetryRequest#max_attempts} via {#dunning} instead. This attribute
-    #     will be removed in the next major version.
-    # @!attribute end_after_days
-    #   @return [Integer]
-    #   @deprecated Please use {DunningRetryRequest#end_after_days} via {#dunning} instead. This attribute
-    #     will be removed in the next major version.
+    #   @deprecated Please use {DunningRetryRequest#max_attempts} via {#dunning} instead, or
+    #     {CheckoutSdk::Common::CustomerRetry#max_attempts} for customer_retry. This attribute will be
+    #     removed in the next major version.
     # @!attribute end_after_day
     #   @return [Integer]
     #   @deprecated Misspelled attribute that serialized as "end_after_day", which the API does not accept.
@@ -28,7 +25,6 @@ class PaymentRetryRequest
                     :dunning,
                     :downtime,
                     :max_attempts,
-                    :end_after_days,
                     :end_after_day
     end
   end
diff --git a/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb b/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
index 449f1f4..5c3ed10 100644
--- a/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
+++ b/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
@@ -3,45 +3,50 @@
 module CheckoutSdk
   module Payments
     # @!attribute amount
-    #   @return [Integer]
+    #   @return [Integer] [Required] The payment amount.
     # @!attribute currency
-    #   @return [String] {CheckoutSdk::Common::Currency}
+    #   @return [String] {CheckoutSdk::Common::Currency} [Required] The three-letter ISO currency code.
     # @!attribute payment_type
-    #   @return [TrueClass, FalseClass]
+    #   @return [TrueClass, FalseClass] [Optional] Must be specified for card-not-present (CNP) payments.
     # @!attribute billing
-    #   @return [BillingInformation]
+    #   @return [BillingInformation] [Required] The billing details.
     # @!attribute billing_descriptor
-    #   @return [BillingDescriptor]
+    #   @return [BillingDescriptor] [Optional] A description of the purchase, which is displayed on the customer's
+    #     statement.
     # @!attribute reference
-    #   @return [String]
+    #   @return [String] [Optional] A reference you can use to identify the payment.
     # @!attribute description
-    #   @return [String]
+    #   @return [String] [Optional] A description for the payment.
     # @!attribute customer
-    #   @return [CheckoutSdk::Common::CustomerRequest]
+    #   @return [CheckoutSdk::Common::CustomerRequest] [Optional] The customer's details.
     # @!attribute shipping
-    #   @return [ShippingDetails]
+    #   @return [ShippingDetails] [Optional] The shipping details
     # @!attribute recipient
-    #   @return [PaymentRecipient]
+    #   @return [PaymentRecipient] [Optional] Information about the recipient of the payment's funds.
     # @!attribute processing
-    #   @return [ProcessingSettings]
+    #   @return [ProcessingSettings] [Optional] Use the processing object to influence or override the data sent
+    #     during card processing
     # @!attribute processing_channel_id
-    #   @return [String]
+    #   @return [String] [Optional] The processing channel to use for the payment.
     # @!attribute expires_on
-    #   @return [Time]
+    #   @return [Time] [Optional] A timestamp specifying when the `PaymentSession` should expire, as an ISO 8601 code.
     # @!attribute payment_method_configuration
-    #   @return [PaymentMethodConfiguration]
+    #   @return [PaymentMethodConfiguration] [Optional] Configurations for payment method-specific settings.
     # @!attribute enabled_payment_methods
-    #   @return [Array(PaymentMethodsType)]
+    #   @return [Array(PaymentMethodsType)] [Optional] Specifies which payment method options to present to the
+    #     customer.
     # @!attribute disabled_payment_methods
-    #   @return [Array(PaymentMethodsType)]
+    #   @return [Array(PaymentMethodsType)] [Optional] Specifies which payment method options to not present to the
+    #     customer.
     # @!attribute items
-    #   @return [Array(Product)]
+    #   @return [Array(Product)] [Optional] The line items in the order.
     # @!attribute amount_allocations
-    #   @return [Array(CheckoutSdk::Common::AmountAllocations)]
+    #   @return [Array(CheckoutSdk::Common::AmountAllocations)] [Optional] The sub-entities that the payment is being
+    #     processed on behalf of.
     # @!attribute risk
-    #   @return [RiskRequest]
+    #   @return [RiskRequest] [Optional] Configures the risk assessment performed during payment processing.
     # @!attribute retry
-    #   @return [PaymentRetryRequest]
+    #   @return [PaymentRetryRequest] [Optional] Configuration of asynchronous retries.
     #   @deprecated Not part of the payment sessions specification. Please use {#customer_retry} instead.
     #     This attribute will be removed in the next major version.
     # @!attribute customer_retry
@@ -50,27 +55,30 @@ module Payments
     #     attempts, excluding the initial payment attempt (minimum 0, maximum 5, default 5); it is required
     #     when customer_retry is set.
     # @!attribute display_name
-    #   @return [String]
+    #   @return [String] [Optional] The merchant's display name.
     # @!attribute success_url
-    #   @return [String]
+    #   @return [String] [Required] Overrides the default success redirect URL configured on your account, for payment
+    #     methods that require a redirect.
     # @!attribute failure_url
-    #   @return [String]
+    #   @return [String] [Required] Overrides the default failure redirect URL configured on your account, for payment
+    #     methods that require a redirect.
     # @!attribute metadata
-    #   @return [Hash{String => Object}]
+    #   @return [Hash{String => Object}] [Optional] Allows you to store additional information about a transaction
+    #     with custom fields and up to five user-defined fields, which can be used for reporting purposes.
     # @!attribute locale
-    #   @return [String]
+    #   @return [String] [Optional] Creates a translated version of the page in the specified language.
     # @!attribute three_ds
-    #   @return [ThreeDSRequest]
+    #   @return [ThreeDSRequest] [Optional] Information required for 3D Secure authentication payments.
     # @!attribute sender
-    #   @return [Sender]
+    #   @return [Sender] [Optional] The sender of the payment.
     # @!attribute capture
-    #   @return [TrueClass, FalseClass]
+    #   @return [TrueClass, FalseClass] [Optional] Specifies whether to capture the payment, if applicable.
     # @!attribute ip_address
-    #   @return [String]
+    #   @return [String] [Optional] The Customers IP address.
     # @!attribute capture_on
-    #   @return [Time]
+    #   @return [Time] [Optional] A timestamp specifying when to capture the payment, as an ISO 8601 code.
     # @!attribute tax_amount
-    #   @return [Integer]
+    #   @return [Integer] [Optional] The total tax amount, in the minor currency unit.
     # @!attribute authorization_type
     #   @return [String] [Optional] {AuthorizationType} Enum: "Final" "Estimated". Default: "Final".
     # @!attribute payment_plan
diff --git a/spec/checkout_sdk/payments/retry_request_serialization_spec.rb b/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
index 581504e..3a3ab71 100644
--- a/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
+++ b/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
@@ -31,12 +31,11 @@ def build_full_retry_request
     expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":false}'))
   end
 
-  it 'serializes deprecated max_attempts and end_after_days with the spec names' do
+  it 'serializes the deprecated top-level max_attempts under its legacy key' do
     request = described_class.new
     request.enabled = true
     request.max_attempts = 3
-    request.end_after_days = 10
-    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":true,"max_attempts":3,"end_after_days":10}'))
+    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":true,"max_attempts":3}'))
   end
 
   it 'keeps the deprecated end_after_day accessor, serialized under its own key' do

From d5d0203b754e91cab6aef67bc53c206f7ba50dd4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Armando=20Rodr=C3=ADguez?=
 <127134616+armando-rodriguez-cko@users.noreply.github.com>
Date: Wed, 28 Oct 2026 21:32:14 +0100
Subject: [PATCH 3/4] fix(payments): drop unloadable retry fields, complete
 request docs

PaymentRetryRequest was never required on master, so its top-level
max_attempts and end_after_day could not be used. Remove them.

Document the payment sessions retry attribute as ignored by the API,
fix the payment_type doc type and enum, and flag tax_amount as not in
the specification. Add instruction to payment links and payment
sessions and payment_method_configuration to payment links. Complete
payment link and hosted payment docs with spec ranges and defaults.
---
 .../hosted/hosted_payments_session.rb         |  4 +--
 .../payments/links/payment_link.rb            | 26 +++++++++++-----
 .../payments/payment_retry_request.rb         | 14 +--------
 .../sessions/payment_sessions_request.rb      | 15 ++++++----
 .../retry_request_serialization_spec.rb       | 30 ++++++++++---------
 5 files changed, 47 insertions(+), 42 deletions(-)

diff --git a/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb b/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
index 81ff36a..710c51e 100644
--- a/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
+++ b/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
@@ -17,12 +17,12 @@ module Payments
     #   @return [String] [Required] For redirect payment methods, this overrides the default failure redirect URL
     #     configured on your account
     # @!attribute amount
-    #   @return [Integer] [Optional] The payment amount.
+    #   @return [Integer] [Optional] The payment amount. Minimum 0.
     # @!attribute payment_type
     #   @return [String] {PaymentType} [Optional] This must be specified for card payments where the cardholder is not
     #     present (i.e., recurring or mail order / telephone order)
     # @!attribute payment_ip
-    #   @return [String] [Optional] The Customers IP address.
+    #   @return [String] [Optional] The Customers IP address. Only IPv4 and IPv6 addresses are accepted.
     # @!attribute billing_descriptor
     #   @return [BillingDescriptor] [Optional] An optional description that is displayed on the customer's statement
     #     identifying a purchase
diff --git a/lib/checkout_sdk/payments/links/payment_link.rb b/lib/checkout_sdk/payments/links/payment_link.rb
index cfa1a31..3b8b937 100644
--- a/lib/checkout_sdk/payments/links/payment_link.rb
+++ b/lib/checkout_sdk/payments/links/payment_link.rb
@@ -8,13 +8,13 @@ module Payments
     #   @return [Integer] [Required] The payment amount.
     # @!attribute currency
     #   @return [String] {CheckoutSdk::Common::Currency} [Required] The three-letter ISO currency code of the
-    #     payment.The `currency` and `billing.address.country` fields determine which payment methods are shown on the
+    #     payment. The `currency` and `billing.address.country` fields determine which payment methods are shown on the
     #     payment page.
     # @!attribute payment_type
     #   @return [String] {PaymentType} [Optional] This must be specified for card payments where the cardholder is not
-    #     present (i.e., recurring or mail order / telephone order)
+    #     present (i.e., recurring or mail order / telephone order). Default: "Regular".
     # @!attribute payment_ip
-    #   @return [String] [Optional] The Customers IP address.
+    #   @return [String] [Optional] The Customers IP address. Only IPv4 and IPv6 addresses are accepted.
     # @!attribute billing_descriptor
     #   @return [BillingDescriptor] [Optional] An optional description that is displayed on the customer's statement
     #     identifying a purchase
@@ -25,11 +25,14 @@ module Payments
     # @!attribute display_name
     #   @return [String] [Optional] The merchant name to display to customers on the checkout page.
     # @!attribute processing_channel_id
-    #   @return [String] - Not available on Previous.
+    #   @return [String] [Optional] The processing channel to use for the payment. This field is required if you
+    #     have more than one processing channel associated with your API key.
     # @!attribute amount_allocations
-    #   @return [Array(CheckoutSdk::Common::AmountAllocations)] - Not available on Previous.
+    #   @return [Array(CheckoutSdk::Common::AmountAllocations)] [Optional] The sub-entities that the payment is being
+    #     processed on behalf of.
     # @!attribute expires_in
-    #   @return [Integer] [Optional] The time for which the link remains valid, in seconds.
+    #   @return [Integer] [Optional] The time for which the link remains valid, in seconds. Minimum 1, maximum 5184000.
+    #     Default: 86400.
     # @!attribute customer
     #   @return [CheckoutSdk::Common::CustomerRequest] [Optional] The customer's details
     # @!attribute shipping
@@ -64,7 +67,8 @@ module Payments
     #   @return [String] [Optional] If provided, the success page will include a button that redirects your customer
     #     to the provided URL.
     # @!attribute locale
-    #   @return [String] [Optional] Creates a translated version of the page in the specified language
+    #   @return [String] [Optional] Creates a translated version of the page in the specified language.
+    #     Default: "en-GB".
     # @!attribute capture
     #   @return [TrueClass, FalseClass] [Optional] Whether to capture the payment (if applicable).
     # @!attribute capture_on
@@ -72,6 +76,10 @@ module Payments
     # @!attribute payment_plan
     #   @return [PaymentPlan] [Optional] The information to process a recurring payment request.
     #     To be used when the payment_type is Recurring.
+    # @!attribute instruction
+    #   @return [HostedPaymentInstruction] [Optional] Details about the payment instruction.
+    # @!attribute payment_method_configuration
+    #   @return [PaymentMethodConfiguration] [Optional] Configuration options for specific payment methods.
     # @!attribute authorization_type
     #   @return [String] [Optional] {AuthorizationType} Enum: "Final" "Estimated". Default: "Final".
     class PaymentLink
@@ -104,7 +112,9 @@ class PaymentLink
                     :capture,
                     :capture_on,
                     :payment_plan,
-                    :authorization_type
+                    :authorization_type,
+                    :instruction,
+                    :payment_method_configuration
 
       def initialize(payment_type: CheckoutSdk::Payments::PaymentType::REGULAR)
         @payment_type = payment_type
diff --git a/lib/checkout_sdk/payments/payment_retry_request.rb b/lib/checkout_sdk/payments/payment_retry_request.rb
index 1d8d41e..aea4767 100644
--- a/lib/checkout_sdk/payments/payment_retry_request.rb
+++ b/lib/checkout_sdk/payments/payment_retry_request.rb
@@ -10,22 +10,10 @@ module Payments
     #   @return [DunningRetryRequest] [Optional] Configuration of asynchronous Dunning retries.
     # @!attribute downtime
     #   @return [DowntimeRetryRequest] [Optional] Configuration of asynchronous Downtime retries.
-    # @!attribute max_attempts
-    #   @return [Integer]
-    #   @deprecated Please use {DunningRetryRequest#max_attempts} via {#dunning} instead, or
-    #     {CheckoutSdk::Common::CustomerRetry#max_attempts} for customer_retry. This attribute will be
-    #     removed in the next major version.
-    # @!attribute end_after_day
-    #   @return [Integer]
-    #   @deprecated Misspelled attribute that serialized as "end_after_day", which the API does not accept.
-    #     Please use {DunningRetryRequest#end_after_days} via {#dunning} instead. This attribute will be
-    #     removed in the next major version.
     class PaymentRetryRequest
       attr_accessor :enabled,
                     :dunning,
-                    :downtime,
-                    :max_attempts,
-                    :end_after_day
+                    :downtime
     end
   end
 end
diff --git a/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb b/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
index 5c3ed10..e2b6a3a 100644
--- a/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
+++ b/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
@@ -7,7 +7,8 @@ module Payments
     # @!attribute currency
     #   @return [String] {CheckoutSdk::Common::Currency} [Required] The three-letter ISO currency code.
     # @!attribute payment_type
-    #   @return [TrueClass, FalseClass] [Optional] Must be specified for card-not-present (CNP) payments.
+    #   @return [String] {PaymentType} [Optional] Must be specified for card-not-present (CNP) payments.
+    #     Enum: "Regular" "Recurring" "MOTO" "Installment" "Unscheduled". Default: "Regular".
     # @!attribute billing
     #   @return [BillingInformation] [Required] The billing details.
     # @!attribute billing_descriptor
@@ -47,8 +48,8 @@ module Payments
     #   @return [RiskRequest] [Optional] Configures the risk assessment performed during payment processing.
     # @!attribute retry
     #   @return [PaymentRetryRequest] [Optional] Configuration of asynchronous retries.
-    #   @deprecated Not part of the payment sessions specification. Please use {#customer_retry} instead.
-    #     This attribute will be removed in the next major version.
+    #   @deprecated Not part of the payment sessions request; the API ignores it. Will be removed in the next
+    #     major version.
     # @!attribute customer_retry
     #   @return [CheckoutSdk::Common::CustomerRetry] [Optional] Configures the parameters for customer retries
     #     performed by the customer on the checkout page. max_attempts is the maximum number of customer retry
@@ -78,9 +79,12 @@ module Payments
     # @!attribute capture_on
     #   @return [Time] [Optional] A timestamp specifying when to capture the payment, as an ISO 8601 code.
     # @!attribute tax_amount
-    #   @return [Integer] [Optional] The total tax amount, in the minor currency unit.
+    #   @return [Integer] [Optional] The total tax amount, in the minor currency unit. Not in the
+    #     payment sessions request specification.
     # @!attribute authorization_type
     #   @return [String] [Optional] {AuthorizationType} Enum: "Final" "Estimated". Default: "Final".
+    # @!attribute instruction
+    #   @return [HostedPaymentInstruction] [Optional] Details about the payment instruction.
     # @!attribute payment_plan
     #   @return [PaymentPlan] [Optional] The information to process a recurring payment request.
     #     To be used when the payment_type is Recurring.
@@ -118,7 +122,8 @@ class PaymentSessionsRequest
                     :capture_on,
                     :tax_amount,
                     :authorization_type,
-                    :payment_plan
+                    :payment_plan,
+                    :instruction
     end
   end
 end
diff --git a/spec/checkout_sdk/payments/retry_request_serialization_spec.rb b/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
index 3a3ab71..3deff5e 100644
--- a/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
+++ b/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
@@ -30,20 +30,6 @@ def build_full_retry_request
     request.enabled = false
     expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":false}'))
   end
-
-  it 'serializes the deprecated top-level max_attempts under its legacy key' do
-    request = described_class.new
-    request.enabled = true
-    request.max_attempts = 3
-    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"enabled":true,"max_attempts":3}'))
-  end
-
-  it 'keeps the deprecated end_after_day accessor, serialized under its own key' do
-    request = described_class.new
-    request.end_after_day = 7
-    expect(request.end_after_day).to eq(7)
-    expect(retry_to_json_hash(request)).to eq(JSON.parse('{"end_after_day":7}'))
-  end
 end
 
 RSpec.describe CheckoutSdk::Payments::DunningRetryRequest do
@@ -88,3 +74,19 @@ def build_full_retry_request
     end
   end
 end
+
+RSpec.describe 'instruction and payment_method_configuration on payment links and payment sessions' do
+  it 'serializes instruction on payment links and payment sessions' do
+    [CheckoutSdk::Payments::PaymentLink, CheckoutSdk::Payments::PaymentSessionsRequest].each do |klass|
+      request = klass.new
+      request.instruction = CheckoutSdk::Payments::HostedPaymentInstruction.new.tap { |i| i.purpose = 'donations' }
+      expect(retry_to_json_hash(request)['instruction']).to eq(JSON.parse('{"purpose":"donations"}'))
+    end
+  end
+
+  it 'serializes payment_method_configuration on payment links' do
+    request = CheckoutSdk::Payments::PaymentLink.new
+    request.payment_method_configuration = CheckoutSdk::Payments::PaymentMethodConfiguration.new
+    expect(retry_to_json_hash(request)).to have_key('payment_method_configuration')
+  end
+end

From e3c3706596c167349e9b91471822642d0056918d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Armando=20Rodr=C3=ADguez?=
 <127134616+armando-rodriguez-cko@users.noreply.github.com>
Date: Wed, 28 Oct 2026 21:38:19 +0100
Subject: [PATCH 4/4] docs(payments): deprecate payment_ip and ip_address per
 the spec

The API reference marks payment_ip on hosted payments and payment
links, and ip_address on payment sessions, as deprecated. Tag them in
the YARD docs and assert the exact payment_method_configuration
serialization with a nested card property.
---
 lib/checkout_sdk/payments/hosted/hosted_payments_session.rb | 2 ++
 lib/checkout_sdk/payments/links/payment_link.rb             | 2 ++
 .../payments/sessions/payment_sessions_request.rb           | 4 +++-
 .../payments/retry_request_serialization_spec.rb            | 6 +++++-
 4 files changed, 12 insertions(+), 2 deletions(-)

diff --git a/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb b/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
index 710c51e..b0c8320 100644
--- a/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
+++ b/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb
@@ -23,6 +23,8 @@ module Payments
     #     present (i.e., recurring or mail order / telephone order)
     # @!attribute payment_ip
     #   @return [String] [Optional] The Customers IP address. Only IPv4 and IPv6 addresses are accepted.
+    #   @deprecated The Customers IP address is deprecated in the API reference. Will be removed in the next
+    #     major version.
     # @!attribute billing_descriptor
     #   @return [BillingDescriptor] [Optional] An optional description that is displayed on the customer's statement
     #     identifying a purchase
diff --git a/lib/checkout_sdk/payments/links/payment_link.rb b/lib/checkout_sdk/payments/links/payment_link.rb
index 3b8b937..7dc654b 100644
--- a/lib/checkout_sdk/payments/links/payment_link.rb
+++ b/lib/checkout_sdk/payments/links/payment_link.rb
@@ -15,6 +15,8 @@ module Payments
     #     present (i.e., recurring or mail order / telephone order). Default: "Regular".
     # @!attribute payment_ip
     #   @return [String] [Optional] The Customers IP address. Only IPv4 and IPv6 addresses are accepted.
+    #   @deprecated The Customers IP address is deprecated in the API reference. Will be removed in the next
+    #     major version.
     # @!attribute billing_descriptor
     #   @return [BillingDescriptor] [Optional] An optional description that is displayed on the customer's statement
     #     identifying a purchase
diff --git a/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb b/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
index e2b6a3a..4ea6b34 100644
--- a/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
+++ b/lib/checkout_sdk/payments/sessions/payment_sessions_request.rb
@@ -75,7 +75,9 @@ module Payments
     # @!attribute capture
     #   @return [TrueClass, FalseClass] [Optional] Specifies whether to capture the payment, if applicable.
     # @!attribute ip_address
-    #   @return [String] [Optional] The Customers IP address.
+    #   @return [String] [Optional] The Customers IP address. Only IPv4 and IPv6 addresses are accepted.
+    #   @deprecated The Customers IP address is deprecated in the API reference. Will be removed in the next
+    #     major version.
     # @!attribute capture_on
     #   @return [Time] [Optional] A timestamp specifying when to capture the payment, as an ISO 8601 code.
     # @!attribute tax_amount
diff --git a/spec/checkout_sdk/payments/retry_request_serialization_spec.rb b/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
index 3deff5e..2074576 100644
--- a/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
+++ b/spec/checkout_sdk/payments/retry_request_serialization_spec.rb
@@ -86,7 +86,11 @@ def build_full_retry_request
 
   it 'serializes payment_method_configuration on payment links' do
     request = CheckoutSdk::Payments::PaymentLink.new
+    card = CheckoutSdk::Payments::Card.new
+    card.store_payment_details = 'collect_consent'
     request.payment_method_configuration = CheckoutSdk::Payments::PaymentMethodConfiguration.new
-    expect(retry_to_json_hash(request)).to have_key('payment_method_configuration')
+    request.payment_method_configuration.card = card
+    expect(retry_to_json_hash(request)['payment_method_configuration'])
+      .to eq(JSON.parse('{"card":{"store_payment_details":"collect_consent"}}'))
   end
 end