checkout_sdk 1.12.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7c26660018aea61f28d8d1e742c57948b6ebadadb0440e245ca45eb14d53eede
-  data.tar.gz: 3192d546b4240013ac01de9de0411f6654a974e465e285529f36d3df666f345c
+  metadata.gz: d496e04f8a60b750fdd7a6bc7c9f8bde76ee833c436b706523066e18d71d2fc7
+  data.tar.gz: 8be2c185284697143ff7caf40146ffb1e068ba507ad1ab9acc8a87f06411731d
 SHA512:
-  metadata.gz: 1791fa5f04fe3a5628e4804312fc778ff407398f657e47c1b51e85844251e4e28f81d88593a994b0318212fc016eb42f392f6de2612dc856aad55430783e7558
-  data.tar.gz: cf4e630a4fd64a029bae0238c0e32bbdb0ab1a4576324fe31a7d09e74bfd54842440baf2725837527118d78d0b2a36b100f2051701c5fa50926c31bae4250c88
+  metadata.gz: 6bdd1474da6e0172ab1a935756b9bee04d7f533ae60107332337b9ee1ef98623af15474d3f52f228065515397c280bfebdc5f3eff1bec62c9859eb7e38ccc7ff
+  data.tar.gz: e37204701650121c179389ec329d96f6cc42b6e55334a5852ea0806543a9774377fa4efcad67b11d159fb29cf62fa895d2868b64308a22a72b332354096ff35b

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

@@ -9,3 +9,8 @@ require 'checkout_sdk/apm/previous/klarna/order_capture_request'
 require 'checkout_sdk/apm/previous/klarna/klarna_client'
 require 'checkout_sdk/apm/previous/sepa/sepa_client'
 require 'checkout_sdk/apm/ideal/ideal_client'
+
+# Bacs
+require 'checkout_sdk/apm/bacs/bacs_notification_type'
+require 'checkout_sdk/apm/bacs/bacs_notification_request'
+require 'checkout_sdk/apm/bacs/bacs_client'

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

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Apm
+    # Bacs Direct Debit client.
+    class BacsClient < Client
+      APMS = 'apms'
+      BACS_NOTIFICATIONS = 'bacs/notifications'
+      private_constant :APMS, :BACS_NOTIFICATIONS
+
+      # @param [ApiClient] api_client
+      # @param [CheckoutConfiguration] configuration
+      def initialize(api_client, configuration)
+        super(api_client, configuration, CheckoutSdk::AuthorizationType::SECRET_KEY)
+      end
+
+      # Sends a Bacs Direct Debit pre-notification (advance notice) to a payer ahead
+      # of collecting funds from their account.
+      #
+      # @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),
+                               sdk_authorization,
+                               bacs_notification_request)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Apm
+    # Bacs Direct Debit notification request.
+    #
+    # @!attribute source_id
+    #   @return [String] The ID of the Bacs Direct Debit instrument to notify
+    #     against. [Required] Pattern: ^(src)_(\w{26})$
+    # @!attribute notification_type
+    #   @return [String] {BacsNotificationType} The type of pre-notification being
+    #     sent to the payer. [Required]
+    # @!attribute collection_date
+    #   @return [String] The date the funds will be collected from the payer's
+    #     account, in the format yyyy-MM-dd. [Required]
+    #     Format: date - pass a yyyy-MM-dd String, not a DateTime.
+    # @!attribute amount
+    #   @return [Integer] The amount to be collected, in the currency's minor unit.
+    #     [Required] min 1
+    # @!attribute currency
+    #   @return [String] {CheckoutSdk::Common::Currency} The three-letter ISO 4217
+    #     currency code of the collection. [Required] min 3 characters,
+    #     max 3 characters.
+    # @!attribute billing_descriptor
+    #   @return [String] The billing descriptor that appears on the payer's bank
+    #     statement. [Required] max 25 characters.
+    # @!attribute customer_email
+    #   @return [String] The email address of the payer that the pre-notification is
+    #     sent to. [Required] Format: email
+    # @!attribute support_email
+    #   @return [String] The support email address included in the pre-notification.
+    #     [Required] Format: email
+    # @!attribute reference
+    #   @return [String] A reference you can use to identify the collection.
+    #     [Optional] max 50 characters.
+    # @!attribute support_phone
+    #   @return [String] The support phone number included in the pre-notification,
+    #     in E.164 format. [Optional]
+    class BacsNotificationRequest
+      attr_accessor :source_id,
+                    :notification_type,
+                    :collection_date,
+                    :amount,
+                    :currency,
+                    :billing_descriptor,
+                    :customer_email,
+                    :support_email,
+                    :reference,
+                    :support_phone
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Apm
+    # The type of pre-notification being sent to the payer.
+    module BacsNotificationType
+      ADVANCE_NOTICE = 'advance_notice'
+    end
+  end
+end

