invoq 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 11bbb19ba09943897da6097ebf8d655bf8a658d4b3cf081eb3c5ccd177b2f6b3
-  data.tar.gz: 91fb9ffc921bdb61f622d615a05a0d87efb6cb853db8b6e60eb3fc9007f7669f
+  metadata.gz: d6735a9a9a69b7d895e5195f2c996067a5e6abc84535da30bb9c1994b235b15d
+  data.tar.gz: 8882cfaa9d72e9beda66de5bf69a213058164e2b0043aeb2681351f0838a9ad6
 SHA512:
-  metadata.gz: 066dd20b88afcdc0e1f5af02d3cf35a2bcbb1b2af19b96ea7cd87e2d8c2d88cb66582d5c4357853fc95543aa598ded42f3265561c057e2e997b2c390300c2ba6
-  data.tar.gz: 850c9c77ca95c4b1df54a5c90fcc17cfd130f04c899562445852fdeb9a526d8ce5b7a2d444fc3bcc770c32827dac9c808314556c4fac3a9f394481f721638bd6
+  metadata.gz: a3ae2327b5bfed2af09db878361a2a15028f4943e905ec610884c1e36dc5cdacd75d2aa9385eda9f61dff1382739a58553a449f9233c2e4e160bf1136803f610
+  data.tar.gz: 43efaca949a9c6e2d9ddaf8d34a4381baf70a9a59eaf07902b32616269a57ec4b1aa7371bfdf49c99decaf0f0b2140ab641c8f4ebc9ef1cd5fca43e247fd013e

data/README.md

@@ -1,11 +1,34 @@
 # invoq Ruby SDK
 
