rail0-sdk 1.7.1 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5d88d3da009d4c04853e8fb794eba655913763a1391c6e0bd6915bda6cb68d36
-  data.tar.gz: 5cc37022ce71f950c6b11dcf421902518b63caebfd54a13f78eaf909a7eef39c
+  metadata.gz: '078c5043f2867777ccba9da57fe022e3db252cff6010f50dbad7c9dd37b7c8a7'
+  data.tar.gz: e64f79000eeb6b94b78367c223eb33f48ac5ffc23218ac89dffb3b99e23504d1
 SHA512:
-  metadata.gz: 2512e0a842d7d76749dc4028a0c1d2590b7fe1dd4e95676572a39aa8c41fa9a882c2e4a534e85080f0fe8089c8001c6f2101ff4b9fb7ab9f4e2cc9d7e6d35d62
-  data.tar.gz: 7b569639525815722a586f308d45ebc67c964cbd4f6f1ae4c5bac4a8c5a731589b03dffebcfcdb375e3a265f9f1143b52162d5e8685de591e39a364de3257cf8
+  metadata.gz: 4030fedd465183a1e4dba618ad1c3d7ff75d667032e3ebce6e7da87aeb4e1c75c9ab1205378d89fd2329a005ceb7f8a1b22ab3504b466e0c06b387117a5736a3
+  data.tar.gz: d894eea1f54c0c8514be643b3fdb7300cdc8c2158dd4c4db0de29b0b8fb09c7226d2910e981c921735a5b5589310484243cc9ddc9b01b92b75692ae68e5c43f0

data/README.md

@@ -382,6 +382,7 @@ client.wallets.list(account_id, token_active: true)
 
 client.wallets.get(account_id, id_or_address)
 client.wallets.update(account_id, id_or_address, label: "Renamed", active: false)
+client.wallets.update(account_id, id_or_address, active: true)      # back on (see below)
 client.wallets.delete(account_id, id_or_address)                    # 204
 client.wallets.balances(account_id, id_or_address, chain_id: 84532) # live on-chain balances
 ```
@@ -392,6 +393,17 @@ refused with 422 `last_active_wallet` — login resolves the account from a wall
 so an account with none could neither act nor add one back. Another wallet must
 be active first.
 
+**Switching a wallet back on.** Every switch-off records who did it in the wallet's
+`deactivated_by`: `"owner"` (a session signed in with that wallet) or `"operator"`
+(an operator session); `nil` while active, and on a switch-off older than the record.
+A deactivated wallet's session is read-only (403 `wallet_deactivated`) except for one
+write: `update(account_id, id, active: true)` on its **own** wallet, which switches it
+back on when its owner switched it off. A wallet an operator switched off (or with
+`deactivated_by: nil`) raises 403 `wallet_deactivated_by_operator`: an operator's
+switch-off revokes the key, so only an operator lifts it. The flip side: a wallet its
+owner switched off can be switched back on by whoever holds its key, so a definitive
+revocation (a leaked key) must come from an operator.
+
 **A session is bound to the wallet it signed in with.** Reads (`list`, `get`,
 `balances`) are account-wide, but `update`, `delete` and the token-holding methods
 act only on the session's own wallet: another wallet of the same account is
@@ -459,6 +471,11 @@ client.payments.create(params, idempotency_key: nil)  # or keyword fields
 client.payments.get(id)
 client.payments.update(id, description: "Order #42")  # → the payment, same shape as get
 client.payments.update(id, description: nil)          # nil (or "") clears it
+# The payee's own fields (the payer gets 403 not_the_payee): an internal note never shown
+# to the payer, and the payment's identifier in the merchant's system. Only what you pass
+# is sent.
+client.payments.update(id, merchant_note: "refund agreed by email")
+client.payments.update(id, reference: "ORD-1042", reference_origin: "commercelayer")
 # The description is the only editable field: off-chain, so any status, settled included.
 # Payer or payee only (a non-participant gets 404); over 255 characters is a 422.
 client.payments.list(status: "authorized", disputed: false, chain_id: 84532, sort: "-created_at")
@@ -632,6 +649,7 @@ client.webhooks.enable(id)
 client.webhooks.disable(id)
 client.webhooks.rotate_secret(id)    # returns a fresh shared_secret
 client.webhooks.reset_circuit(id)
+client.webhooks.test(id)   # signed webhooks.test event now → { delivered:, response_code:, … }; not logged
 # status is "delivered" or "failed" only; payment_id takes a UUID or a rail0_id.
 client.webhooks.event_callbacks(id, status: "failed", response_code: "500")
 client.webhooks.redeliver(id, callback_id)  # 202 { status: "queued" } — replay one delivery
@@ -728,11 +746,13 @@ client.accounts.get(account_id)
 client.accounts.update(account_id, email: "ops@merchant.example")
 client.accounts.update(account_id, name: "Merchant Ltd", email: "ops@merchant.example")
 client.accounts.update(account_id, priority_tip: false)   # minimum tip on the account's own transactions
+# Payment windows of NEW payments: seconds, or :default (sent as null) for the gateway default.
+client.accounts.update(account_id, authorization_ttl: 2 * 86_400, refund_ttl: :default)
 ```
 
 `email` is in the response because the holder is this endpoint's only possible caller.
 
