jamm 2.7.0 → 2.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 4b472b4eb5e6fce821a1f661259e31f08e223d7192d12be515c2a6229253a00b
4
- data.tar.gz: cfe4d590089f2ba73b3f13f4fa96bf4d20df6c520f2194aa212d509d739f1c9e
3
+ metadata.gz: 8bedb3baa2ce6db911a197922c5782407872e542c90d449caba660d2526d83a4
4
+ data.tar.gz: be664aaa04efc5d7e6596c042421b9d033c5278f6c1e1da50eb18ac8b9f986bf
5
5
  SHA512:
6
- metadata.gz: aaae08e45949517f521919d1f9c29ea9a79c72ac99cec017f07161218399d35a0519070b209acac3eee65ba34c2a55cedf92d6e5ec6dc30681400baaa4df98fb
7
- data.tar.gz: 2eaaa934cf8227ab5d583d8d9d479a2a76679fad2f8f526b840efad9352d42e4c948e354fde16b9525cbb7b11d3b954e111658e32a27cb660bcf4fc623565d5e
6
+ metadata.gz: fdc175ea2a97844116c3de3d040b213696298a3d1e0382301efd04351f0ca8f03e35d97241d855615a5f46b348ce634e5c09acf5261baddefcc777314479866c
7
+ data.tar.gz: 5aa7a8c24204387fd3b617df8465f2dfbada4b66961b9939f9378eeedcd1c6d2b3e5b91e5d4e228db58cf2f41373b1031275eb122a482e6f0023502890a588d4
data/CHANGELOG.md CHANGED
@@ -5,6 +5,21 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [Unreleased]
9
+
10
+ ## [2.8.0] - 2026-11-19
11
+
12
+ ### Added
13
+
14
+ - `Jamm::ApiError#api_error_type`: the error type of any API error, e.g. `ERROR_TYPE_PAYMENT_VALIDATION_FAILED`. Use it instead of `error_type`, which reads `ERROR_TYPE_UNSPECIFIED` for REST answers and is unchanged for compatibility. A type this SDK doesn't know yet is passed through as its string.
15
+ - `Jamm::ApiError#charge_id`: the charge ID on an `ERROR_TYPE_PAYMENT_CHARGE_PENDING` answer (outcome not known yet; not returned by the API yet). Retry only with the same `idempotency_key`, or wait for the webhook.
16
+ - `Jamm::Payment.off_session(..., idempotency_key:)`: an optional key that makes a sync charge retry-safe once it is enabled for your merchant (until then a request with a key is rejected). Nothing is sent when it is `nil` or blank; unlike `off_session_async`, no key is generated for you.
17
+ - `amount_refunded_net_discounts` on the refund webhook `refund` — the amount returned to the buyer for this refund (`amount_refunded` minus its share of the charge discount). Sent on `REFUND_SUCCEEDED` only.
18
+
19
+ ### Fixed
20
+
21
+ - `Jamm::ApiError.from_error` no longer raises (`TypeError`, `JSON::ParserError` or `NoMethodError`) when the response body is missing, isn't JSON, or isn't a JSON object: a connection timeout has no body, and a proxy error page isn't JSON. The original error is kept.
22
+
8
23
  ## [2.7.0] - 2026-10-05
9
24
 
10
25
  ### Added
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- jamm (2.7.0)
4
+ jamm (2.8.0)
5
5
  base64 (~> 0.2)
6
6
  rest-client (~> 2.0)
7
7
  typhoeus (~> 1.0, >= 1.0.1)
@@ -9,7 +9,7 @@ PATH
9
9
  GEM
10
10
  remote: https://rubygems.org/
11
11
  specs:
12
- addressable (2.9.0)
12
+ addressable (2.9.1)
13
13
  public_suffix (>= 2.0.2, < 8.0)
14
14
  ast (2.4.2)
15
15
  base64 (0.3.0)
data/README.md CHANGED
@@ -59,6 +59,21 @@ payment = Jamm::Payment.create(
59
59
  )
60
60
  ```
61
61
 
62
+ ## Errors
63
+
64
+ Most API calls raise `Jamm::ApiError` on failure, with the HTTP status in `code` and the error type in `api_error_type`
65
+ (e.g. `ERROR_TYPE_PAYMENT_VALIDATION_FAILED`). Use `api_error_type`: `error_type` reads
66
+ `ERROR_TYPE_UNSPECIFIED` for REST answers and is kept only for compatibility. The generated clients under
67
+ `Jamm::OpenAPI` raise `Jamm::OpenAPI::ApiError`; convert it to read the same fields:
68
+
69
+ ```ruby
70
+ begin
71
+ Jamm::OpenAPI::PaymentApi.new(Jamm::Client.handler).withdraw(request)
72
+ rescue Jamm::OpenAPI::ApiError => e
73
+ raise Jamm::ApiError.from_error(e)
74
+ end
75
+ ```
76
+
62
77
  ## Installation
63
78
  ```sh
64
79
  gem install jamm
@@ -22,6 +22,7 @@ module Api
22
22
  ACCOUNT_MODIFICATION_FAILED = "ERROR_TYPE_ACCOUNT_MODIFICATION_FAILED".freeze
23
23
  ACCOUNT_DELETION_FAILED = "ERROR_TYPE_ACCOUNT_DELETION_FAILED".freeze
24
24
  ACCOUNT_BANK_REGISTRATION_FAILED = "ERROR_TYPE_ACCOUNT_BANK_REGISTRATION_FAILED".freeze
25
+ ACCOUNT_KANA_IDENTITY_LOCKED = "ERROR_TYPE_ACCOUNT_KANA_IDENTITY_LOCKED".freeze
25
26
  KYC_REJECTED = "ERROR_TYPE_KYC_REJECTED".freeze
26
27
  NOTIFICATION_WEBHOOK_FAILED = "ERROR_TYPE_NOTIFICATION_WEBHOOK_FAILED".freeze
27
28
  NOTIFICATION_EMAIL_FAILED = "ERROR_TYPE_NOTIFICATION_EMAIL_FAILED".freeze
@@ -40,6 +41,9 @@ module Api
40
41
  PAYMENT_SERVICE_DISABLED = "ERROR_TYPE_PAYMENT_SERVICE_DISABLED".freeze
41
42
  PAYMENT_BANK_UNAVAILABLE = "ERROR_TYPE_PAYMENT_BANK_UNAVAILABLE".freeze
42
43
  PAYMENT_CHARGE_OVER_DAILY_LIMIT = "ERROR_TYPE_PAYMENT_CHARGE_OVER_DAILY_LIMIT".freeze
44
+ PAYMENT_BRIDGED_SETTLEMENT_OPEN = "ERROR_TYPE_PAYMENT_BRIDGED_SETTLEMENT_OPEN".freeze
45
+ PAYMENT_BRIDGING_NOT_AVAILABLE = "ERROR_TYPE_PAYMENT_BRIDGING_NOT_AVAILABLE".freeze
46
+ PAYMENT_CHARGE_PENDING = "ERROR_TYPE_PAYMENT_CHARGE_PENDING".freeze
43
47
  CSV_VALIDATION_FAILED = "ERROR_TYPE_CSV_VALIDATION_FAILED".freeze
44
48
  CSV_TOTP_REQUIRED = "ERROR_TYPE_CSV_TOTP_REQUIRED".freeze
45
49
  CSV_TOTP_INVALID = "ERROR_TYPE_CSV_TOTP_INVALID".freeze
@@ -55,9 +59,27 @@ module Api
55
59
  TOTP_NOT_ENABLED = "ERROR_TYPE_TOTP_NOT_ENABLED".freeze
56
60
  TOTP_SETUP_INVALID = "ERROR_TYPE_TOTP_SETUP_INVALID".freeze
57
61
  TOTP_DISABLE_FAILED = "ERROR_TYPE_TOTP_DISABLE_FAILED".freeze
62
+ REFUND_BRIDGED_RECEIVABLE_OPEN = "ERROR_TYPE_REFUND_BRIDGED_RECEIVABLE_OPEN".freeze
63
+ BRIDGED_COLLECTION_IN_FLIGHT = "ERROR_TYPE_BRIDGED_COLLECTION_IN_FLIGHT".freeze
64
+ BRIDGED_SETTLEMENT_DEFAULTED = "ERROR_TYPE_BRIDGED_SETTLEMENT_DEFAULTED".freeze
65
+ BANK_ACCOUNT_NAME_MISMATCH = "ERROR_TYPE_BANK_ACCOUNT_NAME_MISMATCH".freeze
66
+ BANK_ACCOUNT_IN_REVIEW = "ERROR_TYPE_BANK_ACCOUNT_IN_REVIEW".freeze
67
+ DASHBOARD_OTP_EXPIRED = "ERROR_TYPE_DASHBOARD_OTP_EXPIRED".freeze
68
+ DASHBOARD_PASSKEY_LOGIN_STATE_EXPIRED = "ERROR_TYPE_DASHBOARD_PASSKEY_LOGIN_STATE_EXPIRED".freeze
69
+ DASHBOARD_PASSKEY_NOT_REQUIRED = "ERROR_TYPE_DASHBOARD_PASSKEY_NOT_REQUIRED".freeze
70
+ DASHBOARD_PASSKEY_ALREADY_REGISTERED = "ERROR_TYPE_DASHBOARD_PASSKEY_ALREADY_REGISTERED".freeze
71
+ DASHBOARD_PASSKEY_NOT_REGISTERED = "ERROR_TYPE_DASHBOARD_PASSKEY_NOT_REGISTERED".freeze
72
+ DASHBOARD_PASSKEY_CEREMONY_EXPIRED = "ERROR_TYPE_DASHBOARD_PASSKEY_CEREMONY_EXPIRED".freeze
73
+ DASHBOARD_PASSKEY_VERIFICATION_FAILED = "ERROR_TYPE_DASHBOARD_PASSKEY_VERIFICATION_FAILED".freeze
74
+ DASHBOARD_PASSKEY_STEP_UP_REQUIRED = "ERROR_TYPE_DASHBOARD_PASSKEY_STEP_UP_REQUIRED".freeze
75
+ DASHBOARD_PASSKEY_STATE_CHANGED = "ERROR_TYPE_DASHBOARD_PASSKEY_STATE_CHANGED".freeze
76
+ DASHBOARD_PASSKEY_LIMIT_REACHED = "ERROR_TYPE_DASHBOARD_PASSKEY_LIMIT_REACHED".freeze
77
+ DASHBOARD_PASSKEY_LAST_PASSKEY = "ERROR_TYPE_DASHBOARD_PASSKEY_LAST_PASSKEY".freeze
78
+ DASHBOARD_PASSKEY_INVALID_NICKNAME = "ERROR_TYPE_DASHBOARD_PASSKEY_INVALID_NICKNAME".freeze
79
+ DASHBOARD_PASSKEY_NOT_FOUND = "ERROR_TYPE_DASHBOARD_PASSKEY_NOT_FOUND".freeze
58
80
 
59
81
  def self.all_vars
