checkout_sdk 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70605c20e50863e9e8fb6d63165387290f09d7ee9df7085aab98773308c9a791
-  data.tar.gz: 423b97c81d8fd1c881f9e78e6ca36ae567cf11f0e2bfcced3820df4e67e00cd2
+  metadata.gz: d6c3aef40d718427d47878b6c6174bfcb1a2f4274c51db158efebfc1fdecd993
+  data.tar.gz: 269022fe826ad896f0125dc3ea9e23ebb8281c69dfc6063c5aa2acf73ba83f0b
 SHA512:
-  metadata.gz: 06b37ee645dd3c8a5290efba79bb812594579749e9f4c35a66a46dbec902c9bf7154aa8cf91639fd6d874951b42f8b72af7a7597ffd8bf4ebaab9e91b92158d1
-  data.tar.gz: fbe86b60e6b66c4b3ba56b3728fe9ae02ea3f861a00a7688488864e59d473a15bd094ba9cf672eb5019a0078c5fef1ab32568b9e815c7cb863f74a62c55441be
+  metadata.gz: 67261cc04bc54a206a83a37f30fc82bb9bdda222042ba3eee48427c6fa32c485949405b89322ac47153d47391496ddfb5368cc02df6107f375657829fe573737
+  data.tar.gz: 35a1f59b1ff5de20afdb8b63957ed8fddd172dacdead62cd996129b3171f1eeeb12f44cb5dea1e59db3056cf70e7e7a8d216af88fa7d6f1124c3b4887c8487e0

data/.rubocop.yml

@@ -18,12 +18,21 @@ Metrics/ModuleLength:
 
 Metrics/MethodLength:
   Max: 25
+  Exclude:
+    # Aggregator that wires up every product client; grows with each new product.
+    - "**/checkout_api.rb"
 
 Metrics/ParameterLists:
   Max: 10
 
 Metrics/ClassLength:
-  Max: 120
+  # Raised from 120: SDK classes (e.g. ApiClient, response DTOs) grow as new
+  # API conventions and fields are adopted upstream.
+  Max: 150
+  Exclude:
+    # Endpoint-collection clients: one method per REST endpoint, grow with the API.
+    - "**/issuing_client.rb"
+    - "**/accounts_client.rb"
 
 Metrics/CyclomaticComplexity:
   Max: 10
@@ -37,6 +46,11 @@ Style/Documentation:
 Style/OpenStructUse:
   Enabled: false
 
+Naming/AccessorMethodName:
+  # The SDK consistently prefixes read endpoints with get_ to mirror the REST API
+  # (e.g. get_cardholder, get_card_details). Zero-arg variants would otherwise flag.
+  Enabled: false
+
 Naming/MethodName:
   Exclude:
     - "**/google_pay_token_data*"

data/lib/checkout_sdk/accounts/accounts.rb

@@ -36,7 +36,6 @@ require 'checkout_sdk/accounts/instrument_details_sepa'
 require 'checkout_sdk/accounts/instrument_details_card_token'
 require 'checkout_sdk/accounts/payment_instrument_request'
 require 'checkout_sdk/accounts/payment_instruments_query'
-require 'checkout_sdk/accounts/headers'
 require 'checkout_sdk/accounts/update_payment_instrument_request'
 require 'checkout_sdk/accounts/additional_document'
 require 'checkout_sdk/accounts/additional_info'
@@ -59,3 +58,13 @@ require 'checkout_sdk/accounts/shareholder_structure'
 require 'checkout_sdk/accounts/shareholder_structure_type'
 require 'checkout_sdk/accounts/tax_verification'
 require 'checkout_sdk/accounts/tax_verification_type'
+require 'checkout_sdk/accounts/submitter'
+require 'checkout_sdk/accounts/entity_requirement_reason'
+require 'checkout_sdk/accounts/entity_requirement_priority'
+require 'checkout_sdk/accounts/entity_requirement_update_status'
+require 'checkout_sdk/accounts/entity_requirement_update_request'
+require 'checkout_sdk/accounts/reserve_rule_holding_duration'
+require 'checkout_sdk/accounts/rolling_reserve_rule'
+require 'checkout_sdk/accounts/reserve_rule_update_request'
+require 'checkout_sdk/accounts/reserve_rule_create_request'
+require 'checkout_sdk/accounts/entity_files_request'

data/lib/checkout_sdk/accounts/accounts_client.rb

@@ -11,7 +11,11 @@ module CheckoutSdk
       PAYOUT_SCHEDULE = 'payout-schedules'
       FILES = 'files'
       PAYMENT_INSTRUMENTS = 'payment-instruments'
