checkout_sdk 2.7.1 → 2.8.1

data/lib/checkout_sdk/payments/destination/bank_account_destination.rb

@@ -2,25 +2,54 @@
 
 module CheckoutSdk
   module Payments
+    # A bank account payout destination (bank payout, type bank_account).
+    #
     # @!attribute account_type
+    #   The type of the bank account. Note that some beneficiary banks do not accept payouts to
+    #   savings accounts.
+    #   [Required]
+    #   Enum: "savings" "current" "cash"
     #   @return [String] {CheckoutSdk::Common::AccountType}
     # @!attribute account_number
+    #   Number (which can contain letters) that identifies the local account.
+    #   [Optional]
     #   @return [String]
     # @!attribute bank_code
+    #   Code that identifies the bank. Also referred as Routing Number in the United States.
+    #   [Optional]
     #   @return [String]
     # @!attribute branch_code
+    #   Code that identifies the bank branch.
+    #   [Optional]
     #   @return [String]
     # @!attribute iban
+    #   Internationally agreed standard for identifying bank accounts. Lengths vary per destination_country.
+    #   [Optional]
     #   @return [String]
     # @!attribute bban
+    #   The combination of bank code and/or branch code and account number.
+    #   [Optional]
     #   @return [String]
     # @!attribute swift_bic
+    #   8 or 11 character code which identifies the bank or bank branch.
+    #   [Optional]
     #   @return [String]
     # @!attribute country
+    #   The two-letter ISO country code of where the account is based. Note that not all countries
+    #   are available.
+    #   [Required]
+    #   2 characters
     #   @return [String] {CheckoutSdk::Common::Country}
     # @!attribute account_holder
+    #   The account holder details.
+    #   [Optional]
     #   @return [CheckoutSdk::Common::AccountHolder]
     # @!attribute bank
+    #   The bank details.
+    #   [Optional]
+    #   @deprecated Not in the request schema of the bank account payout destination; bank only exists on the
+    #     Instruments bank account schemas. Retained for backwards compatibility and will be removed in the
+    #     next major version. There is no replacement.
     #   @return [CheckoutSdk::Common::BankDetails]
     class BankAccountDestination < Destination
       attr_accessor :account_type,

data/lib/checkout_sdk/payments/destination/card_destination.rb

@@ -2,13 +2,33 @@
 
 module CheckoutSdk
   module Payments
+    # A card payout destination. Also the card destination of an unreferenced refund.
+    #
     # @!attribute number
+    #   The card number.
+    #   You can encrypt this field by using the Cko-Encryption-Key-Id and Cko-Encrypted-Properties headers.
+    #   [Required]
+    #   max 19 characters
     #   @return [String]
     # @!attribute expiry_month
+    #   The card's expiration month.
+    #   [Required]
+    #   1 to 2 digits
     #   @return [Integer]
     # @!attribute expiry_year
+    #   The card's expiration year.
+    #   [Required]
+    #   4 digits
     #   @return [Integer]
     # @!attribute account_holder
+    #   The payout or unreferenced refund destination account holder.
+    #   [Required]
+    #   The type discriminates the accepted keys:
+    #   - individual: type, first_name, middle_name, last_name, billing_address, phone,
+    #     identification, email, date_of_birth, country_of_birth
+    #   - corporate, government: type, company_name, billing_address, phone, identification, email
+    #   Other AccountHolder properties (full_name, gender, tax_id, residential_status,
+    #   account_name_inquiry) are not part of this position.
     #   @return [CheckoutSdk::Common::AccountHolder]
     class CardDestination < Destination
       attr_accessor :number,

data/lib/checkout_sdk/payments/destination/destination.rb

@@ -2,7 +2,12 @@
 
 module CheckoutSdk
   module Payments
+    # The destination of the payout, or of the unreferenced refund.
+    # You can encrypt this field by using the Cko-Encryption-Key-Id and Cko-Encrypted-Properties headers.
+    #
     # @!attribute type
