checkout_sdk 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d496e04f8a60b750fdd7a6bc7c9f8bde76ee833c436b706523066e18d71d2fc7
-  data.tar.gz: 8be2c185284697143ff7caf40146ffb1e068ba507ad1ab9acc8a87f06411731d
+  metadata.gz: 8ab7d38f61ed5faeabcf716c00ead8f3863b96ead74abd6c3e2835617d8090c5
+  data.tar.gz: 70b87b4515f6084c189956b6e7d9360a4e96686e91a1bdc293207748302b9f21
 SHA512:
-  metadata.gz: 6bdd1474da6e0172ab1a935756b9bee04d7f533ae60107332337b9ee1ef98623af15474d3f52f228065515397c280bfebdc5f3eff1bec62c9859eb7e38ccc7ff
-  data.tar.gz: e37204701650121c179389ec329d96f6cc42b6e55334a5852ea0806543a9774377fa4efcad67b11d159fb29cf62fa895d2868b64308a22a72b332354096ff35b
+  metadata.gz: 15700b0fe9e01a5d21f8a4b88971c729de748f79b8d213a7e695575c492c4d1f61781e43075228695ee429b3d5172cb8475541fb41122acc17a19d82a7319422
+  data.tar.gz: 1d271293014b5535cb92b87cb7bff5b3ada0021dca9824560c432e0ece531ecdedfacff7ff8f312fe36eb9a285339d7f1bc04e8c8f51a9be998427b1f65933cb

data/lib/checkout_sdk/balances/balances.rb

@@ -4,4 +4,7 @@ require 'checkout_sdk/balances/balances_query'
 require 'checkout_sdk/balances/collateral_breakdown'
 require 'checkout_sdk/balances/balance_values'
 require 'checkout_sdk/balances/currency_account_balance'
+require 'checkout_sdk/balances/top_up_funding_details'
+require 'checkout_sdk/balances/top_up_bank_details'
+require 'checkout_sdk/balances/top_up_instructions'
 require 'checkout_sdk/balances/balances_client'

data/lib/checkout_sdk/balances/balances_client.rb

@@ -4,7 +4,10 @@ module CheckoutSdk
   module Balances
     class BalancesClient < Client
       BALANCES = 'balances'
-      private_constant :BALANCES
+      ENTITIES = 'entities'
+      CURRENCY_ACCOUNTS = 'currency-accounts'
+      TOP_UP_INSTRUCTIONS = 'top-up-instructions'
+      private_constant :BALANCES, :ENTITIES, :CURRENCY_ACCOUNTS, :TOP_UP_INSTRUCTIONS
 
       # @param [ApiClient] api_client
       # @param [CheckoutConfiguration] configuration
@@ -12,11 +15,42 @@ module CheckoutSdk
         super(api_client, configuration, CheckoutSdk::AuthorizationType::SECRET_KEY_OR_OAUTH)
       end
 
-      # @param [String] entity_id
-      # @param [String] balances_query
+      # Retrieves the balances for each sub-account belonging to an entity.
+      #
+      # @param [String] entity_id the ID of the entity
+      # @param [String, BalancesQuery] balances_query a raw query string
+      #   (e.g. "currency:GBP") or a {BalancesQuery}
+      # @return [Hash] the balances response
       def retrieve_entity_balances(entity_id, balances_query)
         api_client.invoke_get(build_path(BALANCES, entity_id), sdk_authorization, balances_query)
       end
+
+      # Retrieves the bank details required to top up a sub-account, along with the payment
+      # reference that attributes an incoming payment to that sub-account.
+      #
+      # Note: The sub-account is referred to as currency account in the API.
+      #
+      # The response maps to {TopUpInstructions}, whose `bank_details` is a {TopUpBankDetails}
+      # holding up to two {TopUpFundingDetails} rails. Neither rail is guaranteed.
+      #
+      # @param [String] entity_id the ID of the entity that owns the sub-account, or of an entity
+      #   above it in your hierarchy; a platform can use its own entity ID to reach the
+      #   sub-accounts of any entity beneath it
+      # @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.
+      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?
+
+        api_client.invoke_get(
+          build_path(ENTITIES, entity_id, CURRENCY_ACCOUNTS, currency_account_id, TOP_UP_INSTRUCTIONS),
+          sdk_authorization
+        )
+      end
     end
   end
 end