-      private_constant :ACCOUNTS, :ENTITIES, :INSTRUMENT, :PAYOUT_SCHEDULE, :FILES, :PAYMENT_INSTRUMENTS
+      REQUIREMENTS = 'requirements'
+      RESERVE_RULES = 'reserve-rules'
+      MEMBERS = 'members'
+      private_constant :ACCOUNTS, :ENTITIES, :INSTRUMENT, :PAYOUT_SCHEDULE, :FILES, :PAYMENT_INSTRUMENTS,
+                       :REQUIREMENTS, :RESERVE_RULES, :MEMBERS
 
       # @param [ApiClient] api_client
       # @param [ApiClient] files_client
@@ -93,6 +97,135 @@ module CheckoutSdk
       def upload_file(file_request)
         files_client.submit_file(FILES, sdk_authorization, file_request)
       end
+
+      # Retrieve the list of pending requirements that a sub-entity must resolve.
+      # @param [String] entity_id
+      def get_entity_requirements(entity_id)
+        api_client.invoke_get(
+          build_path(ACCOUNTS, ENTITIES, entity_id, REQUIREMENTS),
+          sdk_authorization
+        )
+      end
+
+      # Retrieve detailed information for a single requirement.
+      # @param [String] entity_id
+      # @param [String] requirement_id
+      def get_entity_requirement_details(entity_id, requirement_id)
+        api_client.invoke_get(
+          build_path(ACCOUNTS, ENTITIES, entity_id, REQUIREMENTS, requirement_id),
+          sdk_authorization
+        )
+      end
+
+      # Submit a response to resolve a requirement.
+      # @param [String] entity_id
+      # @param [String] requirement_id
+      # @param [Hash, EntityRequirementUpdateRequest] update_request
+      def resolve_entity_requirement(entity_id, requirement_id, update_request)
+        api_client.invoke_put(
+          build_path(ACCOUNTS, ENTITIES, entity_id, REQUIREMENTS, requirement_id),
+          sdk_authorization,
+          update_request
+        )
+      end
+
+      # Add a reserve rule for a sub-entity.
+      # @param [String] entity_id
+      # @param [Hash, ReserveRuleCreateRequest] reserve_rule_request
+      def add_reserve_rule(entity_id, reserve_rule_request)
+        api_client.invoke_post(
+          build_path(ACCOUNTS, ENTITIES, entity_id, RESERVE_RULES),
+          sdk_authorization,
+          reserve_rule_request
+        )
+      end
+
+      # Query reserve rules for a sub-entity.
+      # @param [String] entity_id
+      def query_reserve_rules(entity_id)
+        api_client.invoke_get(
+          build_path(ACCOUNTS, ENTITIES, entity_id, RESERVE_RULES),
+          sdk_authorization
+        )
+      end
+
+      # Retrieve a reserve rule by id.
+      # @param [String] entity_id
+      # @param [String] reserve_rule_id
+      def get_reserve_rule(entity_id, reserve_rule_id)
+        api_client.invoke_get(
+          build_path(ACCOUNTS, ENTITIES, entity_id, RESERVE_RULES, reserve_rule_id),
+          sdk_authorization
+        )
+      end
+
+      # Update a reserve rule.
+      # The API enforces optimistic concurrency: the ETag returned by GET must be
+      # echoed back via {CheckoutSdk::Common::Headers#if_match}, otherwise the
+      # API responds 428 Precondition Required.
+      # @param [String] entity_id
+      # @param [String] reserve_rule_id
+      # @param [String] etag ETag value to forward as the `If-Match` HTTP header.
+      # @param [Hash, ReserveRuleUpdateRequest] reserve_rule_request
+      def update_reserve_rule(entity_id, reserve_rule_id, etag, reserve_rule_request)
+        headers = nil
+        if !etag.nil? && !etag.empty?
+          headers = CheckoutSdk::Common::Headers.new
+          headers.if_match = etag
+        end
+
+        api_client.invoke_put(
+          build_path(ACCOUNTS, ENTITIES, entity_id, RESERVE_RULES, reserve_rule_id),
+          sdk_authorization,
+          reserve_rule_request,
+          headers
+        )
+      end
+
+      # List sub-entity members.
+      # @param [String] entity_id
+      def get_sub_entity_members(entity_id)
+        api_client.invoke_get(
+          build_path(ACCOUNTS, ENTITIES, entity_id, MEMBERS),
+          sdk_authorization
+        )
+      end
+
+      # Reinvite a sub-entity member.
+      # The API marks the request body as required; callers must provide a Hash
+      # (or `PlatformsHostedOnboardReinviteRequest`-shaped object), even if it
+      # is empty `{}` per the current swagger contract.
+      # @param [String] entity_id
+      # @param [String] user_id
+      # @param [Hash] reinvite_request Required body per swagger; pass `{}` if no fields are needed.
+      def reinvite_sub_entity_member(entity_id, user_id, reinvite_request)
+        api_client.invoke_put(
+          build_path(ACCOUNTS, ENTITIES, entity_id, MEMBERS, user_id),
+          sdk_authorization,
+          reinvite_request
+        )
+      end
+
+      # Upload a file scoped to a sub-entity. Hits POST /entities/{entityId}/files.
+      # @param [String] entity_id
+      # @param [Hash, EntityFilesRequest] file_request
+      def upload_entity_file(entity_id, file_request)
+        files_client.submit_file(
+          build_path(ENTITIES, entity_id, FILES),
+          sdk_authorization,
+          file_request
+        )
+      end
+
+      # Retrieve a file scoped to a sub-entity. Hits GET /entities/{entityId}/files/{fileId}.
+      # @param [String] entity_id
+      # @param [String] file_id
+      def get_entity_file(entity_id, file_id)
+        files_client.invoke_get(
+          build_path(ENTITIES, entity_id, FILES, file_id),
+          sdk_authorization
+        )
+      end
     end
   end
 end

