checkout_sdk 2.7.1 → 2.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ffa084c12fc5f4e0c765b41a3e4dd3e970ca006584c25623106e93dae1c6001
-  data.tar.gz: 8b69b0fff53b0eb662383c47f36af073aad85adca12d6d7edb46db9323859eb9
+  metadata.gz: 9849ed54d294ed9bea5fdb04bb5378fb55b942a2adb0ffe0653cb5c628cc0882
+  data.tar.gz: 7bd35374ce13e3feb72eb37a16930316ab6a01ce2cc10c49245f3e5a2daf6229
 SHA512:
-  metadata.gz: c4d4935f79a0e91ce703cae0dbdf02e6445065525e501cba3401adf956de27d7ea399e75d52b230e7c3de5279e5e2d5936fff9fcc77f556b19aae6b80c7de801
-  data.tar.gz: a209f2204ed7275f7e9b880dc4fe0c55758eefbd3687d8c83eed8596c3c69f701f4aadd0193c5d79e4da241756eeb19eaf21f88feefc1f49de076df41d8c3b2d
+  metadata.gz: b6f8c31a1c66aecb8b8fad6345a2b693f133b8bee59376920445caa7779db02a3f18882170318870c5f86fb728d898a4baffc32a0b71159d8b1fa4e17087c144
+  data.tar.gz: 6bdaf1a3c38c96bcafe0f52135ff77edda7a51d66946df1bc7d4b4d8e9e5729bf85f017e0a3a755567466e9132b4464428b7861ee58e56040fbf74294bc97598

data/README.md

@@ -172,6 +172,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)
@@ -68,8 +70,9 @@ module CheckoutSdk
 
     # Attribute name to HTTP header name, for every typed headers container the SDK supports.
     #
-    # The header names are case sensitive in the spec: return-encrypted-cvv is lower case where a
-    # naive conversion would produce Return-Encrypted-Cvv.
+    # The header names are emitted with an exact spelling: return-encrypted-cvv (sent by the
+    # deprecated CardUpdateHeaders) is lower case where a naive conversion would produce
+    # Return-Encrypted-Cvv.
     #
     # The values are Strings, not Symbols, and that is load bearing. Faraday::Utils::Headers
     # preserves a String key verbatim but rewrites a Symbol key as
@@ -139,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/checkout_utils.rb

@@ -21,11 +21,86 @@ 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
+
+    # 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
+
+    def self.utf8_text(text)
+      text.to_s.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 +108,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/common/account_holder.rb

@@ -2,37 +2,114 @@
 
 module CheckoutSdk
   module Common
+    # The account holder of a payment source, an instrument, or a payout or unreferenced refund destination.
+    # This class is shared by many positions; the per-position notes below cover the card payout, bank payout
+    # and unreferenced refund destinations. Each position only accepts the keys its schema declares, so leave
+    # the other properties unset.
+    # - Card payout card and network_token destinations: type, first_name, middle_name, last_name,
+    #   billing_address, phone, identification, email, date_of_birth, country_of_birth.
+    # - Card payout id and token destinations: type, first_name, middle_name, last_name, company_name.
+    # - Bank payout bank_account destination: type, first_name, last_name, company_name, tax_id,
+    #   date_of_birth, country_of_birth, residential_status, billing_address, phone, identification.
+    # - Unreferenced refund destinations: as the card payout card and network_token destinations.
+    #
     # @!attribute type
+    #   The type of account holder.
+    #   [Required] for payout and unreferenced refund destinations (when the account holder is sent)
+    #   Enum: "individual" "corporate" "government"
     #   @return [String] {AccountHolderType}
     # @!attribute full_name
+    #   The account holder's full name.
+    #   [Optional]
+    #   @deprecated Not in the request schema of any account holder. Still returned in the PayPal payment
+    #     details source account_holder.
+    #     Retained for backwards compatibility and will be removed in the next major version. There is no
+    #     replacement.
     #   @return [String]
     # @!attribute first_name
+    #   The account holder's legal first name. The combination of first_name, middle_name and last_name
+    #   should exceed 3 letters in length for card payouts. A single character or all non-alphabetic
+    #   characters return a field validation error.
+    #   [Required] for individual account holders in card payouts, bank payouts and the unreferenced refund
+    #   card and network_token destinations; [Optional] for the unreferenced refund id and token
+    #   destinations. In the card payout id and token destinations it is not required if the first name is
+    #   already stored with the token or instrument.
+    #   max 50 characters (card payouts and unreferenced refunds)
     #   @return [String]
     # @!attribute middle_name
