checkout_sdk 2.8.1 → 2.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9849ed54d294ed9bea5fdb04bb5378fb55b942a2adb0ffe0653cb5c628cc0882
-  data.tar.gz: 7bd35374ce13e3feb72eb37a16930316ab6a01ce2cc10c49245f3e5a2daf6229
+  metadata.gz: ddcb702f44152460535a2f068b532e473f5076ab558231ab49087fa89b85bc5e
+  data.tar.gz: 44453c69fdf11cb1e35e18d22aade6e0fdfc7bed1eeab8db230179e9439fb3f7
 SHA512:
-  metadata.gz: b6f8c31a1c66aecb8b8fad6345a2b693f133b8bee59376920445caa7779db02a3f18882170318870c5f86fb728d898a4baffc32a0b71159d8b1fa4e17087c144
-  data.tar.gz: 6bdaf1a3c38c96bcafe0f52135ff77edda7a51d66946df1bc7d4b4d8e9e5729bf85f017e0a3a755567466e9132b4464428b7861ee58e56040fbf74294bc97598
+  metadata.gz: 5fc31731ba185059c64e43c7c54025fb7e61ec53df0317d6b8115cf10e131da37e187eaafa74ba0f93569ed3e8ef2ca4ac1b36a4ac5044d26f392ab8d9c4034f
+  data.tar.gz: 7318c1c93ad5979a27514c98c486985776648c19aa71544d07b026f8eb812ac1dbecd2c53531796b45f41c581785328fbda42b7c836443da4c0770d792455207

data/README.md