data/lib/checkout_sdk/checkout_api.rb

@@ -73,6 +73,8 @@ module CheckoutSdk
   #   @return [CheckoutSdk::Identities::IdentityVerification::IdentityVerificationClient]
   # @!attribute face_authentication
   #   @return [CheckoutSdk::Identities::FaceAuthentication::FaceAuthenticationClient]
+  # @!attribute bacs
+  #   @return [CheckoutSdk::Apm::BacsClient]
   # @!attribute apple_pay
   #   @return [CheckoutSdk::Payments::ApplePayClient]
   # @!attribute google_pay
@@ -91,6 +93,7 @@ module CheckoutSdk
                 :sessions,
                 :tokens,
                 :ideal,
+                :bacs,
                 :accounts,
                 :workflows,
                 :risk,
@@ -131,6 +134,7 @@ module CheckoutSdk
       @sessions = CheckoutSdk::Sessions::SessionsClient.new api_client, configuration
       @tokens = CheckoutSdk::Tokens::TokensClient.new api_client, configuration
       @ideal = CheckoutSdk::Apm::IdealClient.new api_client, configuration
+      @bacs = CheckoutSdk::Apm::BacsClient.new api_client, configuration
       @workflows = CheckoutSdk::Workflows::WorkflowsClient.new api_client, configuration
       @accounts = CheckoutSdk::Accounts::AccountsClient.new(api_client, files_client(configuration), configuration)
       @risk = CheckoutSdk::Risk::RiskClient.new api_client, configuration

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/common/account_holder_type.rb

@@ -2,9 +2,25 @@
 
 module CheckoutSdk
   module Common
+    # The type of account holder.
+    #
+    # For stored instruments use {CheckoutSdk::Instruments::InstrumentAccountHolderType},
+    # whose schemas declare individual and corporate only.
     module AccountHolderType
       INDIVIDUAL = 'individual'
       CORPORATE = 'corporate'
+
+      # Declared by the account-holder positions (AccountHolder, AccountHolderAch,
+      # PaymentSetupAccountHolder, RefundDestinationAccountHolder and the card-payout
+      # destination and sender) but **not** by any sender schema -
+      # PaymentRequestSender, PayoutSender, PaymentDetailsResponseSender and
+      # PaymentInterfacesSender all omit it. Do not send it as a sender type.
+      GOVERNMENT = 'government'
+
+      # Declared only by the payment and payout *sender* schemas
+      # (PaymentRequestSender, PayoutSender, PaymentDetailsResponseSender), never by
+      # an account-holder position. Retained rather than removed because removal is
+      # breaking; prefer the sender-specific type where one exists.
       INSTRUMENT = 'instrument'
     end
   end

data/lib/checkout_sdk/common/customer_request.rb

@@ -2,18 +2,30 @@
 
 module CheckoutSdk
   module Common
+    # The customer's details.
+    #
+    # This type serves two positions with different property sets. The payments
+    # position (swagger `CustomerRequest`) declares all six properties below. The
+    # instrument position (swagger `StoreCustomerInstrumentRequest`, used by
+    # {CheckoutSdk::Instruments::InstrumentBacs}, {CheckoutSdk::Instruments::InstrumentSepa}
+    # and {CheckoutSdk::Instruments::InstrumentAch}) declares every property except
+    # tax_number - do not send tax_number when storing an instrument.
+    #
     # @!attribute id
     #   @return [String]
     # @!attribute email
     #   @return [String]
     # @!attribute name
-    #   @return [String]
+    #   @return [String] Only sets the name for *new* customers.
     # @!attribute tax_number
-    #   @return [String]
+    #   @return [String] Payments position only. Not declared by
+    #     StoreCustomerInstrumentRequest.
     # @!attribute phone
     #   @return [Phone]
     # @!attribute default
