fix(payments): load retry types and add customer_retry to sessions

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

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

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

lib/checkout_sdk/payments/hosted/hosted_payments_session.rb

@@ -5,67 +5,78 @@
 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. Minimum 0.
     # @!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. 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]
+    #   @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 [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]
+    #   @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.

lib/checkout_sdk/payments/links/payment_link.rb

@@ -5,64 +5,83 @@
 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). Default: "Regular".
     # @!attribute payment_ip
-    #   @return [String]
+    #   @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]
+    #   @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.
+    #   @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]
+    #   @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]
+    #   @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]
+    #   @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.
+    #     Default: "en-GB".
     # @!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.
+    # @!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
@@ -95,7 +114,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

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

lib/checkout_sdk/payments/payment_retry_request.rb

@@ -2,16 +2,18 @@
 
 module CheckoutSdk
   module Payments
+    # Configuration of asynchronous retries (POST /payments).
+    #
     # @!attribute enabled
-    #   @return [TrueClass, FalseClass]
-    # @!attribute max_attempts
-    #   @return [Integer]
-    # @!attribute end_after_days
-    #   @return [Integer]
+    #   @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.
     class PaymentRetryRequest
       attr_accessor :enabled,
-                    :max_attempts,
-                    :end_after_day
+                    :dunning,
+                    :downtime
     end
   end
 end

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'