+**English** · [Bahasa Indonesia](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.id.md) · [Español](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.es-419.md) · [Français](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.fr.md) · [Português](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.pt-BR.md) · [Tiếng Việt](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.vi.md) · [Türkçe](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.tr.md) · [ไทย](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.th.md) · [简体中文](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.zh-Hans.md) · [繁體中文](https://github.com/invoqmoney/sdk-ruby/blob/main/docs/README.zh-Hant.md)
+
 Accept stablecoin payments with invoq from Ruby server code. This SDK wraps
 invoq server APIs and verifies signed webhooks.
 
 Use this gem only on your server. It handles secret keys and should not be
 bundled into browser code.
 
+**Coding with AI? Paste this.**
+
+```
+Add stablecoin payments to my project with invoq. Start in test mode. Read the docs before you write any code: https://invoq.money/llms.txt
+```
+
+## Server SDKs
+
+Create invoices and verify webhooks from your backend in any of these languages — same REST API, same webhook signature. This repository is the Ruby SDK.
+
+| Language | Repository |
+| --- | --- |
+| Node.js | [github.com/invoqmoney/sdk-js](https://github.com/invoqmoney/sdk-js) (`@invoq/server`) |
+| Python | [github.com/invoqmoney/sdk-python](https://github.com/invoqmoney/sdk-python) |
+| PHP | [github.com/invoqmoney/sdk-php](https://github.com/invoqmoney/sdk-php) |
+| Go | [github.com/invoqmoney/sdk-go](https://github.com/invoqmoney/sdk-go) |
+| Rust | [github.com/invoqmoney/sdk-rust](https://github.com/invoqmoney/sdk-rust) |
+| Ruby | **this repo** |
+
+The browser side is the same for every backend: **`@invoq/checkout`** (JavaScript, in [github.com/invoqmoney/sdk-js](https://github.com/invoqmoney/sdk-js)) opens the in-page checkout modal for any frontend.
+
 ## Installation
 
 Install the gem:
@@ -32,6 +55,9 @@ Requires Ruby 2.6 or newer.
 3. In your project's **webhooks** settings, save your webhook URL. The webhook
    secret (`whsec_...`) for that mode is shown once, when you first enable the
    webhook. Store it right away. Webhook URLs must be public HTTPS URLs.
+4. Set up your **Receiving wallet** before going live. Test invoices don't need
+   one; a live invoice with nowhere to settle fails with
+   `409 no_payment_options_available`.
 
 Add both to your server environment:
 
@@ -80,7 +106,6 @@ Create an invoice:
 ```ruby
 invoice = invoq.invoices.create(
   amount: "129",
-  currency: "USD",
   description: "SaaS boilerplate",
   reference_id: "order_1234",
   return_url: "https://merchant.example/thanks"
@@ -93,9 +118,9 @@ checkout_url = "https://pay.invoq.money/#{invoice_id}"
 Notes:
 
 - Use a server-side amount. Do not trust client-supplied amounts.
-- `amount` is a decimal USD string from `"0.01"` to `"999.99"` with up
-  to 2 decimal places, such as `"129"` or `"129.99"`.
-- `currency` is optional and defaults to `"USD"`.
+- `amount` is a decimal USD string from `"0.01"` to `"1000000.00"` with up
+  to 2 decimal places, such as `"129"` or `"129.99"`. Currency is always USD,
+  and test or live comes from the key — neither is a request field.
 - Use a stable, non-empty `reference_id` to map `invoice.paid` webhooks back to
   your order. Creating again with the same `reference_id` and invoice terms
   returns the existing invoice; different terms fail with a
@@ -114,11 +139,10 @@ Get an invoice:
 invoice = invoq.invoices.get("inv_123")
 ```
 
-`invoices.get` returns the public invoice shape used by hosted checkout. It
-includes fields such as `amount_paid`, `amount_due`, `payment_status`,
-`project`, `deposit_address`, `monitoring_ends_at`, and `direct_onchain_rails`,
-but does not include `reference_id`. Use the create response or
-`invoice.paid` webhook when you need your merchant `reference_id`.
+`invoices.get` returns the public invoice shape used by hosted checkout: the
+create shape plus `amount_paid`, `project`, and `transfers`, minus
+`reference_id`. Use the create response or the `invoice.paid` webhook when you
+need your merchant `reference_id`.
 
 Create a test payment:
 
@@ -143,8 +167,7 @@ webhook URL.
 
 To receive webhooks on your machine, expose your local server with an HTTPS
 tunnel such as ngrok or cloudflared and save the tunnel URL as your test webhook
-URL in the dashboard. The dashboard can also send a signed `webhook.ping` to
-check connectivity.
+URL in the dashboard.
 
 Each invoice method returns the response `data` object directly as a Ruby hash.
 
@@ -161,17 +184,40 @@ Share the link or redirect to it when an in-page checkout modal is not a fit.
 ## Inputs and responses
 
 The SDK checks that `amount` values and `invoice_id` arguments are non-empty
-strings before sending requests. The invoq API validates the amount format,
-range, and currency.
+strings before sending requests. The invoq API validates the amount format and
+range.
 
 Leave unset optional fields out of the request hash. When you include
 `description` or `reference_id`, pass a string. `return_url` can be a string or
-`nil`.
+`nil`. Any other key in the hash is dropped rather than sent, because the API
+rejects unknown body keys.
 
 Amounts in responses are normalized to 4 decimal places: create with `"129"`
 and the invoice returns `amount: "129.0000"`. Compare amounts numerically, not
 as strings. `amount_due` is derived as `max(amount - amount_paid, 0)` and uses
-the same 18-decimal scale as `amount_paid`.
+the same 18-decimal scale as `amount_paid`; `amount_overpaid` is its mirror,
+`max(amount_paid - amount, 0)`, so you never subtract money yourself.
+
+Two status fields. `status` is the accounting one — `unpaid`, `partially_paid`,
+`paid`, `settling`, `settled`, `review_required` — where the three paid-like
+values differ only in how far the funds have moved to your wallet.
+`checkout_status` is payer-facing — `open`, `confirming`, `expired`, `paid`,
+`unavailable` — and never authorizes fulfillment. `payment_revision` is a
+non-negative integer that increments whenever the confirmed payment set changes,
+so you can discard a snapshot older than one you already hold.
+
+`payment_options` holds the payment instructions, fixed at creation and `[]` in
+test mode. Entries are discriminated by `status`, then `collection_method`: only
+`"ready"` is payable, `"evm_deposit"` carries `deposit_address` and
+`suggested_amount`, `"direct_exact"` carries `recipient_address` and an
+`exact_amount` the buyer must send to the digit. `transfers` is the confirmed
+receipt trail — `transaction_id`, `event_index`, `amount`,
+`explorer_transaction_url` — and stays `[]` until a payment confirms. Full field
+reference: [REST API docs](https://github.com/invoqmoney/api).
+
+Identify a payment option by `chain_namespace`, `chain_reference`, and
+`token_address`, never by its position in the array. `monitoring_ends_at` is the
+end of the payment window, and is `nil` for test invoices.
 
 ## Webhooks
 
@@ -206,6 +252,11 @@ def handle_invoq_webhook(env)
     fulfillment_key = invoice["reference_id"] || invoice.fetch("id")
 
     # Fulfill the order for fulfillment_key idempotently.
+  elsif Invoq.invoice_payment_reversed?(event)
+    invoice = event.fetch("data").fetch("invoice")
+    fulfillment_key = invoice["reference_id"] || invoice.fetch("id")
+
+    # Hold or reverse the order for fulfillment_key.
   end
 
   [
@@ -222,11 +273,16 @@ from browser results.
 
 When `Invoq.invoice_paid?(event)` is true, the invoice is ready for automatic
 fulfillment; use the invoice `reference_id` or a stored invoice `id` to find
-and fulfill your order. A `review_required` invoice does not emit an
-`invoice.paid` webhook yet. If checkout reports `review_required`, show a
+and fulfill your order. A `review_required` invoice emits no `invoice.paid`
+until the review clears. If checkout reports `review_required`, show a
 pending-review state and wait for a later `invoice.paid` webhook after review
 is approved.
 
+invoq also sends `invoice.payment_reversed` when a previously paid invoice drops
+back below its amount — a chain reorg dropping a confirmed transfer, for
+example. Catch it with `Invoq.invoice_payment_reversed?(event)` and hold or
+reverse the fulfillment according to your own policy.
+
 Important:
 
 - Pass the exact raw request body string received by your Ruby framework.
@@ -236,12 +292,19 @@ Important:
 - Use your webhook secret (`whsec_...`), not `INVOQ_SECRET_KEY`.
 - Make fulfillment idempotent. Retried webhook deliveries can send the same
   event more than once.
-- Respond with a 2xx quickly. Any other status counts as a failed delivery.
-  Transient failures such as timeouts, `429`, and `5xx` responses are retried;
-  other `4xx` responses are not.
+- Respond with a 2xx quickly. Any other status counts as a failed delivery and
+  is retried, including redirects and `4xx`, so a deploy window or a temporarily
+  misrouted path is retried rather than dropped. The ladder is 1 minute,
+  5 minutes, 30 minutes, then 2 hours, for 5 attempts in total.
+- Deliveries can arrive out of order. Keep the snapshot with the highest
+  `payment_revision`.
 
 `Invoq.invoice_paid?` accepts fulfillable `invoice.paid` events whose invoice
 status is `paid`, `settling`, or `settled`; it rejects `review_required`.
+`Invoq.invoice_payment_reversed?` accepts `invoice.payment_reversed` events
+without checking the status at all: a reversal you drop leaves an order
+fulfilled on a payment that no longer exists. An event type this SDK version
+does not model still verifies and is returned as-is.
 
 Webhook verification failures raise `Invoq::SignatureVerificationError`. The
 SDK allows a 5-minute timestamp tolerance. The signature header is:
@@ -254,7 +317,7 @@ invoq-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
 
 ```ruby
 begin
-  invoq.invoices.create(amount: "0.001", currency: "USD")
+  invoq.invoices.create(amount: "0.001")
 rescue Invoq::ApiError => error
   warn error.status
   warn error.code

data/lib/invoq/client.rb

@@ -18,6 +18,12 @@ module Invoq
         raise Error, "invoq API key must be a non-empty string."
       end
 
+      # A control character in a key is either rejected deep in the transport or
+      # silently sent; reject it here so every SDK answers the same way.
+      if api_key.match?(/[\x00-\x1F\x7F]/)
+        raise Error, "invoq API key must not contain control characters."
+      end
+
       @api_key = api_key
       @api_origin = Invoq.normalize_api_origin(api_origin)
       @timeout_ms = Invoq.normalize_timeout_ms(timeout_ms)

data/lib/invoq/internal/request.rb

@@ -51,6 +51,15 @@ module Invoq
           )
         end
 
+        # A non-Hash data is a broken envelope; returning it defers the failure
+        # to the caller's first read.
+        unless payload["data"].is_a?(Hash)
+          raise Error.new(
+            "invoq API response data envelope was not an object.",
+            payload: payload
+          )
+        end
+
         payload["data"]
       rescue JSON::GeneratorError
         raise Error, "Failed to encode invoq API request."
@@ -116,8 +125,11 @@ module Invoq
         fields = value.each_with_object([]) do |field, result|
           next unless field.is_a?(Hash)
 
+          # A location this version does not know is passed through, not
+          # dropped: the caller is already on an error path and needs the code
+          # and message. Only a structurally invalid entry is discarded.
           location = field["location"]
-          next unless %w[query path body header].include?(location)
+          next unless location.is_a?(String)
           next unless field["field"].is_a?(String)
           next unless field["code"].is_a?(String)
           next unless field["message"].is_a?(String)

data/lib/invoq/invoices_resource.rb

@@ -24,7 +24,7 @@ module Invoq
     end
 
     def get(invoice_id)
-      id = encode_path_segment(required_request_string(invoice_id, "invoice_id"))
+      id = encode_path_segment(required_path_segment(invoice_id, "invoice_id"))
 
       Internal::Request.json(
         api_key: @api_key,
@@ -36,7 +36,7 @@ module Invoq
     end
 
     def create_test_payment(invoice_id, input)
-      id = encode_path_segment(required_request_string(invoice_id, "invoice_id"))
+      id = encode_path_segment(required_path_segment(invoice_id, "invoice_id"))
 
       Internal::Request.json(
         api_key: @api_key,
@@ -54,15 +54,16 @@ module Invoq
         raise Error, "request body must be a hash."
       end
 
+      # Only these four fields exist: the API rejects unknown body keys, and
+      # currency (always USD) and mode (from the key) are not request fields,
+      # so anything else in the hash is dropped rather than forwarded.
       body = {
         "amount" => required_request_string(input_value(input, "amount"), "amount")
       }
-      currency = optional_request_value(input, "currency")
       description = optional_request_string(input, "description")
       reference_id = optional_request_string(input, "reference_id")
       return_url = optional_nullable_request_string(input, "return_url")
 
-      body["currency"] = currency unless currency.equal?(MISSING)
       body["description"] = description unless description.equal?(MISSING)
       body["reference_id"] = reference_id unless reference_id.equal?(MISSING)
       body["return_url"] = return_url unless return_url.equal?(MISSING)
@@ -107,6 +108,18 @@ module Invoq
       value
     end
 
+    # A URL resolver pops "." and "..", so an id of either would call a
+    # different endpoint instead of 404ing. Percent-encoding is no help.
+    def required_path_segment(value, field)
+      segment = required_request_string(value, field)
+
+      if segment == "." || segment == ".."
+        raise Error, "#{field} must not be a path segment that resolves ('.' or '..')."
+      end
+
+      segment
+    end
+
     def required_request_string(value, field)
       unless value.is_a?(String) && !value.strip.empty?
         raise Error, "#{field} must be a non-empty string."

data/lib/invoq/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Invoq
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/invoq/webhooks.rb

@@ -56,39 +56,65 @@ module Invoq
     end
 
     def self.invoice_paid?(event)
-      return false unless event.is_a?(Hash)
-      return false unless event["type"] == "invoice.paid"
-      return false unless event["id"].is_a?(String)
-      return false unless invoice_mode?(event["mode"])
-      return false unless event["created_at"].is_a?(String)
+      invoice = lifecycle_event_invoice(event, "invoice.paid")
+
+      # Paid-equivalent statuses only: review_required has money against it but
+      # is not cleared for fulfillment.
+      !invoice.nil? && invoice_paid_status?(invoice["status"])
+    end
+
+    def self.is_invoice_paid(event)
+      invoice_paid?(event)
+    end
+
+    def self.invoice_payment_reversed?(event)
+      # No status check, unlike the paid guard: rejecting an unrecognized status
+      # would drop the event and leave the order fulfilled on a payment that no
+      # longer exists.
+      !lifecycle_event_invoice(event, "invoice.payment_reversed").nil?
+    end
+
+    def self.is_invoice_payment_reversed(event)
+      invoice_payment_reversed?(event)
+    end
+
+    # The fields both lifecycle events share, returned so each guard can apply
+    # its own status rule. nil when this is not a well-formed event of that type.
+    def self.lifecycle_event_invoice(event, type)
+      return nil unless event.is_a?(Hash)
+      return nil unless event["type"] == type
+      return nil unless event["id"].is_a?(String)
+      return nil unless invoice_mode?(event["mode"])
+      return nil unless event["created_at"].is_a?(String)
 
       data = event["data"]
-      return false unless data.is_a?(Hash)
+      return nil unless data.is_a?(Hash)
 
       invoice = data["invoice"]
-      return false unless invoice.is_a?(Hash)
+      return nil unless invoice.is_a?(Hash)
 
       reference_id = invoice.key?("reference_id") ? invoice["reference_id"] : MISSING
       fully_paid_at = invoice.key?("fully_paid_at") ? invoice["fully_paid_at"] : MISSING
 
-      invoice["id"].is_a?(String) &&
+      valid = invoice["id"].is_a?(String) &&
         invoice_mode?(invoice["mode"]) &&
-        invoice_paid_status?(invoice["status"]) &&
+        invoice["status"].is_a?(String) &&
         invoice["amount"].is_a?(String) &&
         invoice["currency"] == "USD" &&
         invoice["amount_paid"].is_a?(String) &&
         (reference_id.is_a?(String) || reference_id.nil?) &&
+        invoice["payment_revision"].is_a?(Integer) &&
         (fully_paid_at.is_a?(String) || fully_paid_at.nil?)
-    end
 
-    def self.is_invoice_paid(event)
-      invoice_paid?(event)
+      valid ? invoice : nil
     end
+    private_class_method :lifecycle_event_invoice
 
     def self.parse_signature_header(signature_header)
       parts = {}
 
-      signature_header.split(",").each do |part|
+      # -1 keeps trailing empty fields, so a trailing comma reaches the check below.
+      signature_header.split(",", -1).each do |part|
         separator_index = part.index("=")
 
         unless separator_index
@@ -146,7 +172,7 @@ module Invoq
     def self.hmac_sha256_hex(secret, timestamp, raw_body)
       OpenSSL::HMAC.hexdigest(
         "SHA256",
-        secret.encode("UTF-8"),
+        secret.b,
         "#{timestamp}.".b + body_bytes(raw_body)
       )
     end

data/lib/invoq.rb

@@ -21,4 +21,12 @@ module Invoq
   def self.is_invoice_paid(event)
     invoice_paid?(event)
   end
+
+  def self.invoice_payment_reversed?(event)
+    Webhooks.invoice_payment_reversed?(event)
+  end
+
+  def self.is_invoice_payment_reversed(event)
+    invoice_payment_reversed?(event)
+  end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: invoq
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - invoq
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -45,7 +44,6 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '14.0'
 description: Ruby SDK for invoq server APIs and webhook verification.
-email: 
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -64,7 +62,6 @@ licenses:
 - MIT
 metadata:
   allowed_push_host: https://rubygems.org
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -79,8 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3.1
-signing_key: 
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Ruby SDK for invoq stablecoin payment acceptance.
 test_files: []