60
- @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, PAYMENT_BANK_UNAVAILABLE, PAYMENT_CHARGE_OVER_DAILY_LIMIT, 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
82
+ @all_vars ||= [UNSPECIFIED, AUTH_FAILED, AUTH_REJECTED, ACCOUNT_CREATION_FAILED, ACCOUNT_MODIFICATION_FAILED, ACCOUNT_DELETION_FAILED, ACCOUNT_BANK_REGISTRATION_FAILED, ACCOUNT_KANA_IDENTITY_LOCKED, 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, PAYMENT_BANK_UNAVAILABLE, PAYMENT_CHARGE_OVER_DAILY_LIMIT, PAYMENT_BRIDGED_SETTLEMENT_OPEN, PAYMENT_BRIDGING_NOT_AVAILABLE, PAYMENT_CHARGE_PENDING, 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, REFUND_BRIDGED_RECEIVABLE_OPEN, BRIDGED_COLLECTION_IN_FLIGHT, BRIDGED_SETTLEMENT_DEFAULTED, BANK_ACCOUNT_NAME_MISMATCH, BANK_ACCOUNT_IN_REVIEW, DASHBOARD_OTP_EXPIRED, DASHBOARD_PASSKEY_LOGIN_STATE_EXPIRED, DASHBOARD_PASSKEY_NOT_REQUIRED, DASHBOARD_PASSKEY_ALREADY_REGISTERED, DASHBOARD_PASSKEY_NOT_REGISTERED, DASHBOARD_PASSKEY_CEREMONY_EXPIRED, DASHBOARD_PASSKEY_VERIFICATION_FAILED, DASHBOARD_PASSKEY_STEP_UP_REQUIRED, DASHBOARD_PASSKEY_STATE_CHANGED, DASHBOARD_PASSKEY_LIMIT_REACHED, DASHBOARD_PASSKEY_LAST_PASSKEY, DASHBOARD_PASSKEY_INVALID_NICKNAME, DASHBOARD_PASSKEY_NOT_FOUND].freeze
61
83
  end
62
84
 
63
85
  # Builds the enum from string
@@ -22,7 +22,7 @@ module Api
22
22
  # Description is an arbitrary string for merchant to track the charge. This information is displayed on Merchant Dashboard. 決済の説明。ショップが決済を追跡するための任意の文字列です。 @gotags: validate:\"required,max=1024\"
23
23
  attr_accessor :description
24
24
 
25
- # 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_* の列挙名を設定すると 決済エラーをシミュレートできます。動作はフローによって異なります。 詳細は上記の英語コメントを参照してください。 At most 50 entries; keys up to 64 and values up to 512 characters. 最大50件、キーは64文字、値は512文字までです。
25
+ # 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 or customer eligibility requirements not met - 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_* の列挙名を設定すると 決済エラーをシミュレートできます。動作はフローによって異なります。 詳細は上記の英語コメントを参照してください。 At most 50 entries; keys up to 64 and values up to 512 characters. 最大50件、キーは64文字、値は512文字までです。
26
26
  attr_accessor :metadata
27
27
 
28
28
  # 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手数料以上である必要があります。
@@ -20,11 +20,15 @@ module Api
20
20
 
21
21
  attr_accessor :charge
22
22
 
23
+ # Merchant-supplied idempotency key for retry safety. Not enabled yet: a request with a key is rejected with 400. ASCII only, 1-255 chars matching ^[a-zA-Z0-9_\\-]{1,255}$.
24
+ attr_accessor :idempotency_key
25
+
23
26
  # Attribute mapping from ruby-style variable name to JSON key.
24
27
  def self.attribute_map
25
28
  {
26
29
  :'customer' => :'customer',
27
- :'charge' => :'charge'
30
+ :'charge' => :'charge',
31
+ :'idempotency_key' => :'idempotencyKey'
28
32
  }
29
33
  end
30
34
 
@@ -37,7 +41,8 @@ module Api
37
41
  def self.openapi_types
38
42
  {
39
43
  :'customer' => :'String',
40
- :'charge' => :'InitialCharge'
44
+ :'charge' => :'InitialCharge',
45
+ :'idempotency_key' => :'String'
41
46
  }
42
47
  end
43
48
 
@@ -69,6 +74,10 @@ module Api
69
74
  if attributes.key?(:'charge')
70
75
  self.charge = attributes[:'charge']
71
76
  end
77
+
78
+ if attributes.key?(:'idempotency_key')
79
+ self.idempotency_key = attributes[:'idempotency_key']
80
+ end
72
81
  end
73
82
 
74
83
  # Show invalid properties with the reasons. Usually used together with valid?
