fix(payments): align PaymentSetups with the spec

lib/checkout_sdk/payments/payments.rb

@@ -210,6 +210,9 @@
 require 'checkout_sdk/payments/setups/account_funding_transaction_sender'
 require 'checkout_sdk/payments/setups/account_funding_transaction_recipient'
 require 'checkout_sdk/payments/setups/payment_setup_account_funding_transaction'
+require 'checkout_sdk/payments/setups/payment_setup_billing_descriptor'
+require 'checkout_sdk/payments/setups/payment_setup_presentment_details'
+require 'checkout_sdk/payments/setups/payment_setup_terminal'
 require 'checkout_sdk/payments/setups/blik_payment_method'
 require 'checkout_sdk/payments/setups/bacs_payment_method'
 require 'checkout_sdk/payments/setups/card_present_payment_method'

lib/checkout_sdk/payments/setups/payment_setup_billing_descriptor.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The billing descriptor for payment.
+    #
+    # @!attribute name
+    #   @return [String] A dynamic description of the payment. Max length: 25.
+    # @!attribute city
+    #   @return [String] The city from which the payment was made. Max length: 13.
+    # @!attribute reference
+    #   @return [String] The reference shown on the statement. Max length: 50.
+    class PaymentSetupBillingDescriptor
+      attr_accessor :name,
+                    :city,
+                    :reference
+    end
+  end
+end

lib/checkout_sdk/payments/setups/payment_setup_presentment_details.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # The amount and currency to present to the customer, when the settlement
+    # currency differs from the customer-facing currency.
+    #
+    # @!attribute amount
+    #   @return [Integer] The presentment amount, in the minor currency unit.
+    # @!attribute currency
+    #   @return [String] The presentment currency, as a three-letter ISO currency code.
+    class PaymentSetupPresentmentDetails
+      attr_accessor :amount,
+                    :currency
+    end
+  end
+end

lib/checkout_sdk/payments/setups/payment_setup_terminal.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Terminal details.
+    #
+    # @!attribute id
+    #   @return [String] Terminal identifier. Length: 8.
+    # @!attribute local_date_time
+    #   @return [String] The local date and time on the terminal, in ISO 8601 format.
+    class PaymentSetupTerminal
+      attr_accessor :id,
+                    :local_date_time
+    end
+  end
+end

lib/checkout_sdk/payments/setups/payment_setups_client.rb

@@ -22,6 +22,9 @@ def initialize(api_client, configuration)
       # [Beta]
       #
       # @param [Hash] payment_setups_request
+      #   May include :billing_descriptor {PaymentSetupBillingDescriptor},
+      #   :presentment_details {PaymentSetupPresentmentDetails} and
+      #   :terminal {PaymentSetupTerminal}.
       def create_payment_setup(payment_setups_request)
         api_client.invoke_post(
           build_path(PAYMENTS_PATH, SETUPS_PATH),
@@ -38,6 +41,9 @@ def create_payment_setup(payment_setups_request)
       #
       # @param [String] id - The unique identifier of the Payment Setup to update
       # @param [Hash] payment_setups_request
+      #   May include :billing_descriptor {PaymentSetupBillingDescriptor},
+      #   :presentment_details {PaymentSetupPresentmentDetails} and
+      #   :terminal {PaymentSetupTerminal}.
       def update_payment_setup(id, payment_setups_request)
         api_client.invoke_put(
           build_path(PAYMENTS_PATH, SETUPS_PATH, id),
@@ -58,15 +64,15 @@ def get_payment_setup(id)
       end
 
       # Confirms a Payment Setup to begin processing the payment request with your chosen
-      # payment method option.
+      # payment method.
       # [Beta]
       #
       # @param [String] id - The unique identifier of the Payment Setup
-      # @param [String] payment_method_option_id - The unique identifier of the payment option
-      # to process the payment with
-      def confirm_payment_setup(id, payment_method_option_id)
+      # @param [String] payment_method_name - The name of the payment method to process the
+      # payment with (for example, "tabby", "klarna", "card")
+      def confirm_payment_setup(id, payment_method_name)
         api_client.invoke_post(
-          build_path(PAYMENTS_PATH, SETUPS_PATH, id, CONFIRM_PATH, payment_method_option_id),
+          build_path(PAYMENTS_PATH, SETUPS_PATH, id, CONFIRM_PATH, payment_method_name),
           sdk_authorization
         )
       end

spec/checkout_sdk/payments/setups/payment_setups_client_spec.rb

@@ -50,10 +50,41 @@
   end
 
   describe '#confirm_payment_setup' do
-    it 'POSTs payments/setups/{id}/confirm/{payment_method_option_id}' do
+    it 'POSTs payments/setups/{id}/confirm/{payment_method_name}' do
       expect(api_client_mock).to receive(:invoke_post)
-        .with('payments/setups/ps_1/confirm/pmo_1', 'secret_key').and_return('response')
-      expect(client.confirm_payment_setup('ps_1', 'pmo_1')).to eq('response')
+        .with('payments/setups/ps_1/confirm/klarna', 'secret_key').and_return('response')
+      expect(client.confirm_payment_setup('ps_1', 'klarna')).to eq('response')
+    end
+
+    it 'builds the correct path for a card payment method name' do
+      expect(api_client_mock).to receive(:invoke_post)
+        .with('payments/setups/ps_1/confirm/card', 'secret_key').and_return('response')
+      expect(client.confirm_payment_setup('ps_1', 'card')).to eq('response')
+    end
+  end
+
+  describe '#create_payment_setup with billing_descriptor, presentment_details and terminal' do
+    it 'passes billing_descriptor, presentment_details and terminal through untouched' do
+      request = {
+        amount: 1000,
+        currency: 'GBP',
+        billing_descriptor: {
+          name: 'Checkout.com',
+          city: 'London',
+          reference: 'Payment for order 123456'
+        },
+        presentment_details: {
+          amount: 110,
+          currency: 'EUR'
+        },
+        terminal: {
+          id: '12345678',
+          local_date_time: '2026-05-26T13:05:14+01:00'
+        }
+      }
+      expect(api_client_mock).to receive(:invoke_post)
+        .with('payments/setups', 'secret_key', request).and_return('response')
+      expect(client.create_payment_setup(request)).to eq('response')
     end
   end
 end

spec/checkout_sdk/payments/setups/payment_setups_helper.rb

@@ -42,6 +42,15 @@ def create_payment_setup_request(**opts)
         device: {
           locale: 'en_GB'
         }
+      },
+      billing_descriptor: {
+        name: 'Checkout.com',
+        city: 'London',
+        reference: 'Payment for order 123456'
+      },
+      presentment_details: {
+        amount: 110,
+        currency: 'EUR'
       }
     }
   end