-`update` needs at least one of `name`/`email`/`priority_tip` (it raises `ArgumentError`
+`update` needs at least one of `name`/`email`/`priority_tip`/a payment window (it raises `ArgumentError`
 before sending an empty PATCH, which the gateway would answer with 400). Name and email are
 unique across accounts, so a value another account holds answers **409**. It is a write on
 the account, so a deactivated wallet (403 `wallet_deactivated`) or account (403
@@ -743,6 +763,15 @@ exposed here.
 capture, void, release, refund): `true`, the default, tips the network's suggested priority
 fee; `false` uses the chain's minimum tip (0 on most chains, 25 gwei on Polygon PoS/Amoy) —
 cheaper, slower to confirm under load. The buyer's dispute/close-dispute never read it.
+
+**Payment windows** — `authorization_ttl` (how long an authorization can be captured) and
+`refund_ttl` (how long a payment can be refunded or disputed), in seconds — are the deadlines
+the account's **new** payments are created with: its own value, or the gateway default. The
+profile's `payment_windows` says which, and the bounds; outside them, or with the refund
+window less than `min_refund_window` (one day) past the authorization, the gateway answers
+**422** `invalid_payment_windows`. A payment's deadlines are signed into it, so a change moves
+only the payments created afterwards.
+
 The account's wallets are a collection under the same path (`client.wallets`), and
 buyer-facing discovery is `client.payment_methods`.
 
@@ -1070,25 +1099,52 @@ uses them everywhere, table-aligned hashes because some literals are tables, and
 (`retry_on_429`, `eip712`, `secp256k1`) that each spell themselves their own way. A linter
 that argues with the codebase teaches people to ignore it.
 
-## Publishing
-
-Releases publish from GitHub Actions (`.github/workflows/release.yml`) through RubyGems
-**Trusted Publishing**: RubyGems.org trusts that workflow in this repo, so there is no API
-key to store or rotate and no OTP prompt.
-
-1. Merge a PR that bumps `Rail0::VERSION` in `lib/rail0/version.rb`.
-2. Publish a GitHub release on `main` tagged `v<version>` (e.g. `v1.2.0`).
-
-The workflow checks the tag against `Rail0::VERSION`, runs `rake build` (rubocop and the
-specs first, then the gem) and pushes it. A version already on RubyGems.org is skipped, so
-a re-run (Actions → release → Run workflow, from `main`, with the tag as input) is always
-safe — that is also how a release cut before the workflow existed gets published.
-
-One-time setup, by an owner of the gem on rubygems.org: rail0-sdk → Trusted publishers →
-GitHub Actions, repository `commercelayer/rail0-ruby`, workflow `release.yml`.
-
-Publishing by hand still works as a fallback (`gem build rail0-sdk.gemspec && gem push
-rail0-sdk-<version>.gem`, with the OTP the gem's `rubygems_mfa_required` asks for).
+## Releasing
+
+A release is an approved pull request: merging it is what publishes.
+
+1. `bin/release-prepare`, on an up-to-date, clean `main`. It computes the version from the titles of the pull requests merged since the last tag
+   (Conventional Commits): a breaking change — `!` after the type, as in `feat(api)!:`, or a
+   `BREAKING CHANGE:` footer — makes it a major, any `feat` a minor, anything else a patch,
+   and it refuses when nothing merged. `bin/release-prepare minor` (or `patch`, `major`,
+   `X.Y.Z`) sets it by hand instead. The release PR says which pull requests decided it.
+   It then bumps `Rail0::VERSION` and `Gemfile.lock`, writes the release
+   notes from the pull requests merged since the last tag, and opens
+   `chore(release): vX.Y.Z`. `--dry-run` prints all of it and writes nothing.
+
+   **Or on a feature branch**, to release a change in the same review: run it on a clean
+   branch that is pushed, contains `origin/main` and has an open pull request into `main`.
+   The bump is committed and pushed on that branch (`chore(release): vX.Y.Z`), the pull
+   request's own title counts toward the version and gets a line in the notes, and the
+   notes go into its description between `<!-- release:start -->` markers — the text above
+   them is kept. Re-run it after new commits or a merge of `main`: it refreshes the version
+   and the notes instead of bumping twice. One approval then covers the change and its
+   release.
+2. Review the pull request (edit the notes in its body if needed), approve and merge it.
+   The approval must come from a reviewer **other than the pull request's author**, on its
+   final commit: release.yml checks it before publishing anything and stops otherwise —
+   an admin merge that bypassed the review, a direct push to `main` or a resume of an
+   unapproved release publishes nothing.
+3. `.github/workflows/release.yml` runs on that push to `main`: CI again on the release
+   commit, `gem push` through RubyGems **Trusted Publishing**, then the tag `vX.Y.Z` and
+   the GitHub release (notes from the pull request), then a Slack message.
+
+A merge that does not change the version releases nothing. If a run stops halfway, Actions
+→ release → Run workflow (on `main`) resumes it: what is already on RubyGems.org or already
+tagged is skipped. `rake release` is disabled (it would tag and push from a laptop), and no
+API key exists anywhere: RubyGems.org trusts only `release.yml` in this repo.
+
+One-time settings (repository admins):
+
+- environment `release` (Settings → Environments), deployment limited to `main`;
+- on rubygems.org, rail0-sdk's trusted publisher (repository `commercelayer/rail0-ruby`,
+  workflow `release.yml`) bound to environment `release` — only once the new
+  `release.yml` is on `main`;
+- a tag ruleset on `v*`: block updates and deletions, restrict creation to GitHub Actions
+  and admins;
+- branch protection on `main`: required `ci` check (`spec`), "Include administrators";
+- the Slack channel: `release.yml` posts through the `PIPELINE_SLACK_CHANNEL_WEBHOOK_URL`
+  secret, named in one place (the `announce` job).
 
 ## License
 

data/lib/rail0/error_hints.rb

@@ -55,7 +55,10 @@ module Rail0
     "not_payer_or_payee" => "only the payer or the payee may do this",
     "release_submitter_not_a_party" => "a release must be sent by the payment's payer or payee — omit `from` to build it for the signed-in wallet",
     "payer_must_be_caller" => "the payer must be the signed-in wallet — sign in as the buyer to create its payment",
-    "wallet_deactivated" => "this wallet is deactivated: it can still read, but not act on payments or change the account — reactivate it or sign in with another of the account's wallets",
+    # gateway#439: a deactivated session may switch its OWN wallet back on when its owner
+    # switched it off; an operator's switch-off is the operator's to lift.
+    "wallet_deactivated" => "this wallet is deactivated: it can still read, but not act on payments or change the account — if you switched it off, its own session can switch it back on (wallets.update(..., active: true)), or sign in with another of the account's wallets",
+    "wallet_deactivated_by_operator" => "an operator deactivated this wallet, so only an operator can reactivate it — ask an operator to reactivate it",
     "account_deactivated" => "the merchant account is deactivated: void, release and refund still work, but authorize, charge, capture and account changes do not — ask an operator to reactivate it",
     # A session is bound to the one wallet it signed in with: the account's other wallets
     # are readable, but not this session's to change (operators are exempt).
@@ -65,8 +68,9 @@ module Rail0
     "wallet_add_unavailable" => "adding a wallet to an account is not available yet — it returns with the merchant wallet-management section",
     # Login resolves the account FROM a wallet, so an account left with no active one
     # could neither act nor add a wallet back. Adding a wallet is suspended and a session
-    # changes only its own wallet, so the other wallet has to be reactivated by an operator.
-    "last_active_wallet" => "this is the account's only active wallet — another wallet must be active before this one can be switched off (adding a wallet is not available yet; an operator can reactivate one)",
+    # changes only its own wallet, so the other wallet comes back on from its own session
+    # (if its owner switched it off) or from an operator (gateway#439).
+    "last_active_wallet" => "this is the account's only active wallet — another wallet must be active before this one can be switched off: sign in with one you switched off and reactivate it, or ask an operator (adding a wallet is not available yet)",
     "last_admin" => "the change would leave no active operator — grant the operator role to another active account first",
     "not_redrivable" => "only a pending transaction that already holds its signed bytes can be redriven — check the transaction's `redrivable` flag, and submit the signature if it has none",
     "refund_expired" => "the refund window has closed (refundExpiry passed) — refund/dispute is no longer possible",

data/lib/rail0/resources/accounts.rb

@@ -30,12 +30,16 @@ module Rail0
 
       # The account's own profile.
       # @param account_id [String] The account UUID — must be the one this JWT belongs to.
-      # @return [Hash] `id`, `name`, `email`, `priority_tip`, `created_at`, `updated_at`.
+      # @return [Hash] `id`, `name`, `email`, `priority_tip`, `authorization_ttl`, `refund_ttl`,
+      #   `payment_windows`, `created_at`, `updated_at`.
       #   `email` is part of the response because only the account's owner, or an operator,
       #   can read it. `priority_tip` is the fee setting of the account's OWN transactions
       #   (authorize, capture, void, release, refund): true, the default, tips the network's
       #   suggested priority fee; false uses the chain's minimum tip — 0 on most chains,
       #   25 gwei on Polygon PoS/Amoy. The buyer's dispute/close_dispute never read it.
+      #   `authorization_ttl` / `refund_ttl` are the payment windows the account's NEW
+      #   payments are created with, in seconds — its own or the gateway default;
+      #   `payment_windows` says which, and the bounds a new value must fit.
       def get(account_id)
         http.get("/accounts/#{segment(account_id)}")
       end
@@ -48,6 +52,10 @@ module Rail0
       # are UNIQUE across accounts, so a value another account already holds answers 409.
       # `priority_tip: false` is a value, not an absence: it is sent as false and switches
       # the account's own transactions to the chain's minimum tip; nil leaves it alone.
+      # The payment windows take a number of seconds, or `:default` to put one back on the
+      # gateway default (sent as null); nil leaves it alone. Outside the bounds in
+      # `payment_windows`, or closer than its `min_refund_window`, the gateway answers 422
+      # invalid_payment_windows. A change moves only the payments created afterwards.
       #
       # This is a write on the account itself, so a deactivated wallet (403
       # wallet_deactivated) or a deactivated account (403 account_deactivated) cannot
@@ -60,17 +68,35 @@ module Rail0
       # @param priority_tip [Boolean, nil] Tip the network's suggested priority fee on the
       #   account's own transactions (true, the gateway default) or the chain's minimum tip
       #   (false). Owner or admin.
+      # @param authorization_ttl [Integer, :default, nil] Authorization (capture) window of
+      #   new payments, in seconds, or :default. Owner or admin.
+      # @param refund_ttl [Integer, :default, nil] Refund and dispute window of new
+      #   payments, in seconds, or :default. Owner or admin.
       # @return [Hash] the updated profile, same shape as {get}.
-      # @raise [ArgumentError] when none of name, email or priority_tip is given.
-      def update(account_id, name: nil, email: nil, priority_tip: nil)
+      # @raise [ArgumentError] when no field is given, or a window is neither an Integer
+      #   nor :default.
+      def update(account_id, name: nil, email: nil, priority_tip: nil, authorization_ttl: nil, refund_ttl: nil)
         body = {}
         body[:name]         = name         unless name.nil?
         body[:email]        = email        unless email.nil?
         body[:priority_tip] = priority_tip unless priority_tip.nil?
-        raise ArgumentError, "at least one of name, email or priority_tip is required" if body.empty?
+        { authorization_ttl: authorization_ttl, refund_ttl: refund_ttl }.each do |key, value|
+          body[key] = window(key, value) unless value.nil?
+        end
+        raise ArgumentError, "at least one of name, email, priority_tip or a payment window is required" if body.empty?
 
         http.patch("/accounts/#{segment(account_id)}", body)
       end
+
+      private
+
+      # A payment window as the gateway takes it: whole seconds, or null for the default.
+      def window(key, value)
+        return if value == :default
+        return value if value.is_a?(Integer)
+
+        raise ArgumentError, "#{key} must be an Integer number of seconds or :default"
+      end
     end
   end
 end

data/lib/rail0/resources/payments.rb

@@ -13,6 +13,11 @@ module Rail0
     # step (e.g. MetaMask) skip the local signer and report the hash via
     # {submit_by_hash} instead.
     class Payments
+      # The default of {update}'s keywords: "not passed", told apart from an explicit +nil+
+      # (which is sent, as JSON null, and clears the field).
+      UNSET = Object.new.freeze
+      private_constant :UNSET
+
       include Query
 
       # Operations accepted by the prepare/submit endpoints.
@@ -62,6 +67,10 @@ module Rail0
       #   `last_error_code`, false = none.
       # @param expiring_within [Integer, nil] scope "all" only: `authorized` payments whose
       #   `authorization_expiry` falls within this many SECONDS from now (1..90 days).
+      # @param reference [String, nil] Only payments with this reference — the payment's
+      #   identifier in the merchant's own system (exact match).
+      # @param reference_origin [String, nil] Only payments whose reference comes from this
+      #   system (case-insensitive).
       # @param sort [String, nil] Comma-separated sort fields; prefix with - for desc.
       # @param page [Integer, nil] Page number (1-based; 1..1,000,000, 400 outside).
       # @param per_page [Integer, nil] Items per page (max 100).
@@ -74,9 +83,11 @@ module Rail0
       def list(status: nil, mode: nil, payer: nil, payee: nil, token: nil, rail0_id: nil,
                chain_id: nil, disputed: nil, operation: nil, min_amount: nil, max_amount: nil,
                created_from: nil, created_to: nil, scope: nil, account_id: nil, has_error: nil,
-               expiring_within: nil, sort: nil, page: nil, per_page: nil)
+               expiring_within: nil, reference: nil, reference_origin: nil, sort: nil, page: nil,
+               per_page: nil)
         query = build_query(status: status, mode: mode, payer: payer, payee: payee, token: token,
-                            rail0_id: rail0_id, chain_id: chain_id, disputed: disputed,
+                            rail0_id: rail0_id, reference: reference, reference_origin: reference_origin,
+                            chain_id: chain_id, disputed: disputed,
                             operation: operation,
                             min_amount: min_amount, max_amount: max_amount,
                             created_from: created_from, created_to: created_to,
@@ -97,7 +108,10 @@ module Rail0
       #   create(chain_id: 84532, mode: "authorize", amount: "100.00", token: "0x…", payer: "0x…", payee: "0x…")
       #   create({ chain_id: 84532, ... }, idempotency_key: "order-42")
       #
-      # @param params [Hash, nil] chain_id, mode, amount, token, payer, payee, description (opt), metadata (opt).
+      # @param params [Hash, nil] chain_id, mode, amount, token, payer, payee, description (opt),
+      #   metadata (opt), reference (opt — the payment's identifier in the merchant's own
+      #   system, max 128 characters, not unique, an idempotency term), reference_origin (opt
+      #   — which system: a lowercase slug, e.g. "commercelayer"; needs a reference).
       # @param idempotency_key [String, nil] Optional Idempotency-Key header value.
       # @param fields [Hash] Field keywords, used when +params+ is omitted.
       # @return [Hash]
@@ -116,22 +130,36 @@ module Rail0
         http.get("/payments/#{segment(id)}")
       end
 
-      # Set or clear a payment's description (PATCH /payments/{id}).
+      # Set or clear a payment's off-chain fields (PATCH /payments/{id}).
+      #
+      # Off-chain metadata, so it can change at any status, settled payments included. Only
+      # a participant (the payer or the payee) may call it — a non-participant gets the same
+      # 404 as an unknown id, and a deactivated caller wallet a 403 `wallet_deactivated`.
+      #
+      # Only the keywords you PASS are sent, and at least one is required (ArgumentError
+      # first, rather than the gateway's 400). +nil+ or +""+ clears a field.
       #
-      # The description is the only field this route edits: it is off-chain metadata, so
-      # it can change at any status, settled payments included. Only a participant (the
-      # payer or the payee) may edit it — a non-participant gets the same 404 as an unknown
-      # id, and a deactivated caller wallet a 403 `wallet_deactivated`.
+      # - +description:+ either party, max 255 characters (422 over).
+      # - +merchant_note:+ the PAYEE's internal note, max 2000 characters — never shown to
+      #   the payer, not in webhooks.
+      # - +reference:+ / +reference_origin:+ the payment's identifier in the merchant's own
+      #   system and which system; the payee corrects them, and clearing the reference
+      #   clears its origin.
       #
-      # +description:+ is required, and is always sent: passing +nil+ sends JSON +null+,
-      # which clears it (as does +""+). Over 255 characters is a 422.
-      # (rail0-gateway#373)
+      # The last three are the payee's: the payer gets 403 `not_the_payee`.
       #
       # @param id [String] Payment UUID or rail0_id.
-      # @param description [String, nil] The new description; +nil+ or +""+ clears it.
       # @return [Hash] The updated payment, the same shape {get} returns.
-      def update(id, description:)
-        http.patch("/payments/#{segment(id)}", { description: description })
+      # @raise [ArgumentError] when no field is given.
+      def update(id, description: UNSET, merchant_note: UNSET, reference: UNSET, reference_origin: UNSET)
+        body = { description: description, merchant_note: merchant_note, reference: reference,
+                 reference_origin: reference_origin }.reject { |_, v| v.equal?(UNSET) }
+        if body.empty?
+          raise ArgumentError,
+                "at least one of description, merchant_note, reference or reference_origin is required"
+        end
+
+        http.patch("/payments/#{segment(id)}", body)
       end
 
       # List on-chain transactions for a payment.

data/lib/rail0/resources/wallets.rb

@@ -92,11 +92,16 @@ module Rail0
       # operator may change any). +active: false+ on the account's only active wallet
       # raises ApiError 422 +last_active_wallet+: login resolves the account from a
       # wallet, so an account with none could neither act nor add one back.
+      #
+      # +active: true+ is the one write a deactivated wallet's own session may make: it
+      # switches the wallet back on when its owner switched it off. A wallet an operator
+      # switched off (+deactivated_by+ "operator", or nil on an older switch-off) raises
+      # ApiError 403 +wallet_deactivated_by_operator+: only an operator lifts it.
       # @param account_id [String] Account UUID.
       # @param id_or_address [String] Wallet UUID or 0x address.
       # @param label [String, nil] New label.
       # @param active [Boolean, nil] New active status.
-      # @return [Hash] id, address, label, active
+      # @return [Hash] id, address, label, active, deactivated_by
       def update(account_id, id_or_address, label: nil, active: nil)
         body = {}
         body[:label]  = label  unless label.nil?

data/lib/rail0/resources/webhooks.rb

@@ -127,6 +127,18 @@ module Rail0
         http.put("/webhooks/#{segment(id)}/reset_circuit")
       end
 
+      # Send a test event to the webhook's callback now and report what it did
+      # (POST /webhooks/{id}/test). The event has topic "webhooks.test", +test: true+ and
+      # no payment, and is signed and delivered like a real one. Synchronous, one attempt,
+      # not logged in {event_callbacks} and not counted by the circuit breaker; it works on
+      # a disabled webhook. A refusal by the endpoint is a result, not an error.
+      # @param id [String] Webhook UUID.
+      # @return [Hash] +delivered+, +response_code+, +response_message+, +error_reason+,
+      #   +duration_ms+.
+      def test(id)
+        http.post("/webhooks/#{segment(id)}/test", {})
+      end
+
       # List delivery attempts for a webhook.
       # @param id [String] Webhook UUID.
       # @param status [String, nil] Filter by delivery status: "delivered" or "failed" only

data/lib/rail0/types.rb

@@ -209,10 +209,11 @@ module Rail0
 
     # Public-safe wallet view (the reduced set a buyer needs to discover a merchant's payment methods).
     Wallet = Struct.new(
-      :id,       # String
-      :address,  # String
+      :id,              # String
+      :address,         # String
       :label,
-      :active,   # Boolean
+      :active,          # Boolean
+      :deactivated_by,  # Who switched the wallet off: `owner` (a session signed in with this wallet) or `operator` (an admin session). Null while active, and on a switch-off that predates the record — treated as `operator`. A wallet an operator switched off can be switched back on only by an operator (403 `wallet_deactivated_by_operator`). Always null on GET /payment_methods, which serves active wallets only.
       keyword_init: true
     )
 
@@ -229,11 +230,12 @@ module Rail0
     # A wallet with its token holdings nested inline. `tokens` is empty when the wallet has none — the
     # wallet is still returned, never omitted.
     WalletWithTokens = Struct.new(
-      :id,       # String
-      :address,  # String
+      :id,              # String
+      :address,         # String
       :label,
-      :active,   # Boolean
-      :tokens,   # Array
+      :active,          # Boolean
+      :deactivated_by,  # Who switched the wallet off: `owner` (a session signed in with this wallet) or `operator` (an admin session). Null while active, and on a switch-off that predates the record — treated as `operator`. A wallet an operator switched off can be switched back on only by an operator (403 `wallet_deactivated_by_operator`). Always null on GET /payment_methods, which serves active wallets only.
+      :tokens,          # Array
       keyword_init: true
     )
 
@@ -263,6 +265,9 @@ module Rail0
       :last_error_code,       # Decoded reason of the last failed on-chain attempt; null once the payment makes forward progress. Non-null means the latest attempt failed.
       :last_error_message,    # Human-readable form of last_error_code.
       :description,
+      :reference,             # This payment's identifier in the merchant's own system; set at create, correctable by the payee.
+      :reference_origin,      # The system the reference comes from, a lowercase slug (e.g. commercelayer).
+      :merchant_note,         # The payee's internal note (PATCH /payments/{id}). Present only when the session is the payment's PAYEE, and on the operator's Full view; absent for the payer.
       :metadata,
       :signed_at,             # When the payer signature was stored (null while unsigned).
       :created_at,            # String
@@ -289,6 +294,16 @@ module Rail0
       keyword_init: true
     )
 