-    #   @return [TrueClass, FalseClass]
+    #   @return [TrueClass, FalseClass] If true, this instrument becomes the default
+    #     for the customer. An instrument is automatically the default when the
+    #     request creates a new customer.
     class CustomerRequest
       attr_accessor :id,
                     :email,

data/lib/checkout_sdk/common/instrument_type.rb

@@ -2,11 +2,19 @@
 
 module CheckoutSdk
   module Common
+    # The type of a payment instrument.
     module InstrumentType
       BANK_ACCOUNT = 'bank_account'
       TOKEN = 'token'
       CARD = 'card'
       SEPA = 'sepa'
+
+      # Current API (NAS) only. The previous API (ABC) instrument schemas declare
+      # neither of these, so do not use them with a previous-platform client.
+      ACH = 'ach'
+      BACS = 'bacs'
+
+      # Previous API (ABC) only. Not declared by any current-API instrument schema.
       CARD_TOKEN = 'card_token'
     end
   end

data/lib/checkout_sdk/common/payment_source_type.rb

@@ -2,6 +2,19 @@
 
 module CheckoutSdk
   module Common
+    # The type of a payment source or destination.
+    #
+    # This module is shared by the current API (NAS) and the previous API (ABC),
+    # which is still actively maintained. These 22 values are declared by neither
+    # `PaymentRequestSourceType` nor `PaymentDetailsResponseSourceType` in the
+    # current specification and are **previous API (ABC) only**:
+    #
+    #   afterpay, alipay, applepay, baloto, bank_account, benefit, benefitpay,
+    #   boleto, cvconnect, dlocal, giropay, googlepay, illicado, oxxo, pagofacil,
+    #   poli, postfinance, provider_token, rapipago, sofort, tabby, trustly
+    #
+    # Use them only with a previous-platform client. Every other value below is
+    # current-API.
     module PaymentSourceType
       CARD = 'card'
       ID = 'id'
@@ -54,10 +67,16 @@ module CheckoutSdk
       ILLICADO = 'illicado'
       SEPA = 'sepa'
       ACH = 'ach'
+      BACS = 'bacs'
       BIZUM = 'bizum'
       OCTOPUS = 'octopus'
       PLAID = 'plaid'
       SEQURA = 'sequra'
+      MOBILEPAY = 'mobilepay'
+      PAYNOW = 'paynow'
+      SWISH = 'swish'
+      TWINT = 'twint'
+      VIPPS = 'vipps'
       TABBY = 'tabby'
       APPLEPAY = 'applepay'
       GOOGLEPAY = 'googlepay'

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/instruments/ach_account_type.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The type of Direct Debit account on an ACH instrument.
+    #
+    # The ACH instrument schemas declare savings and checking only. The ACH payment
+    # source additionally declares cash - see {CheckoutSdk::Common::AccountType}.
+    module AchAccountType
+      SAVINGS = 'savings'
+      CHECKING = 'checking'
+    end
+  end
+end

data/lib/checkout_sdk/instruments/bacs_payment_type.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The type of payment on a Bacs Direct Debit instrument.
+    #
+    # Declared capitalized by the Bacs instrument schemas, unlike {SepaPaymentType}
+    # which declares the same two concepts lowercase. The casing is not
+    # interchangeable and must not be unified.
+    module BacsPaymentType
+      RECURRING = 'Recurring'
+      REGULAR = 'Regular'
+    end
+  end
+end

data/lib/checkout_sdk/instruments/create/create_ach_account_holder.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Instruments
+    # The account holder details of an ACH instrument being stored.
+    #
+    # The specification lists all four properties in the schema's required array,
+    # while the individual field descriptions make them conditional on type
+    # ("Required for individual account holder type" / "Required for corporate
+    # account holder type"). The two readings contradict each other; send the pair
+    # that matches your type value.
+    #
+    # @!attribute first_name
+    #   @return [String] First name. Required for individual account holder type.
+    # @!attribute last_name
+    #   @return [String] Last name. Required for individual account holder type.
+    # @!attribute company_name
+    #   @return [String] Company name. Required for corporate account holder type.
+    # @!attribute type
+    #   @return [String] {InstrumentAccountHolderType} Account holder type.
+    #     [Required]
+    class CreateAchAccountHolder
+      attr_accessor :first_name,
+                    :last_name,
+                    :company_name,
+                    :type
+    end
+  end
+end