+    #   The payout or unreferenced refund destination type. Set by each subclass.
+    #   [Required]
     #   @return [String] {DestinationType}
     class Destination
       attr_reader :type

data/lib/checkout_sdk/payments/destination/destination_type.rb

@@ -2,11 +2,18 @@
 
 module CheckoutSdk
   module Payments
+    # The payout destination type.
+    #
+    # Three destination discriminators share these values:
+    # - card payout destination: card, network_token, id, token
+    # - unreferenced refund destination: card, network_token, id, token
+    # - bank payout destination: id, bank_account
     module DestinationType
       CARD = 'card'
       ID = 'id'
       TOKEN = 'token'
       BANK_ACCOUNT = 'bank_account'
+      NETWORK_TOKEN = 'network_token'
     end
   end
 end

data/lib/checkout_sdk/payments/destination/id_destination.rb

@@ -2,9 +2,25 @@
 
 module CheckoutSdk
   module Payments
+    # A payment instrument payout destination. Used by card payouts, bank payouts and unreferenced refunds.
+    #
     # @!attribute id
+    #   The payment source ID. This will be an ID with the prefix `src_`.
+    #   [Required]
+    #   ^(src)_(\w{26})$
+    #   30 characters (card payout and unreferenced refund)
     #   @return [String]
     # @!attribute account_holder
+    #   The payout or unreferenced refund destination account holder.
+    #   [Required] for card payouts, [Optional] for unreferenced refunds.
+    #   Not declared by the bank payout id destination.
+    #   The type discriminates the accepted keys. For card payouts:
+    #   - individual: type, first_name, middle_name, last_name
+    #   - corporate, government: type, company_name
+    #   For unreferenced refunds, where no name is required:
+    #   - individual: type, first_name, middle_name, last_name, billing_address, phone,
+    #     identification, email, date_of_birth, country_of_birth
+    #   - corporate, government: type, company_name, billing_address, phone, identification, email
     #   @return [CheckoutSdk::Common::AccountHolder]
     class IdDestination < Destination
       attr_accessor :id,

data/lib/checkout_sdk/payments/destination/network_token_destination.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # A network token payout destination, used as the destination of a card payout or of an
+    # unreferenced refund.
+    #
+    # @!attribute token
+    #   The network token's Primary Account Number (PAN).
+    #   [Required]
+    #   @return [String]
+    # @!attribute expiry_month
+    #   The network token's expiration month.
+    #   [Required]
+    #   min 1
+    #   1 to 2 digits
+    #   @return [Integer]
+    # @!attribute expiry_year
+    #   The network token's expiration year.
+    #   [Required]
+    #   4 digits
+    #   @return [Integer]
+    # @!attribute token_type
+    #   The network token type.
+    #   [Required]
+    #   Enum: "vts" "mdes" "applepay" "googlepay"
+    #   @return [String] {CheckoutSdk::Payments::NetworkTokenType}
+    # @!attribute cryptogram
+    #   The network token's Base64-encoded cryptographic identifier (TAVV).
+    #   The cryptogram is used by card schemes to validate the token verification result.
+    #   [Optional]
+    #   max 50 characters
+    #   @return [String]
+    # @!attribute eci
+    #   The network token's Electronic Commerce Indicator (ECI) security level.
+    #   [Optional]
+    #   max 2 characters
+    #   @return [String]
+    # @!attribute account_holder
+    #   The payout or unreferenced refund destination account holder.
+    #   [Required]
+    #   The type discriminates the accepted keys:
+    #   - individual: type, first_name, middle_name, last_name, billing_address, phone,
+    #     identification, email, date_of_birth, country_of_birth
+    #   - corporate, government: type, company_name, billing_address, phone, identification, email
+    #   Other AccountHolder properties (full_name, gender, tax_id, residential_status,
+    #   account_name_inquiry) are not part of this position.
+    #   @return [CheckoutSdk::Common::AccountHolder]
+    class NetworkTokenDestination < Destination
+      attr_accessor :token,
+                    :expiry_month,
+                    :expiry_year,
+                    :token_type,
+                    :cryptogram,
+                    :eci,
+                    :account_holder
+
+      def initialize
+        super(CheckoutSdk::Payments::DestinationType::NETWORK_TOKEN)
+      end
+    end
+  end
+end