data/lib/checkout_sdk/accounts/entity_files_request.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Request body for POST /entities/{entityId}/files.
+    #
+    # @!attribute purpose
+    #   @return [String] Purpose of the file (e.g. "bank_verification").
+    class EntityFilesRequest
+      attr_accessor :purpose
+    end
+  end
+end

data/lib/checkout_sdk/accounts/entity_requirement_priority.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Priority of a sub-entity requirement. "critical" if the deadline is within 7 days,
+    # otherwise "high" by default.
+    module EntityRequirementPriority
+      HIGH = 'high'
+      CRITICAL = 'critical'
+    end
+  end
+end

data/lib/checkout_sdk/accounts/entity_requirement_reason.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Reasons why a requirement was raised on a sub-entity.
+    module EntityRequirementReason
+      PERIODIC_REVIEW = 'periodic_review'
+      ATTESTATION = 'attestation'
+    end
+  end
+end

data/lib/checkout_sdk/accounts/entity_requirement_update_request.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Request body for PUT /accounts/entities/{id}/requirements/{requirementId}.
+    #
+    # The expected shape of `value` is defined by the JSON Schema returned in
+    # the requirement details response. Common shapes include a file reference
+    # (e.g. { "file_id": "file_..." }), a primitive value, or a structured object.
+    #
+    # @!attribute value
+    #   The response to the requirement. Polymorphic per swagger
+    #   (`oneOf [object, array, string, number, boolean]`), so the only valid
+    #   Ruby annotation is `Object`. The concrete shape is dictated at runtime
+    #   by the requirement's `_schema` returned from
+    #   `GET /accounts/entities/{id}/requirements/{requirementId}`.
+    #   @return [Object]
+    class EntityRequirementUpdateRequest
+      attr_accessor :value
+    end
+  end
+end

data/lib/checkout_sdk/accounts/entity_requirement_update_status.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Status returned after submitting a requirement response.
+    # While processing, the requirement is no longer retrievable via GET endpoints;
+    # if validation fails downstream the requirement may reappear.
+    module EntityRequirementUpdateStatus
+      PROCESSING = 'processing'
+    end
+  end
+end

data/lib/checkout_sdk/accounts/onboard_entity.rb

@@ -20,6 +20,12 @@ module CheckoutSdk
     #   @return [OnboardSubEntityDocuments]
     # @!attribute additional_info
     #   @return [AdditionalInfo]
+    # @!attribute seller_category
+    #   @return [String] Identifier of a seller category configured on the platform
+    #     during onboarding. Used for US ISV onboarding variants.
+    # @!attribute submitter
+    #   @return [Submitter] Captures evidence of the end-user's consent to onboarding.
+    #     Used for US ISV onboarding variants.
     class OnboardEntity
       attr_accessor :reference,
                     :is_draft,
@@ -29,7 +35,9 @@ module CheckoutSdk
                     :processing_details,
                     :individual,
                     :documents,
-                    :additional_info
+                    :additional_info,
+                    :seller_category,
+                    :submitter
     end
   end
 end

data/lib/checkout_sdk/accounts/reserve_rule_create_request.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Request body for POST /accounts/entities/{id}/reserve-rules.
+    # Extends {ReserveRuleUpdateRequest} with `valid_from`.
+    #
+    # @!attribute valid_from
+    #   @return [String] ISO-8601 timestamp; must be at least 15 minutes in the future.
+    class ReserveRuleCreateRequest < ReserveRuleUpdateRequest
+      attr_accessor :valid_from
+    end
+  end
+end

