jamm 2.5.0 → 2.7.0

data/lib/jamm/api/models/v1_webhook_endpoint.rb

@@ -0,0 +1,307 @@
+=begin
+#Jamm API
+
+#No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+
+The version of the OpenAPI document: 1.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.9.0
+
+=end
+
+require 'date'
+require 'time'
+
+module Api
+  # WebhookEndpoint is a webhook receiver with its pinned API version.  WebhookEndpoint は固定されたAPIバージョンを持つWebhook受信先です。
+  class WebhookEndpoint
+    # Endpoint ID, prefixed with `wep-`.  エンドポイントID。`wep-` で始まります。
+    attr_accessor :id
+
+    # URL that receives deliveries.  配信先URL。
+    attr_accessor :url
+
+    attr_accessor :status
+
+    # API version deliveries are rendered at, as `YYYY-MM-DD`. Unset means the endpoint inherits the merchant's pinned version.  配信の形式を決めるAPIバージョン（`YYYY-MM-DD`）。 未設定の場合は加盟店に固定されたバージョンを継承します。
+    attr_accessor :api_version
+
+    # API version that was live before the last promote. Set only while a rollback is possible.  直前の昇格前に有効だったAPIバージョン。ロールバックが可能な間のみ設定されます。
+    attr_accessor :previous_api_version
+
+    # When the last promote happened. Set only while a rollback is possible.  直前の昇格が行われた時刻。ロールバックが可能な間のみ設定されます。
+    attr_accessor :promoted_at
+
+    attr_accessor :created_at
+
+    attr_accessor :updated_at
+
+    class EnumAttributeValidator
+      attr_reader :datatype
+      attr_reader :allowable_values
+
+      def initialize(datatype, allowable_values)
+        @allowable_values = allowable_values.map do |value|
+          case datatype.to_s
+          when /Integer/i
+            value.to_i
+          when /Float/i
+            value.to_f
+          else
+            value
+          end
+        end
+      end
+
+      def valid?(value)
+        !value || allowable_values.include?(value)
+      end
+    end
+
+    # Attribute mapping from ruby-style variable name to JSON key.
+    def self.attribute_map
+      {
+        :'id' => :'id',
+        :'url' => :'url',
+        :'status' => :'status',
+        :'api_version' => :'apiVersion',
+        :'previous_api_version' => :'previousApiVersion',
+        :'promoted_at' => :'promotedAt',
+        :'created_at' => :'createdAt',
+        :'updated_at' => :'updatedAt'
+      }
+    end
+
+    # Returns all the JSON keys this model knows about
+    def self.acceptable_attributes
+      attribute_map.values
+    end
+
+    # Attribute type mapping.
+    def self.openapi_types
+      {
+        :'id' => :'String',
+        :'url' => :'String',
+        :'status' => :'WebhookEndpointStatus',
+        :'api_version' => :'String',
+        :'previous_api_version' => :'String',
+        :'promoted_at' => :'Time',
+        :'created_at' => :'Time',
+        :'updated_at' => :'Time'
+      }
+    end
+
+    # List of attributes with nullable: true
+    def self.openapi_nullable
+      Set.new([
+      ])
+    end
+
+    # Initializes the object
+    # @param [Hash] attributes Model attributes in the form of hash
+    def initialize(attributes = {})
+      if (!attributes.is_a?(Hash))
+        fail ArgumentError, "The input argument (attributes) must be a hash in `Api::WebhookEndpoint` initialize method"
+      end
+
+      # check to see if the attribute exists and convert string to symbol for hash key
+      attributes = attributes.each_with_object({}) { |(k, v), h|
+        if (!self.class.attribute_map.key?(k.to_sym))
+          fail ArgumentError, "`#{k}` is not a valid attribute in `Api::WebhookEndpoint`. Please check the name to make sure it's valid. List of attributes: " + self.class.attribute_map.keys.inspect
+        end
+        h[k.to_sym] = v
+      }
+
+      if attributes.key?(:'id')
+        self.id = attributes[:'id']
+      end
+
+      if attributes.key?(:'url')
+        self.url = attributes[:'url']
+      end
+
+      if attributes.key?(:'status')
+        self.status = attributes[:'status']
+      else
+        self.status = 'WEBHOOK_ENDPOINT_STATUS_UNSPECIFIED'
+      end
+
+      if attributes.key?(:'api_version')
+        self.api_version = attributes[:'api_version']
+      end
+
+      if attributes.key?(:'previous_api_version')
+        self.previous_api_version = attributes[:'previous_api_version']
+      end
+
+      if attributes.key?(:'promoted_at')
+        self.promoted_at = attributes[:'promoted_at']
+      end
+
+      if attributes.key?(:'created_at')
+        self.created_at = attributes[:'created_at']
+      end
+
+      if attributes.key?(:'updated_at')
+        self.updated_at = attributes[:'updated_at']
+      end
+    end
+
+    # Show invalid properties with the reasons. Usually used together with valid?
+    # @return Array for valid properties with the reasons
+    def list_invalid_properties
+      warn '[DEPRECATED] the `list_invalid_properties` method is obsolete'
+      invalid_properties = Array.new
+      invalid_properties
+    end
+
+    # Check to see if the all the properties in the model are valid
+    # @return true if the model is valid
+    def valid?
+      warn '[DEPRECATED] the `valid?` method is obsolete'
+      true
+    end
+
+    # Checks equality by comparing each attribute.
+    # @param [Object] Object to be compared
+    def ==(o)
+      return true if self.equal?(o)
+      self.class == o.class &&
+          id == o.id &&
+          url == o.url &&
+          status == o.status &&
+          api_version == o.api_version &&
+          previous_api_version == o.previous_api_version &&
+          promoted_at == o.promoted_at &&
+          created_at == o.created_at &&
+          updated_at == o.updated_at
+    end
+
+    # @see the `==` method
+    # @param [Object] Object to be compared
+    def eql?(o)
+      self == o
+    end
+
+    # Calculates hash code according to all attributes.
+    # @return [Integer] Hash code
+    def hash
+      [id, url, status, api_version, previous_api_version, promoted_at, created_at, updated_at].hash
+    end
+
+    # Builds the object from hash
+    # @param [Hash] attributes Model attributes in the form of hash
+    # @return [Object] Returns the model itself
+    def self.build_from_hash(attributes)
+      return nil unless attributes.is_a?(Hash)
+      attributes = attributes.transform_keys(&:to_sym)
+      transformed_hash = {}
+      openapi_types.each_pair do |key, type|
+        if attributes.key?(attribute_map[key]) && attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = nil
+        elsif type =~ /\AArray<(.*)>/i
+          # check to ensure the input is an array given that the attribute
+          # is documented as an array but the input is not
+          if attributes[attribute_map[key]].is_a?(Array)
+            transformed_hash["#{key}"] = attributes[attribute_map[key]].map { |v| _deserialize($1, v) }
+          end
+        elsif !attributes[attribute_map[key]].nil?
+          transformed_hash["#{key}"] = _deserialize(type, attributes[attribute_map[key]])
+        end
+      end
+      new(transformed_hash)
+    end
+
+    # Deserializes the data based on type
+    # @param string type Data type
+    # @param string value Value to be deserialized
+    # @return [Object] Deserialized data
+    def self._deserialize(type, value)
+      case type.to_sym
+      when :Time
+        Time.parse(value)
+      when :Date
+        Date.parse(value)
+      when :String
+        value.to_s
+      when :Integer
+        value.to_i
+      when :Float
+        value.to_f
+      when :Boolean
+        if value.to_s =~ /\A(true|t|yes|y|1)\z/i
+          true
+        else
+          false
+        end
+      when :Object
+        # generic object (usually a Hash), return directly
+        value
+      when /\AArray<(?<inner_type>.+)>\z/
+        inner_type = Regexp.last_match[:inner_type]
+        value.map { |v| _deserialize(inner_type, v) }
+      when /\AHash<(?<k_type>.+?), (?<v_type>.+)>\z/
+        k_type = Regexp.last_match[:k_type]
+        v_type = Regexp.last_match[:v_type]
+        {}.tap do |hash|
+          value.each do |k, v|
+            hash[_deserialize(k_type, k)] = _deserialize(v_type, v)
+          end
+        end
+      else # model
+        # models (e.g. Pet) or oneOf
+        klass = Api.const_get(type)
+        klass.respond_to?(:openapi_any_of) || klass.respond_to?(:openapi_one_of) ? klass.build(value) : klass.build_from_hash(value)
+      end
+    end
+
+    # Returns the string representation of the object
+    # @return [String] String presentation of the object
+    def to_s
+      to_hash.to_s
+    end
+
+    # to_body is an alias to to_hash (backward compatibility)
+    # @return [Hash] Returns the object in the form of hash
+    def to_body
+      to_hash
+    end
+
+    # Returns the object in the form of hash
+    # @return [Hash] Returns the object in the form of hash
+    def to_hash
+      hash = {}
+      self.class.attribute_map.each_pair do |attr, param|
+        value = self.send(attr)
+        if value.nil?
+          is_nullable = self.class.openapi_nullable.include?(attr)
+          next if !is_nullable || (is_nullable && !instance_variable_defined?(:"@#{attr}"))
+        end
+
+        hash[param] = _to_hash(value)
+      end
+      hash
+    end
+
+    # Outputs non-array value in the form of hash
+    # For object, use to_hash. Otherwise, just return the value
+    # @param [Object] value Any valid value
+    # @return [Hash] Returns the value in the form of hash
+    def _to_hash(value)
+      if value.is_a?(Array)
+        value.compact.map { |v| _to_hash(v) }
+      elsif value.is_a?(Hash)
+        {}.tap do |hash|
+          value.each { |k, v| hash[k] = _to_hash(v) }
+        end
+      elsif value.respond_to? :to_hash
+        value.to_hash
+      else
+        value
+      end
+    end
+
+  end
+
+end

data/lib/jamm/api/models/v1_webhook_endpoint_status.rb

@@ -0,0 +1,42 @@
+=begin
+#Jamm API
+
+#No description provided (generated by Openapi Generator https://github.com/openapitools/openapi-generator)
+
+The version of the OpenAPI document: 1.0
+
+Generated by: https://openapi-generator.tech
+Generator version: 7.9.0
+
+=end
+
+require 'date'
+require 'time'
+
+module Api
+  class WebhookEndpointStatus
+    UNSPECIFIED = "WEBHOOK_ENDPOINT_STATUS_UNSPECIFIED".freeze
+    LIVE = "WEBHOOK_ENDPOINT_STATUS_LIVE".freeze
+    TEST = "WEBHOOK_ENDPOINT_STATUS_TEST".freeze
+    DISABLED = "WEBHOOK_ENDPOINT_STATUS_DISABLED".freeze
+
+    def self.all_vars
+      @all_vars ||= [UNSPECIFIED, LIVE, TEST, DISABLED].freeze
+    end
+
+    # Builds the enum from string
+    # @param [String] The enum value in the form of the string
+    # @return [String] The enum value
+    def self.build_from_hash(value)
+      new.build_from_hash(value)
+    end
+
+    # Builds the enum from string
+    # @param [String] The enum value in the form of the string
+    # @return [String] The enum value
+    def build_from_hash(value)
+      return value if WebhookEndpointStatus.all_vars.include?(value)
+      raise "Invalid ENUM value #{value} for class #WebhookEndpointStatus"
+    end
+  end
+end

data/lib/jamm/api.rb

@@ -19,6 +19,7 @@ require 'jamm/api/configuration'
 # Models
 require 'jamm/api/models/apiv1_error'
 require 'jamm/api/models/apiv1_status'
+require 'jamm/api/models/charge_message_api_source'
 require 'jamm/api/models/customer_service_update_customer_body'
 require 'jamm/api/models/googlerpc_status'
 require 'jamm/api/models/protobuf_any'
@@ -47,6 +48,8 @@ require 'jamm/api/models/v1_create_contract_without_charge_request'
 require 'jamm/api/models/v1_create_contract_without_charge_response'
 require 'jamm/api/models/v1_create_customer_request'
 require 'jamm/api/models/v1_create_customer_response'
+require 'jamm/api/models/v1_create_webhook_endpoint_request'
+require 'jamm/api/models/v1_create_webhook_endpoint_response'
 require 'jamm/api/models/v1_customer'
 require 'jamm/api/models/v1_delete_customer_response'
 require 'jamm/api/models/v1_deposit_type'
@@ -80,14 +83,21 @@ require 'jamm/api/models/v1_pagination'
 require 'jamm/api/models/v1_payment_authorization_status'
 require 'jamm/api/models/v1_payment_link'
 require 'jamm/api/models/v1_ping_response'
+require 'jamm/api/models/v1_promote_webhook_endpoint_response'
 require 'jamm/api/models/v1_refund_info'
 require 'jamm/api/models/v1_refund_request'
 require 'jamm/api/models/v1_refund_response'
+require 'jamm/api/models/v1_refund_webhook_content'
+require 'jamm/api/models/v1_rollback_webhook_endpoint_response'
 require 'jamm/api/models/v1_search_banks_response'
 require 'jamm/api/models/v1_search_branches_response'
+require 'jamm/api/models/v1_trigger_webhook_event_request'
+require 'jamm/api/models/v1_trigger_webhook_event_response'
 require 'jamm/api/models/v1_url'
 require 'jamm/api/models/v1_update_customer_response'
 require 'jamm/api/models/v1_user_account_message'
+require 'jamm/api/models/v1_webhook_endpoint'
+require 'jamm/api/models/v1_webhook_endpoint_status'
 require 'jamm/api/models/v1_withdraw_async_request'
 require 'jamm/api/models/v1_withdraw_async_response'
 require 'jamm/api/models/v1_withdraw_async_status_request'
@@ -99,6 +109,7 @@ require 'jamm/api/models/v1_withdraw_response'
 require 'jamm/api/api/customer_api'
 require 'jamm/api/api/healthcheck_api'
 require 'jamm/api/api/payment_api'
+require 'jamm/api/api/webhook_endpoint_api'
 require 'jamm/api/api/webhook_service_api'
 
 module Api

data/lib/jamm/api_version.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+# Code generated by make sdkversions. DO NOT EDIT.
+#
+# Bumped only by the release workflow, which checks the API serves it first.
+
+module Jamm
+  # The Jamm API version this SDK was built against.
+  API_VERSION = '2026-08-26'
+end

data/lib/jamm/client.rb

@@ -2,6 +2,17 @@
 
 module Jamm
   module Client
+    # Applied after header_params are merged so per-call or default_headers overrides cannot change the version.
+    module PinAPIVersion
+      def build_request(http_method, path, opts = {})
+        request = super
+        headers = request.options[:headers]
+        headers.delete_if { |k, _| k.to_s.casecmp?('Jamm-API-Version') }
+        headers['Jamm-API-Version'] = Jamm.api_version
+        request
+      end
+    end
+
     def self.handler(merchant: nil)
       base = Jamm::OpenAPI::ApiClient.new
 
@@ -9,7 +20,8 @@ module Jamm
       base.config.host = Jamm.openapi.config.host
       base.config.scheme = Jamm.openapi.config.scheme
       base.default_headers['Authorization'] = "Bearer #{Jamm::OAuth.token}"
-      base.default_headers['X-SDK-Version'] = "ruby:#{Jamm::VERSION}"
+      base.default_headers['Jamm-SDK-Version'] = "ruby:#{Jamm::VERSION}"
+      base.extend(PinAPIVersion)
 
       # Platform feature, optionally set merchant id to call Jamm API
       # on behalf of the merchant.

data/lib/jamm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jamm
-  VERSION = '2.5.0'
+  VERSION = '2.7.0'
 end

data/lib/jamm/webhook.rb

@@ -11,39 +11,174 @@ module Jamm
     # Parse command is for parsing the received webhook message.
     # It does not call anything remotely, instead returns the suitable object.
     def self.parse(json)
-      out = Jamm::OpenAPI::MerchantWebhookMessage.new(json)
-
-      case json[:event_type]
-      when Jamm::OpenAPI::EventType::CHARGE_CREATED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
+      # Webhook payloads may arrive with string or symbol keys depending on how
+      # the caller decoded the JSON (e.g. JSON.parse with or without
+      # symbolize_names: true). Normalize to symbols so event-type routing,
+      # wrapper flattening, and field lookups are reliable either way.
+      json = deep_symbolize_keys(json)
+
+      out = build(Jamm::OpenAPI::MerchantWebhookMessage, json)
+
+      # Route on the coerced event type: the wire value is an enum string today,
+      # but `build` also resolves a numeric wire value onto its string constant,
+      # so routing survives either serialization.
+      case out.event_type
+      when Jamm::OpenAPI::EventType::CHARGE_CREATED,
+           Jamm::OpenAPI::EventType::CHARGE_UPDATED,
+           Jamm::OpenAPI::EventType::REFUND_SUCCEEDED,
+           Jamm::OpenAPI::EventType::REFUND_FAILED,
+           Jamm::OpenAPI::EventType::CHARGE_SUCCESS,
+           Jamm::OpenAPI::EventType::CHARGE_FAIL
+        out.content = build(Jamm::OpenAPI::ChargeMessage, flatten_charge_content(json[:content]))
         return out
 
-      when Jamm::OpenAPI::EventType::CHARGE_UPDATED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
+      when Jamm::OpenAPI::EventType::CONTRACT_ACTIVATED
+        out.content = build(Jamm::OpenAPI::ContractMessage, json[:content])
         return out
 
-      when Jamm::OpenAPI::EventType::REFUND_SUCCEEDED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
+      when Jamm::OpenAPI::EventType::USER_ACCOUNT_DELETED
+        out.content = build(Jamm::OpenAPI::UserAccountMessage, json[:content])
         return out
+      end
 
-      when Jamm::OpenAPI::EventType::REFUND_FAILED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
-        return out
+      raise 'Unknown event type'
+    end
 
-      when Jamm::OpenAPI::EventType::CHARGE_SUCCESS
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
-        return out
+    # Build a generated model from a webhook payload while normalizing the
+    # quirks of the webhook wire format. Applied to every model, so charges,
+    # contracts, user-account and refund messages all benefit:
+    #
+    #   1. Forward-compat: the Jamm backend can add new fields to webhook
+    #      payloads at any time. The generated model `initialize` raises
+    #      ArgumentError on any key outside `attribute_map`, so unknown keys are
+    #      dropped first. Known keys are snake_case, matching `attribute_map`.
+    #   2. Numeric enums: the backend serializes webhook payloads with Go's
+    #      `json.Marshal` (not protojson), so every enum field (status,
+    #      api_source, ...) arrives as its integer value, while the generated
+    #      enums are string-based. Each integer is mapped back to the enum string
+    #      so it matches the values returned by the REST API.
+    #   3. Nested models: the generated `initialize` assigns nested objects
+    #      verbatim (the `_deserialize` coercion only runs from `build_from_hash`,
+    #      which expects camelCase keys the webhook does not use). So a nested
+    #      field like `refund.error` would stay a raw Hash and `error.code` would
+    #      raise NoMethodError. We coerce nested model fields (and arrays of them)
+    #      recursively so the typed accessors work.
+    def self.build(klass, attributes)
+      return nil if attributes.nil?
+
+      types = klass.openapi_types
+      filtered = attributes.each_with_object({}) do |(key, value), acc|
+        sym = attribute_for(klass, key)
+        next if sym.nil?
+
+        acc[sym] = coerce(types[sym], value)
+      end
 
-      when Jamm::OpenAPI::EventType::CHARGE_FAIL
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
-        return out
+      klass.new(filtered)
+    end
 
-      when Jamm::OpenAPI::EventType::CONTRACT_ACTIVATED
-        out.content = Jamm::OpenAPI::ContractMessage.new(json[:content])
-        return out
+    # attribute_map is { snake_symbol => jsonCamelName }; accept either
+    # spelling. Both cannot arrive together; the last would win.
+    def self.attribute_for(klass, key)
+      sym = key.to_sym
+      return sym if klass.attribute_map.key?(sym)
+
+      by_serialized(klass)[sym]
+    end
+
+    # Memoised per class: Hash#key is a linear scan, paid once per field otherwise.
+    def self.by_serialized(klass)
+      @by_serialized ||= {}
+      @by_serialized[klass] ||= klass.attribute_map.invert
+    end
+
+    # Refund webhooks (REFUND_SUCCEEDED / REFUND_FAILED) deliver `content` as a
+    # nested { transaction, refund } wrapper instead of a flat ChargeMessage.
+    # Flatten it back into a ChargeMessage so callers always receive the same shape.
+    def self.flatten_charge_content(content)
+      return content unless content.is_a?(Hash) && content.key?(:transaction)
+
+      refund = content[:refund]
+      # Keep `refund` as the raw Hash: `build` coerces it into a typed RefundInfo
+      # (and recursively types its nested `error`). Also surface the refund's
+      # `rfd-` id on the flat `refund_id` attribute the model documents.
+      charge = content[:transaction].merge(refund: refund)
+      charge[:refund_id] = refund[:id] if refund.is_a?(Hash) && !refund[:id].nil?
+      charge
+    end
+
+    # Coerce a raw webhook value into the shape the generated model expects,
+    # based on the field's openapi type: numeric enums become their string
+    # constant, nested models become typed instances, and `Array<T>` elements are
+    # coerced by `T`. Anything else passes through untouched.
+    def self.coerce(type, value)
+      return value if value.nil?
+
+      inner = array_inner_type(type)
+      return coerce_array(inner, value) unless inner.nil?
+
+      klass = openapi_const(type)
+      return value if klass.nil?
+
+      if klass.respond_to?(:all_vars)
+        resolve_enum(klass, value)
+      elsif klass.respond_to?(:openapi_types) && value.is_a?(Hash)
+        build(klass, value)
+      else
+        value
       end
+    end
 
-      raise 'Unknown event type'
+    # Coerce each element of an `Array<T>` field by its inner type `T`.
+    def self.coerce_array(inner_type, value)
+      return value unless value.is_a?(Array)
+
+      value.map { |element| coerce(inner_type, element) }
+    end
+
+    # Extract `T` from an `Array<T>` openapi type, or nil when not an array type.
+    def self.array_inner_type(type)
+      match = type.to_s.match(/\AArray<(.+)>\z/)
+      match && match[1]
+    end
+
+    # Map a numeric enum wire value onto its string enum constant. A value that
+    # is already a string (REST-style) passes through untouched.
+    def self.resolve_enum(enum, value)
+      return value unless value.is_a?(Integer)
+
+      vars = enum.all_vars
+      # Guard the bounds explicitly: Ruby maps negative indices from the end of
+      # the array, so any unexpected wire value must fall back to the *_UNSPECIFIED
+      # member (index 0) rather than silently selecting the wrong constant.
+      value.between?(0, vars.length - 1) ? vars[value] : vars[0]
+    end
+
+    # Resolve an openapi_types entry (e.g. :ChargeMessageApiSource, :RefundInfo)
+    # to its generated class, or nil when the type is a primitive (String,
+    # Integer, ...) or otherwise unresolvable.
+    def self.openapi_const(type)
+      return nil if type.nil?
+
+      name = type.to_s
+      return nil unless Jamm::OpenAPI.const_defined?(name)
+
+      Jamm::OpenAPI.const_get(name)
+    rescue NameError
+      nil
+    end
+
+    # Recursively convert Hash keys to symbols so parsing is robust regardless of
+    # how the caller decoded the webhook JSON.
+    def self.deep_symbolize_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = deep_symbolize_keys(v) }
+      when Array
+        value.map { |v| deep_symbolize_keys(v) }
+      else
+        value
+      end
     end
 
     # Verify message.

data/lib/jamm.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require 'date'
 require 'rest-client'
 require 'openssl'
 require 'json'
 
+require 'jamm/api_version'
 require 'jamm/client'
 require 'jamm/errors'
 require 'jamm/oauth'
@@ -38,13 +40,33 @@ module Jamm
   @max_retry = 0
 
   class << self
-    attr_accessor :api, :client_id, :client_secret, :api_base, :environment, :mode, :oauth_base, :api_version, :connect_base,
+    attr_accessor :api, :client_id, :client_secret, :api_base, :environment, :mode, :oauth_base, :connect_base,
                   :openapi, :open_timeout, :read_timeout, :max_retry, :retry_initial_delay, :retry_max_delay
   end
 
+  # The Jamm-API-Version sent on every request; defaults to the version this SDK was built against.
+  def self.api_version
+    @api_version || Jamm::API_VERSION
+  end
+
+  def self.api_version=(version)
+    if version.nil? || version.to_s.empty?
+      @api_version = nil
+      return
+    end
+
+    version = version.to_s
+    raise ArgumentError, "invalid api_version \"#{version}\": expected YYYY-MM-DD" unless version.match?(/\A\d{4}-\d{2}-\d{2}\z/) && Date.valid_date?(*version.split('-').map(&:to_i))
+    raise ArgumentError, "api_version #{version} is newer than this SDK supports (#{Jamm::API_VERSION}); upgrade the SDK to use it" if version > Jamm::API_VERSION
+
+    @api_version = version
+  end
+
   # Configure SDK with Client ID and Secret.
   # Optionally enable `platform` for platformers to call Jamm API on behalf of their merchant.
-  def self.configure(client_id:, client_secret:, env:, platform: false)
+  # Optionally pin `api_version` (YYYY-MM-DD) to an API version older than the one this SDK was built against.
+  def self.configure(client_id:, client_secret:, env:, platform: false, api_version: nil)
+    self.api_version = api_version
     Jamm.client_id = client_id
     Jamm.client_secret = client_secret