+    #   The account holder's middle name.
+    #   [Optional] Card payouts and unreferenced refunds only.
+    #   max 50 characters
     #   @return [String]
     # @!attribute last_name
+    #   The account holder's legal last name. The combination of first_name, middle_name and last_name
+    #   should exceed 3 letters in length for card payouts. A single character or all non-alphabetic
+    #   characters return a field validation error.
+    #   [Required] for individual account holders in card payouts, bank payouts and the unreferenced refund
+    #   card and network_token destinations; [Optional] for the unreferenced refund id and token
+    #   destinations. In the card payout id and token destinations it is not required if the last name is
+    #   already stored with the token or instrument.
+    #   max 50 characters (card payouts and unreferenced refunds)
     #   @return [String]
     # @!attribute email
+    #   The account holder's email address.
+    #   [Optional] Card payout card and network_token destinations and unreferenced refunds only.
+    #   max 255 characters
     #   @return [String]
     # @!attribute gender
+    #   The account holder's gender.
+    #   [Optional]
+    #   @deprecated Not in the request schema of any account holder. Still returned in the Klarna payment
+    #     details source account_holder.
+    #     Retained for backwards compatibility and will be removed in the next major version. There is no
+    #     replacement.
     #   @return [String]
     # @!attribute company_name
+    #   The legal name of the corporate or government account holder. A single character or all
+    #   non-alphabetic characters return a field validation error.
+    #   [Required] for corporate and government payout and unreferenced refund destinations
+    #   max 50 characters (card payouts and unreferenced refunds)
     #   @return [String]
     # @!attribute tax_id
+    #   The legal account holder's tax number or reference.
+    #   [Optional] Bank payouts only.
     #   @return [String]
     # @!attribute date_of_birth
+    #   The account holder's date of birth, in the format YYYY-MM-DD. Individual account holders only.
+    #   [Optional]
+    #   10 characters (card payouts and unreferenced refunds)
     #   @return [String]
     # @!attribute country_of_birth
-    #   @return [Country]
+    #   The account holder's country of birth, as a two-letter ISO country code. Individual account holders
+    #   only.
+    #   [Optional]
+    #   2 characters
+    #   @return [String] {Country}
     # @!attribute residential_status
+    #   The account holder's residential status.
+    #   [Optional] Bank payouts only.
+    #   Enum: "resident" "non_resident"
     #   @return [String] {ResidentialStatusType}
     # @!attribute billing_address
+    #   The account holder's billing address. For card payouts and unreferenced refunds, it is required if
+    #   your company is incorporated in the United States.
+    #   [Required] for individual bank payout destinations, [Optional] otherwise
     #   @return [Address]
     # @!attribute phone
+    #   The account holder's phone number.
+    #   [Optional] Not part of the card payout id and token destinations, nor of the corporate and
+    #   government bank payout destinations.
     #   @return [Phone]
     # @!attribute identification
+    #   The account holder's identification. Providing identification details for the payout recipient
+    #   increases the likelihood of a successful payout.
+    #   [Optional] Not part of the card payout id and token destinations, nor of the corporate and
+    #   government bank payout destinations.
     #   @return [AccountHolderIdentification]
     # @!attribute account_name_inquiry
+    #   Whether the ANI (account name inquiry) check should be performed with the scheme (Visa or
+    #   Mastercard). Payment sources only.
+    #   [Optional] Not declared by the payout or unreferenced refund destination schemas.
     #   @return [Boolean]
     class AccountHolder
       attr_accessor :type,

data/lib/checkout_sdk/common/account_holder_identification.rb

@@ -2,13 +2,34 @@
 
 module CheckoutSdk
   module Common
+    # The identification of an account holder or a sender. Shared by the card payout, bank payout,
+    # unreferenced refund and regular payment positions.
+    #
     # @!attribute type
+    #   The type of identification.
+    #   [Required] for card payout and unreferenced refund account holders and card payout senders,
+    #   [Optional] for bank payout and regular payment senders and bank payout account holders
+    #   Enum: "passport" "driving_license" "national_id" "company_registration" "tax_id" (card payouts and
+    #   unreferenced refunds); "passport" "driving_licence" "national_id" (bank payout and regular payment
+    #   senders)
     #   @return [String] {AccountHolderIdentificationType}
     # @!attribute number
+    #   The identification number.
+    #   [Required] for card payout and unreferenced refund account holders and card payout senders,
+    #   [Optional] for bank payout and regular payment senders and bank payout account holders
+    #   max 25 characters (card payout and unreferenced refund account holders)
     #   @return [String]
     # @!attribute issuing_country