data/lib/checkout_sdk/payments/destination/token_destination.rb

@@ -2,9 +2,24 @@
 
 module CheckoutSdk
   module Payments
+    # A token payout destination. Also the token destination of an unreferenced refund.
+    #
     # @!attribute token
+    #   The Checkout.com card token ID. This will be an ID with the prefix `tok_`.
+    #   [Required]
+    #   ^(tok)_(\w{26})$
+    #   30 characters
     #   @return [String]
     # @!attribute account_holder
+    #   The payout or unreferenced refund destination account holder.
+    #   [Required] for card payouts, [Optional] for unreferenced refunds.
+    #   The type discriminates the accepted keys. For card payouts:
+    #   - individual: type, first_name, middle_name, last_name
+    #   - corporate, government: type, company_name
+    #   For unreferenced refunds, where no name is required:
+    #   - individual: type, first_name, middle_name, last_name, billing_address, phone,
+    #     identification, email, date_of_birth, country_of_birth
+    #   - corporate, government: type, company_name, billing_address, phone, identification, email
     #   @return [CheckoutSdk::Common::AccountHolder]
     class TokenDestination < Destination
       attr_accessor :token,

data/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

data/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

data/lib/checkout_sdk/payments/hosted/hosted_payment_instruction.rb

@@ -2,7 +2,16 @@
 
 module CheckoutSdk
   module Payments
+    # Details about the payment instruction of a hosted payments session.
+    # Hosted payments use purpose only.
+    #
     # @!attribute purpose
+    #   The purpose of the payment. This field might be required for AFT transactions depending on the
+    #   card's issuer_country.
+    #   [Optional]
+    #   Enum: "donations" "education" "emergency_need" "expatriation" "family_support" "financial_services"
+    #   "gifts" "income" "insurance" "investment" "it_services" "leisure" "loan_payment" "medical_treatment"
+    #   "other" "pension" "royalties" "savings" "travel_and_tourism"
     #   @return [String] {PaymentPurposeType}
     class HostedPaymentInstruction
       attr_accessor :purpose

data/lib/checkout_sdk/payments/hosted/hosted_payments_session.rb

@@ -5,67 +5,78 @@ require 'checkout_sdk/payments/payment_type'
 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.

data/lib/checkout_sdk/payments/instruction_remittance.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The remittance details of a bank payout instruction, used for reconciliation.
+    #
+    # @!attribute reference
+    #   A merchant-provided reference for the remittance payment.
+    #   This value is used for payment reconciliation and is reviewed by our banking partner.
+    #   [Optional]
+    #   max 80 characters
+    #   @return [String]
+    class InstructionRemittance
+      attr_accessor :reference
+    end
+  end
+end

data/lib/checkout_sdk/payments/instruction_scheme.rb

@@ -2,7 +2,12 @@
 
 module CheckoutSdk
   module Payments
+    # The payment scheme type of a bank payout instruction.
+    # Enum: "local" "instant"
     class InstructionScheme
+      # @deprecated Not in the request schema, which only lists local and instant; still returned in
+      #   PayoutDetails (instruction.scheme). Retained for backwards compatibility and will be removed in the
+      #   next major version. There is no replacement.
       SWIFT = 'swift'
       LOCAL = 'local'
       INSTANT = 'instant'

data/lib/checkout_sdk/payments/links/payment_link.rb

@@ -5,64 +5,83 @@ require 'checkout_sdk/payments/payment_type'
 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 @@ module CheckoutSdk
                     :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

data/lib/checkout_sdk/payments/payment_instruction.rb

@@ -2,27 +2,74 @@
 
 module CheckoutSdk
   module Payments
+    # Additional details about the instruction of a payment, a payout or an unreferenced refund.
+    # Card payouts and unreferenced refunds use purpose and funds_transfer_type; bank payouts use scheme and
+    # remittance; regular payments (PaymentRequest) use purpose only.
+    #
     # @!attribute purpose
-    #   @return [String]
+    #   The purpose of the payment, card payout or unreferenced refund.
+    #   For card payouts, required if the card's issuer_country is one of AR, BD, CL, CO, EG, IN, MX or SA.
+    #   For unreferenced refunds, required if the card's issuer_country is one of AR, BD, CL, CO, EG, IN or MX.
+    #   For regular payments, it might be required for AFT transactions depending on the card's issuer_country.
+    #   [Optional]
+    #   Enum: "family_support" "expatriation" "travel_and_tourism" "education" "medical_treatment"
+    #   "emergency_need" "leisure" "savings" "gifts" "donations" "financial_services" "it_services"
+    #   "investment" "insurance" "loan_payment" "pension" "royalties" "other" "income"
+    #   @return [String] {PaymentPurposeType}
     # @!attribute charge_bearer
+    #   The charge bearer of a bank payout.
+    #   [Optional]
+    #   @deprecated Not in the request schema; still returned in PayoutDetails (instruction.charge_bearer).
+    #     Retained for backwards compatibility and will be removed in the next major version. There is no
+    #     replacement.
     #   @return [String] {ChargeBearer}
     # @!attribute repair
+    #   Whether the bank payout may be repaired.
+    #   [Optional]
+    #   @deprecated Not in the request schema; still returned in PayoutDetails (instruction.repair).
+    #     Retained for backwards compatibility and will be removed in the next major version. There is no
+    #     replacement.
     #   @return [TrueClass, FalseClass]
     # @!attribute scheme
+    #   An option to restrict the payment scheme type of a bank payout, when not available payouts will fail.
+    #   [Optional]
+    #   Enum: "local" "instant"
     #   @return [String] {InstructionScheme}
+    # @!attribute remittance
+    #   The remittance details of a bank payout, used for reconciliation.
+    #   [Optional]
+    #   @return [InstructionRemittance]
     # @!attribute quote_id
+    #   The FX quote identifier of a bank payout.
+    #   [Optional]
+    #   @deprecated Not in the request schema; still returned in PayoutDetails (instruction.quote_id).
+    #     Retained for backwards compatibility and will be removed in the next major version. There is no
+    #     replacement.
     #   @return [String]
     # @!attribute skip_expiry
+    #   [Optional]
+    #   @deprecated Not in any schema of the specification. Retained for backwards compatibility and will be
+    #     removed in the next major version. There is no replacement.
     #   @return [TrueClass, FalseClass]
     # @!attribute funds_transfer_type
+    #   The funds transfer type code for the type of card payout you're performing.
+    #   You can only use codes that have been assigned to you by the card schemes and Checkout.com, based
+    #   on your business case and requirements. If you have only been assigned one funds transfer type
+    #   code, this field is optional. For unreferenced refunds it is required if
+    #   processing.processing_speed is fast: use MI for Visa and C60 for Mastercard.
+    #   [Required] for card payouts, [Optional] for unreferenced refunds
     #   @return [String]
     # @!attribute mvv
+    #   [Optional]
+    #   @deprecated Not in any schema of the specification. Retained for backwards compatibility and will be
+    #     removed in the next major version. There is no replacement.
     #   @return [String]
     class PaymentInstruction
       attr_accessor :purpose,
                     :charge_bearer,
                     :repair,
                     :scheme,
+                    :remittance,
                     :quote_id,
                     :skip_expiry,
                     :funds_transfer_type,

data/lib/checkout_sdk/payments/payment_request.rb

@@ -62,7 +62,7 @@ module CheckoutSdk
     # @!attribute items
     #   @return [Array(Product)]
     # @!attribute retry
-    #   @return [PaymentRetryRequest]
+    #   @return [PaymentRetryRequest] [Optional] Configuration of asynchronous retries.
     # @!attribute metadata
     #   @return [Hash{String => Object}]
     # @!attribute instruction