spec/checkout_sdk/payments/setups/payment_setups_integration_spec.rb

@@ -19,9 +19,16 @@
                                      description
                                      customer.name
                                      settings.success_url
-                                     settings.failure_url])
+                                     settings.failure_url
+                                     billing_descriptor.name
+                                     billing_descriptor.city
+                                     billing_descriptor.reference
+                                     presentment_details.amount
+                                     presentment_details.currency])
         expect(response.amount).to eq(1000)
         expect(response.currency).to eq('USD')
+        expect(response.billing_descriptor.name).to eq('Checkout.com')
+        expect(response.presentment_details.currency).to eq('EUR')
       end
     end
 
@@ -116,10 +123,10 @@
         skip 'No payment method options available in sandbox' if get_response.payment_method_options.nil? || get_response.payment_method_options.empty?
 
         # Get the first payment method option ID
-        payment_method_option_id = get_response.payment_method_options.first['id']
-        
+        payment_method_name = get_response.payment_method_options.first['type']
+
         # Confirm the payment setup
-        response = @api.payments_setups.confirm_payment_setup(create_response.id, payment_method_option_id)
+        response = @api.payments_setups.confirm_payment_setup(create_response.id, payment_method_name)
 
         assert_response(response, %w[id
                                      action_id
@@ -134,26 +141,26 @@
       end
     end
 
-    context 'when confirming with invalid payment method option' do
+    context 'when confirming with invalid payment method name' do
       it 'raises an exception' do
         # Create a payment setup first
         create_response = create_payment_setup(amount: 1000)
-        
-        fake_option_id = 'invalid_option_id'
-        
+
+        fake_payment_method_name = 'invalid_payment_method'
+
         expect {
-          @api.payments_setups.confirm_payment_setup(create_response.id, fake_option_id)
+          @api.payments_setups.confirm_payment_setup(create_response.id, fake_payment_method_name)
         }.to raise_error(CheckoutSdk::CheckoutApiException)
       end
     end
 
     context 'when confirming non-existent payment setup' do
       it 'raises an exception' do
         fake_setup_id = 'ps_non_existent_id'
-        fake_option_id = 'option_id'
-        
+        fake_payment_method_name = 'klarna'
+
         expect {
-          @api.payments_setups.confirm_payment_setup(fake_setup_id, fake_option_id)
+          @api.payments_setups.confirm_payment_setup(fake_setup_id, fake_payment_method_name)
         }.to raise_error(CheckoutSdk::CheckoutApiException)
       end
     end
@@ -182,9 +189,9 @@
 
         # Step 4: Attempt to confirm (might skip if no options available in sandbox)
         unless get_response.payment_method_options.nil? || get_response.payment_method_options.empty?
-          payment_method_option_id = get_response.payment_method_options.first['id']
-          
-          confirm_response = @api.payments_setups.confirm_payment_setup(create_response.id, payment_method_option_id)
+          payment_method_name = get_response.payment_method_options.first['type']
+
+          confirm_response = @api.payments_setups.confirm_payment_setup(create_response.id, payment_method_name)
           expect(confirm_response.id).not_to be nil
           expect(confirm_response.amount).to eq(1000)
           expect(confirm_response.status).not_to be nil