checkout_sdk 2.8.0 → 2.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26bd6c4871771d8d22c647b6724c577af0434c881b9af1433959cb1e4fdf98c8
-  data.tar.gz: b18c0c03cef39d44080aadbf798f76910c87fc84506ecb4d6dfcb9b6c67a5d76
+  metadata.gz: ddcb702f44152460535a2f068b532e473f5076ab558231ab49087fa89b85bc5e
+  data.tar.gz: 44453c69fdf11cb1e35e18d22aade6e0fdfc7bed1eeab8db230179e9439fb3f7
 SHA512:
-  metadata.gz: abbd929efceca48389c89b804075ee1c49a18a2a99532e03445ce061221a69c07545dbd1271cbb209435ca60da1209ad3c30c585d35b15a1db1d29832023fee8
-  data.tar.gz: 2bb659ec58fa5022fd17278f9d4467ab9f18b8ca47f657240c2d8da0b76724bc13d136ab865d68d90d01b81791e2a32fb886258eaa3d9edc34f3f90b5a7fcf38
+  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
@@ -172,6 +177,10 @@ api = CheckoutSdk.builder
                  .build
 ```
 
+If your connection uses the `raise_error` middleware, configure it as the default client does:
+`conn.response :raise_error, include_request: false` (the option needs Faraday 2.7.11 or later;
+the SDK leaves the request data out of the errors it raises in any case).
+
 You don't need to specify the URL for Faraday constructor the SDK grabs the belong URI from `CheckoutSdk::Environment`
 however if you want to
 use specific URI's without a proxy you can create the `Environment` object as follows.

data/lib/checkout_sdk/api_client.rb

@@ -52,10 +52,12 @@ module CheckoutSdk
       json_body = CheckoutSdk::JsonSerializer.to_custom_hash(body).to_json
 
       begin
-        @log.info "#{method}: /#{path}"
+        @log.info "#{method}: /#{CheckoutUtils.loggable_path(path)}"
         response = @client.run_request(method, path, json_body, headers)
       rescue Faraday::ClientError => e
-        raise CheckoutApiException, e.response
+        raise CheckoutApiException.new(e.response), cause: nil
+      rescue Faraday::Error => e
+        raise CheckoutUtils.without_request_data(e), cause: nil
       end
 
       parse_response(response)
@@ -140,10 +142,12 @@ module CheckoutSdk
         form = build_multipart_request(file_request, file)
 
         begin
-          @log.info "post: /#{path}"
+          @log.info "post: /#{CheckoutUtils.loggable_path(path)}"
           response = @multipart_client.run_request(:post, path, form, headers)
         rescue Faraday::ClientError => e
-          raise CheckoutApiException, e.response
+          raise CheckoutApiException.new(e.response), cause: nil
+        rescue Faraday::Error => e
+          raise CheckoutUtils.without_request_data(e), cause: nil
         end
 
         parse_response(response)

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

@@ -21,11 +21,130 @@ module CheckoutSdk
       http_metadata
     end
 
+    MAX_MESSAGE_DETAILS_LENGTH = 256
+    private_constant :MAX_MESSAGE_DETAILS_LENGTH
+
+    # Returns the request path in a form safe for a single log line: the query string is left out
+    # and control characters are escaped.
+    #
+    # @param [String, nil] path
+    # @return [String]
+    def self.loggable_path(path)
+      escape_control_characters(utf8_text(path).split('?', 2).first.to_s)
+    end
+
+    # Builds an exception message from a prefix and a response body. A JSON object body adds its
+    # "key: value" pairs as details; any other non-empty body is added as is only when
+    # include_text_body is true. Details are shortened and their control characters escaped.
+    #
+    # @param [String] prefix
+    # @param [String, nil] body
+    # @param [Boolean] include_text_body
+    # @return [String]
+    def self.error_message(prefix, body, include_text_body: false)
+      text = utf8_text(body).strip
+      parsed = json_object(text)
+      details = parsed&.map { |key, value| "#{key}: #{value}" }&.join(', ')
+      details = text if details.nil? && include_text_body
+      return prefix if details.nil? || details.empty?
+
+      details = "#{details[0, MAX_MESSAGE_DETAILS_LENGTH]}..." if details.length > MAX_MESSAGE_DETAILS_LENGTH
+      "#{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.
+    #
+    # @param [Faraday::Error] error
+    # @return [Faraday::Error]
+    def self.without_request_data(error)
+      return error if error.response.nil?
+
+      metadata = map_to_http_metadata(error.response)
+      rebuilt = error.exception(response_error_message(metadata.status_code, error.response))
+      rebuilt.instance_variable_set(:@response,
+                                    { status: metadata.status_code, headers: metadata.headers, body: metadata.body })
+      rebuilt
+    end
+
+    def self.response_error_message(status, response)
+      message = "the server responded with status #{status}"
+      request = response.is_a?(Hash) ? response[:request] : nil
+      return message unless request.is_a?(Hash) && request[:url]
+
+      "#{message} for #{request[:method].to_s.upcase} #{loggable_path(request[:url].to_s)}"
+    end
+    private_class_method :response_error_message
+
+    def self.json_object(text)
+      parsed = JSON.parse(text)
+      parsed.is_a?(Hash) ? parsed : nil
+    rescue JSON::ParserError
+      nil
+    end
+    private_class_method :json_object
+
+    # Escapes control characters and Unicode line and paragraph separators in UTF-8 text.
+    def self.escape_control_characters(text)
+      text.gsub(/[[:cntrl:]\p{Zl}\p{Zp}]/) { |char| char.dump[1..-2] }
+    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 = text.to_s
+      (to_valid_utf8(text) || text.dup.force_encoding(Encoding::UTF_8)).scrub
+    end
+    private_class_method :utf8_text
+
     # @return [Faraday::Connection]
     def self.build_multipart_client
       Faraday.new do |f|
         f.request :multipart
-        f.response :raise_error
+        f.response :raise_error, include_request: false
       end
     end
 
@@ -33,7 +152,7 @@ module CheckoutSdk
     def self.build_default_client
       Faraday.new do |f|
         f.response :follow_redirects
-        f.response :raise_error
+        f.response :raise_error, include_request: false
       end
     end
   end

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/error.rb

@@ -6,6 +6,16 @@ module CheckoutSdk
   class CheckoutArgumentException < CheckoutException; end
 
   class CheckoutAuthorizationException < CheckoutException
+    # @return [CheckoutSdk::HttpMetadata, nil] response status, headers and body when raised for an OAuth token response
+    attr_reader :http_metadata
+
+    # @param [String, nil] message
+    # @param [CheckoutSdk::HttpMetadata, nil] http_metadata
+    def initialize(message = nil, http_metadata = nil)
+      @http_metadata = http_metadata
+      super(message)
+    end
+
     def self.invalid_authorization(authorization_type)
       new("Operation requires #{authorization_type} authorization type.")
     end
@@ -13,6 +23,22 @@ module CheckoutSdk
     def self.invalid_key(key_type)
       new("#{key_type} is required for this operation.")
     end
+
+    # Builds the error for an unsuccessful OAuth token response from the response data only.
+    #
+    # @param [CheckoutSdk::HttpMetadata] http_metadata
+    # @return [CheckoutSdk::CheckoutAuthorizationException]
+    def self.token_request_failed(http_metadata)
+      prefix = "The OAuth token response status code (#{http_metadata.status_code}) does not indicate success."
+      new(CheckoutUtils.error_message(prefix, http_metadata.body, include_text_body: true), http_metadata)
+    end
+
+    # Builds the error for an OAuth token request that failed without a response.
+    #
+    # @return [CheckoutSdk::CheckoutAuthorizationException]
+    def self.token_request_without_response
+      new('The OAuth token request failed without a response.')
+    end
   end
 
   class CheckoutApiException < CheckoutException
@@ -35,12 +61,8 @@ module CheckoutSdk
     end
 
     def build_error_message
-      message = "The API response status code (#{http_metadata.status_code}) does not indicate success."
-      if @error_details && !@error_details.to_h.empty?
-        details = @error_details.to_h.map { |key, value| "#{key}: #{value}" }.join(', ')
-        message += " Details: #{details}."
-      end
-      message
+      prefix = "The API response status code (#{http_metadata.status_code}) does not indicate success."
+      CheckoutUtils.error_message(prefix, http_metadata.body)
     end
   end
 end

data/lib/checkout_sdk/events/events_client.rb

@@ -20,7 +20,7 @@ module CheckoutSdk
 
         # @param [String,nil] version
         def retrieve_all_event_types(version = nil)
-          query = "version=#{version}" unless version.nil?
+          query = URI.encode_www_form(version: version) unless version.nil?
           api_client.invoke_get(EVENT_TYPES, sdk_authorization, query)
         end
 

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/oauth_sdk_credentials.rb

@@ -65,17 +65,7 @@ module CheckoutSdk
         scope: @scopes.join(' ')
       }
 
-      headers = { 'Content-Type': 'application/x-www-form-urlencoded' }
-      body = URI.encode_www_form data
-
-      begin
-        @log.info "post: #{authorization_uri}"
-        response = @oauth_http_client.run_request(:post, @authorization_uri, body, headers)
-      rescue Faraday::ClientError => e
-        raise CheckoutAuthorizationException, e.response
-      rescue Faraday::ConnectionFailed => e
-        raise CheckoutArgumentException, e.wrapped_exception
-      end
+      response = request_access_token(URI.encode_www_form(data))
 
       if !response.body.nil? && response.body != ''
         oauth_response = JSON.parse(response.body, object_class: OpenStruct)
@@ -90,6 +80,23 @@ module CheckoutSdk
 
     private
 
+    # @param [String] body
+    # @return [Faraday::Response]
+    def request_access_token(body)
+      headers = { 'Content-Type': 'application/x-www-form-urlencoded' }
+      @log.info "post: #{CheckoutUtils.loggable_path(authorization_uri)}"
+      @oauth_http_client.run_request(:post, @authorization_uri, body, headers)
+    rescue Faraday::ClientError => e
+      raise CheckoutAuthorizationException.token_request_without_response if e.response.nil?
+
+      raise CheckoutAuthorizationException.token_request_failed(CheckoutUtils.map_to_http_metadata(e.response)),
+            cause: nil
+    rescue Faraday::ConnectionFailed => e
+      raise CheckoutArgumentException, e.wrapped_exception
+    rescue Faraday::Error => e
+      raise CheckoutUtils.without_request_data(e), cause: nil
+    end
+
     # @param [String] client_id
     # @param [String] client_secret
     # @param [Environment] environment

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.0'
+  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.0
+  version: 2.8.2
 platform: ruby
 authors:
 - Checkout
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-11-02 00:00:00.000000000 Z
+date: 2026-11-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.60'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: faraday
   requirement: !ruby/object:Gem::Requirement