nowpayments-ruby 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b1798eb671822215a938ff5390a7f2ccb29a4f1551fdccb25b09f1871840c30f
+  data.tar.gz: 8056cd086f729d178d9c01d20ab73e6b7a9250122635e7d7b73ab9d400638443
+SHA512:
+  metadata.gz: 16eee9ec92b349c824757e15311b43a3a2e61b4930c629a03558d74348897e7708e32b0daa716607b7ae831f2af3e1b725acdc63c291d5826d5db8014517c086
+  data.tar.gz: b5527e6b8a6dc3416f2957136c2362263daceb50530b6c1bee38bf4e05e899d52a975cdf0dca88c284ba5fb38430b54b7ce525d02d362f2d0c53ac7906fbc948

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Foisalislambd
+
+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,514 @@
+# nowpayments-ruby
+
+<p align="center">
+  <img src="https://img.shields.io/gem/v/nowpayments?color=6366f1&style=for-the-badge&logo=ruby" alt="gem version" />
+  <img src="https://img.shields.io/badge/license-MIT-22c55e?style=for-the-badge" alt="license" />
+  <img src="https://img.shields.io/badge/Ruby-2.7+-cc342d?style=for-the-badge&logo=ruby" alt="Ruby" />
+</p>
+
+<h1 align="center">nowpayments-ruby</h1>
+<p align="center">
+  <strong>Full-featured Ruby SDK for NOWPayments</strong><br/>
+  Accept 300+ cryptocurrencies with auto-conversion to your wallet
+</p>
+
+<p align="center">
+  <a href="#-quick-start">Quick Start</a> •
+  <a href="#-features">Features</a> •
+  <a href="#-examples">Examples</a> •
+  <a href="#-api-reference">API</a> •
+  <a href="#-links">Links</a>
+</p>
+
+---
+
+## ✨ Features
+
+| Feature | Support |
+|---------|---------|
+| **Payments** | Create, status, list, update estimate |
+| **Invoices** | Create invoice + redirect flow |
+| **Payouts** | Mass payout, verify 2FA, cancel scheduled |
+| **Fiat Payouts** | Currencies, payment methods, list |
+| **Subscriptions** | Plans, recurring payments, cancel |
+| **Custody** | Sub-partners, transfers, deposit, write-off |
+| **Conversions** | In-custody currency conversion |
+| **IPN Webhooks** | HMAC signature verification |
+| **Helpers** | `payment_complete?`, `status_label`, etc. |
+
+---
+
+## 🚀 Quick Start
+
+```bash
+gem install nowpayments-ruby
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem "nowpayments-ruby"
+```
+
+```ruby
+require "nowpayments"
+
+np = NowPayments::Client.new(
+  api_key: ENV["NOWPAYMENTS_API_KEY"],
+  sandbox: true  # false for production
+)
+
+# Create payment
+payment = np.create_payment(
+  price_amount: 29.99,
+  price_currency: "usd",
+  pay_currency: "btc",
+  order_id: "order-123"
+)
+
+puts "Pay #{payment["pay_amount"]} #{(payment["pay_currency"] || "").to_s.upcase} → #{payment["pay_address"]}"
+```
+
+---
+
+## ⚙️ Config
+
+| Option | Required | Default | Description |
+|--------|----------|---------|-------------|
+| `api_key` | Yes | — | From [Dashboard](https://account.nowpayments.io) |
+| `sandbox` | No | `false` | Use sandbox API |
+| `timeout` | No | `30000` | Request timeout (ms) |
+| `ipn_secret` | No | — | For webhook verification |
+| `base_url` | No | — | Override API URL |
+
+---
+
+## 📁 Examples
+
+All examples use the same setup. Set `NOWPAYMENTS_API_KEY` before running:
+
+```bash
+export NOWPAYMENTS_API_KEY=your_api_key
+```
+
+| File | Description | Run |
+|------|-------------|-----|
+| `01_create_payment.rb` | Create payment, show address to customer | `ruby examples/01_create_payment.rb` |
+| `02_check_status.rb` | Check payment status + helper labels | `ruby examples/02_check_status.rb PAYMENT_ID` |
+| `03_list_payments.rb` | List payments with filters | `ruby examples/03_list_payments.rb` |
+| `04_create_invoice.rb` | Create invoice (redirect flow) | `ruby examples/04_create_invoice.rb` |
+| `05_estimate_and_min_amount.rb` | Price estimate + minimum amount | `ruby examples/05_estimate_and_min_amount.rb` |
+| `06_get_currencies.rb` | Get available currencies | `ruby examples/06_get_currencies.rb` |
+| `07_payout_flow.rb` | Payout: validate → create → verify | `ruby examples/07_payout_flow.rb` |
+| `08_subscription.rb` | Subscription plans + create subscription | `ruby examples/08_subscription.rb` |
+| `09_ipn_webhook.rb` | IPN signature verification demo | `ruby examples/09_ipn_webhook.rb` |
+| `10_custody_and_balance.rb` | Balance, sub-partners, deposit payment | `ruby examples/10_custody_and_balance.rb` |
+| `11_conversions.rb` | Create conversion (custody) | `ruby examples/11_conversions.rb` |
+
+### Example: Create Payment
+
+```ruby
+# examples/01_create_payment.rb
+require "nowpayments"
+
+np = NowPayments::Client.new(api_key: ENV["NOWPAYMENTS_API_KEY"], sandbox: true)
+
+payment = np.create_payment(
+  price_amount: 29.99,
+  price_currency: "usd",
+  pay_currency: "btc",
+  order_id: "order-#{Time.now.to_i}",
+  order_description: "Premium Plan",
+  ipn_callback_url: "https://yoursite.com/webhook"
+)
+
+puts "Payment created: #{payment["payment_id"]}"
+puts "Pay #{payment["pay_amount"]} #{payment["pay_currency"].to_s.upcase} to:"
+puts payment["pay_address"]
+```
+
+### Example: Check Payment Status
+
+```ruby
+# examples/02_check_status.rb
+payment_id = ARGV[0] || "PASTE_PAYMENT_ID_HERE"
+payment = np.get_payment_status(payment_id)
+
+puts "Status: #{NowPayments::Helpers.status_label(payment["payment_status"])}"
+puts "Amount: #{payment["pay_amount"]} #{payment["pay_currency"]}"
+
+if NowPayments::Helpers.payment_complete?(payment["payment_status"])
+  puts "✅ Payment done! Fulfill the order."
+else
+  puts "⏳ Waiting for payment..."
+end
+```
+
+### Example: List Payments
+
+```ruby
+# examples/03_list_payments.rb
+result = np.get_payments(
+  limit: 5,
+  page: 0,
+  sortBy: "created_at",
+  orderBy: "desc",
+  dateFrom: "2024-01-01",
+  dateTo: "2024-12-31"
+)
+
+puts "Total: #{result["total"]}"
+puts "Page: #{result["page"] + 1} of #{result["pagesCount"]}"
+result["data"].each_with_index do |p, i|
+  puts "#{i + 1}. #{p["payment_id"]} | #{p["payment_status"]} | #{p["price_amount"]} #{p["price_currency"]}"
+end
+```
+
+### Example: Create Invoice
+
+```ruby
+# examples/04_create_invoice.rb
+invoice = np.create_invoice(
+  price_amount: 49.99,
+  price_currency: "usd",
+  pay_currency: "btc",
+  order_id: "inv-#{Time.now.to_i}",
+  order_description: "Premium subscription",
+  success_url: "https://yoursite.com/success",
+  cancel_url: "https://yoursite.com/cancel"
+)
+
+puts "Redirect customer to: #{invoice["invoice_url"]}"
+```
+
+### Example: Estimate & Min Amount
+
+```ruby
+# examples/05_estimate_and_min_amount.rb
+estimate = np.get_estimate_price(
+  amount: 100,
+  currency_from: "usd",
+  currency_to: "btc"
+)
+puts "100 USD ≈ #{estimate["estimated_amount"]} BTC"
+
+min = np.get_min_amount(
+  currency_from: "usd",
+  currency_to: "btc",
+  fiat_equivalent: "usd"
+)
+puts "Min amount: #{min["min_amount"]} BTC (≈ #{min["fiat_equivalent"]} USD)"
+```
+
+### Example: Get Currencies
+
+```ruby
+# examples/06_get_currencies.rb
+currencies = np.get_currencies["currencies"]
+puts "Supported: #{currencies.first(15).join(", ")}..."
+puts "Total: #{currencies.length}"
+
+btc_info = np.get_currency("btc")
+puts "BTC info: #{btc_info}"
+
+full = np.get_full_currencies["currencies"]
+btc_full = full.find { |c| c["code"]&.downcase == "btc" }
+puts "BTC full: #{btc_full}"
+```
+
+### Example: Payout Flow (JWT required)
+
+```ruby
+# examples/07_payout_flow.rb
+# Env: NOWPAYMENTS_API_KEY, EMAIL, PASSWORD, PAYOUT_ADDRESS, VERIFICATION_CODE?
+
+# 1. Validate address
+np.validate_payout_address(address: payout_address, currency: "btc")
+
+# 2. Get JWT
+auth = np.get_auth_token(ENV["EMAIL"], ENV["PASSWORD"])
+token = auth["token"]
+
+# 3. Create payout
+payout = np.create_payout(
+  {
+    withdrawals: [{ address: payout_address, currency: "btc", amount: 0.0001 }],
+    ipn_callback_url: "https://yoursite.com/payout-webhook"
+  },
+  token
+)
+
+# 4. Verify (2FA code from email)
+np.verify_payout(payout["id"], ENV["VERIFICATION_CODE"], token)
+```
+
+### Example: Subscriptions
+
+```ruby
+# examples/08_subscription.rb
+plans = np.get_subscription_plans
+puts "Plans: #{plans["result"]&.length || 0}"
+
+plan = plans["result"]&.first
+if plan
+  auth = np.get_auth_token(ENV["EMAIL"], ENV["PASSWORD"])
+  sub = np.create_subscription(
+    { subscription_plan_id: plan["id"], email: "customer@example.com" },
+    auth["token"]
+  )
+  puts "Subscription: #{sub["result"]}"
+end
+```
+
+### Example: IPN Webhook
+
+```ruby
+# examples/09_ipn_webhook.rb
+# In Sinatra/Rails: verify before processing
+
+np = NowPayments::Client.new(api_key: "...", ipn_secret: ENV["IPN_SECRET"])
+
+# In your webhook handler:
+# if np.verify_ipn(request.body.read, request.env["HTTP_X_NOWPAYMENTS_SIG"])
+#   payload = JSON.parse(request.body.read)
+#   if NowPayments::Helpers.payment_complete?(payload["payment_status"])
+#     # Fulfill order
+#   end
+# end
+
+# Standalone verification
+valid = NowPayments::IPN.verify_signature(payload, signature, ipn_secret)
+NowPayments::IPN.create_signature(payload, ipn_secret)  # For testing
+```
+
+### Example: Custody & Balance
+
+```ruby
+# examples/10_custody_and_balance.rb
+balance = np.get_balance
+puts "Balance: #{balance}"
+
+partners = np.get_sub_partners
+puts "Sub-partners: #{partners}"
+
+# Deposit with payment (JWT required)
+auth = np.get_auth_token(ENV["EMAIL"], ENV["PASSWORD"])
+result = np.create_sub_partner_payment(
+  { currency: "trx", amount: 50, sub_partner_id: ENV["SUB_PARTNER_ID"] },
+  auth["token"]
+)
+puts "Deposit: #{result["result"]["pay_address"]} #{result["result"]["pay_amount"]} TRX"
+```
+
+### Example: Conversions (JWT required)
+
+```ruby
+# examples/11_conversions.rb
+auth = np.get_auth_token(ENV["EMAIL"], ENV["PASSWORD"])
+token = auth["token"]
+
+conv = np.create_conversion(
+  { amount: 0.001, from_currency: "btc", to_currency: "usd" },
+  token
+)
+
+if conv["deposit_id"]
+  status = np.get_conversion_status(conv["deposit_id"], token)
+  puts "Status: #{status}"
+end
+```
+
+---
+
+## 📖 API Reference
+
+### Auth & Status
+
+```ruby
+np.get_status
+auth = np.get_auth_token("your@email.com", "password")
+token = auth["token"]
+```
+
+### Currencies
+
+```ruby
+np.get_currencies
+np.get_currencies(true)  # fixed rate
+np.get_full_currencies
+np.get_merchant_coins
+np.get_currency("btc")
+```
+
+### Payments
+
+```ruby
+payment = np.create_payment(
+  price_amount: 29.99,
+  price_currency: "usd",
+  pay_currency: "btc",
+  order_id: "order-123",
+  ipn_callback_url: "https://yoursite.com/webhook",
+  is_fixed_rate: true
+)
+
+np.get_payment_status(payment_id)
+np.get_payments(limit: 10, page: 0, sortBy: "created_at", orderBy: "desc")
+np.update_payment_estimate(payment_id)
+```
+
+### Estimate & Min Amount
+
+```ruby
+np.get_estimate_price(amount: 100, currency_from: "usd", currency_to: "btc")
+np.get_min_amount(currency_from: "usd", currency_to: "btc", fiat_equivalent: "usd")
+```
+
+### Invoices
+
+```ruby
+invoice = np.create_invoice(
+  price_amount: 49.99,
+  price_currency: "usd",
+  order_id: "inv-001",
+  success_url: "https://yoursite.com/success",
+  cancel_url: "https://yoursite.com/cancel"
+)
+# invoice["invoice_url"] → redirect customer
+
+np.create_invoice_payment(iid: invoice_id, pay_currency: "btc")
+```
+
+### Payouts (JWT required)
+
+```ruby
+np.validate_payout_address(address: "0x...", currency: "eth")
+
+batch = np.create_payout(
+  {
+    ipn_callback_url: "https://yoursite.com/payout-webhook",
+    withdrawals: [
+      { address: "TEmGw...", currency: "trx", amount: 200 },
+      { address: "0x1EB...", currency: "eth", amount: 0.1 }
+    ]
+  },
+  token
+)
+
+np.verify_payout(batch["id"], "123456", token)
+np.cancel_payout(payout_id, token)
+np.get_payout_status(payout_id, token)
+np.get_payouts(batch_id: "...", limit: 10, page: 0)
+```
+
+### Fiat Payouts
+
+```ruby
+np.get_fiat_payouts_crypto_currencies({ provider: "transfi" }, token)
+np.get_fiat_payouts_payment_methods({ provider: "transfi", currency: "usd" }, token)
+np.get_fiat_payouts({ status: "FINISHED", limit: 10 }, token)
+```
+
+### Balance
+
+```ruby
+np.get_balance(token)
+```
+
+### Subscriptions
+
+```ruby
+np.get_subscription_plans(limit: 10, offset: 0)
+np.get_subscription_plan(id)
+np.update_subscription_plan(id, amount: 9.99, interval_day: "30")
+np.create_subscription({ subscription_plan_id: 76215585, email: "user@example.com" }, token)
+np.get_subscriptions(status: "PAID", limit: 10)
+np.get_subscription(id)
+np.delete_subscription(id, token)
+```
+
+### Custody / Sub-partners (JWT required)
+
+```ruby
+np.create_sub_partner("user-123", token)
+np.create_sub_partner_payment({ currency: "trx", amount: 50, sub_partner_id: "1631380403" }, token)
+np.get_sub_partners({ offset: 0, limit: 10 }, token)
+np.get_sub_partner_balance(sub_partner_id)
+np.create_transfer({ currency: "trx", amount: 0.3, from_id: 111, to_id: 222 }, token)
+np.deposit({ currency: "trx", amount: 0.5, sub_partner_id: "111" }, token)
+np.write_off({ currency: "trx", amount: 0.3, sub_partner_id: "111" }, token)
+np.get_transfers({ status: "FINISHED", limit: 10 }, token)
+np.get_transfer(id, token)
+```
+
+### Conversions (JWT required)
+
+```ruby
+np.create_conversion({ amount: 50, from_currency: "usdttrc20", to_currency: "usdterc20" }, token)
+np.get_conversion_status(conversion_id, token)
+np.get_conversions({ status: "FINISHED", limit: 10 }, token)
+```
+
+### IPN / Webhooks
+
+```ruby
+np = NowPayments::Client.new(api_key: "...", ipn_secret: "SECRET")
+
+# In webhook handler (Sinatra/Rails)
+if np.verify_ipn(request.body.read, request.env["HTTP_X_NOWPAYMENTS_SIG"])
+  payload = JSON.parse(request.body.read)
+  # Process payment
+end
+
+# Standalone
+NowPayments.verify_ipn_signature(payload, signature, ipn_secret)
+NowPayments.create_ipn_signature(payload, ipn_secret)  # For testing
+NowPayments::IPN.verify_signature(payload, signature, ipn_secret)
+NowPayments::IPN.create_signature(payload, ipn_secret)
+```
+
+### Helper functions
+
+```ruby
+NowPayments::Helpers.payment_complete?(payment["payment_status"])
+NowPayments::Helpers.payment_pending?(payment["payment_status"])
+NowPayments::Helpers.status_label(payment["payment_status"])
+NowPayments::Helpers.payment_summary(payment)
+
+# Constants
+NowPayments::PAYMENT_STATUSES
+NowPayments::PAYMENT_DONE_STATUSES
+NowPayments::PAYMENT_PENDING_STATUSES
+NowPayments::PAYMENT_STATUS_LABELS
+```
+
+### Error handling
+
+```ruby
+begin
+  np.create_payment(...)
+rescue NowPayments::NowPaymentsError => e
+  puts e.message
+  puts e.status_code
+  puts e.code
+  puts e.response
+  puts e.to_s
+end
+```
+
+---
+
+## 🔗 Links
+
+| Link | URL |
+|------|-----|
+| **API Docs** | [Postman](https://documenter.getpostman.com/view/7907941/2s93JusNJt) |
+| **Sandbox** | [Postman Sandbox](https://documenter.getpostman.com/view/7907941/T1LSCRHC) |
+| **Help** | [nowpayments.io/help](https://nowpayments.io/help/payments/api) |
+| **Dashboard** | [account.nowpayments.io](https://account.nowpayments.io) |
+
+---
+
+## 📄 License
+
+MIT © [Foisalislambd](https://github.com/Foisalislambd)

data/lib/nowpayments/client.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require_relative 'http'
+require_relative 'ipn'
+require_relative 'constants'
+
+module NowPayments
+  # Main client for NOWPayments API
+  # @see https://documenter.getpostman.com/view/7907941/2s93JusNJt
+  class Client
+    def initialize(api_key:, sandbox: false, base_url: nil, timeout: 30_000, ipn_secret: nil)
+      raise ArgumentError, 'NOWPayments API key is required. Get yours at https://account.nowpayments.io' if api_key.to_s.strip.empty?
+
+      @config = {
+        api_key: api_key.to_s.strip,
+        sandbox: sandbox,
+        base_url: base_url,
+        timeout: (timeout || 30_000) / 1000.0, # Faraday uses seconds
+        ipn_secret: ipn_secret
+      }
+      @http = Http.new(@config)
+    end
+
+    # --- Status & Auth ---
+
+    def get_status
+      @http.get('/v1/status')
+    end
+
+    def get_auth_token(email, password)
+      @http.post('/v1/auth', { email: email, password: password })
+    end
+
+    # --- Currencies ---
+
+    def get_currencies(fixed_rate = nil)
+      params = fixed_rate.nil? ? {} : { fixed_rate: fixed_rate }
+      @http.get('/v1/currencies', params)
+    end
+
+    def get_full_currencies
+      @http.get('/v1/full-currencies')
+    end
+
+    def get_merchant_coins(fixed_rate = nil)
+      params = fixed_rate.nil? ? {} : { fixed_rate: fixed_rate }
+      @http.get('/v1/merchant/coins', params)
+    end
+
+    def get_currency(currency)
+      code = currency.to_s.strip
+      raise ArgumentError, 'Currency code is required (e.g. "btc", "eth")' if code.empty?
+
+      @http.get("/v1/currencies/#{code}")
+    end
+
+    # --- Estimate & Min Amount ---
+
+    def get_estimate_price(amount:, currency_from:, currency_to:)
+      @http.get('/v1/estimate', {
+        amount: amount,
+        currency_from: currency_from,
+        currency_to: currency_to
+      })
+    end
+
+    def get_min_amount(currency_from:, currency_to:, fiat_equivalent: nil, is_fixed_rate: nil, is_fee_paid_by_user: nil)
+      params = { currency_from: currency_from, currency_to: currency_to }
+      params[:fiat_equivalent] = fiat_equivalent unless fiat_equivalent.nil?
+      params[:is_fixed_rate] = is_fixed_rate unless is_fixed_rate.nil?
+      params[:is_fee_paid_by_user] = is_fee_paid_by_user unless is_fee_paid_by_user.nil?
+      @http.get('/v1/min-amount', params)
+    end
+
+    # --- Payments ---
+
+    def create_payment(params)
+      body = params.dup
+      # Alias fixed_rate → is_fixed_rate (Node.js compatibility, supports both symbol and string keys)
+      fixed_val = body[:fixed_rate] || body["fixed_rate"]
+      has_is_fixed = body.key?(:is_fixed_rate) || body.key?("is_fixed_rate")
+      if !fixed_val.nil? && !has_is_fixed
+        body[:is_fixed_rate] = fixed_val
+        body.delete(:fixed_rate)
+        body.delete("fixed_rate")
+      end
+      @http.post('/v1/payment', body)
+    end
+
+    def get_payment_status(payment_id)
+      raise ArgumentError, 'Payment ID is required' if payment_id.nil? || payment_id.to_s.strip.empty?
+
+      @http.get("/v1/payment/#{payment_id}")
+    end
+
+    def get_payments(params = {})
+      @http.get('/v1/payment/', params)
+    end
+
+    def update_payment_estimate(payment_id)
+      @http.post("/v1/payment/#{payment_id}/update-merchant-estimate", {})
+    end
+
+    # --- Invoices ---
+
+    def create_invoice(params)
+      @http.post('/v1/invoice', params)
+    end
+
+    def create_invoice_payment(params)
+      @http.post('/v1/invoice-payment', params)
+    end
+
+    # --- Payouts ---
+
+    def validate_payout_address(params)
+      @http.post('/v1/payout/validate-address', params)
+    end
+
+    def create_payout(params, jwt_token)
+      raise ArgumentError, 'JWT token is required for create_payout. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post('/v1/payout', params, jwt_token)
+    end
+
+    def verify_payout(payout_id, verification_code, jwt_token)
+      raise ArgumentError, 'JWT token is required for verify_payout. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post("/v1/payout/#{payout_id}/verify", { verification_code: verification_code }, jwt_token)
+    end
+
+    def cancel_payout(payout_id, jwt_token)
+      raise ArgumentError, 'JWT token is required for cancel_payout. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post("/v1/payout/#{payout_id}/cancel", { payout_id: payout_id }, jwt_token)
+    end
+
+    def get_payout_status(payout_id, jwt_token = nil)
+      @http.get("/v1/payout/#{payout_id}", {}, jwt_token)
+    end
+
+    def get_payouts(params = {})
+      @http.get('/v1/payout', params)
+    end
+
+    # --- Fiat Payouts ---
+
+    def get_fiat_payouts_crypto_currencies(params = {}, jwt_token = nil)
+      @http.get('/v1/fiat-payouts/crypto-currencies', params, jwt_token)
+    end
+
+    def get_fiat_payouts_payment_methods(params = {}, jwt_token = nil)
+      @http.get('/v1/fiat-payouts/payment-methods', params, jwt_token)
+    end
+
+    def get_fiat_payouts(params = {}, jwt_token = nil)
+      @http.get('/v1/fiat-payouts', params, jwt_token)
+    end
+
+    # --- Balance ---
+
+    def get_balance(jwt_token = nil)
+      @http.get('/v1/balance', {}, jwt_token)
+    end
+
+    # --- Subscriptions ---
+
+    def get_subscriptions(params = {})
+      @http.get('/v1/subscriptions', params)
+    end
+
+    def get_subscription(id)
+      @http.get("/v1/subscriptions/#{id}")
+    end
+
+    def delete_subscription(id, jwt_token = nil)
+      @http.delete("/v1/subscriptions/#{id}", jwt_token)
+    end
+
+    def get_subscription_plans(params = {})
+      @http.get('/v1/subscriptions/plans', params)
+    end
+
+    def get_subscription_plan(id)
+      @http.get("/v1/subscriptions/plans/#{id}")
+    end
+
+    def update_subscription_plan(id, updates)
+      @http.patch("/v1/subscriptions/plans/#{id}", updates)
+    end
+
+    def create_subscription(params, jwt_token)
+      raise ArgumentError, 'JWT token is required for create_subscription. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post('/v1/subscriptions', params, jwt_token)
+    end
+
+    # --- Sub-Partners / Custody ---
+
+    def create_sub_partner(name, jwt_token)
+      raise ArgumentError, 'JWT token is required for create_sub_partner. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post('/v1/sub-partner/balance', { name: name }, jwt_token)
+    end
+
+    def create_sub_partner_payment(params, jwt_token)
+      raise ArgumentError, 'JWT token is required for create_sub_partner_payment. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post('/v1/sub-partner/payment', params, jwt_token)
+    end
+
+    def get_sub_partners(params = {}, jwt_token = nil)
+      @http.get('/v1/sub-partner', params, jwt_token)
+    end
+
+    def get_sub_partner_balance(sub_partner_id)
+      @http.get("/v1/sub-partner/balance/#{sub_partner_id}")
+    end
+
+    def get_transfers(params = {}, jwt_token = nil)
+      @http.get('/v1/sub-partner/transfers', params, jwt_token)
+    end
+
+    def get_transfer(id, jwt_token = nil)
+      @http.get("/v1/sub-partner/transfer/#{id}", {}, jwt_token)
+    end
+
+    def create_transfer(params, jwt_token)
+      raise ArgumentError, 'JWT token is required for create_transfer. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post('/v1/sub-partner/transfer', params, jwt_token)
+    end
+
+    def deposit(params, jwt_token)
+      raise ArgumentError, 'JWT token is required for deposit. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post('/v1/sub-partner/deposit', params, jwt_token)
+    end
+
+    def write_off(params, jwt_token = nil)
+      @http.post('/v1/sub-partner/write-off', params, jwt_token)
+    end
+
+    # --- Conversions ---
+
+    def create_conversion(params, jwt_token)
+      raise ArgumentError, 'JWT token is required for create_conversion. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.post('/v1/conversion', params, jwt_token)
+    end
+
+    def get_conversion_status(conversion_id, jwt_token)
+      raise ArgumentError, 'JWT token is required for get_conversion_status. Call get_auth_token first.' if jwt_token.to_s.strip.empty?
+
+      @http.get("/v1/conversion/#{conversion_id}", {}, jwt_token)
+    end
+
+    def get_conversions(params = {}, jwt_token = nil)
+      @http.get('/v1/conversion', params, jwt_token)
+    end
+
+    # --- IPN ---
+
+    def verify_ipn(payload, signature)
+      secret = @config[:ipn_secret]
+      raise ArgumentError, 'IPN secret not configured. Pass ipn_secret in constructor or use verify_ipn_signature with explicit secret.' if secret.to_s.strip.empty?
+
+      IPN.verify_signature(payload, signature, secret)
+    end
+  end
+end

data/lib/nowpayments/constants.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module NowPayments
+  PRODUCTION_URL = "https://api.nowpayments.io"
+  SANDBOX_URL = "https://api-sandbox.nowpayments.io"
+
+  PAYMENT_STATUSES = %w[
+    waiting confirming confirmed spending sending
+    partially_paid finished failed refunded expired
+  ].freeze
+
+  PAYMENT_DONE_STATUSES = %w[finished failed refunded expired].freeze
+  PAYMENT_PENDING_STATUSES = %w[waiting confirming confirmed spending sending partially_paid].freeze
+
+  PAYMENT_STATUS_LABELS = {
+    "waiting" => "Awaiting payment",
+    "confirming" => "Confirming",
+    "confirmed" => "Confirmed",
+    "spending" => "Processing",
+    "sending" => "Sending to wallet",
+    "partially_paid" => "Partially paid",
+    "finished" => "Completed",
+    "failed" => "Failed",
+    "refunded" => "Refunded",
+    "expired" => "Expired"
+  }.freeze
+end

data/lib/nowpayments/error.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module NowPayments
+  class NowPaymentsError < StandardError
+    attr_reader :status_code, :code, :response
+
+    def initialize(message, status_code = nil, code = nil, response = nil)
+      super(message)
+      @status_code = status_code
+      @code = code
+      @response = response
+    end
+
+    def to_s
+      parts = [message]
+      parts << "(status: #{status_code})" if status_code
+      parts << "[#{code}]" if code
+      parts.join(" ")
+    end
+  end
+end

data/lib/nowpayments/helpers.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module NowPayments
+  # Human-friendly helpers for payment status and display
+  module Helpers
+    # Check if payment is complete (success or terminal state)
+    #
+    # @param status [String] Payment status
+    # @return [Boolean]
+    def self.payment_complete?(status)
+      PAYMENT_DONE_STATUSES.include?(status.to_s)
+    end
+
+    # Check if payment is still pending (customer should pay)
+    #
+    # @param status [String] Payment status
+    # @return [Boolean]
+    def self.payment_pending?(status)
+      PAYMENT_PENDING_STATUSES.include?(status.to_s)
+    end
+
+    # Get human-readable status label
+    #
+    # @param status [String] Payment status
+    # @return [String]
+    def self.status_label(status)
+      PAYMENT_STATUS_LABELS[status.to_s] || status.to_s
+    end
+
+    # Build a short summary for displaying to users
+    # e.g. "Awaiting payment: 0.001234 BTC → bc1q..."
+    #
+    # @param payment [Hash] Payment object with pay_amount, pay_currency, pay_address, payment_status
+    # @return [String]
+    def self.payment_summary(payment)
+      pay_amount = payment["pay_amount"] || payment[:pay_amount]
+      pay_currency = (payment["pay_currency"] || payment[:pay_currency] || "").to_s.upcase
+      pay_address = payment["pay_address"] || payment[:pay_address] || "…"
+      payment_status = payment["payment_status"] || payment[:payment_status]
+      label = PAYMENT_STATUS_LABELS[payment_status.to_s] || payment_status.to_s
+      "#{label}: #{pay_amount} #{pay_currency} → #{pay_address}"
+    end
+  end
+end

data/lib/nowpayments/http.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/json"
+
+module NowPayments
+  class Http
+    def initialize(config)
+      @config = config
+      @conn = build_connection
+    end
+
+    def get(path, params = {}, jwt_token = nil)
+      response = @conn.get(path) do |req|
+        req.params = params unless params.empty?
+        req.headers["Authorization"] = "Bearer #{jwt_token}" if jwt_token.to_s.strip != ""
+      end
+      handle_response(response)
+    rescue Faraday::Error => e
+      raise NowPaymentsError.new(
+        e.is_a?(Faraday::TimeoutError) ? "Request timed out. Check your connection or try again." : (e.message || "Network error. Check your connection."),
+        nil, e.class.name, e
+      )
+    end
+
+    def post(path, body = nil, jwt_token = nil)
+      response = @conn.post(path) do |req|
+        req.body = body.nil? ? {} : body
+        req.headers["Authorization"] = "Bearer #{jwt_token}" if jwt_token.to_s.strip != ""
+      end
+      handle_response(response)
+    rescue Faraday::Error => e
+      raise NowPaymentsError.new(
+        e.is_a?(Faraday::TimeoutError) ? "Request timed out. Check your connection or try again." : (e.message || "Network error. Check your connection."),
+        nil, e.class.name, e
+      )
+    end
+
+    def patch(path, body, jwt_token = nil)
+      response = @conn.patch(path) do |req|
+        req.body = body
+        req.headers["Authorization"] = "Bearer #{jwt_token}" if jwt_token.to_s.strip != ""
+      end
+      handle_response(response)
+    rescue Faraday::Error => e
+      raise NowPaymentsError.new(
+        e.is_a?(Faraday::TimeoutError) ? "Request timed out. Check your connection or try again." : (e.message || "Network error. Check your connection."),
+        nil, e.class.name, e
+      )
+    end
+
+    def delete(path, jwt_token = nil)
+      response = @conn.delete(path) do |req|
+        req.headers["Authorization"] = "Bearer #{jwt_token}" if jwt_token.to_s.strip != ""
+      end
+      handle_response(response)
+    rescue Faraday::Error => e
+      raise NowPaymentsError.new(
+        e.is_a?(Faraday::TimeoutError) ? "Request timed out. Check your connection or try again." : (e.message || "Network error. Check your connection."),
+        nil, e.class.name, e
+      )
+    end
+
+    private
+
+    def build_connection
+      base_url = @config[:base_url] || (@config[:sandbox] ? SANDBOX_URL : PRODUCTION_URL)
+      timeout = @config[:timeout] || 30.0
+
+      Faraday.new(url: base_url) do |f|
+        f.request :json
+        f.response :json, content_type: /\bjson$/
+        f.options.timeout = timeout
+        f.headers["Content-Type"] = "application/json"
+        f.headers["x-api-key"] = @config[:api_key]
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def handle_response(response)
+      return response.body if response.success?
+
+      data = response.body
+      message = data.is_a?(Hash) ? (data["message"] || data["msg"] || data["error"]) : nil
+      message ||= response.reason_phrase || "Request failed"
+      raise NowPaymentsError.new(
+        message,
+        response.status,
+        data.is_a?(Hash) ? data["code"] : nil,
+        data
+      )
+    end
+  end
+end

data/lib/nowpayments/ipn.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module NowPayments
+  # IPN (Instant Payment Notification) verification utilities
+  # Matches official docs: sort keys recursively, then HMAC-SHA512
+  # @see https://nowpayments.io/help/payments/api
+  module IPN
+    # Recursively sort object keys (matches NOWPayments IPN spec).
+    # Normalizes to string keys for consistent JSON output (matches Node.js JSON.parse behavior).
+    def self.sort_object(obj)
+      return obj unless obj.is_a?(Hash)
+
+      normalized = obj.transform_keys(&:to_s)
+      normalized.keys.sort.each_with_object({}) do |key, result|
+        val = normalized[key]
+        result[key] = val.is_a?(Hash) && !val.is_a?(Array) ? sort_object(val) : val
+        result
+      end
+    end
+
+    # Verify IPN callback signature from NOWPayments.
+    # Safe to call – handles invalid input gracefully.
+    #
+    # @param payload [String, Hash] Raw request body (string or parsed object)
+    # @param signature [String] Value from x-nowpayments-sig header
+    # @param ipn_secret [String] Your IPN Secret from Dashboard → Store Settings
+    # @return [Boolean] true if signature is valid, false otherwise
+    def self.verify_signature(payload, signature, ipn_secret)
+      return false if signature.nil? || signature.to_s.strip.empty?
+      return false if ipn_secret.nil? || ipn_secret.to_s.strip.empty?
+
+      obj = case payload
+            when String
+              JSON.parse(payload)
+            when Hash
+              payload
+            else
+              return false
+            end
+
+      json_string = JSON.generate(sort_object(obj))
+      computed_sig = OpenSSL::HMAC.hexdigest('SHA512', ipn_secret.strip, json_string)
+
+      sig_bytes = [signature].pack('H*')
+      computed_bytes = [computed_sig].pack('H*')
+      return false if sig_bytes.bytesize != computed_bytes.bytesize
+
+      OpenSSL::fixed_length_secure_compare(sig_bytes, computed_bytes)
+    rescue JSON::ParserError, ArgumentError
+      false
+    end
+
+    # Create IPN signature for testing (e.g., mocking callbacks)
+    #
+    # @param payload [Hash] Payload to sign
+    # @param ipn_secret [String] IPN secret
+    # @return [String] Hex-encoded HMAC-SHA512 signature
+    def self.create_signature(payload, ipn_secret)
+      json_string = JSON.generate(sort_object(payload))
+      OpenSSL::HMAC.hexdigest('SHA512', ipn_secret.strip, json_string)
+    end
+  end
+end

data/lib/nowpayments/version.rb

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

data/lib/nowpayments.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "nowpayments/version"
+require "nowpayments/constants"
+require "nowpayments/error"
+require "nowpayments/http"
+require "nowpayments/ipn"
+require "nowpayments/helpers"
+require "nowpayments/client"
+
+module NowPayments
+  class Error < StandardError; end
+
+  # Convenience aliases (Node.js style)
+  def self.verify_ipn_signature(payload, signature, ipn_secret)
+    IPN.verify_signature(payload, signature, ipn_secret)
+  end
+
+  def self.create_ipn_signature(payload, ipn_secret)
+    IPN.create_signature(payload, ipn_secret)
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: nowpayments-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Foisalislambd
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+description: Accept 300+ cryptocurrencies with auto-conversion. Payments, invoices,
+  payouts, subscriptions, custody, IPN webhooks.
+email:
+- ''
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/nowpayments.rb
+- lib/nowpayments/client.rb
+- lib/nowpayments/constants.rb
+- lib/nowpayments/error.rb
+- lib/nowpayments/helpers.rb
+- lib/nowpayments/http.rb
+- lib/nowpayments/ipn.rb
+- lib/nowpayments/version.rb
+homepage: https://github.com/Foisalislambd/nowpayments-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Foisalislambd/nowpayments-ruby
+  source_code_uri: https://github.com/Foisalislambd/nowpayments-ruby
+  changelog_uri: https://github.com/Foisalislambd/nowpayments-ruby/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Full-featured Ruby SDK for NOWPayments cryptocurrency payment API
+test_files: []