+    # What the callback did with a test event (POST /webhooks/{id}/test).
+    WebhookTestResult = Struct.new(
+      :delivered,         # Boolean — The endpoint answered 2xx.
+      :response_code,     # The HTTP status it answered; null when no response came (see error_reason).
+      :response_message,  # Up to 1000 printable characters of its response body.
+      :error_reason,      # Why no response came: a refused address, a TLS or connection error, the deadline.
+      :duration_ms,       # Integer — How long the attempt took.
+      keyword_init: true
+    )
+
     Transaction = Struct.new(
       :id,                    # String
       :payment_id,            # String
@@ -334,32 +349,48 @@ module Rail0
     )
 
     # The account's own profile as the holder reads it (GET) and as a PATCH returns it — id, name,
-    # email, priority_tip, timestamps. Deliberately no admin/role field: the operator grant lives in a
-    # separate table, so a standard account's profile carries no trace of that axis. An ADMIN reading
-    # any account gets the whole record plus `admin` instead, which is a different shape and not this
-    # one.
+    # email, priority_tip, payment windows, timestamps. Deliberately no admin/role field: the operator
+    # grant lives in a separate table, so a standard account's profile carries no trace of that axis. An
+    # ADMIN reading any account gets the whole record plus `admin` instead, which is a different shape
+    # and not this one.
     Account = Struct.new(
-      :id,            # String
-      :name,          # String
+      :id,                 # String
+      :name,               # String
       :email,
-      :priority_tip,  # Boolean — Whether the merchant's own transactions tip the network's suggested priority fee (true, the default) or the chain's minimum tip (false: 0 on most chains, 25 gwei on Polygon PoS/Amoy). The buyer's dispute/close_dispute never read it.
-      :created_at,    # String
-      :updated_at,    # String
+      :priority_tip,       # Boolean — Whether the merchant's own transactions tip the network's suggested priority fee (true, the default) or the chain's minimum tip (false: 0 on most chains, 25 gwei on Polygon PoS/Amoy). The buyer's dispute/close_dispute never read it.
+      :authorization_ttl,  # Integer — Seconds an authorization of the account's new payments stays capturable after the payment is created: the account's own value, or the gateway default (AUTHORIZATION_TTL).
+      :refund_ttl,         # Integer — Seconds the account's new payments stay refundable, and open to a dispute, after they are created: the account's own value, or the gateway default (REFUND_TTL).
+      :payment_windows,    # PaymentWindows
+      :created_at,         # String
+      :updated_at,         # String
+      keyword_init: true
+    )
+
+    # How the account's windows are set and what a new value must meet: per window, whether it is the
+    # account's own (custom) or the default, the default, and the bounds. The refund window has no floor
+    # of its own: the pair must keep refund_ttl - authorization_ttl >= min_refund_window.
+    PaymentWindows = Struct.new(
+      :authorization_ttl,  # Hash
+      :refund_ttl,         # Hash
+      :min_refund_window,  # Integer
       keyword_init: true
     )
 
     # The whole account record, as an operator reads it (Full entity: GET /accounts, and GET/PATCH
     # /accounts/{account_id} for an admin session): every column plus `admin` and the derived `status`.
     AccountFull = Struct.new(
-      :id,            # String
-      :name,          # String
-      :email,         # String — Stored lowercase.
-      :active,        # Boolean — The operator's switch. false = deactivated.
-      :priority_tip,  # Boolean — The merchant's fee setting (see Account.priority_tip).
-      :created_at,    # String
-      :updated_at,    # String
-      :admin,         # Boolean — Whether the account holds the operator grant (a row in administrators).
-      :status,        # String — One-word reading of active: active, or deactivated (switched off by an operator).
+      :id,                 # String
+      :name,               # String
+      :email,              # String — Stored lowercase.
+      :active,             # Boolean — The operator's switch. false = deactivated.
+      :priority_tip,       # Boolean — The merchant's fee setting (see Account.priority_tip).
+      :authorization_ttl,  # Integer — Seconds an authorization of the account's new payments stays capturable after the payment is created: the account's own value, or the gateway default (AUTHORIZATION_TTL).
+      :refund_ttl,         # Integer — Seconds the account's new payments stay refundable, and open to a dispute, after they are created: the account's own value, or the gateway default (REFUND_TTL).
+      :payment_windows,    # PaymentWindows
+      :created_at,         # String
+      :updated_at,         # String
+      :admin,              # Boolean — Whether the account holds the operator grant (a row in administrators).
+      :status,             # String — One-word reading of active: active, or deactivated (switched off by an operator).
       keyword_init: true
     )
 