data/lib/checkout_sdk/balances/top_up_bank_details.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Balances
+    # The bank details for each available funding rail (swagger schema: TopUpBankDetails).
+    #
+    # Both `domestic` and `international` are optional, and their availability depends on the
+    # sub-account's holding currency, jurisdiction, and banking partner. Do not assume that both
+    # rails are always available; neither may be present.
+    #
+    # @!attribute domestic
+    #   [Optional]
+    #   @return [TopUpFundingDetails] The bank details for the domestic funding rail.
+    # @!attribute international
+    #   [Optional]
+    #   @return [TopUpFundingDetails] The bank details for the international funding rail.
+    class TopUpBankDetails
+      attr_accessor :domestic,
+                    :international
+    end
+  end
+end

data/lib/checkout_sdk/balances/top_up_funding_details.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Balances
+    # The bank details for a single funding rail (swagger schema: TopUpFundingDetails).
+    #
+    # `beneficiary_account_name` and `bank_name` are the only fields always returned. The
+    # remaining fields vary by rail and the receiving bank's jurisdiction, and are omitted when
+    # they do not apply.
+    #
+    # @!attribute beneficiary_account_name
+    #   [Required]
+    #   @return [String] The name of the account that receives the funds.
+    # @!attribute beneficiary_address
+    #   [Optional]
+    #   @return [String] The address of the beneficiary, if the rail requires it.
+    # @!attribute bank_name
+    #   [Required]
+    #   @return [String] The name of the bank that receives the funds.
+    # @!attribute bank_address
+    #   [Optional]
+    #   @return [String] The address of the receiving bank, if the rail requires it.
+    # @!attribute account_number
+    #   [Optional]
+    #   @return [String] The account number of the receiving account.
+    # @!attribute sort_code
+    #   [Optional]
+    #   @return [String] The sort code of the receiving bank. Returned for United Kingdom
+    #     domestic transfers.
+    # @!attribute routing_number
+    #   [Optional]
+    #   @return [String] The routing number of the receiving bank. Returned for United States
+    #     domestic transfers.
+    # @!attribute iban
+    #   [Optional]
+    #   @return [String] The International Bank Account Number of the receiving account.
+    # @!attribute swift_code
+    #   [Optional]
+    #   @return [String] The SWIFT or BIC code of the receiving bank. Returned for
+    #     international transfers.
+    class TopUpFundingDetails
+      attr_accessor :beneficiary_account_name,
+                    :beneficiary_address,
+                    :bank_name,
+                    :bank_address,
+                    :account_number,
+                    :sort_code,
+                    :routing_number,
+                    :iban,
+                    :swift_code
+    end
+  end
+end

data/lib/checkout_sdk/balances/top_up_instructions.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Balances
+    # The bank details and payment reference used to top up a sub-account
+    # (swagger schema: TopUpInstructionsResponse).
+    #
+    # Returned by
+    # GET /entities/{entityId}/currency-accounts/{currencyAccountId}/top-up-instructions.
+    #
+    # @!attribute currency_account_id
+    #   [Required]
+    #   @return [String] The unique identifier of the sub-account that the instructions apply to.
+    # @!attribute currency
+    #   [Required]
+    #   @return [String] {CheckoutSdk::Common::Currency} The currency that funds must be sent in,
+    #     as a three-letter ISO 4217 currency code. This is the sub-account's holding currency,
+    #     returned as `holding_currency` by the Retrieve entity balances endpoint.
+    # @!attribute payment_reference
+    #   [Required]
+    #   @return [String] The reference that must be quoted on the payment. It is how an incoming
+    #     payment is attributed to the sub-account. A payment sent without this reference may not
+    #     be credited.
+    # @!attribute bank_details
+    #   [Required]
+    #   @return [TopUpBankDetails] The bank details for each available funding rail.
+    class TopUpInstructions
+      attr_accessor :currency_account_id,
+                    :currency,
+                    :payment_reference,
+                    :bank_details
+    end
+  end
+end

