checkout_sdk 1.12.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c26660018aea61f28d8d1e742c57948b6ebadadb0440e245ca45eb14d53eede
-  data.tar.gz: 3192d546b4240013ac01de9de0411f6654a974e465e285529f36d3df666f345c
+  metadata.gz: c470151f96c3425b61e6c49458a3612daf2174cf3b69e92861c5932dacfe5879
+  data.tar.gz: 2201bb66edace8b6b24edb4e84decf122dde349e6418c268e68dacdb1d8239b6
 SHA512:
-  metadata.gz: 1791fa5f04fe3a5628e4804312fc778ff407398f657e47c1b51e85844251e4e28f81d88593a994b0318212fc016eb42f392f6de2612dc856aad55430783e7558
-  data.tar.gz: cf4e630a4fd64a029bae0238c0e32bbdb0ab1a4576324fe31a7d09e74bfd54842440baf2725837527118d78d0b2a36b100f2051701c5fa50926c31bae4250c88
+  metadata.gz: 9d28b90870372311da801cb4c93f3fd16933b8ee79f43954bb837c8d30f82fe2ddef2ed965a41a81611a32263bf11d2778c8f21f49c8031d0b977b9aad2d15ce
+  data.tar.gz: d2a7438c35e5815e9be95804597218ae62d7a967e92ef6285f749110a77d82cead49c1933d88994551822547ea59ce5ee41b3466f2b0773569ac11eada4dd663

data/README.md

