jamm 2.1.0 → 2.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9d9cfa81304a829a1d016ff3a4d2e53fe2b15caf2fa6c4e8513161b16881dff
-  data.tar.gz: 9f1ffda9436127fa5101cbff162f8ac24f52a8b151ade3c7691a39e9144e52aa
+  metadata.gz: 0dc69a9799a5215efa21041879db8ee9d8b67678dc6ac20dc92046c165eec6fd
+  data.tar.gz: 33bd5a72e96fdc0212e956762e5bb7983604a5d1a1e9792d577267a61a2d96bd
 SHA512:
-  metadata.gz: 8af376c181770bbc2fb93c1002ca29493fde1c6cdf4227475a1ce891fd82d83c073774c7296c67e911ae064d55fa8314fb8550d390dbe9b991d56167ca30e95a
-  data.tar.gz: 6c8c4ca5abb8f6b4bcc0d94ab15441bfa1ca572e000a4358072bccf340e8493776c7791b6fcb4d798e0dd647ceac2db9c1937720aebcde971d132825f576328b
+  metadata.gz: 82fd64ead34ca1e458d831d21874ccb6bd53774e27170944a2c8d4d1532dcad9db4e589ffe55ce4a24b60bbd658f8816aebcc674afc6f5d096ba931ec1ae2806
+  data.tar.gz: f8d88d108bcd9822c56a05133248bf759b100f31ef3af3bc5b7f5ed14ea4c7ba5d111ca96a482fec038e5de09ac10d769d7d559ab57ac53dcb64dbbc9ce21785

data/CHANGELOG.md

@@ -0,0 +1,66 @@
+# 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.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,16 +1,18 @@
 PATH
   remote: .
   specs:
-    jamm (2.1.0)
+    jamm (2.2.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)
@@ -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/v1_error_type.rb

@@ -35,6 +35,8 @@ 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
     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 +54,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, 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). 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_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/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.2.0'
 end

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: jamm
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 2.2.0
 platform: ruby
 authors:
 - Jamm
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-06 00:00:00.000000000 Z
+date: 2026-05-25 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