data/lib/checkout_sdk/accounts/reserve_rule_holding_duration.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # The length of time a rolling reserve collateral balance is held for.
+    #
+    # @!attribute weeks
+    #   @return [Integer] Min 2, max 104.
+    class ReserveRuleHoldingDuration
+      attr_accessor :weeks
+    end
+  end
+end

data/lib/checkout_sdk/accounts/reserve_rule_update_request.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Request body for PUT /accounts/entities/{entityId}/reserve-rules/{id}.
+    #
+    # @!attribute type
+    #   @return [String] Reserve rule type (e.g. "rolling").
+    # @!attribute rolling
+    #   @return [RollingReserveRule]
+    class ReserveRuleUpdateRequest
+      attr_accessor :type, :rolling
+    end
+  end
+end

data/lib/checkout_sdk/accounts/rolling_reserve_rule.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Rolling reserve rule parameters.
+    #
+    # @!attribute percentage
+    #   @return [Float] Min 0, max 100.
+    # @!attribute holding_duration
+    #   @return [ReserveRuleHoldingDuration]
+    class RollingReserveRule
+      attr_accessor :percentage, :holding_duration
+    end
+  end
+end

data/lib/checkout_sdk/accounts/submitter.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Accounts
+    # Captures evidence of the end-user's consent to onboarding.
+    #
+    # @!attribute ip_address
+    #   @return [String] IP address of the end-user submitting the onboarding request.
+    class Submitter
+      attr_accessor :ip_address
+    end
+  end
+end

data/lib/checkout_sdk/agentic_commerce/agentic_commerce.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require 'checkout_sdk/agentic_commerce/delegated_payment_method_card'
+require 'checkout_sdk/agentic_commerce/delegated_payment_allowance'
+require 'checkout_sdk/agentic_commerce/delegated_payment_billing_address'
+require 'checkout_sdk/agentic_commerce/delegated_payment_risk_signal'
+require 'checkout_sdk/agentic_commerce/delegated_payment_request'
+require 'checkout_sdk/agentic_commerce/agentic_commerce_client'

data/lib/checkout_sdk/agentic_commerce/agentic_commerce_client.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module AgenticCommerce
+    # Client for the Agentic Commerce Protocol API (Beta).
+    # Used by AI agents to create delegated payment tokens scoped to a single purchase.
+    class AgenticCommerceClient < Client
+      AGENTIC_COMMERCE = 'agentic_commerce'
+      DELEGATE_PAYMENT = 'delegate_payment'
+      private_constant :AGENTIC_COMMERCE, :DELEGATE_PAYMENT
+
+      # @param [ApiClient] api_client
+      # @param [CheckoutConfiguration] configuration
+      def initialize(api_client, configuration)
+        super(api_client, configuration, CheckoutSdk::AuthorizationType::SECRET_KEY)
+      end
+
+      # Create a delegated payment token.
+      # @param [Hash, DelegatedPaymentRequest] delegated_payment_request
+      # @param [String] idempotency_key Optional
+      def create_delegated_payment_token(delegated_payment_request, idempotency_key = nil)
+        api_client.invoke_post(
+          build_path(AGENTIC_COMMERCE, DELEGATE_PAYMENT),
+          sdk_authorization,
+          delegated_payment_request,
+          idempotency_key
+        )
+      end
+    end
+  end
+end

data/lib/checkout_sdk/agentic_commerce/delegated_payment_allowance.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module AgenticCommerce
+    # Spend-limit allowance attached to a delegated payment.
+    #
+    # @!attribute reason
+    #   @return [String] e.g. "purchase".
+    # @!attribute max_amount
+    #   @return [Integer] Maximum amount in the minor currency unit.
+    # @!attribute currency
+    #   @return [String] {CheckoutSdk::Common::Currency}
+    # @!attribute checkout_session_id
+    #   @return [String]
+    # @!attribute merchant_id
+    #   @return [String]
+    # @!attribute expires_at
+    #   @return [String] RFC 3339 timestamp.
+    class DelegatedPaymentAllowance
+      attr_accessor :reason,
+                    :max_amount,
+                    :currency,
+                    :checkout_session_id,
+                    :merchant_id,
+                    :expires_at
+    end
+  end
+end