@@ -151,6 +151,11 @@ All the API responses that do not fall in the 2** status codes will cause a `Che
 exception
 encapsulates the `http_metadata` and a map of `error_details`, if available.
 
+Identifiers passed to client methods (for example a payment id) are sent as single, percent-encoded path
+segments: pass them unencoded. A `CheckoutSdk::CheckoutArgumentException` is raised before any request is sent
+when an identifier is `nil`, empty, `.` or `..`, cannot be converted to valid UTF-8, or contains `/`, `\` or an
+ASCII control character (U+0000 to U+001F, U+007F).
+
 ## Custom Http Client
 
 Ruby SDK supports your own configuration for `http client` using `Faraday::Connection` object, you can pass

data/lib/checkout_sdk/apm/bacs/bacs_client.rb

@@ -5,8 +5,9 @@ module CheckoutSdk
     # Bacs Direct Debit client.
     class BacsClient < Client
       APMS = 'apms'
-      BACS_NOTIFICATIONS = 'bacs/notifications'
-      private_constant :APMS, :BACS_NOTIFICATIONS
+      BACS = 'bacs'
+      NOTIFICATIONS = 'notifications'
+      private_constant :APMS, :BACS, :NOTIFICATIONS
 
       # @param [ApiClient] api_client
       # @param [CheckoutConfiguration] configuration
@@ -20,7 +21,7 @@ module CheckoutSdk
       # @param [Hash, BacsNotificationRequest] bacs_notification_request
       # @return [Hash] the BacsNotificationResponse, carrying event_id.
       def send_notification(bacs_notification_request)
-        api_client.invoke_post(build_path(APMS, BACS_NOTIFICATIONS),
+        api_client.invoke_post(build_path(APMS, BACS, NOTIFICATIONS),
                                sdk_authorization,
                                bacs_notification_request)
       end

data/lib/checkout_sdk/apm/previous/sepa/sepa_client.rb

@@ -5,10 +5,11 @@ module CheckoutSdk
     module Apm
       class SepaClient < Client
         APMS = 'apms'
-        SEPA_MANDATES = 'sepa/mandates'
+        SEPA = 'sepa'
+        MANDATES = 'mandates'
         PPRO = 'ppro'
         CANCEL = 'cancel'
-        private_constant :APMS, :SEPA_MANDATES, :PPRO, :CANCEL
+        private_constant :APMS, :SEPA, :MANDATES, :PPRO, :CANCEL
 
         # @param [ApiClient] api_client
         # @param [CheckoutConfiguration] configuration
@@ -18,22 +19,22 @@ module CheckoutSdk
 
         # @param mandate_id [String]
         def get_mandate(mandate_id)
-          api_client.invoke_get(build_path(SEPA_MANDATES, mandate_id), sdk_authorization)
+          api_client.invoke_get(build_path(SEPA, MANDATES, mandate_id), sdk_authorization)
         end
 
         # @param mandate_id [String]
         def cancel_mandate(mandate_id)
-          api_client.invoke_post(build_path(SEPA_MANDATES, mandate_id, CANCEL), sdk_authorization)
+          api_client.invoke_post(build_path(SEPA, MANDATES, mandate_id, CANCEL), sdk_authorization)
         end
 
         # @param mandate_id [String]
         def get_mandate_via_ppro(mandate_id)
-          api_client.invoke_get(build_path(APMS, PPRO, SEPA_MANDATES, mandate_id), sdk_authorization)
+          api_client.invoke_get(build_path(APMS, PPRO, SEPA, MANDATES, mandate_id), sdk_authorization)
         end
 
         # @param mandate_id [String]
         def cancel_mandate_via_ppro(mandate_id)
-          api_client.invoke_post(build_path(APMS, PPRO, SEPA_MANDATES, mandate_id, CANCEL), sdk_authorization)
+          api_client.invoke_post(build_path(APMS, PPRO, SEPA, MANDATES, mandate_id, CANCEL), sdk_authorization)
         end
       end
     end

data/lib/checkout_sdk/balances/balances_client.rb

@@ -39,9 +39,8 @@ module CheckoutSdk
       # @param [String] currency_account_id the ID of the sub-account to retrieve top-up
       #   instructions for
       # @return [Hash] the top-up instructions response
-      # @raise [CheckoutArgumentException] if either path parameter is nil, empty or blank. Both
-      #   segments are interpolated straight into the request path, so a blank value would build a
-      #   malformed URL and be rejected by the API rather than by the SDK.
+      # @raise [CheckoutArgumentException] if either path parameter is nil, empty or blank, or is not
+      #   a valid path segment (see Client#build_path).
       def retrieve_top_up_instructions(entity_id, currency_account_id)
         raise CheckoutArgumentException, 'entity_id cannot be blank' if entity_id.to_s.strip.empty?
         raise CheckoutArgumentException, 'currency_account_id cannot be blank' if currency_account_id.to_s.strip.empty?

data/lib/checkout_sdk/checkout_utils.rb

@@ -52,6 +52,37 @@ module CheckoutSdk
       "#{prefix} Details: #{escape_control_characters(details)}."
     end
 
+    INVALID_PATH_SEGMENTS = ['', '.', '..'].freeze
+    FORBIDDEN_PATH_SEGMENT_BYTES = %r{[/\\\x00-\x1F\x7F]}n.freeze
+    INVALID_PATH_SEGMENT_MESSAGE = "Invalid path segment: it must be valid text, not nil, empty, '.' or '..', " \
+                                   "and must not contain '/', '\\' or ASCII control characters"
+    private_constant :INVALID_PATH_SEGMENTS, :FORBIDDEN_PATH_SEGMENT_BYTES, :INVALID_PATH_SEGMENT_MESSAGE
+
+    # Encodes a value as one RFC 3986 path segment. The value is converted to UTF-8 and every byte
+    # outside the unreserved set (A-Z, a-z, 0-9, "-", ".", "_", "~") is percent-encoded, so the value
+    # always stays a single segment of the request path. The checks run on the converted text.
+    #
+    # @param [String, Symbol, Integer] value
+    # @return [String]
+    # @raise [CheckoutArgumentException] when the value is nil, empty, "." or "..", cannot be converted
+    #   to valid UTF-8, contains "/", "\" or an ASCII control character (U+0000 to U+001F, U+007F), or
+    #   its to_s does not return a String
+    def self.encode_path_segment(value)
+      text = value.nil? ? '' : value.to_s
+      raise CheckoutArgumentException, INVALID_PATH_SEGMENT_MESSAGE unless text.is_a?(String)
+
+      bytes = to_valid_utf8(text)&.b
+      if bytes.nil? || FORBIDDEN_PATH_SEGMENT_BYTES.match?(bytes)
+        raise CheckoutArgumentException, INVALID_PATH_SEGMENT_MESSAGE
+      end
+
+      encoded = bytes.gsub(/[^A-Za-z0-9\-._~]/n) { |byte| format('%%%02X', byte.ord) }
+                     .force_encoding(Encoding::UTF_8)
+      raise CheckoutArgumentException, INVALID_PATH_SEGMENT_MESSAGE if INVALID_PATH_SEGMENTS.include?(encoded)
+
+      encoded
+    end
+
     # Returns a copy of the Faraday error, of the same class and with the same backtrace and wrapped
     # exception, that keeps only the response status, headers and body and whose message names the
     # method and URL without the query string. Errors without a response are returned unchanged.
@@ -91,8 +122,21 @@ module CheckoutSdk
     end
     private_class_method :escape_control_characters
 
+    # Converts text to UTF-8, transcoding from its own encoding. Returns nil when the text cannot be
+    # converted or the result is not valid UTF-8.
+    def self.to_valid_utf8(text)
+      converted = text.encode(Encoding::UTF_8)
+      converted.valid_encoding? ? converted : nil
+    rescue EncodingError
+      nil
+    end
+    private_class_method :to_valid_utf8
+
+    # Lenient form of to_valid_utf8 for log and message text: bytes that cannot be converted are read
+    # as UTF-8 and invalid sequences are replaced.
     def self.utf8_text(text)
-      text.to_s.dup.force_encoding(Encoding::UTF_8).scrub
+      text = text.to_s
+      (to_valid_utf8(text) || text.dup.force_encoding(Encoding::UTF_8)).scrub
     end
     private_class_method :utf8_text
 

data/lib/checkout_sdk/client.rb

@@ -23,9 +23,15 @@ module CheckoutSdk
       @configuration = configuration
     end
 
-    # @param [Array] args
+    # Joins the arguments into a request path. Each argument is one path segment and is
+    # percent-encoded, so it never adds segments, a query or a fragment.
+    #
+    # @param [Array<String, Symbol, Integer>] args
+    # @return [String]
+    # @raise [CheckoutArgumentException] when an argument is not a valid path segment (see
+    #   CheckoutUtils.encode_path_segment)
     def build_path(*args)
-      args.join('/')
+      args.map { |segment| CheckoutUtils.encode_path_segment(segment) }.join('/')
     end
 
     # @return [TrueClass, FalseClass]

data/lib/checkout_sdk/instruments/instruments_client.rb

@@ -3,8 +3,9 @@
 module CheckoutSdk
   module Instruments
     class InstrumentsClient < BaseInstrumentsClient
-      VALIDATION = 'validation/bank-accounts'
-      private_constant :VALIDATION
+      VALIDATION = 'validation'
+      BANK_ACCOUNTS = 'bank-accounts'
+      private_constant :VALIDATION, :BANK_ACCOUNTS
 
       # @param [ApiClient] api_client
       # @param [CheckoutConfiguration] configuration
@@ -29,7 +30,7 @@ module CheckoutSdk
       # @param [String] currency {CheckoutSdk::Common::Currency}
       # @param [Hash, BankAccountFieldQuery] bank_account_field_query
       def get_bank_account_field_formatting(country, currency, bank_account_field_query)
-        api_client.invoke_get(build_path(VALIDATION, country, currency),
+        api_client.invoke_get(build_path(VALIDATION, BANK_ACCOUNTS, country, currency),
                               sdk_authorization(CheckoutSdk::AuthorizationType::OAUTH),
                               bank_account_field_query)
       end

data/lib/checkout_sdk/payments/setups/payment_setups_client.rb

@@ -248,6 +248,8 @@ module CheckoutSdk
       #   :schemes (supported card scheme names; Google Pay never lists cartes_bancaires) and card
       #   details :last4, :bin, :scheme (Strings) and :expires_on (date-time); instrument returns the
       #   read-only :type (String) and :action (:type, "set_instrument").
+      # @raise [CheckoutArgumentException] when id or payment_method_name is not a valid path segment
+      #   (see Client#build_path)
       def confirm_payment_setup(id, payment_method_name)
         api_client.invoke_post(
           build_path(PAYMENTS_PATH, SETUPS_PATH, id, CONFIRM_PATH, payment_method_name),

data/lib/checkout_sdk/risk/risk_client.rb

@@ -5,9 +5,11 @@ module CheckoutSdk
     #   @deprecated Risk endpoints are no longer supported officially, This module will be removed in a
     # future release.
     class RiskClient < Client
-      PRE_AUTHENTICATION = 'risk/assessments/pre-authentication'
-      PRE_CAPTURE = 'risk/assessments/pre-capture'
-      private_constant :PRE_AUTHENTICATION, :PRE_CAPTURE
+      RISK = 'risk'
+      ASSESSMENTS = 'assessments'
+      PRE_AUTHENTICATION = 'pre-authentication'
+      PRE_CAPTURE = 'pre-capture'
+      private_constant :RISK, :ASSESSMENTS, :PRE_AUTHENTICATION, :PRE_CAPTURE
 
       # @param [ApiClient] api_client
       # @param [CheckoutConfiguration] configuration
@@ -17,12 +19,14 @@ module CheckoutSdk
 
       # @param [Hash, PreAuthenticationAssessment] pre_authentication_request
       def pre_authentication_scan(pre_authentication_request)
-        api_client.invoke_post(PRE_AUTHENTICATION, sdk_authorization, pre_authentication_request)
+        api_client.invoke_post(build_path(RISK, ASSESSMENTS, PRE_AUTHENTICATION),
+                               sdk_authorization,
+                               pre_authentication_request)
       end
 
       # @param [Hash, PreCaptureAssessment] pre_capture_request
       def pre_capture_scan(pre_capture_request)
-        api_client.invoke_post(PRE_CAPTURE, sdk_authorization, pre_capture_request)
+        api_client.invoke_post(build_path(RISK, ASSESSMENTS, PRE_CAPTURE), sdk_authorization, pre_capture_request)
       end
     end
   end

data/lib/checkout_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CheckoutSdk
-  VERSION = '2.8.1'
+  VERSION = '2.8.2'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: checkout_sdk
 version: !ruby/object:Gem::Version
-  version: 2.8.1
+  version: 2.8.2
 platform: ruby
 authors:
 - Checkout
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-11-04 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake