jamm 2.1.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9d9cfa81304a829a1d016ff3a4d2e53fe2b15caf2fa6c4e8513161b16881dff
-  data.tar.gz: 9f1ffda9436127fa5101cbff162f8ac24f52a8b151ade3c7691a39e9144e52aa
+  metadata.gz: cb73f3a736756e42ca49cedb1fb255e011fb39e0c34dabc2f85bfd537836afe1
+  data.tar.gz: d5ce67a32f315473bca8800024d19b939b9dafefb358a077e7f30fa551dd01ed
 SHA512:
-  metadata.gz: 8af376c181770bbc2fb93c1002ca29493fde1c6cdf4227475a1ce891fd82d83c073774c7296c67e911ae064d55fa8314fb8550d390dbe9b991d56167ca30e95a
-  data.tar.gz: 6c8c4ca5abb8f6b4bcc0d94ab15441bfa1ca572e000a4358072bccf340e8493776c7791b6fcb4d798e0dd647ceac2db9c1937720aebcde971d132825f576328b
+  metadata.gz: ff218dca883cf3515ce3d37a89147c6ce1a615fc53568f0916edb48211f6de1a5b4af7c5613066a74a3df017cd81ec76d734c9ecec259b3a78457af4eb3d4900
+  data.tar.gz: 69cd60e93b565297f43fd08f7b6a768a6ae5955dddd47d4553b18756e5a3123cdb6548e596e1c9317928f613064c96c66630de9783fab57229d146e78ecfcbe2

data/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+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
+
+- Added `Jamm::Payment.off_session_async` for async off-session charges
+- Auto-fill `idempotency_key` with a UUID when `nil` or blank
+
+## [2.1.0] - 2026-04-06
+
+### Added
+
+- Added `ChargeError` details on `ChargeResult` for failed charges
+
+## [2.0.0] - 2026-03-16
+
+### Added
+
+- Platform authentication support
+- Refund support and split refund webhook events (succeeded / rejected)
+
+### Changed
+
+- Renamed `cancel` operations to `refund` across API and webhooks
+
+## [1.7.0] - 2025-11-11
+
+### Removed
+
+- Deprecated legacy contract charge public APIs
+
+## [1.6.0] - 2025-11-11
+
+### Changed
+
+- Version bump aligned with other SDKs
+
+## [1.5.0] - 2025-10-09
+
+### Changed
+
+- `OnSessionPayment` redirect link is now optional
+
+## [1.4.1] - 2025-08-22
+
+### Changed
+
+- Updated RubyGem GitHub source URL
+
+## [1.4.0] - 2025-08-22
+
+### Added
+
+- On-session and off-session payment support
+
+## [1.3.0] - 2025-07-08
+
+### Added
+
+- Embedded `error.v1` typed errors into OpenAPI proto

data/Gemfile

@@ -4,6 +4,7 @@ source 'https://rubygems.org'
 
 gemspec
 
+gem 'base64', '~> 0.2'
 gem 'rest-client', '~> 2.0'
 gem 'typhoeus', '~> 1.0', '>= 1.0.1'
 

data/Gemfile.lock

@@ -1,19 +1,21 @@
 PATH
   remote: .
   specs:
-    jamm (2.1.0)
+    jamm (2.3.0)
+      base64 (~> 0.2)
       rest-client (~> 2.0)
       typhoeus (~> 1.0, >= 1.0.1)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.6)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     ast (2.4.2)
+    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
@@ -47,7 +49,7 @@ GEM
     pry (0.14.2)
       coderay (~> 1.1)
       method_source (~> 1.0)
-    public_suffix (5.0.5)
+    public_suffix (5.1.1)
     racc (1.7.3)
     rainbow (3.1.1)
     rake (13.2.1)
@@ -90,6 +92,7 @@ PLATFORMS
   x86_64-linux
 
 DEPENDENCIES
+  base64 (~> 0.2)
   faker
   gimei
   jamm!

data/jamm.gemspec

@@ -15,6 +15,7 @@ Gem::Specification.new do |s|
   s.homepage    = 'https://jamm-pay.jp'
   s.license     = 'MIT'
 
+  s.add_dependency('base64', '~> 0.2')
   s.add_dependency('rest-client', '~> 2.0')
   s.add_dependency('typhoeus', '~> 1.0', '>= 1.0.1')
 

data/lib/jamm/api/api/payment_api.rb

@@ -89,7 +89,7 @@ module Api
 
     # Initiate async off-session payment
     # Starts asynchronous off-session payment processing and returns request tracking information.
-    # @param body [OffSessionPaymentAsyncRequest] This message represents a request to process an off-session payment asynchronously. It contains the customer ID and the amount to charge.
+    # @param body [OffSessionPaymentAsyncRequest] This message represents a request to process an off-session payment asynchronously. It contains the customer ID and the amount to charge. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
     # @param [Hash] opts the optional parameters
     # @return [OffSessionPaymentAsyncResponse]
     def async_off_session_payment(body, opts = {})
@@ -99,7 +99,7 @@ module Api
 
     # Initiate async off-session payment
     # Starts asynchronous off-session payment processing and returns request tracking information.
-    # @param body [OffSessionPaymentAsyncRequest] This message represents a request to process an off-session payment asynchronously. It contains the customer ID and the amount to charge.
+    # @param body [OffSessionPaymentAsyncRequest] This message represents a request to process an off-session payment asynchronously. It contains the customer ID and the amount to charge. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
     # @param [Hash] opts the optional parameters
     # @return [Array<(OffSessionPaymentAsyncResponse, Integer, Hash)>] OffSessionPaymentAsyncResponse data, response status code and response headers
     def async_off_session_payment_with_http_info(body, opts = {})
@@ -425,7 +425,7 @@ module Api
 
     # Initiate async withdraw (internal)
     # Internal-only endpoint for initiating asynchronous withdrawal processing.
-    # @param body [WithdrawAsyncRequest] This message represents a request to withdraw money from a customer asynchronously. It contains the customer ID and the amount to withdraw.
+    # @param body [WithdrawAsyncRequest] This message represents a request to withdraw money from a customer asynchronously. It contains the customer ID and the amount to withdraw. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
     # @param [Hash] opts the optional parameters
     # @return [WithdrawAsyncResponse]
     def internal_withdraw_async(body, opts = {})
@@ -435,7 +435,7 @@ module Api
 
     # Initiate async withdraw (internal)
     # Internal-only endpoint for initiating asynchronous withdrawal processing.
-    # @param body [WithdrawAsyncRequest] This message represents a request to withdraw money from a customer asynchronously. It contains the customer ID and the amount to withdraw.
+    # @param body [WithdrawAsyncRequest] This message represents a request to withdraw money from a customer asynchronously. It contains the customer ID and the amount to withdraw. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
     # @param [Hash] opts the optional parameters
     # @return [Array<(WithdrawAsyncResponse, Integer, Hash)>] WithdrawAsyncResponse data, response status code and response headers
     def internal_withdraw_async_with_http_info(body, opts = {})
@@ -561,7 +561,7 @@ module Api
 
     # Process payment directly without redirect
     # Execute a payment off-session within your application without redirecting to a payment page.
-    # @param body [OffSessionPaymentRequest] This message represents a request to process a payment directly within the application. It contains the customer ID and charge details to be processed.
+    # @param body [OffSessionPaymentRequest] This message represents a request to process a payment directly within the application. It contains the customer ID and charge details to be processed. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
     # @param [Hash] opts the optional parameters
     # @return [OffSessionPaymentResponse]
     def off_session_payment(body, opts = {})
@@ -571,7 +571,7 @@ module Api
 
     # Process payment directly without redirect
     # Execute a payment off-session within your application without redirecting to a payment page.
-    # @param body [OffSessionPaymentRequest] This message represents a request to process a payment directly within the application. It contains the customer ID and charge details to be processed.
+    # @param body [OffSessionPaymentRequest] This message represents a request to process a payment directly within the application. It contains the customer ID and charge details to be processed. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
     # @param [Hash] opts the optional parameters
     # @return [Array<(OffSessionPaymentResponse, Integer, Hash)>] OffSessionPaymentResponse data, response status code and response headers
     def off_session_payment_with_http_info(body, opts = {})
@@ -629,7 +629,7 @@ module Api
 
     # Process payment with optional redirect
     # Unified interface for creating payments - supports existing customers, new customers with charges, and contract-only creation.
-    # @param body [OnSessionPaymentRequest] Request message for the unified payment interface. The system intelligently routes the request to the appropriate payment method based on the provided parameters.
+    # @param body [OnSessionPaymentRequest] Request message for the unified payment interface. The system intelligently routes the request to the appropriate payment method based on the provided parameters. Supports triggerError for test error simulation via the core InitiatePayment/ApprovePayment flow. See InitialCharge.metadata for details on behavior differences by stage.
     # @param [Hash] opts the optional parameters
     # @return [OnSessionPaymentResponse]
     def on_session_payment(body, opts = {})
@@ -639,7 +639,7 @@ module Api
 
     # Process payment with optional redirect
     # Unified interface for creating payments - supports existing customers, new customers with charges, and contract-only creation.