data/lib/checkout_sdk/json_serializer.rb

@@ -6,7 +6,9 @@ module CheckoutSdk
                              account_holder_type: 'account-holder-type',
                              payment_network: 'payment-network',
                              from_: 'from',
-                             if_match: 'if-match' }.freeze
+                             if_match: 'if-match',
+                             with_currency_account_id: 'withCurrencyAccountId',
+                             balances_at: 'balancesAt' }.freeze
 
     def self.to_custom_hash(object)
       hash = {}

data/lib/checkout_sdk/oauth_scopes.rb

@@ -36,6 +36,7 @@ module CheckoutSdk
     TRANSFERS_VIEW = 'transfers:view'
     BALANCES = 'balances'
     BALANCES_VIEW = 'balances:view'
+    BALANCES_TOP_UP_INSTRUCTIONS = 'balances:top-up-instructions'
     MIDDLEWARE = 'middleware'
     MIDDLEWARE_MERCHANTS_SECRET = 'middleware:merchants-secret'
     MIDDLEWARE_MERCHANTS_PUBLIC = 'middleware:merchants-public'

data/lib/checkout_sdk/payments/flow/flow_client.rb

@@ -32,8 +32,14 @@ module CheckoutSdk
       # Use this endpoint to submit payment details and process the payment for an existing session.
       # [Beta]
       #
+      # The request accepts `amount_allocations`: the sub-entities the payment is being
+      # processed on behalf of, min 1 max 50 items. Each entry maps to
+      # {CheckoutSdk::Common::AmountAllocations} (id, amount, reference, commission), where `id`
+      # and `amount` are required.
+      #
       # @param [String] id - The unique identifier of the Payment Session
       # @param [Hash] submit_payment_session_request
+      # @return [Hash] the payment submission response
       def submit_payment_session(id, submit_payment_session_request)
         api_client.invoke_post(
           build_path(PAYMENT_SESSIONS_PATH, id, SUBMIT_PATH),

data/lib/checkout_sdk/payments/payments.rb

@@ -210,6 +210,9 @@ require 'checkout_sdk/payments/setups/account_funding_transaction_identification
 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'

data/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

data/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

data/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

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

@@ -22,6 +22,9 @@ module CheckoutSdk
       # [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 @@ module CheckoutSdk
       #
       # @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 @@ module CheckoutSdk
       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

data/lib/checkout_sdk/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: checkout_sdk
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Checkout
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-07 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -250,6 +250,9 @@ files:
 - lib/checkout_sdk/balances/balances_query.rb
 - lib/checkout_sdk/balances/collateral_breakdown.rb
 - lib/checkout_sdk/balances/currency_account_balance.rb
+- lib/checkout_sdk/balances/top_up_bank_details.rb
+- lib/checkout_sdk/balances/top_up_funding_details.rb
+- lib/checkout_sdk/balances/top_up_instructions.rb
 - lib/checkout_sdk/checkout_api.rb
 - lib/checkout_sdk/checkout_configuration.rb
 - lib/checkout_sdk/checkout_oauth_sdk_builder.rb
@@ -564,6 +567,9 @@ files:
 - lib/checkout_sdk/payments/setups/card_present_payment_method.rb
 - lib/checkout_sdk/payments/setups/pay_by_bank_payment_method.rb
 - lib/checkout_sdk/payments/setups/payment_setup_account_funding_transaction.rb
+- lib/checkout_sdk/payments/setups/payment_setup_billing_descriptor.rb
+- lib/checkout_sdk/payments/setups/payment_setup_presentment_details.rb
+- lib/checkout_sdk/payments/setups/payment_setup_terminal.rb
 - lib/checkout_sdk/payments/setups/payment_setups_client.rb
 - lib/checkout_sdk/payments/setups/stablecoin_payment_method.rb
 - lib/checkout_sdk/payments/shipping_details.rb