@@ -474,7 +505,8 @@ module Rail0
       :webhooks,      # Hash
       :settlement,    # Hash
       :rate_limit,    # Hash
-      :siwe,          # Hash
+      :siwe,          # Hash — domains (SIWE_DOMAIN), accepted_chain_ids (1 plus the ids of the active catalog chains: the chainId values a login may carry) and nonce_ttl.
+      :session,       # Hash — environment (RAIL0_ENVIRONMENT, default RACK_ENV: the scope every issued token is bound to), jwt_ttl and jwt_audience: the session token's lifetime (a constant) and audience (`rail0-gateway:<environment>`).
       :fees,          # Hash
       :rpc,           # Hash
       :onboarding,    # Hash
@@ -532,18 +564,5 @@ module Rail0
       :contract_address,  # String — Address (lowercase) of the RAIL0 deployment the payment is bound to, archived versions included. The sweeper accepts a receipt's event only when this contract emitted it.
       keyword_init: true
     )
-
-    # Per-chain indexer config.
-    SyncBlockchain = Struct.new(
-      :chain_id,                # Integer
-      :start_block,             # Integer
-      :required_confirmations,  # Integer — Fallback burial depth, used where the chain serves no finality tag.
-      :finality_tag,            # String — Which block the chain calls settled; the indexer gates every notify on it.
-      :explorer_url,            # Block explorer base URL; null when the chain has none.
-      :network_type,            # String — "testnet" or "mainnet"; selects which chains a deployment indexes.
-      :rpc_urls,                # Array — Ordered list of public RPC endpoints tried in turn (serial fallback).
-      :contracts,               # Array — Active RAIL0 contract addresses on the chain (all watched versions).
-      keyword_init: true
-    )
   end
 end

data/lib/rail0/version.rb

@@ -5,5 +5,5 @@ module Rail0
   # consumed by path from a sibling checkout, where the number bought nothing: no registry
   # ever served a 1.x, no tag was ever cut, and the one consumer resolves the working tree.
   # Publishing from 1.2.0 would have implied two releases nobody can install.
-  VERSION = "1.7.1"
+  VERSION = "1.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rail0-sdk
 version: !ruby/object:Gem::Version
-  version: 1.7.1
+  version: 1.8.0
 platform: ruby
 authors:
 - Commerce Layer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-20 00:00:00.000000000 Z
+date: 2026-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: logger