-    # @param body [OnSessionPaymentRequest] Request message for the unified payment interface. The system intelligently routes the request to the appropriate payment method based on the provided parameters.
+    # @param body [OnSessionPaymentRequest] Request message for the unified payment interface. The system intelligently routes the request to the appropriate payment method based on the provided parameters. Supports triggerError for test error simulation via the core InitiatePayment/ApprovePayment flow. See InitialCharge.metadata for details on behavior differences by stage.
     # @param [Hash] opts the optional parameters
     # @return [Array<(OnSessionPaymentResponse, Integer, Hash)>] OnSessionPaymentResponse data, response status code and response headers
     def on_session_payment_with_http_info(body, opts = {})
@@ -765,7 +765,7 @@ module Api
 
     # Withdraw money from customer immediately, without redirect
     # This call is synchronous. The money will be withdrawn immediately.
-    # @param body [WithdrawRequest] This message represents a request to withdraw money from a customer. It contains the customer ID and the amount to withdraw.
+    # @param body [WithdrawRequest] This message represents a request to withdraw money from a customer. It contains the customer ID and the amount to withdraw. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
     # @param [Hash] opts the optional parameters
     # @return [WithdrawResponse]
     def withdraw(body, opts = {})
@@ -775,7 +775,7 @@ module Api
 
     # Withdraw money from customer immediately, without redirect
     # This call is synchronous. The money will be withdrawn immediately.
-    # @param body [WithdrawRequest] This message represents a request to withdraw money from a customer. It contains the customer ID and the amount to withdraw.
+    # @param body [WithdrawRequest] This message represents a request to withdraw money from a customer. It contains the customer ID and the amount to withdraw. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
     # @param [Hash] opts the optional parameters
     # @return [Array<(WithdrawResponse, Integer, Hash)>] WithdrawResponse data, response status code and response headers
     def withdraw_with_http_info(body, opts = {})

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

@@ -35,6 +35,9 @@ module Api
     PAYMENT_CHARGE_SUBSCRIPTION_EXPIRED = "ERROR_TYPE_PAYMENT_CHARGE_SUBSCRIPTION_EXPIRED".freeze
     PAYMENT_LINK_EXPIRED = "ERROR_TYPE_PAYMENT_LINK_EXPIRED".freeze
     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
@@ -52,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, 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.  Chargeに関する任意のキーと値の追加情報。 加盟店ダッシュボードで確認できます。
+    # 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_off_session_payment_async_request.rb

@@ -14,17 +14,21 @@ require 'date'
 require 'time'
 
 module Api
-  # This message represents a request to process an off-session payment asynchronously. It contains the customer ID and the amount to charge.
+  # This message represents a request to process an off-session payment asynchronously. It contains the customer ID and the amount to charge. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
   class OffSessionPaymentAsyncRequest
     attr_accessor :customer
 
     attr_accessor :charge
 
+    # Merchant-supplied idempotency key for retry safety. When present, a retry with the same (merchant, idempotency_key) returns the original charge instead of creating a new one. When absent (empty), the server generates a UUID per call (current behavior). ASCII only, 1-255 chars matching ^[a-zA-Z0-9_\\-]{1,255}$.
+    attr_accessor :idempotency_key
+
     # Attribute mapping from ruby-style variable name to JSON key.
     def self.attribute_map
       {
         :'customer' => :'customer',
-        :'charge' => :'charge'
+        :'charge' => :'charge',
+        :'idempotency_key' => :'idempotencyKey'
       }
     end
 
@@ -37,7 +41,8 @@ module Api
     def self.openapi_types
       {
         :'customer' => :'String',
-        :'charge' => :'InitialCharge'
+        :'charge' => :'InitialCharge',
+        :'idempotency_key' => :'String'
       }
     end
 
@@ -69,6 +74,10 @@ module Api
       if attributes.key?(:'charge')
         self.charge = attributes[:'charge']
       end
+
+      if attributes.key?(:'idempotency_key')
+        self.idempotency_key = attributes[:'idempotency_key']
+      end
     end
 
     # Show invalid properties with the reasons. Usually used together with valid?
@@ -92,7 +101,8 @@ module Api
       return true if self.equal?(o)
       self.class == o.class &&
           customer == o.customer &&
-          charge == o.charge
+          charge == o.charge &&
+          idempotency_key == o.idempotency_key
     end
 
     # @see the `==` method
@@ -104,7 +114,7 @@ module Api
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [customer, charge].hash
+      [customer, charge, idempotency_key].hash
     end
 
     # Builds the object from hash

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

@@ -14,7 +14,7 @@ require 'date'
 require 'time'
 
 module Api
-  # This message represents a request to process a payment directly within the application. It contains the customer ID and charge details to be processed.
+  # This message represents a request to process a payment directly within the application. It contains the customer ID and charge details to be processed. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
   class OffSessionPaymentRequest
     attr_accessor :customer
 

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

@@ -14,7 +14,7 @@ require 'date'
 require 'time'
 
 module Api
