arionpay 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6e3d6f2c62cdee103707f3836b49b1a9983bda9b56ac692c6f678f8853b1349b
+  data.tar.gz: ebe0440db59cf2e684bac0aa8b9f1bafd02553be28376bcb0a39935ca8f5f02d
+SHA512:
+  metadata.gz: 587bb93c96ffae870470d68747dba5fba3f3095fde736eaf76b744f1d8950937e07e305813fda51bad49b88784c84e8f9e29774538a56953b4507e9dd4d84dcc
+  data.tar.gz: 5daa050c630734dc0cdd6a4386004de2dfb52783a9ea80daa66ddf3df4f03f13ade3d82aa27aab2451cd669b9a4596a3f777c4a3388fca4d3c00238e882fabfa

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 1.0.0 (2026-11-14)
+
+First release: create_invoice, get_invoice, simulate_payment, send_test_webhook, currencies, rates, verify_webhook,
+test_event?, order_matches?.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ArionPay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,174 @@
+# ArionPay for Ruby
+
+Official Ruby client for [ArionPay](https://arionpay.com). Create crypto invoices, send customers to the payment page, and check webhooks. The money goes straight to your own wallet: ArionPay never holds it.
+
+- No dependencies (standard library only). Ruby 3.0 or newer.
+- Works with Rails, Sinatra, Hanami, any Rack app or plain scripts.
+- Safe retries: every invoice request carries an idempotency key, so a network error can never create two invoices.
+
+```bash
+gem install arionpay        # or in your Gemfile: gem "arionpay"
+```
+
+## Keys
+
+In your ArionPay dashboard, open your store:
+
+| Value | Where | Starts with |
+| --- | --- | --- |
+| API key | Store page, **API key** | `pk_` |
+| API secret | Store page, **API secret** (asks for your authenticator code) | `sk_` |
+| Webhook secret | **Webhooks** page, **signing secret** | `whsec_` |
+
+Keep them on your server, for example in environment variables or Rails credentials.
+
+## Take a payment
+
+```ruby
+require "arionpay"
+
+ARIONPAY = ArionPay::Client.new(
+  api_key: ENV.fetch("ARIONPAY_API_KEY"),
+  api_secret: ENV.fetch("ARIONPAY_API_SECRET"),
+  webhook_secret: ENV.fetch("ARIONPAY_WEBHOOK_SECRET")
+)
+
+invoice = ARIONPAY.create_invoice(
+  amount: "49.90",
+  currency: "USD",
+  order_id: "1001",
+  success_url: "https://shop.example.com/thanks/1001",
+  cancel_url: "https://shop.example.com/cart",
+  metadata: { "user_id" => 42 }
+)
+# send the customer to invoice["invoiceUrl"]
+```
+
+The customer coming back to `success_url` does **not** prove they paid. Deliver the order when the `invoice.paid` webhook arrives (or when `get_invoice` says `paid`).
+
+Invoices are Hashes with string keys and the same field names as the webhook's `data.invoice` (`"id"`, `"status"`, `"orderId"`, `"amountFiat"`, `"currency"`, `"asset"`, `"paidCrypto"`, `"transactions"`, `"test"`, `"metadata"`, ...), so one method can handle a webhook and a read.
+
+## Webhooks
+
+Set your webhook address on the **Webhooks** page of the dashboard (a public `https://` address), or per invoice with `callback_url:`. Check the signature against the **raw** body, before you parse it.
+
+### Rails
+
+```ruby
+# config/routes.rb:  post "/arionpay/webhook", to: "arionpay_webhooks#create"
+class ArionpayWebhooksController < ActionController::API   # or ApplicationController with skip_forgery_protection
+  def create
+    event = ARIONPAY.verify_webhook(request.raw_post, request.headers["ArionPay-Signature"])
+    handle_event(event) unless ArionPay.test_event?(event) # "Send test webhook": not a real order
+    head :ok
+  rescue ArionPay::SignatureError
+    head :unauthorized
+  end
+end
+```
+
+### Sinatra
+
+```ruby
+post "/arionpay/webhook" do
+  request.body.rewind if request.body.respond_to?(:rewind) # Rack 3 bodies may not rewind
+  begin
+    event = ARIONPAY.verify_webhook(request.body.read, request.env["HTTP_ARIONPAY_SIGNATURE"])
+  rescue ArionPay::SignatureError
+    halt 401
+  end
+  handle_event(event) unless ArionPay.test_event?(event)
+  status 200
+end
+```
+
+On Rack 3, `request.body.rewind` without the `respond_to?` check fails with `NoMethodError` on some servers (WEBrick, for one), and every webhook then gets a 500.
+
+### Plain Rack
+
+```ruby
+raw = env["rack.input"].read
+event = ARIONPAY.verify_webhook(raw, env["HTTP_ARIONPAY_SIGNATURE"])
+```
+
+No client at hand? `ArionPay.verify_webhook(raw, header, webhook_secret)` does the same.
+
+### Handling an event
+
+```ruby
+def handle_event(event)
+  return if WebhookEvent.exists?(event_id: event["id"]) # the same event can arrive more than once
+
+  invoice = event["data"]["invoice"]
+  order = Order.find_by(number: invoice["orderId"])
+  if event["type"] == "invoice.paid" && order && !order.paid? &&
+     ArionPay.order_matches?(invoice, order.total, order.currency) && invoice["test"] == order.test?
+    order.mark_paid!(invoice) # deliver here
+  end
+  WebhookEvent.create!(event_id: event["id"])
+end
+```
+
+`ArionPay.order_matches?(invoice, "49.90", "USD")` is true when the invoice price is that total, to the cent, in that currency.
+
+| Event | Meaning | What to do |
+| --- | --- | --- |
+| `invoice.pending` | A payment was seen on the network and waits for confirmations. | Show "payment on its way". Do not deliver yet. |
+| `invoice.partial` | Less than the full amount arrived. The invoice stays open for the rest. | Do not deliver. |
+| `invoice.paid` | Fully paid and confirmed. Also sent when you accept a payment by hand in the dashboard. | Deliver the order. |
+| `invoice.expired` | Time ran out without full payment. A late payment can still make it `paid`. | Keep the order unpaid. |
+| `invoice.needs_review` | Something needs a person, for example more money arrived after the invoice was paid. | Tell a human. Do not change the order. |
+
+ArionPay sends again when your server does not answer `2xx` (for about 3 days).
+
+### Rules for a safe integration
+
+1. Check the signature on the raw body. Never trust a webhook you could not verify.
+2. Deliver only on `invoice.paid` (or when `get_invoice(id)["status"] == "paid"`).
+3. Match the invoice to your order: your `order_id` or `metadata`, and the same amount and currency as the order's current total (`ArionPay.order_matches?`).
+4. Ignore test events (`ArionPay.test_event?(event)`), and in your live shop ignore invoices with `"test" => true`.
+5. Handle each `event["id"]` once, and answer `2xx` quickly (send emails from a background job).
+6. Do not compare crypto amounts yourself. ArionPay decides when an invoice is paid, including payments inside your store's payment tolerance and payments you accept in Payment Radar.
+
+## Test without real money
+
+```ruby
+invoice = ARIONPAY.create_invoice(amount: "10", order_id: "test-1", asset: "USDT_TRC20", test: true)
+ARIONPAY.simulate_payment(invoice["id"], "exact") # your webhook gets invoice.paid, like a real payment
+```
+
+Scenarios: `exact`, `detected`, `confirm`, `underpaid_1pct`, `underpaid_5pct`, `overpaid`, `partial_half`, `late`.
+
+`ARIONPAY.send_test_webhook("invoice.paid")` sends a signed sample event to your store's webhook address. It describes a made-up invoice (`inv_test_...`) and must never change an order.
+
+Complete small shops: [`examples/config.ru`](examples/config.ru) (plain Rack) and [`examples/sinatra.rb`](examples/sinatra.rb).
+
+## Reference
+
+| Method | Returns |
+| --- | --- |
+| `create_invoice(amount:, currency: "USD", order_id: nil, ...)` | `{"id", "invoiceUrl", "status", "amountFiat", "currency", "asset", "address", "amountCrypto", "expiresAt", "orderId", "raw"}` |
+| `get_invoice(invoice_id)` | The invoice, with the webhook field names (`"raw"` has every field ArionPay sent). |
+| `simulate_payment(invoice_id, scenario = "exact")` | Sandbox only (test invoices). |
+| `send_test_webhook(event_type = "invoice.paid")` | `{"delivered", "httpStatus", "eventId"}` |
+| `currencies` | Coins you can pass as `asset:` / `allowed_assets:`. |
+| `rates(currency = "USD")` | Current coin prices. |
+| `verify_webhook(raw_body, signature_header)` | The event Hash, or raises `ArionPay::SignatureError`. Also a module method taking the secret as third argument. |
+
+`create_invoice` keyword arguments: `amount:` (required), `currency:`, `order_id:`, `description:`, `customer_email:`, `success_url:`, `cancel_url:`, `callback_url:`, `asset:`, `allowed_assets:`, `expires_min:` (5 to 1440), `metadata:`, `idempotency_key:`, `test:`. `nil` values are not sent.
+
+Errors from ArionPay are `ArionPay::APIError` with `status` (HTTP status, `0` when ArionPay could not be reached), `code` (for example `idempotency_key_reused`, `rate_limited`, `unknown_asset`) and `message`. Messages never contain your secret. Bad arguments raise `ArgumentError` before anything is sent.
+
+`ArionPay::Client.new` options: `api_key:`, `api_secret:`, `webhook_secret:`, `base_url:` (default `https://merchant.arionpay.com`), `timeout:` (seconds, default 20), `max_attempts:` (default 3), `app_info:` (added to the User-Agent). A client is safe to share between threads (Puma, Sidekiq).
+
+## Tests
+
+```bash
+rake test                   # unit tests; the live test is skipped
+ARIONPAY_IT_BASE_URL=... ARIONPAY_IT_API_KEY=pk_... ARIONPAY_IT_API_SECRET=sk_... \
+ARIONPAY_IT_WEBHOOK_SECRET=whsec_... ruby -Ilib -Itest test/test_integration.rb
+```
+
+## License
+
+MIT

data/lib/arionpay/client.rb

@@ -0,0 +1,256 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "uri"
+
+module ArionPay
+  DEFAULT_BASE_URL = "https://merchant.arionpay.com"
+
+  # Scenarios for Client#simulate_payment (test invoices only).
+  SCENARIOS = %w[detected confirm exact underpaid_1pct underpaid_5pct overpaid partial_half late].freeze
+
+  # ArionPay merchant API client. Safe to share between threads.
+  #
+  #   client = ArionPay::Client.new(api_key: ENV["ARIONPAY_API_KEY"], api_secret: ENV["ARIONPAY_API_SECRET"])
+  #   invoice = client.create_invoice(amount: "49.90", currency: "USD", order_id: "1001")
+  #   # send the customer to invoice["invoiceUrl"]
+  #
+  # Invoices are Hashes with string keys and the same field names as the webhook's data.invoice ("id", "status",
+  # "orderId", "amountFiat", ...), so one method can handle a webhook and a read.
+  class Client
+    PK_PATTERN = /\Apk_[A-Za-z0-9_-]{8,64}\z/.freeze
+    ID_PATTERN = /\A[0-9a-fA-F]{24}\z/.freeze
+    NETWORK_ERRORS = [SocketError, SystemCallError, IOError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse, Net::ProtocolError].freeze
+
+    # transport (for tests): ->(method, url, headers, body, timeout) { [status, headers_hash, body_string] }
+    def initialize(api_key:, api_secret:, webhook_secret: "", base_url: DEFAULT_BASE_URL, timeout: 20, max_attempts: 3,
+                   app_info: nil, transport: nil, sleeper: nil, clock: nil)
+      raise ArgumentError, "api_key must be your store API key (it starts with pk_)." unless api_key.is_a?(String) && api_key.match?(PK_PATTERN)
+      raise ArgumentError, "api_secret is required (your store API secret, it starts with sk_)." if api_secret.nil? || api_secret.to_s.empty?
+
+      uri = begin
+        URI.parse(base_url.to_s)
+      rescue URI::InvalidURIError
+        nil
+      end
+      unless uri.is_a?(URI::HTTP) && uri.host && !uri.host.empty?
+        raise ArgumentError, "base_url must be an http(s) address."
+      end
+
+      @api_key = api_key
+      @api_secret = api_secret.to_s
+      @webhook_secret = webhook_secret.to_s
+      @scheme = uri.scheme
+      @host = uri.host
+      @port = uri.port
+      @base_path = uri.path.to_s.sub(%r{/+\z}, "")
+      @timeout = timeout.to_f
+      @max_attempts = max_attempts.to_i.clamp(1, 5)
+      @transport = transport || method(:net_http_transport)
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @clock = clock || -> { Time.now.to_i }
+      @user_agent = "arionpay-ruby/#{VERSION} ruby/#{RUBY_VERSION}#{app_info ? " #{app_info}" : ""}"
+    end
+
+    attr_reader :user_agent
+
+    # Creates an invoice. Returns {"id", "invoiceUrl", "status", "amountFiat", "currency", "asset", "address",
+    # "amountCrypto", "expiresAt", "orderId", "raw"}. Send the customer to "invoiceUrl".
+    #
+    # Safe to retry: each call carries an idempotency key (a random one when you pass none), so a repeat after a
+    # network error returns the same invoice. Pass your own key (e.g. "order-1001-49.90USD") to be safe across
+    # restarts. The customer coming back to success_url does NOT prove payment: wait for the invoice.paid webhook.
+    def create_invoice(amount:, currency: "USD", order_id: nil, description: nil, customer_email: nil, success_url: nil,
+                       cancel_url: nil, callback_url: nil, asset: nil, allowed_assets: nil, expires_min: nil,
+                       metadata: nil, idempotency_key: nil, test: nil)
+      raise ArgumentError, "amount is required." if amount.nil? || amount == true || amount == false || amount.to_s.strip.empty?
+
+      fields = {
+        "amount" => amount.to_s,
+        "currency" => currency,
+        "orderId" => order_id&.to_s,
+        "description" => description,
+        "customerEmail" => customer_email,
+        "successUrl" => success_url,
+        "cancelUrl" => cancel_url,
+        "callbackUrl" => callback_url,
+        "asset" => asset,
+        "allowedAssets" => allowed_assets,
+        "expiresMin" => expires_min,
+        "metadata" => metadata,
+        "idempotencyKey" => idempotency_key || "sdk_#{SecureRandom.uuid}",
+        "test" => test
+      }
+      r = request("POST", "/api/v1/invoices", fields.compact, retry_safe: true)
+      d = r["data"].is_a?(Hash) ? r["data"] : r
+      {
+        "id" => (d["id"] || r["id"]).to_s,
+        "invoiceUrl" => (d["invoice_url"] || r["invoice_url"]).to_s,
+        "status" => (d["status"] || "new").to_s,
+        "amountFiat" => d["amount_fiat"],
+        "currency" => (d["currency"] || currency).to_s,
+        "asset" => d["asset"],
+        "address" => d["address"],
+        "amountCrypto" => d["amount_crypto"],
+        "expiresAt" => d["expires_at"],
+        "orderId" => d.key?("order_id") ? d["order_id"] : order_id,
+        "raw" => r
+      }
+    end
+
+    # Reads an invoice, signed, straight from ArionPay (webhook field names). Use it to double-check, or to poll.
+    def get_invoice(invoice_id)
+      check_id(invoice_id)
+      ArionPay.normalize_invoice_read(request("GET", "/api/v1/invoices/#{invoice_id}", nil, retry_safe: true))
+    end
+
+    # Sandbox: moves a TEST invoice through a payment scenario (see SCENARIOS); webhooks then fire as for a real
+    # payment. Create the test invoice with asset: (e.g. "USDT_TRC20") so a coin is chosen.
+    def simulate_payment(invoice_id, scenario = "exact")
+      check_id(invoice_id)
+      raise ArgumentError, "scenario must be one of: #{SCENARIOS.join(", ")}" unless SCENARIOS.include?(scenario)
+
+      request("POST", "/api/v1/invoices/#{invoice_id}/simulate", { "scenario" => scenario }, retry_safe: false)
+    end
+
+    # Asks ArionPay to send a signed sample event to your store's webhook address. It never describes a real order.
+    def send_test_webhook(event_type = "invoice.paid")
+      request("POST", "/api/v1/webhooks/test", { "eventType" => event_type }, retry_safe: false)
+    end
+
+    # Coins you can pass as asset: / allowed_assets: ("USDT_TRC20", "BTC", "LTC", ...), with USD rates.
+    def currencies
+      r = request("GET", "/api/v1/currencies", nil, retry_safe: true, signed: false)
+      r["currencies"].is_a?(Array) ? r["currencies"] : []
+    end
+
+    # Current coin prices in one fiat currency.
+    def rates(currency = "USD")
+      request("GET", "/api/v1/rates?currency=#{URI.encode_www_form_component(currency)}", nil, retry_safe: true, signed: false)
+    end
+
+    # Checks a webhook with the webhook_secret given to the constructor. See ArionPay.verify_webhook.
+    def verify_webhook(raw_body, signature_header, tolerance_sec: DEFAULT_TOLERANCE_SEC)
+      ArionPay.verify_webhook(raw_body, signature_header, @webhook_secret, tolerance_sec: tolerance_sec)
+    end
+
+    def inspect
+      "#<ArionPay::Client #{@scheme}://#{@host}#{@base_path} key=#{@api_key}>" # never shows the secrets
+    end
+
+    private
+
+    def check_id(invoice_id)
+      return if invoice_id.is_a?(String) && invoice_id.match?(ID_PATTERN)
+
+      raise ArgumentError, "Invoice id must be the 24-character id ArionPay returned."
+    end
+
+    def request(method, path, body, retry_safe:, signed: true)
+      raw = body.nil? ? nil : JSON.generate(body)
+      replay_retry_used = false
+      attempt = 0
+      begin
+        attempt += 1
+        send_request(method, path, raw, signed)
+      rescue APIError => e
+        # Two identical signed requests in the same second have the same signature; only the first is accepted.
+        if e.status == 401 && e.message.downcase.include?("already used") && !replay_retry_used
+          replay_retry_used = true
+          @sleeper.call(1.1)
+          retry
+        end
+        retry_after = Integer(e.body["retryAfterSec"] || 0, exception: false) || 0
+        temporary = [0, 502, 503, 504].include?(e.status) || (e.status == 429 && retry_after <= 5)
+        raise if !retry_safe || !temporary || attempt >= @max_attempts
+
+        @sleeper.call(e.status == 429 ? [1, retry_after].max : 0.5 * (3**(attempt - 1)))
+        retry
+      end
+    end
+
+    def send_request(method, path, raw, signed)
+      path_only, query = path.split("?", 2)
+      full_path = @base_path + path_only + (query ? "?#{query}" : "")
+      headers = { "Accept" => "application/json", "User-Agent" => @user_agent }
+      if signed
+        ts = @clock.call
+        headers["x-api-key"] = @api_key
+        headers["x-timestamp"] = ts.to_s
+        headers["x-signature"] = ArionPay.sign_request(@api_secret, ts, method, full_path, raw || "")
+      end
+      headers["Content-Type"] = "application/json" if raw
+      begin
+        status, resp_headers, data = @transport.call(method, "#{@scheme}://#{@host}:#{@port}#{full_path}", headers, raw, @timeout)
+      rescue *NETWORK_ERRORS => e
+        raise APIError.new("Could not reach ArionPay: #{e.message}", status: 0, code: "network_error", body: {})
+      end
+      obj = begin
+        decoded = data.nil? || data.empty? ? {} : JSON.parse(data.dup.force_encoding(Encoding::UTF_8))
+        decoded.is_a?(Hash) ? decoded : {}
+      rescue JSON::ParserError, EncodingError
+        {}
+      end
+      return obj if status >= 200 && status < 300
+
+      message = [obj["error"], obj["message"]].find { |m| m.is_a?(String) } || "HTTP #{status}"
+      err_body = obj.dup
+      lower = (resp_headers || {}).each_with_object({}) { |(k, v), h| h[k.to_s.downcase] = Array(v).first }
+      retry_after = Integer(lower["retry-after"].to_s, exception: false)
+      err_body["retryAfterSec"] = retry_after if retry_after&.positive?
+      raise APIError.new("ArionPay API error (#{status}): #{message}", status: status, code: obj["code"].is_a?(String) ? obj["code"] : "", body: err_body)
+    end
+
+    def net_http_transport(method, url, headers, body, timeout)
+      uri = URI.parse(url)
+      http = Net::HTTP.new(uri.hostname, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout
+      http.max_retries = 0 # retries are decided above (a POST must never be repeated blindly)
+      req = method == "GET" ? Net::HTTP::Get.new(uri.request_uri) : Net::HTTP::Post.new(uri.request_uri)
+      headers.each { |k, v| req[k] = v }
+      req.body = body if body
+      res = http.start { |h| h.request(req) } # Net::HTTP never follows redirects
+      [res.code.to_i, res.each_header.to_h, res.body.to_s]
+    end
+  end
+
+  module_function
+
+  # Turns the signed read (GET /api/v1/invoices/<id>) into the webhook invoice field names.
+  def normalize_invoice_read(r)
+    out = {
+      "id" => (r["invoiceId"] || r["id"]).to_s,
+      "status" => r["status"].to_s.downcase,
+      "orderId" => r["orderId"],
+      "amountFiat" => r["amountFiat"],
+      "currency" => r["currency"].to_s,
+      "asset" => r["settledCurrency"].to_s,
+      "network" => r["network"].to_s,
+      "amountCrypto" => r["amountExpected"].to_s,
+      "paidCrypto" => (r["amountReceived"] || "0").to_s,
+      "confirmedCrypto" => (r["amountConfirmed"] || "0").to_s,
+      "overpaid" => r["overpaid"] == true,
+      "underpaidWithinTolerance" => r["underpaidWithinTolerance"] == true,
+      "late" => r["late"] == true,
+      "needsReview" => r["needsReview"] == true,
+      "reviewReason" => r["reviewReason"],
+      "manual" => r["manual"] == true,
+      "test" => r["test"] == true,
+      "transactions" => r["transactions"].is_a?(Array) ? r["transactions"] : [],
+      "metadata" => r["metadata"].is_a?(Hash) ? r["metadata"] : {},
+      "paidAt" => r["settledAt"],
+      "txHash" => r["txHash"],
+      "confirmations" => r["confirmations"] || 0,
+      "requiredConfirmations" => r["requiredConfirmations"] || 0,
+      "raw" => r
+    }
+    out["paidVia"] = r["paidVia"] if r.key?("paidVia")
+    out
+  end
+end

data/lib/arionpay/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module ArionPay
+  # Base class of every error this library raises (bad arguments raise ArgumentError).
+  class Error < StandardError; end
+
+  # ArionPay answered with an error, or could not be reached (status 0).
+  class APIError < Error
+    # HTTP status, 0 when ArionPay could not be reached
+    attr_reader :status
+    # ArionPay error code, e.g. "idempotency_key_reused", "rate_limited", "unknown_asset" ("" when none)
+    attr_reader :code
+    # decoded error body ("retryAfterSec" added from a Retry-After header)
+    attr_reader :body
+
+    def initialize(message, status: 0, code: "", body: {})
+      super(message)
+      @status = status
+      @code = code
+      @body = body
+    end
+  end
+
+  # A webhook must not be trusted: bad or stale signature, wrong secret, or not an ArionPay event.
+  class SignatureError < Error; end
+end

data/lib/arionpay/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ArionPay
+  VERSION = "1.0.0"
+end

data/lib/arionpay/webhook.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "json"
+require "openssl"
+
+module ArionPay
+  # Webhooks signed more than this many seconds ago (or ahead) are refused. ArionPay signs again on every retry.
+  DEFAULT_TOLERANCE_SEC = 300
+
+  EVENT_TYPES = %w[invoice.pending invoice.partial invoice.paid invoice.expired invoice.needs_review].freeze
+
+  module_function
+
+  # The x-signature of one API request:
+  # POST: hex HMAC-SHA256(secret, "<ts>.<raw body>"), GET: hex HMAC-SHA256(secret, "<ts>.GET <path and query>").
+  def sign_request(secret_key, timestamp, method, path_and_query, raw_body = "")
+    data = if method.to_s.casecmp?("GET")
+             "#{timestamp.to_i}.GET #{path_and_query}"
+           else
+             "#{timestamp.to_i}.".b + raw_body.to_s.b
+           end
+    OpenSSL::HMAC.hexdigest("SHA256", secret_key.to_s, data)
+  end
+
+  # Reads "t=<unix seconds>,v1=<hex>". Returns [t, v1] or nil when the header is malformed.
+  def parse_signature_header(header)
+    return nil unless header.is_a?(String)
+
+    values = {}
+    header.split(",").each do |part|
+      key, value = part.split("=", 2)
+      values[key.strip] = value.strip if key && value
+    end
+    t = values["t"]
+    v1 = values["v1"]
+    return nil unless t&.match?(/\A[0-9]{1,12}\z/) && v1&.match?(/\A[0-9a-fA-F]{64}\z/)
+
+    [t.to_i, v1.downcase]
+  end
+
+  # True when header is a valid, fresh signature of exactly raw_body. Never raises.
+  def valid_signature?(raw_body, header, webhook_secret, tolerance_sec: DEFAULT_TOLERANCE_SEC, now: Time.now.to_i)
+    return false unless raw_body.is_a?(String) && webhook_secret.is_a?(String) && !webhook_secret.empty?
+
+    parsed = parse_signature_header(header)
+    return false unless parsed
+
+    t, v1 = parsed
+    return false if (now.to_i - t).abs > tolerance_sec
+
+    expected = OpenSSL::HMAC.hexdigest("SHA256", webhook_secret, "#{t}.".b + raw_body.b)
+    OpenSSL.fixed_length_secure_compare(expected, v1)
+  end
+
+  # Checks a webhook and returns the event (a Hash with string keys, as ArionPay sent it), or raises SignatureError.
+  #
+  # raw_body must be the exact bytes ArionPay sent: request.raw_post (Rails), request.body.read (Sinatra/Rack),
+  # never parsed and re-encoded JSON.
+  def verify_webhook(raw_body, signature_header, webhook_secret, tolerance_sec: DEFAULT_TOLERANCE_SEC, now: Time.now.to_i)
+    if webhook_secret.nil? || webhook_secret.to_s.empty?
+      raise SignatureError, "The webhook secret is empty. Copy it from the Webhooks page of your ArionPay dashboard (it starts with whsec_)."
+    end
+    unless raw_body.is_a?(String)
+      raise SignatureError, "Pass the raw request body (a String: request.raw_post in Rails, request.body.read in Sinatra), not parsed JSON."
+    end
+    raise SignatureError, "Missing or malformed ArionPay-Signature header." unless parse_signature_header(signature_header)
+    unless valid_signature?(raw_body, signature_header, webhook_secret.to_s, tolerance_sec: tolerance_sec, now: now)
+      raise SignatureError, "Invalid webhook signature or stale timestamp. Check the webhook secret and your server clock."
+    end
+
+    text = raw_body.dup.force_encoding(Encoding::UTF_8)
+    raise SignatureError, "The webhook body is not JSON." unless text.valid_encoding?
+
+    begin
+      event = JSON.parse(text)
+    rescue JSON::ParserError
+      raise SignatureError, "The webhook body is not JSON."
+    end
+    valid = event.is_a?(Hash) && event["id"].is_a?(String) && !event["id"].empty? &&
+            event["type"].is_a?(String) && !event["type"].empty? &&
+            event["data"].is_a?(Hash) && event["data"]["invoice"].is_a?(Hash)
+    raise SignatureError, "The webhook body is not an ArionPay event." unless valid
+
+    event
+  end
+
+  # True for events made by "Send test webhook": a made-up invoice that must never change an order.
+  def test_event?(event)
+    return false unless event.is_a?(Hash)
+
+    invoice = event.dig("data", "invoice")
+    event["test"] == true || event["id"].to_s.start_with?("evt_test_") ||
+      (invoice.is_a?(Hash) && invoice["id"].to_s.start_with?("inv_test_"))
+  end
+
+  # True when the invoice price is exactly this order total (to the cent) in this currency: the check to make before
+  # you deliver. Crypto amounts never need comparing: ArionPay decides whether an invoice is paid.
+  def order_matches?(invoice, order_total, currency)
+    return false unless invoice.is_a?(Hash)
+
+    paid = fiat(invoice["amountFiat"])
+    !paid.nil? && paid == fiat(order_total) && invoice["currency"].to_s.casecmp?(currency.to_s)
+  end
+
+  # "49.90" for 49.9, "49.9" or "49.90"; nil when it is not a number.
+  def fiat(value)
+    return nil if value.nil? || value == true || value == false
+
+    f = Float(value.to_s)
+    f.finite? ? format("%.2f", f) : nil
+  rescue ArgumentError, TypeError
+    nil
+  end
+end

data/lib/arionpay.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+# ArionPay: create crypto invoices, read them, and verify webhooks. Payments go straight to the merchant's own wallet.
+# Use it on your server only: it holds your API secret.
+require_relative "arionpay/version"
+require_relative "arionpay/errors"
+require_relative "arionpay/webhook"
+require_relative "arionpay/client"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: arionpay
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- ArionPay
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-11-14 00:00:00.000000000 Z
+dependencies: []
+description: Create crypto invoices (Bitcoin, USDT, Litecoin, Ethereum, TRON and more),
+  send customers to the ArionPay payment page, and verify signed webhooks. Payments
+  go straight to your own wallet. Standard library only; works with Rails, Sinatra,
+  Hanami and any Rack app.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/arionpay.rb
+- lib/arionpay/client.rb
+- lib/arionpay/errors.rb
+- lib/arionpay/version.rb
+- lib/arionpay/webhook.rb
+homepage: https://arionpay.com
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/ArionPay-Dev/arionpay-ruby
+  changelog_uri: https://github.com/ArionPay-Dev/arionpay-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: 'Official Ruby client for ArionPay crypto payments: invoices, signed webhooks,
+  sandbox.'
+test_files: []