@@ -92,7 +101,8 @@ module Api
92
101
  return true if self.equal?(o)
93
102
  self.class == o.class &&
94
103
  customer == o.customer &&
95
- charge == o.charge
104
+ charge == o.charge &&
105
+ idempotency_key == o.idempotency_key
96
106
  end
97
107
 
98
108
  # @see the `==` method
@@ -104,7 +114,7 @@ module Api
104
114
  # Calculates hash code according to all attributes.
105
115
  # @return [Integer] Hash code
106
116
  def hash
107
- [customer, charge].hash
117
+ [customer, charge, idempotency_key].hash
108
118
  end
109
119
 
110
120
  # Builds the object from hash
@@ -19,9 +19,12 @@ module Api
19
19
  # External refund identifier (rfd-*).
20
20
  attr_accessor :id
21
21
 
22
- # Amount refunded for this event.
22
+ # Amount the merchant requested to refund for this event, before discount.
23
23
  attr_accessor :amount_refunded
24
24
 
25
+ # Amount returned to the customer for this event: amount_refunded minus the share of the charge discount it carries (not present on refund_failed events).
26
+ attr_accessor :amount_refunded_net_discounts
27
+
25
28
  # Jamm fee for this refund event.
26
29
  attr_accessor :jamm_fee
27
30
 