-  # Request message for the unified payment interface. The system intelligently routes the request to the appropriate payment method based on the provided parameters.
+  # Request message for the unified payment interface. The system intelligently routes the request to the appropriate payment method based on the provided parameters. Supports triggerError for test error simulation via the core InitiatePayment/ApprovePayment flow. See InitialCharge.metadata for details on behavior differences by stage.
   class OnSessionPaymentRequest
     attr_accessor :customer
 

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/models/v1_withdraw_async_request.rb

@@ -14,17 +14,21 @@ require 'date'
 require 'time'
 
 module Api
-  # This message represents a request to withdraw money from a customer asynchronously. It contains the customer ID and the amount to withdraw.
+  # This message represents a request to withdraw money from a customer asynchronously. It contains the customer ID and the amount to withdraw. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
   class WithdrawAsyncRequest
     attr_accessor :customer
 
     attr_accessor :charge
 
+    # Merchant-supplied idempotency key for retry safety. When present, a retry with the same (merchant, idempotency_key) returns the original charge instead of creating a new one. When absent (empty), the server generates a UUID per call (current behavior). ASCII only, 1-255 chars matching ^[a-zA-Z0-9_\\-]{1,255}$.
+    attr_accessor :idempotency_key
+
     # Attribute mapping from ruby-style variable name to JSON key.
     def self.attribute_map
       {
         :'customer' => :'customer',
-        :'charge' => :'charge'
+        :'charge' => :'charge',
+        :'idempotency_key' => :'idempotencyKey'
       }
     end
 
@@ -37,7 +41,8 @@ module Api
     def self.openapi_types
       {
         :'customer' => :'String',
-        :'charge' => :'InitialCharge'
+        :'charge' => :'InitialCharge',
+        :'idempotency_key' => :'String'
       }
     end
 
@@ -69,6 +74,10 @@ module Api
       if attributes.key?(:'charge')
         self.charge = attributes[:'charge']
       end
+
+      if attributes.key?(:'idempotency_key')
+        self.idempotency_key = attributes[:'idempotency_key']
+      end
     end
 
     # Show invalid properties with the reasons. Usually used together with valid?
@@ -92,7 +101,8 @@ module Api
       return true if self.equal?(o)
       self.class == o.class &&
           customer == o.customer &&
-          charge == o.charge
+          charge == o.charge &&
+          idempotency_key == o.idempotency_key
     end
 
     # @see the `==` method
@@ -104,7 +114,7 @@ module Api
     # Calculates hash code according to all attributes.
     # @return [Integer] Hash code
     def hash
-      [customer, charge].hash
+      [customer, charge, idempotency_key].hash
     end
 
     # Builds the object from hash

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

@@ -14,7 +14,7 @@ require 'date'
 require 'time'
 
 module Api
-  # This message represents a request to withdraw money from a customer. It contains the customer ID and the amount to withdraw.
+  # This message represents a request to withdraw money from a customer. It contains the customer ID and the amount to withdraw. Supports triggerError in charge.metadata for test error simulation. See InitialCharge.metadata.
   class WithdrawRequest
     attr_accessor :customer
 

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/payment.rb

@@ -3,6 +3,7 @@
 require 'rest-client'
 require 'json'
 require 'base64'
+require 'securerandom'
 require 'jamm/errors'
 
 module Jamm
@@ -50,6 +51,29 @@ module Jamm
       raise Jamm::ApiError.from_error(e)
     end
 
+    # Auto-fills idempotency_key with a UUID when the caller did not supply one,
+    # so every async charge is retry-safe by default. A caller-supplied key is
+    # left untouched so explicit retries reuse the same value.
+    def self.off_session_async(customer:, charge:, idempotency_key: nil, merchant: nil)
+      key =
+        if idempotency_key.nil? || idempotency_key.strip.empty?
+          SecureRandom.uuid
+        else
+          idempotency_key
+        end
+
+      request = Jamm::OpenAPI::OffSessionPaymentAsyncRequest.new(
+        customer: customer,
+        charge: charge,
+        idempotency_key: key
+      )
+
+      handler = Jamm::Client.handler(merchant: merchant)
+      Jamm::OpenAPI::PaymentApi.new(handler).async_off_session_payment(request)
+    rescue Jamm::OpenAPI::ApiError => e
+      raise Jamm::ApiError.from_error(e)
+    end
+
     def self.get(charge_id, merchant: nil)
       handler = Jamm::Client.handler(merchant: merchant)
 

data/lib/jamm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Jamm
-  VERSION = '2.1.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,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: jamm
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Jamm
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-06 00:00:00.000000000 Z
+date: 2026-06-24 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
 - !ruby/object:Gem::Dependency
   name: rest-client
   requirement: !ruby/object:Gem::Requirement
@@ -52,6 +66,7 @@ extra_rdoc_files: []
 files:
 - ".gitignore"
 - ".rubocop.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -69,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