+    #   If applicable, the country that issued the identification, as a two-letter ISO country code.
+    #   Providing it increases the likelihood of a successful identity verification.
+    #   [Optional]
+    #   2 characters (card payouts and unreferenced refunds)
     #   @return [String] {Country}
     # @!attribute date_of_expiry
+    #   If applicable, the expiration date of the identification, in the format YYYY-MM-DD.
+    #   Card payouts and unreferenced refunds only.
+    #   [Optional]
+    #   10 characters
     #   @return [String]
     class AccountHolderIdentification
       attr_accessor :type,

data/lib/checkout_sdk/common/common.rb

@@ -9,6 +9,7 @@ require 'checkout_sdk/common/account_holder'
 require 'checkout_sdk/common/country'
 require 'checkout_sdk/common/account_holder_identification_type'
 require 'checkout_sdk/common/account_holder_type'
+require 'checkout_sdk/common/residential_status_type'
 require 'checkout_sdk/common/instrument_type'
 require 'checkout_sdk/common/bank_details'
 require 'checkout_sdk/common/payment_source_type'

data/lib/checkout_sdk/common/customer_retry.rb

@@ -1,11 +1,23 @@
 # frozen_string_literal: true
 
 module CheckoutSdk
-  module Accounts
+  module Common
+    # Configures the parameters for customer retries. A customer retry is a payment attempt
+    # performed by the customer on the checkout page, used by hosted payments, payment links
+    # and payment sessions.
+    #
     # @!attribute max_attempts
-    #   @return [Integer]
+    #   @return [Integer] [Optional] The maximum number of customer retry attempts, excluding the
+    #     initial payment attempt. Minimum 0, maximum 5. Default 5.
+    #     Required when used in a payment sessions request.
     class CustomerRetry
       attr_accessor :max_attempts
     end
   end
+
+  module Accounts
+    # @deprecated Please use {CheckoutSdk::Common::CustomerRetry} instead. This alias will be
+    #   removed in the next major version.
+    CustomerRetry = CheckoutSdk::Common::CustomerRetry
+  end
 end

data/lib/checkout_sdk/common/residential_status_type.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Common
+    # The account holder's residential status (bank payout and refund destination account holders).
+    module ResidentialStatusType
+      RESIDENT = 'resident'
+      NON_RESIDENT = 'non_resident'
+    end
+  end
+end

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/issuing/card_update_headers.rb

@@ -4,26 +4,25 @@ module CheckoutSdk
   module Issuing
     # The optional HTTP headers accepted when updating a card's details.
     #
+    # @deprecated The API no longer documents these headers; use the method without headers. Will
+    #   be removed in the next major version. Headers that are set are still sent unchanged.
+    #
     # Modelled as its own class rather than added to {CheckoutSdk::Common::Headers} because these
     # two headers belong to one endpoint, and Common::Headers is shared by every client.
     #
     # @!attribute return_encrypted_cvv
-    #   Set to "true" to retrieve the card's encrypted credentials in the response. Requires an
-    #   RSA public key in the Encryption-Key header, otherwise the API answers 422 with error code
-    #   encryption_key_required.
-    #
-    #   A String rather than a boolean: the value is emitted verbatim as an HTTP header, and "true"
-    #   is what the spec shows.
+    #   @deprecated The API no longer documents these headers; use the method without headers.
+    #     Will be removed in the next major version.
+    #   No longer documented by the API. Still sent unchanged as the return-encrypted-cvv HTTP
+    #   header when set.
     #   [Optional]
-    #   Maps to HTTP header return-encrypted-cvv.
-    #   Example: "true"
     #   @return [String]
     # @!attribute encryption_key
-    #   The RSA public key used to encrypt returned credentials. Required when
-    #   return_encrypted_cvv is set. Provide the public key with the BEGIN PUBLIC KEY and END
-    #   PUBLIC KEY headers and any newline characters removed, encoded as Base64.
+    #   @deprecated The API no longer documents these headers; use the method without headers.
+    #     Will be removed in the next major version.
+    #   No longer documented by the API. Still sent unchanged as the Encryption-Key HTTP header
+    #   when set.
     #   [Optional]
-    #   Maps to HTTP header Encryption-Key.
     #   @return [String]
     class CardUpdateHeaders
       attr_accessor :return_encrypted_cvv, :encryption_key

data/lib/checkout_sdk/issuing/issuing_client.rb

@@ -90,13 +90,13 @@ module CheckoutSdk
       #
       # @param [String] card_id
       # @param [Hash, UpdateCardRequest] update_card_request