@@ -69,6 +69,10 @@ account [here](https://www.checkout.com/get-test-account).
 
 **PLEASE NEVER SHARE OR PUBLISH YOUR CHECKOUT CREDENTIALS.**
 
+### Subdomain value
+
+Requests must be made through your merchant-specific subdomain (MSSD): the first 8 characters of your client ID (excluding `cli_`). For example, if your client ID is `cli_vkuhvk4vjn2edkps7dfsq6emqm`, your subdomain is `vkuhvk4v`. When `with_environment_subdomain` is set the SDK sends requests to `https://vkuhvk4v.api.checkout.com`. See [Base URLs](https://api-reference.checkout.com/#section/Base-URLs) and [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints) for further details, and for where to find your unique client ID. Private Link merchants use their `pl-` prefixed subdomain (for example `pl-vkuhvk4v`), which the SDK also accepts.
+
 ### Default
 
 Default keys client instantiation can be done as follows:
@@ -79,6 +83,7 @@ api = CheckoutSdk.builder
                  .with_secret_key('secret_key')
                  .with_public_key('public_key') # optional, only required for operations related with tokens
                  .with_environment(CheckoutSdk::Environment.sandbox)
+                 .with_environment_subdomain('subdomain') # required, the first 8 characters of your client ID
                  .build
 ```
 
@@ -89,10 +94,10 @@ The SDK supports client credentials OAuth, when initialized as follows:
 ```ruby
 api = CheckoutSdk.builder
                  .oauth
-                 .with_authorization_uri('https://access.sandbox.checkout.com/connect/token') # custom authorization URI, optional
                  .with_client_credentials("client_id", "client_secret")
                  .with_scopes([CheckoutSdk::OAuthScopes::VAULT, CheckoutSdk::OAuthScopes::GATEWAY]) # array of scopes
                  .with_environment(CheckoutSdk::Environment.sandbox)
+                 .with_environment_subdomain('subdomain') # required, the first 8 characters of your client ID
                  .build
 ```
 
@@ -107,6 +112,7 @@ api = CheckoutSdk.builder
                  .with_secret_key('secret_key')
                  .with_public_key('public_key') # optional, only required for operations related with tokens
                  .with_environment(CheckoutSdk::Environment.sandbox)
+                 .with_environment_subdomain('subdomain') # optional for the Previous platform
                  .build
 ```
 
@@ -267,6 +273,23 @@ If you absolutely need to skip the pre-commit hooks:
 OVERCOMMIT_DISABLE=1 git commit -m "your message"
 ```
 
+## Legacy domain (emergency use only)
+
+> :warning: **Only use if merchant specific sub domains are causing issues.** Connecting through your merchant-specific subdomain (see [Subdomain value](#subdomain-value)) is the supported way of using the Checkout.com API, and non-subdomain usage will be deprecated.
+
+If, in exceptional circumstances, you cannot use your merchant-specific subdomain, you can explicitly opt out by calling `with_legacy_domain` instead of `with_environment_subdomain`:
+
+```ruby
+api = CheckoutSdk.builder
+                 .static_keys
+                 .with_secret_key('secret_key')
+                 .with_environment(CheckoutSdk::Environment.sandbox)
+                 .with_legacy_domain # deprecated, emergency fallback only
+                 .build
+```
+
+This routes requests to `api.checkout.com` (or `api.sandbox.checkout.com`) and `access.checkout.com` (or `access.sandbox.checkout.com`). The method prints a deprecation warning. Exactly one of `with_environment_subdomain` or `with_legacy_domain` must be set: the SDK raises a `CheckoutSdk::CheckoutArgumentException` if both, or neither, are. The Previous (ABC) platform predates merchant-specific subdomains and is exempt from this requirement.
+
 ## Code of Conduct
 
 Please refer to [Code of Conduct](CODE_OF_CONDUCT.md)

data/lib/checkout_sdk/abstract_checkout_sdk_builder.rb

@@ -8,9 +8,13 @@ module CheckoutSdk
     #   @return [Faraday::Connection]
     # @!attribute multipart_http_client
     #   @return [Faraday::Connection]
-    # @!attribute environment_subdomain
-    #   @return [EnvironmentSubdomain, nil]
-    attr_accessor :environment, :http_client, :multipart_http_client, :logger, :environment_subdomain
+    # @!attribute subdomain
+    #   @return [String, nil]
+    attr_accessor :environment, :http_client, :multipart_http_client, :logger, :subdomain
+
+    def initialize
+      @use_legacy_domain = false
+    end
 
     # @param [Environment] environment
     def with_environment(environment)
@@ -37,11 +41,41 @@ module CheckoutSdk
 
     # @param [String, nil] subdomain
     def with_environment_subdomain(subdomain)
-      @environment_subdomain = EnvironmentSubdomain.new(@environment, subdomain)
+      @subdomain = subdomain
+      self
+    end
+
+    # Opts out of the merchant-specific subdomain, sending every request to the shared hosts
+    # instead (api.checkout.com and access.checkout.com, or their sandbox equivalents).
+    #
+    # @deprecated This is an emergency fallback for the rare case where the merchant-specific
+    #   subdomain cannot be used, and will be removed in a future release. Call
+    #   {#with_environment_subdomain} instead.
+    #   See https://api-reference.checkout.com/#section/Base-URLs
+    def with_legacy_domain
+      warn '[DEPRECATION] with_legacy_domain is deprecated and will be removed in a future ' \
+           'release. It is intended only as an emergency fallback when the merchant-specific ' \
+           'subdomain cannot be used. Call with_environment_subdomain instead. ' \
+           'See https://api-reference.checkout.com/#section/Base-URLs'
+      @use_legacy_domain = true
       self
     end
 
+    # @return [EnvironmentSubdomain, nil]
+    def environment_subdomain
+      return nil if subdomain.nil?
+
+      EnvironmentSubdomain.new(environment, subdomain)
+    end
+
+    # Whether this builder requires the merchant-specific subdomain to be configured. The
+    # Previous (ABC) platform predates merchant-specific subdomains, so it overrides this.
+    def requires_environment_subdomain?
+      true
+    end
+
     def build
+      validate_environment_settings
       with_environment(Environment.sandbox) if environment.nil?
       if http_client.nil?
         @http_client = CheckoutUtils.build_default_client
@@ -59,5 +93,22 @@ module CheckoutSdk
       end
       @logger = SimpleLogger.new.logger if @logger.nil?
     end
+
+    private
+
+    def validate_environment_settings
+      if !subdomain.nil? && @use_legacy_domain
+        raise CheckoutArgumentException,
+              'with_environment_subdomain and with_legacy_domain cannot both be set - provide ' \
+              'only your merchant-specific subdomain'
+      end
+      return unless subdomain.nil? && !@use_legacy_domain && requires_environment_subdomain?
+
+      raise CheckoutArgumentException,
+            'environment subdomain is required - provide your merchant-specific subdomain ' \
+            '(typically your client ID excluding the cli_ prefix, see ' \
+            'https://api-reference.checkout.com/#section/Base-URLs), or call with_legacy_domain ' \
+            'to opt out only if merchant specific sub domains are causing issues'
+    end
   end
 end

data/lib/checkout_sdk/accounts/schedule_frequency_daily.rb

@@ -2,6 +2,8 @@
 
 module CheckoutSdk
   module Accounts
+    # For SaaS sellers (ISV), a daily schedule runs on working days only (Monday to Friday);
+    # payouts do not take place on weekends.
     class ScheduleFrequencyDaily < ScheduleRequest
       def initialize
         super(ScheduleFrequencyType::DAILY)

data/lib/checkout_sdk/accounts/schedule_frequency_monthly.rb

@@ -3,7 +3,9 @@
 module CheckoutSdk
   module Accounts
     # @!attribute by_month_day
-    #   @return [Array(Integer)]
+    #   @return [Array(Integer)] The day or days of the month the payout should take place.
+    #     For SaaS sellers (ISV), only the following combinations are supported, in any order:
+    #     [1], [15], [1, 15] or [1, 16].
     class ScheduleFrequencyMonthly < ScheduleRequest
       attr_accessor :by_month_day
 

data/lib/checkout_sdk/accounts/schedule_frequency_weekly.rb

@@ -3,7 +3,9 @@
 module CheckoutSdk
   module Accounts
     # @!attribute by_day
-    #   @return [Array(String)]
+    #   @return [Array(String)] The day or days of the week the payout should take place.
+    #     For SaaS sellers (ISV), only working days (Monday to Friday) are supported;
+    #     payouts set to take place on weekends are rejected.
     class ScheduleFrequencyWeekly < ScheduleRequest
       attr_accessor :by_day
 

data/lib/checkout_sdk/accounts/update_schedule.rb

@@ -6,11 +6,22 @@ module CheckoutSdk
     #   @return [TrueClass, FalseClass]
     # @!attribute threshold
     #   @return [TrueClass, FalseClass]
+    # @!attribute balance_minimum
+    #   @return [Integer] The amount, in the minor units of the schedule's currency, to retain in the
+    #     sub-entity's available balance. SaaS sellers (ISV) only. Defaults to 0 if you do not set it.
+    # @!attribute carry_forward_enabled
+    #   @return [TrueClass, FalseClass] Indicates whether to carry forward any balance below the configured
+    #     minimum to the next payout. SaaS sellers (ISV) only. Defaults to false if you do not set it.
+    # @!attribute payment_instrument_id
+    #   @return [String] The ID of the platforms payment instrument used as the payout destination.
     # @!attribute recurrence
     #   @return [ScheduleRequest]
     class UpdateSchedule
       attr_accessor :enabled,
                     :threshold,
+                    :balance_minimum,
+                    :carry_forward_enabled,
+                    :payment_instrument_id,
                     :recurrence
     end
   end

data/lib/checkout_sdk/checkout_oauth_sdk_builder.rb

@@ -42,15 +42,8 @@ module CheckoutSdk
     def build
       super
 
-      # Determine authorization URI following Go logic
-      auth_uri = authorization_uri
-      if auth_uri.nil? || auth_uri.empty?
-        auth_uri = if environment_subdomain
-                     environment_subdomain.authorization_uri
-                   else
-                     environment.authorization_uri
-                   end
-      end
+      env_subdomain = environment_subdomain
+      auth_uri = resolve_authorization_uri(env_subdomain)
 
       configuration = CheckoutConfiguration.new(
         OAuthSdkCredentials.new(client_id,
@@ -66,9 +59,29 @@ module CheckoutSdk
         logger
       )
 
-      configuration.environment_subdomain = environment_subdomain if environment_subdomain
+      configuration.environment_subdomain = env_subdomain if env_subdomain
 
       CheckoutApi.new(configuration)
     end
+
+    private
+
+    # @param [EnvironmentSubdomain, nil] env_subdomain
+    # @return [String]
+    def resolve_authorization_uri(env_subdomain)
+      auth_uri = authorization_uri
+      explicit_uri_set = !(auth_uri.nil? || auth_uri.empty?)
+
+      if explicit_uri_set && env_subdomain
+        raise CheckoutArgumentException,
+              'authorization_uri and environment_subdomain cannot both be set - the token ' \
+              'endpoint is derived from your subdomain; combine authorization_uri with ' \
+              'with_legacy_domain if you need a custom token host'
+      end
+
+      return auth_uri if explicit_uri_set
+
+      env_subdomain ? env_subdomain.authorization_uri : environment.authorization_uri
+    end
   end
 end

data/lib/checkout_sdk/checkout_static_keys_sdk_builder.rb

@@ -19,7 +19,8 @@ module CheckoutSdk
         logger
       )
 
-      configuration.environment_subdomain = environment_subdomain if environment_subdomain
+      env_subdomain = environment_subdomain
+      configuration.environment_subdomain = env_subdomain if env_subdomain
 
       CheckoutApi.new(configuration)
     end

data/lib/checkout_sdk/environment_subdomain.rb

@@ -23,36 +23,35 @@ module CheckoutSdk
 
     private
 
-    # Applies subdomain transformation to any given URI.
-    # If the subdomain is valid (alphanumeric pattern), prepends it to the host.
-    # Otherwise, returns the original URI unchanged.
+    # Applies subdomain transformation to any given URI, prepending the subdomain to the host.
     #
     # @param original_url [String] The original URL to transform.
     # @param subdomain [String] The subdomain to prepend to the host.
-    # @return [String] The transformed URL with subdomain, or original URL if subdomain is invalid.
+    # @return [String] The transformed URL with subdomain.
+    # @raise [CheckoutArgumentException] If the subdomain is not a valid merchant-specific
+    #   subdomain.
     def create_url_with_subdomain(original_url, subdomain)
-      new_environment = original_url
-
-      if subdomain =~ /^(?:pl-)?[a-z0-9]+$/
-        url_parts = URI.parse(original_url)
-        new_host = "#{subdomain}.#{url_parts.host}"
-
-        port = url_parts.scheme == 'https' && url_parts.port == 443 ? nil : url_parts.port
+      unless subdomain =~ /\A(?:pl-)?[a-z0-9]+\z/
+        raise CheckoutArgumentException,
+              'invalid environment subdomain - provide your merchant-specific subdomain, ' \
+              'typically your client ID excluding the cli_ prefix (see ' \
+              'https://api-reference.checkout.com/#section/Base-URLs)'
+      end
 
-        new_url_parts = URI::Generic.build(
-          scheme: url_parts.scheme,
-          userinfo: url_parts.userinfo,
-          host: new_host,
-          port: port,
-          path: url_parts.path,
-          query: url_parts.query,
-          fragment: url_parts.fragment
-        )
+      url_parts = URI.parse(original_url)
+      new_host = "#{subdomain}.#{url_parts.host}"
 
-        new_environment = new_url_parts.to_s
-      end
+      port = url_parts.scheme == 'https' && url_parts.port == 443 ? nil : url_parts.port
 
-      new_environment
+      URI::Generic.build(
+        scheme: url_parts.scheme,
+        userinfo: url_parts.userinfo,
+        host: new_host,
+        port: port,
+        path: url_parts.path,
+        query: url_parts.query,
+        fragment: url_parts.fragment
+      ).to_s
     end
   end
 end

data/lib/checkout_sdk/payments/void_request.rb

@@ -2,12 +2,16 @@
 
 module CheckoutSdk
   module Payments
+    # @!attribute amount
+    #   @return [Integer] the amount to void, min 0, max 9999999999.
+    #     If not specified, the full payment amount is voided.
     # @!attribute reference
     #   @return [String]
     # @!attribute metadata
     #   @return [Hash{String => Object}]
     class VoidRequest
-      attr_accessor :reference,
+      attr_accessor :amount,
+                    :reference,
                     :metadata
     end
   end

data/lib/checkout_sdk/previous/checkout_previous_static_keys_sdk_builder.rb

@@ -7,6 +7,12 @@ module CheckoutSdk
       PUBLIC_KEY_PATTERN = '^pk_(test_)?(\\w{8})-(\\w{4})-(\\w{4})-(\\w{4})-(\\w{12})$'
       private_constant :SECRET_KEY_PATTERN, :PUBLIC_KEY_PATTERN
 
+      # The Previous (ABC) platform predates merchant-specific subdomains, so it is exempt from
+      # the mandatory with_environment_subdomain/with_legacy_domain configuration.
+      def requires_environment_subdomain?
+        false
+      end
+
       def build
         @secret_key_pattern = SECRET_KEY_PATTERN
         @public_key_pattern = PUBLIC_KEY_PATTERN
@@ -19,7 +25,8 @@ module CheckoutSdk
           logger
         )
 
-        configuration.environment_subdomain = environment_subdomain if environment_subdomain
+        env_subdomain = environment_subdomain
+        configuration.environment_subdomain = env_subdomain if env_subdomain
 
         CheckoutApi.new(configuration)
       end

data/lib/checkout_sdk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: checkout_sdk
 version: !ruby/object:Gem::Version
-  version: 1.12.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Checkout
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-08-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake