jamm 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dc69a9799a5215efa21041879db8ee9d8b67678dc6ac20dc92046c165eec6fd
-  data.tar.gz: 33bd5a72e96fdc0212e956762e5bb7983604a5d1a1e9792d577267a61a2d96bd
+  metadata.gz: cb73f3a736756e42ca49cedb1fb255e011fb39e0c34dabc2f85bfd537836afe1
+  data.tar.gz: d5ce67a32f315473bca8800024d19b939b9dafefb358a077e7f30fa551dd01ed
 SHA512:
-  metadata.gz: 82fd64ead34ca1e458d831d21874ccb6bd53774e27170944a2c8d4d1532dcad9db4e589ffe55ce4a24b60bbd658f8816aebcc674afc6f5d096ba931ec1ae2806
-  data.tar.gz: f8d88d108bcd9822c56a05133248bf759b100f31ef3af3bc5b7f5ed14ea4c7ba5d111ca96a482fec038e5de09ac10d769d7d559ab57ac53dcb64dbbc9ce21785
+  metadata.gz: ff218dca883cf3515ce3d37a89147c6ce1a615fc53568f0916edb48211f6de1a5b4af7c5613066a74a3df017cd81ec76d734c9ecec259b3a78457af4eb3d4900
+  data.tar.gz: 69cd60e93b565297f43fd08f7b6a768a6ae5955dddd47d4553b18756e5a3123cdb6548e596e1c9317928f613064c96c66630de9783fab57229d146e78ecfcbe2

data/CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.3.0] - 2026-06-24
+
+### Added
+
+- Resolve numeric enum wire values (`status`, `api_source`, …) onto their string enum constants on every webhook model, matching REST API responses (the backend serializes webhooks with `json.Marshal`, so all enums arrive numeric)
+- Surface the refund `rfd-` id on the flat `refund_id` attribute in addition to the nested `refund.id`
+- Parse `EVENT_TYPE_USER_ACCOUNT_DELETED` webhooks (previously raised `Unknown event type`)
+
+### Fixed
+
+- Webhook parsing no longer fails on new fields added by the backend (forward-compatible)
+- Refund webhooks now expose the nested transaction fields and the refund's `rfd-` id (`refund.id`)
+- `status` on refund/charge webhooks is no longer left as a raw integer
+- Nested webhook fields (e.g. `refund.error`) are now typed model instances instead of raw Hashes, so `error.code` / `error.message` work instead of raising `NoMethodError`
+- `Webhook.parse` now accepts payloads with either string or symbol keys
+
 ## [2.2.0] - 2026-05-20
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jamm (2.2.0)
+    jamm (2.3.0)
       base64 (~> 0.2)
       rest-client (~> 2.0)
       typhoeus (~> 1.0, >= 1.0.1)
@@ -15,7 +15,7 @@ GEM
     base64 (0.3.0)
     bigdecimal (3.1.7)
     coderay (1.1.3)
-    concurrent-ruby (1.3.4)
+    concurrent-ruby (1.3.7)
     crack (1.0.0)
       bigdecimal
       rexml

data/lib/jamm/api/models/charge_message_api_source.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 ChargeMessageApiSource
+    UNSPECIFIED = "API_SOURCE_UNSPECIFIED".freeze
+    OFF_SESSION_SYNC = "API_SOURCE_OFF_SESSION_SYNC".freeze
+    OFF_SESSION_ASYNC = "API_SOURCE_OFF_SESSION_ASYNC".freeze
+    ON_SESSION = "API_SOURCE_ON_SESSION".freeze
+
+    def self.all_vars
+      @all_vars ||= [UNSPECIFIED, OFF_SESSION_SYNC, OFF_SESSION_ASYNC, ON_SESSION].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 ChargeMessageApiSource.all_vars.include?(value)
+      raise "Invalid ENUM value #{value} for class #ChargeMessageApiSource"
+    end
+  end
+end

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

@@ -62,6 +62,8 @@ module Api
 
     attr_accessor :refund
 
+    attr_accessor :api_source
+
     class EnumAttributeValidator
       attr_reader :datatype
       attr_reader :allowable_values
@@ -105,7 +107,8 @@ module Api
         :'consumption_tax' => :'consumptionTax',
         :'error' => :'error',
         :'refund_id' => :'refundId',
-        :'refund' => :'refund'
+        :'refund' => :'refund',
+        :'api_source' => :'apiSource'
       }
     end
 
@@ -135,7 +138,8 @@ module Api
         :'consumption_tax' => :'Integer',
         :'error' => :'Apiv1Error',
         :'refund_id' => :'String',
-        :'refund' => :'RefundInfo'
+        :'refund' => :'RefundInfo',
+        :'api_source' => :'ChargeMessageApiSource'
       }
     end
 
@@ -237,6 +241,12 @@ module Api
       if attributes.key?(:'refund')
         self.refund = attributes[:'refund']
       end
+
+      if attributes.key?(:'api_source')
+        self.api_source = attributes[:'api_source']
+      else
+        self.api_source = 'API_SOURCE_UNSPECIFIED'
+      end
     end
 
     # Show invalid properties with the reasons. Usually used together with valid?
@@ -277,7 +287,8 @@ module Api
           consumption_tax == o.consumption_tax &&
           error == o.error &&
           refund_id == o.refund_id &&
-          refund == o.refund
+          refund == o.refund &&
+          api_source == o.api_source
     end
 
     # @see the `==` method
@@ -289,7 +300,7 @@ module Api
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [id, customer, status, description, merchant_name, initial_amount, discount, final_amount, amount_refunded, currency, processed_at, jamm_fee, created_at, updated_at, original_transaction_jamm_fee, consumption_tax, error, refund_id, refund].hash
+      [id, customer, status, description, merchant_name, initial_amount, discount, final_amount, amount_refunded, currency, processed_at, jamm_fee, created_at, updated_at, original_transaction_jamm_fee, consumption_tax, error, refund_id, refund, api_source].hash
     end
 
     # Builds the object from hash

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

@@ -37,6 +37,7 @@ module Api
     PAYMENT_CHARGE_INSUFFICIENT_FUNDS = "ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS".freeze
     PAYMENT_CUSTOMER_NOT_FOUND = "ERROR_TYPE_PAYMENT_CUSTOMER_NOT_FOUND".freeze
     PAYMENT_CUSTOMER_INACTIVE = "ERROR_TYPE_PAYMENT_CUSTOMER_INACTIVE".freeze
+    PAYMENT_SERVICE_DISABLED = "ERROR_TYPE_PAYMENT_SERVICE_DISABLED".freeze
     CSV_VALIDATION_FAILED = "ERROR_TYPE_CSV_VALIDATION_FAILED".freeze
     CSV_TOTP_REQUIRED = "ERROR_TYPE_CSV_TOTP_REQUIRED".freeze
     CSV_TOTP_INVALID = "ERROR_TYPE_CSV_TOTP_INVALID".freeze
@@ -54,7 +55,7 @@ module Api
     TOTP_DISABLE_FAILED = "ERROR_TYPE_TOTP_DISABLE_FAILED".freeze
 
     def self.all_vars
-      @all_vars ||= [UNSPECIFIED, AUTH_FAILED, AUTH_REJECTED, ACCOUNT_CREATION_FAILED, ACCOUNT_MODIFICATION_FAILED, ACCOUNT_DELETION_FAILED, ACCOUNT_BANK_REGISTRATION_FAILED, KYC_REJECTED, NOTIFICATION_WEBHOOK_FAILED, NOTIFICATION_EMAIL_FAILED, NOTIFICATION_SMS_FAILED, PAYMENT_GATEWAY_UNAVAILABLE, PAYMENT_GATEWAY_FAILED, PAYMENT_VALIDATION_FAILED, PAYMENT_CHARGE_FAILED, PAYMENT_CHARGE_REJECTED, PAYMENT_CHARGE_OVER_LIMIT, PAYMENT_CHARGE_SUBSCRIPTION_EXPIRED, PAYMENT_LINK_EXPIRED, PAYMENT_CHARGE_INSUFFICIENT_FUNDS, PAYMENT_CUSTOMER_NOT_FOUND, PAYMENT_CUSTOMER_INACTIVE, CSV_VALIDATION_FAILED, CSV_TOTP_REQUIRED, CSV_TOTP_INVALID, CSV_TOTP_EXPIRED, CSV_TOTP_LOCKED, CSV_BATCH_TOO_LARGE, CSV_CUSTOMER_NOT_FOUND, CSV_PROCESSING_FAILED, CSV_CHALLENGE_NOT_FOUND, CSV_DUPLICATE_USER, TOTP_SETUP_FAILED, TOTP_ALREADY_ENABLED, TOTP_NOT_ENABLED, TOTP_SETUP_INVALID, TOTP_DISABLE_FAILED].freeze
+      @all_vars ||= [UNSPECIFIED, AUTH_FAILED, AUTH_REJECTED, ACCOUNT_CREATION_FAILED, ACCOUNT_MODIFICATION_FAILED, ACCOUNT_DELETION_FAILED, ACCOUNT_BANK_REGISTRATION_FAILED, KYC_REJECTED, NOTIFICATION_WEBHOOK_FAILED, NOTIFICATION_EMAIL_FAILED, NOTIFICATION_SMS_FAILED, PAYMENT_GATEWAY_UNAVAILABLE, PAYMENT_GATEWAY_FAILED, PAYMENT_VALIDATION_FAILED, PAYMENT_CHARGE_FAILED, PAYMENT_CHARGE_REJECTED, PAYMENT_CHARGE_OVER_LIMIT, PAYMENT_CHARGE_SUBSCRIPTION_EXPIRED, PAYMENT_LINK_EXPIRED, PAYMENT_CHARGE_INSUFFICIENT_FUNDS, PAYMENT_CUSTOMER_NOT_FOUND, PAYMENT_CUSTOMER_INACTIVE, PAYMENT_SERVICE_DISABLED, CSV_VALIDATION_FAILED, CSV_TOTP_REQUIRED, CSV_TOTP_INVALID, CSV_TOTP_EXPIRED, CSV_TOTP_LOCKED, CSV_BATCH_TOO_LARGE, CSV_CUSTOMER_NOT_FOUND, CSV_PROCESSING_FAILED, CSV_CHALLENGE_NOT_FOUND, CSV_DUPLICATE_USER, TOTP_SETUP_FAILED, TOTP_ALREADY_ENABLED, TOTP_NOT_ENABLED, TOTP_SETUP_INVALID, TOTP_DISABLE_FAILED].freeze
     end
 
     # Builds the enum from string

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

@@ -22,7 +22,7 @@ module Api
     # Description is an arbitrary string for merchant to track the charge. This information is displayed on Merchant Dashboard.  決済の説明。ショップが決済を追跡するための任意の文字列です。  @gotags: validate:\"required,max=1024\"
     attr_accessor :description
 
-    # Arbitrary key-value additional information about the charge. You can see this information in our merchant dashboard.  ## Testing with triggerError  Set the key \"triggerError\" to a valid ERROR_TYPE_* enum name (e.g. \"ERROR_TYPE_PAYMENT_CHARGE_FAILED\") to simulate a payment failure. Behavior differs by flow:  Off-session (Withdraw, WithdrawAsync, OffSessionPayment, OffSessionPaymentAsync):   Reads triggerError from this field (charge.metadata).   Creates a failed transaction record and sends a failure webhook.   Returns transport-level 400 for ERROR_TYPE_PAYMENT_VALIDATION_FAILED,   500 for all other ERROR_TYPE_* values.  On-session (InitiatePayment / ApprovePayment — consumer-facing core service):   Reads triggerError from the payment's stored metadata (charge or merchant-customer).   Initiate stage: only ERROR_TYPE_PAYMENT_VALIDATION_FAILED and     ERROR_TYPE_PAYMENT_LINK_EXPIRED are honored; other types are ignored.     No failed transaction or webhook is created. Returns 200 OK with     an embedded InitiatePaymentError payload.   Approve stage: all ERROR_TYPE_* values are honored.     Creates workflow-specific failure records (cancelled contract and/or     failed transaction depending on the workflow type). Returns 200 OK with     an embedded ApprovePaymentError payload.  Note: CreateContractWithoutCharge has no charge, so this field does not apply. On-session triggerError for that flow is read from merchant-customer metadata instead.  ## Error types by payment stage  Initiate (payment session setup, workflow creation):   - ERROR_TYPE_PAYMENT_VALIDATION_FAILED  — invalid request   - ERROR_TYPE_PAYMENT_LINK_EXPIRED       — payment link expired  Approve (pre-charge validation + BankPay charge execution):   - ERROR_TYPE_PAYMENT_VALIDATION_FAILED  — invalid request (e.g. deleted/inactive customer)   - ERROR_TYPE_PAYMENT_CHARGE_REJECTED    — KYC not approved   - ERROR_TYPE_PAYMENT_CHARGE_OVER_LIMIT  — charge exceeds bank quota   - ERROR_TYPE_PAYMENT_LINK_EXPIRED       — payment link expired   - ERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLE — BankPay/bank under maintenance   - ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS — insufficient funds in customer's account   - ERROR_TYPE_PAYMENT_GATEWAY_FAILED     — BankPay rejected the charge   - ERROR_TYPE_PAYMENT_CHARGE_FAILED      — generic charge failure (internal, not found, etc.)  Chargeに関する任意のキーと値の追加情報。 加盟店ダッシュボードで確認できます。  テスト環境では、\"triggerError\" キーに ERROR_TYPE_* の列挙名を設定すると 決済エラーをシミュレートできます。動作はフローによって異なります。 詳細は上記の英語コメントを参照してください。
+    # Arbitrary key-value additional information about the charge. You can see this information in our merchant dashboard.  ## Testing with triggerError  Set the key \"triggerError\" to a valid ERROR_TYPE_* enum name (e.g. \"ERROR_TYPE_PAYMENT_CHARGE_FAILED\") to simulate a payment failure. Behavior differs by flow:  Off-session (Withdraw, WithdrawAsync, OffSessionPayment, OffSessionPaymentAsync):   Reads triggerError from this field (charge.metadata).   Creates a failed transaction record and sends a failure webhook.   Returns transport-level 400 for ERROR_TYPE_PAYMENT_VALIDATION_FAILED,   500 for all other ERROR_TYPE_* values.  On-session (InitiatePayment / ApprovePayment — consumer-facing core service):   Reads triggerError from the payment's stored metadata (charge or merchant-customer).   Initiate stage: only ERROR_TYPE_PAYMENT_VALIDATION_FAILED and     ERROR_TYPE_PAYMENT_LINK_EXPIRED are honored; other types are ignored.     No failed transaction or webhook is created. Returns 200 OK with     an embedded InitiatePaymentError payload.   Approve stage: all ERROR_TYPE_* values are honored.     Creates workflow-specific failure records (cancelled contract and/or     failed transaction depending on the workflow type). For charge-bearing     workflows it also sends a charge.fail webhook (api_source ON_SESSION),     mirroring off-session triggerError and real on-session failures.     Returns 200 OK with an embedded ApprovePaymentError payload.  Note: CreateContractWithoutCharge has no charge, so this field does not apply. On-session triggerError for that flow is read from merchant-customer metadata instead.  ## Error types by payment stage  Initiate (payment session setup, workflow creation):   - ERROR_TYPE_PAYMENT_VALIDATION_FAILED  — invalid request   - ERROR_TYPE_PAYMENT_LINK_EXPIRED       — payment link expired  Approve (pre-charge validation + BankPay charge execution):   - ERROR_TYPE_PAYMENT_VALIDATION_FAILED  — invalid request (e.g. deleted/inactive customer)   - ERROR_TYPE_PAYMENT_CHARGE_REJECTED    — KYC not approved   - ERROR_TYPE_PAYMENT_CHARGE_OVER_LIMIT  — charge exceeds bank quota   - ERROR_TYPE_PAYMENT_LINK_EXPIRED       — payment link expired   - ERROR_TYPE_PAYMENT_GATEWAY_UNAVAILABLE — BankPay/bank under maintenance   - ERROR_TYPE_PAYMENT_CHARGE_INSUFFICIENT_FUNDS — insufficient funds in customer's account   - ERROR_TYPE_PAYMENT_GATEWAY_FAILED     — BankPay rejected the charge   - ERROR_TYPE_PAYMENT_CHARGE_FAILED      — generic charge failure (internal, not found, etc.)  Chargeに関する任意のキーと値の追加情報。 加盟店ダッシュボードで確認できます。  テスト環境では、\"triggerError\" キーに ERROR_TYPE_* の列挙名を設定すると 決済エラーをシミュレートできます。動作はフローによって異なります。 詳細は上記の英語コメントを参照してください。
     attr_accessor :metadata
 
     # Fee charged by the platform (in JPY). Must be >= the Jamm fee for the merchant. Only meaningful when the caller is a platform. Ignored for direct merchant calls.  プラットフォームが徴収する手数料（日本円）。加盟店のJamm手数料以上である必要があります。

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

@@ -17,7 +17,7 @@ module Api
   # RefundInfo contains refund-specific details for refund and refund_failed webhook events.
   class RefundInfo
     # External refund identifier (rfd-*).
-    attr_accessor :refund_id
+    attr_accessor :id
 
     # Amount refunded for this event.
     attr_accessor :amount_refunded
@@ -39,7 +39,7 @@ module Api
     # Attribute mapping from ruby-style variable name to JSON key.
     def self.attribute_map
       {
-        :'refund_id' => :'refundId',
+        :'id' => :'id',
         :'amount_refunded' => :'amountRefunded',
         :'jamm_fee' => :'jammFee',
         :'consumption_tax' => :'consumptionTax',
@@ -57,7 +57,7 @@ module Api
     # Attribute type mapping.
     def self.openapi_types
       {
-        :'refund_id' => :'String',
+        :'id' => :'String',
         :'amount_refunded' => :'Integer',
         :'jamm_fee' => :'Integer',
         :'consumption_tax' => :'Integer',
@@ -88,8 +88,8 @@ module Api
         h[k.to_sym] = v
       }
 
-      if attributes.key?(:'refund_id')
-        self.refund_id = attributes[:'refund_id']
+      if attributes.key?(:'id')
+        self.id = attributes[:'id']
       end
 
       if attributes.key?(:'amount_refunded')
@@ -137,7 +137,7 @@ module Api
     def ==(o)
       return true if self.equal?(o)
       self.class == o.class &&
-          refund_id == o.refund_id &&
+          id == o.id &&
           amount_refunded == o.amount_refunded &&
           jamm_fee == o.jamm_fee &&
           consumption_tax == o.consumption_tax &&
@@ -155,7 +155,7 @@ module Api
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [refund_id, amount_refunded, jamm_fee, consumption_tax, original_transaction_fee_waived, error, processed_at].hash
+      [id, amount_refunded, jamm_fee, consumption_tax, original_transaction_fee_waived, error, processed_at].hash
     end
 
     # Builds the object from hash

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'

data/lib/jamm/version.rb

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

data/lib/jamm/webhook.rb

@@ -11,39 +11,157 @@ 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)
+      # 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)
 
       case json[:event_type]
-      when Jamm::OpenAPI::EventType::CHARGE_CREATED
-        out.content = Jamm::OpenAPI::ChargeMessage.new(json[:content])
+      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?
+
+      known = klass.attribute_map
+      types = klass.openapi_types
+      filtered = attributes.each_with_object({}) do |(key, value), acc|
+        sym = key.to_sym
+        next unless known.key?(sym)
+
+        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
+    # 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.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jamm
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Jamm
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-25 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -84,6 +84,7 @@ files:
 - lib/jamm/api/configuration.rb
 - lib/jamm/api/models/apiv1_error.rb
 - lib/jamm/api/models/apiv1_status.rb
+- lib/jamm/api/models/charge_message_api_source.rb
 - lib/jamm/api/models/customer_service_update_customer_body.rb
 - lib/jamm/api/models/googlerpc_status.rb
 - lib/jamm/api/models/protobuf_any.rb