-      # @param [CardUpdateHeaders, nil] headers the optional return-encrypted-cvv and
-      #   Encryption-Key HTTP headers. Setting return_encrypted_cvv without encryption_key returns
-      #   a 422 with error code encryption_key_required.
-      # @return [OpenStruct] the update response, carrying encrypted_cvv when requested. For a
-      #   virtual card the response may also carry is_single_use (boolean, default false),
-      #   specifying whether the card is set to expire after a single use. Physical cards never
-      #   send it.
+      # @param [CardUpdateHeaders, nil] headers deprecated. The API no longer documents these
+      #   headers; use the method without headers. Will be removed in the next major version.
+      #   When set, the return-encrypted-cvv and Encryption-Key headers are still sent unchanged.
+      # @return [OpenStruct] the update-card-response: the updated card details and _links. The
+      #   type field discriminates the variant; a virtual card response also carries
+      #   is_single_use (boolean, default false), whether the card expires after a single use.
+      #   Physical card responses never carry it.
       def update_card(card_id, update_card_request, headers = nil)
         api_client.invoke_patch(
           build_path(ISSUING, CARDS, card_id),
@@ -134,15 +134,24 @@ module CheckoutSdk
         api_client.invoke_get(build_path(ISSUING, CARDS, card_id, CREDENTIALS), sdk_authorization, query)
       end
 
+      # Revoke a card. POST /issuing/cards/{cardId}/revoke. The request body is optional; when
+      # omitted an empty JSON object is sent.
       # @param [String] card_id
-      # @param [Hash] revoke_request
-      def revoke_card(card_id, revoke_request)
+      # @param [Hash, nil] revoke_request optional, may carry reason (expired, reported_lost,
+      #   reported_stolen)
+      # @return [OpenStruct] the revoke-card-response, carrying _links with self and controls.
+      def revoke_card(card_id, revoke_request = nil)
         api_client.invoke_post(build_path(ISSUING, CARDS, card_id, REVOKE), sdk_authorization, revoke_request)
       end
 
+      # Suspend a card. POST /issuing/cards/{cardId}/suspend. The request body is optional; when
+      # omitted an empty JSON object is sent.
       # @param [String] card_id
-      # @param [Hash] suspend_request
-      def suspend_card(card_id, suspend_request)
+      # @param [Hash, nil] suspend_request optional, may carry reason (suspected_lost,
+      #   suspected_stolen)
+      # @return [OpenStruct] the suspend-card-response, carrying _links with self, activate,
+      #   revoke and controls.
+      def suspend_card(card_id, suspend_request = nil)
         api_client.invoke_post(build_path(ISSUING, CARDS, card_id, SUSPEND), sdk_authorization, suspend_request)
       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/card_payout_item.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # A line item of a card payout.
+    #
+    # @!attribute type
+    #   The item type. For example, physical or digital.
+    #   This field is used to provide item level metadata where applicable.
+    #   [Optional]
+    #   Enum: "digital" "physical"
+    #   @return [String] {ProductItemType}
+    # @!attribute sub_type
+    #   The digital item type.
+    #   If type is set to digital, this field is required.
+    #   [Optional]
+    #   Enum: "blockchain" "cbdc" "cryptocurrency" "nft" "stablecoin"
+    #   @return [String] {ProductSubType}
+    class CardPayoutItem
+      attr_accessor :type,
+                    :sub_type
+    end
+  end
+end

data/lib/checkout_sdk/payments/card_payout_processing.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module CheckoutSdk
+  module Payments
+    # Information related to the processing of a card payout.
+    #
+    # @!attribute affiliate_id
+    #   The unique identifier for Visa-registered ramp providers.
+    #   Must only contain alphanumeric characters.
+    #   If you're a Visa-registered ramp provider operating with affiliates, this field is required.
+    #   [Optional]
+    #   ^[a-zA-Z0-9]{1,15}$
+    #   max 15 characters
+    #   @return [String]
+    # @!attribute affiliate_url
+    #   The affiliate URL.
+    #   If you're a Visa-registered ramp provider operating with affiliates, this field is required.
+    #   [Optional]
+    #   @return [String]
+    # @!attribute processing_speed
+    #   The speed at which the payout is processed.
+    #   Only applicable for unreferenced refunds.
+    #   [Optional]
+    #   Enum: "fast"
+    #   @return [String]
+    # @!attribute purchase_country
+    #   The two-letter ISO country code of the purchase country.
+    #   If you're a Visa-registered ramp provider operating with affiliates, this field is required.
+    #   [Optional]
+    #   max 2 characters
+    #   @return [String] {CheckoutSdk::Common::Country}
+    class CardPayoutProcessing
+      attr_accessor :affiliate_id,
+                    :affiliate_url,
+                    :processing_speed,
+                    :purchase_country
+    end
+  end
+end