data/lib/checkout_sdk/agentic_commerce/delegated_payment_billing_address.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module AgenticCommerce
+    # Billing address required for delegated payments. Mirrors swagger
+    # `DelegatedPaymentBillingAddress`. Required: `name`, `line_one`, `city`,
+    # `postal_code`, `country`.
+    #
+    # @!attribute name
+    #   @return [String] Full customer name. [Required]
+    # @!attribute line_one
+    #   @return [String] First line of the street address. [Required]
+    # @!attribute line_two
+    #   @return [String] Second line of the street address.
+    # @!attribute city
+    #   @return [String] [Required]
+    # @!attribute state
+    #   @return [String] State / region.
+    # @!attribute postal_code
+    #   @return [String] Postal/ZIP code. [Required]
+    # @!attribute country
+    #   @return [String] ISO 3166-1 alpha-2. [Required]
+    class DelegatedPaymentBillingAddress
+      attr_accessor :name,
+                    :line_one,
+                    :line_two,
+                    :city,
+                    :state,
+                    :postal_code,
+                    :country
+    end
+  end
+end

data/lib/checkout_sdk/agentic_commerce/delegated_payment_method_card.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module AgenticCommerce
+    # Card payment-method block used inside a {DelegatedPaymentRequest}.
+    # Mirrors swagger `DelegatedPaymentMethodCard`. Required fields per spec:
+    # `type`, `card_number_type`, `number`, `metadata`.
+    #
+    # @!attribute type
+    #   @return [String] Always "card".
+    # @!attribute card_number_type
+    #   @return [String] Either "fpan" or "network_token".
+    # @!attribute number
+    #   @return [String] The full card number.
+    # @!attribute exp_month
+    #   @return [String] Two-digit expiry month (MM).
+    # @!attribute exp_year
+    #   @return [String] Four-digit expiry year (YYYY).
+    # @!attribute name
+    #   @return [String] Cardholder name.
+    # @!attribute cvc
+    #   @return [String] Card verification code.
+    # @!attribute cryptogram
+    #   @return [String] Cryptogram for network-token transactions.
+    # @!attribute eci_value
+    #   @return [String] ECI / Security Level Indicator value.
+    # @!attribute checks_performed
+    #   @return [Array<String>] Verification checks performed on the card.
+    # @!attribute iin
+    #   @return [String] Issuer Identification Number (BIN).
+    # @!attribute display_card_funding_type
+    #   @return [String] "credit", "debit", or "prepaid".
+    # @!attribute display_wallet_type
+    #   @return [String] Wallet type for display.
+    # @!attribute display_brand
+    #   @return [String] Card brand for display (e.g. "Visa").
+    # @!attribute display_last4
+    #   @return [String] Last four digits for display.
+    # @!attribute metadata
+    #   @return [Hash{String => String}] Key-value pairs; required per swagger.
+    class DelegatedPaymentMethodCard
+      attr_accessor :type,
+                    :card_number_type,
+                    :number,
+                    :exp_month,
+                    :exp_year,
+                    :name,
+                    :cvc,
+                    :cryptogram,
+                    :eci_value,
+                    :checks_performed,
+                    :iin,
+                    :display_card_funding_type,
+                    :display_wallet_type,
+                    :display_brand,
+                    :display_last4,
+                    :metadata
+
+      def initialize
+        @type = 'card'
+      end
+    end
+  end
+end

data/lib/checkout_sdk/agentic_commerce/delegated_payment_request.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module AgenticCommerce
+    # Request body for POST /agentic_commerce/delegate_payment.
+    #
+    # @!attribute payment_method
+    #   @return [DelegatedPaymentMethodCard]
+    # @!attribute allowance
+    #   @return [DelegatedPaymentAllowance]
+    # @!attribute billing_address
+    #   @return [DelegatedPaymentBillingAddress]
+    # @!attribute risk_signals
+    #   @return [Array<DelegatedPaymentRiskSignal>]
+    # @!attribute metadata
+    #   @return [Hash{String => String}] Free-form key/value metadata.
+    class DelegatedPaymentRequest
+      attr_accessor :payment_method,
+                    :allowance,
+                    :billing_address,
+                    :risk_signals,
+                    :metadata
+    end
+  end
+end

data/lib/checkout_sdk/agentic_commerce/delegated_payment_risk_signal.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module AgenticCommerce
+    # Risk signal attached to a delegated payment request. Mirrors swagger
+    # `DelegatedPaymentRiskSignal`. All three fields are required per spec.
+    #
+    # @!attribute type
+    #   @return [String] Risk signal type. [Required]
+    # @!attribute score
+    #   @return [Integer] Risk score. [Required]
+    # @!attribute action
+    #   @return [String] Action taken based on the risk assessment. [Required]
+    class DelegatedPaymentRiskSignal
+      attr_accessor :type,
+                    :score,
+                    :action
+    end
+  end
+end