@@ -41,6 +44,7 @@ module Api
41
44
  {
42
45
  :'id' => :'id',
43
46
  :'amount_refunded' => :'amountRefunded',
47
+ :'amount_refunded_net_discounts' => :'amountRefundedNetDiscounts',
44
48
  :'jamm_fee' => :'jammFee',
45
49
  :'consumption_tax' => :'consumptionTax',
46
50
  :'original_transaction_fee_waived' => :'originalTransactionFeeWaived',
@@ -59,6 +63,7 @@ module Api
59
63
  {
60
64
  :'id' => :'String',
61
65
  :'amount_refunded' => :'Integer',
66
+ :'amount_refunded_net_discounts' => :'Integer',
62
67
  :'jamm_fee' => :'Integer',
63
68
  :'consumption_tax' => :'Integer',
64
69
  :'original_transaction_fee_waived' => :'Boolean',
@@ -96,6 +101,10 @@ module Api
96
101
  self.amount_refunded = attributes[:'amount_refunded']
97
102
  end
98
103
 
104
+ if attributes.key?(:'amount_refunded_net_discounts')
105
+ self.amount_refunded_net_discounts = attributes[:'amount_refunded_net_discounts']
106
+ end
107
+
99
108
  if attributes.key?(:'jamm_fee')
100
109
  self.jamm_fee = attributes[:'jamm_fee']
101
110
  end
@@ -139,6 +148,7 @@ module Api
139
148
  self.class == o.class &&
140
149
  id == o.id &&
141
150
  amount_refunded == o.amount_refunded &&
151
+ amount_refunded_net_discounts == o.amount_refunded_net_discounts &&
142
152
  jamm_fee == o.jamm_fee &&
143
153
  consumption_tax == o.consumption_tax &&
144
154
  original_transaction_fee_waived == o.original_transaction_fee_waived &&
@@ -155,7 +165,7 @@ module Api
155
165
  # Calculates hash code according to all attributes.
156
166
  # @return [Integer] Hash code
157
167
  def hash
158
- [id, amount_refunded, jamm_fee, consumption_tax, original_transaction_fee_waived, error, processed_at].hash
168
+ [id, amount_refunded, amount_refunded_net_discounts, jamm_fee, consumption_tax, original_transaction_fee_waived, error, processed_at].hash
159
169
  end
160
170
 
161
171
  # Builds the object from hash
@@ -20,11 +20,15 @@ module Api
20
20
 
21
21
  attr_accessor :charge
22
22
 
23
+ # Merchant-supplied idempotency key for retry safety. Not enabled yet: a request with a key is rejected with 400. ASCII only, 1-255 chars matching ^[a-zA-Z0-9_\\-]{1,255}$.
24
+ attr_accessor :idempotency_key
25
+
23
26
  # Attribute mapping from ruby-style variable name to JSON key.
24
27
  def self.attribute_map
25
28
  {
26
29
  :'customer' => :'customer',
27
- :'charge' => :'charge'
30
+ :'charge' => :'charge',
31
+ :'idempotency_key' => :'idempotencyKey'
28
32
  }
29
33
  end
30
34
 
@@ -37,7 +41,8 @@ module Api
37
41
  def self.openapi_types
38
42
  {
39
43
  :'customer' => :'String',
40
- :'charge' => :'InitialCharge'
44
+ :'charge' => :'InitialCharge',
45
+ :'idempotency_key' => :'String'
41
46
  }
42
47
  end
43
48
 
@@ -69,6 +74,10 @@ module Api
69
74
  if attributes.key?(:'charge')
70
75
  self.charge = attributes[:'charge']
71
76
  end
77
+
78
+ if attributes.key?(:'idempotency_key')
79
+ self.idempotency_key = attributes[:'idempotency_key']
80
+ end
72
81
  end
73
82
 
74
83
  # Show invalid properties with the reasons. Usually used together with valid?
@@ -92,7 +101,8 @@ module Api
92
101
  return true if self.equal?(o)
93
102
  self.class == o.class &&
94
103
  customer == o.customer &&
95
- charge == o.charge
104
+ charge == o.charge &&
105
+ idempotency_key == o.idempotency_key
96
106
  end
97
107
 
98
108
  # @see the `==` method
@@ -104,7 +114,7 @@ module Api
104
114
  # Calculates hash code according to all attributes.
105
115
  # @return [Integer] Hash code
106
116
  def hash
107
- [customer, charge].hash
117
+ [customer, charge, idempotency_key].hash
108
118
  end
109
119
 
110
120
  # Builds the object from hash
data/lib/jamm/errors.rb CHANGED
@@ -35,38 +35,72 @@ module Jamm
35
35
  # - Jamm: code is string, message is string originating from Jamm's protobuf definition.
36
36
  # - OpenAPI: code is integer, message is string originating from ConnectRPC error format.
37
37
  class ApiError < StandardError
38
- attr_reader :code, :error_code, :error_type, :message, :headers, :body
38
+ # error_type is kept for compatibility (it reads ERROR_TYPE_UNSPECIFIED for REST answers); use api_error_type.
39
+ attr_reader :code, :error_code, :error_type, :api_error_type, :charge_id, :message, :headers, :body
40
+
41
+ VALUE_DETAIL = 'type.googleapis.com/google.protobuf.Value'
42
+ CHARGE_PENDING_DETAIL = 'type.googleapis.com/api.v1.ChargePendingDetail'
43
+ private_constant :VALUE_DETAIL, :CHARGE_PENDING_DETAIL
39
44
 
40
45
  # Add this class method to convert StandardError to ApiError
41
46
  def self.from_error(e)
42
- error_type = Api::ErrorType::UNSPECIFIED
43
-
44
- # Convert Protobuf oriented error to error type.
45
- details = JSON.parse(e.response_body)['details']
46
-
47
- if details.is_a?(Array) && details.any?
48
- details.each do |d|
49
- # Loop through all error types to find a match
50
- Api::ErrorType.all_vars.each do |type|
51
- error_type = type.to_s if d['debug'] == type.to_s
52
- end
53
- end
54
- end
47
+ details = parse_details(e.response_body)
55
48
 
56
49
  new(
57
50
  code: e.code,
58
51
  message: e.message,
59
- error_type: error_type,
52
+ error_type: legacy_error_type_from(details),
53
+ api_error_type: api_error_type_from(details),
54
+ charge_id: charge_id_from(details),
60
55
  response_headers: e.response_headers,
61
56
  response_body: e.response_body
62
57
  )
63
58
  end
64
59
 
60
+ # A connection timeout has no body, and a proxy error page isn't JSON: keep the real error.
61
+ def self.parse_details(body)
62
+ parsed = body.is_a?(Hash) ? body : JSON.parse(body.to_s)
63
+ return [] unless parsed.is_a?(Hash) && parsed['details'].is_a?(Array)
64
+
65
+ parsed['details'].select { |d| d.is_a?(Hash) }
66
+ rescue JSON::ParserError, TypeError
67
+ []
68
+ end
69
+
70
+ # error_type keeps its historic rule (a known type in `debug`), which REST answers never match.
71
+ def self.legacy_error_type_from(details)
72
+ error_type = Api::ErrorType::UNSPECIFIED
73
+ details.each do |d|
74
+ Api::ErrorType.all_vars.each { |type| error_type = type.to_s if d['debug'] == type.to_s }
75
+ end
76
+ error_type
77
+ end
78
+
79
+ # REST answers carry the type as a google.protobuf.Value detail, Connect as `debug`.
80
+ # An unknown ERROR_TYPE_* passes through, so a newer server's type isn't lost.
81
+ def self.api_error_type_from(details)
82
+ details.each do |d|
83
+ type = d['@type'] == VALUE_DETAIL ? d['value'] : d['debug']
84
+ return type if type.is_a?(String) && type.start_with?('ERROR_TYPE_')
85
+ end
86
+ Api::ErrorType::UNSPECIFIED
87
+ end
88
+
89
+ # The charge ID of a pending sync charge (outcome unknown): retry only with the same idempotency_key.
90
+ def self.charge_id_from(details)
91
+ pending = details.find { |d| d['@type'] == CHARGE_PENDING_DETAIL }
92
+ id = pending && pending['chargeId']
93
+ id.is_a?(String) && !id.empty? ? id : nil
94
+ end
95
+ private_class_method :parse_details, :legacy_error_type_from, :api_error_type_from, :charge_id_from
96
+
65
97
  def initialize(args = {})
66
98
  # Check code existence and convert to string if it's integer
67
99
  @code = args[:code]
68
100
  @message = args[:message]
69
101
  @error_type = args[:error_type]
102
+ @api_error_type = args[:api_error_type]
103
+ @charge_id = args[:charge_id]
70
104
  @headers = args[:response_headers]
71
105
 
72
106
  raw_body = if args[:response_body].nil?
@@ -75,7 +109,8 @@ module Jamm
75
109
  args[:response_body]
76
110
  elsif args[:response_body].is_a?(String)
77
111
  begin
78
- JSON.parse(args[:response_body])
112
+ parsed = JSON.parse(args[:response_body])
113
+ parsed.is_a?(Hash) ? parsed : {}
79
114
  rescue StandardError
80
115
  {}
81
116
  end
data/lib/jamm/payment.rb CHANGED
@@ -39,11 +39,13 @@ module Jamm
39
39
  raise Jamm::ApiError.from_error(e)
40
40
  end
41
41
 
42
- def self.off_session(customer:, charge:, merchant: nil)
42
+ # Sends idempotency_key only when given: unlike off_session_async, no key is generated.
43
+ def self.off_session(customer:, charge:, idempotency_key: nil, merchant: nil)
43
44
  request = Jamm::OpenAPI::OffSessionPaymentRequest.new(
44
45
  customer: customer,
45
46
  charge: charge
46
47
  )
48
+ request.idempotency_key = idempotency_key unless idempotency_key.nil? || idempotency_key.strip.empty?
47
49
 
48
50
  handler = Jamm::Client.handler(merchant: merchant)
49
51
  Jamm::OpenAPI::PaymentApi.new(handler).off_session_payment(request)
data/lib/jamm/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Jamm
4
- VERSION = '2.7.0'
4
+ VERSION = '2.8.0'
5
5
  end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: jamm
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.7.0
4
+ version: 2.8.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Jamm
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2026-10-07 00:00:00.000000000 Z
11
+ date: 2026-11-19 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: base64