nowpayments 0.2.0

data/lib/nowpayments/api/estimation.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Estimation and calculation endpoints
+    module Estimation
+      # Get minimum payment amount for currency pair
+      # GET /v1/min-amount
+      # @param currency_from [String] Source currency code
+      # @param currency_to [String] Target currency code
+      # @return [Hash] Minimum amount info
+      def min_amount(currency_from:, currency_to:)
+        get("min-amount", params: {
+              currency_from: currency_from,
+              currency_to: currency_to
+            }).body
+      end
+
+      # Estimate price for currency pair
+      # GET /v1/estimate
+      # @param amount [Numeric] Amount to estimate
+      # @param currency_from [String] Source currency
+      # @param currency_to [String] Target currency
+      # @return [Hash] Price estimate
+      def estimate(amount:, currency_from:, currency_to:)
+        get("estimate", params: {
+              amount: amount,
+              currency_from: currency_from,
+              currency_to: currency_to
+            }).body
+      end
+    end
+  end
+end

data/lib/nowpayments/api/fiat_payouts.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Fiat Payouts API endpoints (Beta)
+    # All endpoints require JWT authentication
+    # Note: This is a Beta feature with limited availability
+    module FiatPayouts
+      # Get available fiat payment methods
+      # GET /v1/fiat-payouts/payment-methods
+      # @param fiat_currency [String, nil] Optional filter by fiat currency (e.g., "EUR", "USD")
+      # @return [Hash] Available payment methods
+      def fiat_payout_payment_methods(fiat_currency: nil)
+        params = {}
+        params[:fiatCurrency] = fiat_currency if fiat_currency
+        get("fiat-payouts/payment-methods", params: params).body
+      end
+
+      # Create a fiat payout account
+      # POST /v1/fiat-payouts/account
+      # @param provider [String] Payment provider (e.g., "transfi")
+      # @param fiat_currency [String] Fiat currency code (e.g., "EUR", "USD")
+      # @param account_data [Hash] Provider-specific account data
+      # @return [Hash] Created account details
+      def create_fiat_payout_account(provider:, fiat_currency:, account_data:)
+        params = {
+          provider: provider,
+          fiatCurrency: fiat_currency,
+          accountData: account_data
+        }
+        post("fiat-payouts/account", body: params).body
+      end
+
+      # Get list of fiat payout accounts
+      # GET /v1/fiat-payouts/account
+      # @param provider [String, nil] Optional filter by provider
+      # @param fiat_currency [String, nil] Optional filter by fiat currency
+      # @param limit [Integer] Number of results per page (default: 10)
+      # @param page [Integer] Page number (default: 0)
+      # @return [Hash] List of payout accounts
+      def fiat_payout_accounts(provider: nil, fiat_currency: nil, limit: 10, page: 0)
+        params = { limit: limit, page: page }
+        params[:provider] = provider if provider
+        params[:fiatCurrency] = fiat_currency if fiat_currency
+        get("fiat-payouts/account", params: params).body
+      end
+
+      # Update a fiat payout account
+      # PATCH /v1/fiat-payouts/account/:account_id
+      # @param account_id [String, Integer] Account ID
+      # @param account_data [Hash] Updated account data
+      # @return [Hash] Updated account details
+      def update_fiat_payout_account(account_id:, account_data:)
+        params = { accountData: account_data }
+        patch("fiat-payouts/account/#{account_id}", body: params).body
+      end
+
+      # Create a fiat payout
+      # POST /v1/fiat-payouts
+      # @param account_id [String, Integer] Payout account ID
+      # @param crypto_currency [String] Cryptocurrency code (e.g., "btc", "eth")
+      # @param crypto_amount [Numeric] Amount in cryptocurrency
+      # @param request_id [String, nil] Optional unique request ID
+      # @return [Hash] Created payout details
+      def create_fiat_payout(account_id:, crypto_currency:, crypto_amount:, request_id: nil)
+        params = {
+          accountId: account_id,
+          cryptoCurrency: crypto_currency,
+          cryptoAmount: crypto_amount
+        }
+        params[:requestId] = request_id if request_id
+        post("fiat-payouts", body: params).body
+      end
+
+      # Get fiat payout status
+      # GET /v1/fiat-payouts/:payout_id
+      # @param payout_id [String, Integer] Payout ID
+      # @return [Hash] Payout details and status
+      def fiat_payout_status(payout_id)
+        get("fiat-payouts/#{payout_id}").body
+      end
+
+      # Get list of fiat payouts
+      # GET /v1/fiat-payouts
+      # @param id [String, Integer, nil] Optional filter by payout ID
+      # @param provider [String, nil] Optional filter by provider
+      # @param request_id [String, nil] Optional filter by request ID
+      # @param fiat_currency [String, nil] Optional filter by fiat currency
+      # @param crypto_currency [String, nil] Optional filter by crypto currency
+      # @param status [String, nil] Optional filter by status (e.g., "FINISHED", "PENDING")
+      # @param filter [String, nil] Optional text filter
+      # @param provider_payout_id [String, nil] Optional filter by provider's payout ID
+      # @param limit [Integer] Number of results per page (default: 10)
+      # @param page [Integer] Page number (default: 0)
+      # @param order_by [String, nil] Optional field to order by
+      # @param sort_by [String, nil] Optional sort direction ("asc" or "desc")
+      # @param date_from [String, nil] Optional start date (ISO 8601)
+      # @param date_to [String, nil] Optional end date (ISO 8601)
+      # @return [Hash] List of payouts
+      def fiat_payouts(
+        id: nil,
+        provider: nil,
+        request_id: nil,
+        fiat_currency: nil,
+        crypto_currency: nil,
+        status: nil,
+        filter: nil,
+        provider_payout_id: nil,
+        limit: 10,
+        page: 0,
+        order_by: nil,
+        sort_by: nil,
+        date_from: nil,
+        date_to: nil
+      )
+        params = { limit: limit, page: page }
+        params[:id] = id if id
+        params[:provider] = provider if provider
+        params[:requestId] = request_id if request_id
+        params[:fiatCurrency] = fiat_currency if fiat_currency
+        params[:cryptoCurrency] = crypto_currency if crypto_currency
+        params[:status] = status if status
+        params[:filter] = filter if filter
+        params[:provider_payout_id] = provider_payout_id if provider_payout_id
+        params[:orderBy] = order_by if order_by
+        params[:sortBy] = sort_by if sort_by
+        params[:dateFrom] = date_from if date_from
+        params[:dateTo] = date_to if date_to
+        get("fiat-payouts", params: params).body
+      end
+
+      # Get fiat conversion rates
+      # POST /v1/fiat-payouts/rates
+      # @param crypto_currency [String] Cryptocurrency code (e.g., "btc", "eth")
+      # @param fiat_currency [String] Fiat currency code (e.g., "EUR", "USD")
+      # @param crypto_amount [Numeric, nil] Optional crypto amount to convert
+      # @param fiat_amount [Numeric, nil] Optional fiat amount to convert
+      # @return [Hash] Conversion rates and amounts
+      def fiat_payout_rates(crypto_currency:, fiat_currency:, crypto_amount: nil, fiat_amount: nil)
+        params = {
+          cryptoCurrency: crypto_currency,
+          fiatCurrency: fiat_currency
+        }
+        params[:cryptoAmount] = crypto_amount if crypto_amount
+        params[:fiatAmount] = fiat_amount if fiat_amount
+        post("fiat-payouts/rates", body: params).body
+      end
+    end
+  end
+end

data/lib/nowpayments/api/invoices.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Invoice-related endpoints
+    module Invoices
+      # Create an invoice (hosted payment page)
+      # POST /v1/invoice
+      # @param price_amount [Numeric] Fiat amount
+      # @param price_currency [String] Fiat currency
+      # @param pay_currency [String, nil] Optional crypto (if nil, customer chooses)
+      # @param order_id [String, nil] Optional merchant order ID
+      # @param order_description [String, nil] Optional description
+      # @param ipn_callback_url [String, nil] Optional webhook URL
+      # @param success_url [String, nil] Optional redirect after success
+      # @param cancel_url [String, nil] Optional redirect after cancel
+      # @return [Hash] Invoice with invoice_url
+      def create_invoice(
+        price_amount:,
+        price_currency:,
+        pay_currency: nil,
+        order_id: nil,
+        order_description: nil,
+        ipn_callback_url: nil,
+        success_url: nil,
+        cancel_url: nil
+      )
+        params = {
+          price_amount: price_amount,
+          price_currency: price_currency
+        }
+
+        params[:pay_currency] = pay_currency if pay_currency
+        params[:order_id] = order_id if order_id
+        params[:order_description] = order_description if order_description
+        params[:ipn_callback_url] = ipn_callback_url if ipn_callback_url
+        params[:success_url] = success_url if success_url
+        params[:cancel_url] = cancel_url if cancel_url
+
+        post("invoice", body: params).body
+      end
+
+      # Create payment by invoice
+      # POST /v1/invoice-payment
+      # @param iid [Integer, String] Invoice ID
+      # @param pay_currency [String] Crypto currency
+      # @param purchase_id [String, Integer, nil] Optional purchase ID
+      # @param order_description [String, nil] Optional description
+      # @param customer_email [String, nil] Optional customer email
+      # @param payout_address [String, nil] Optional custom payout address
+      # @param payout_extra_id [String, nil] Optional extra ID for payout
+      # @param payout_currency [String, nil] Required if payout_address set
+      # @return [Hash] Payment details
+      def create_invoice_payment(
+        iid:,
+        pay_currency:,
+        purchase_id: nil,
+        order_description: nil,
+        customer_email: nil,
+        payout_address: nil,
+        payout_extra_id: nil,
+        payout_currency: nil
+      )
+        params = {
+          iid: iid,
+          pay_currency: pay_currency
+        }
+
+        params[:purchase_id] = purchase_id if purchase_id
+        params[:order_description] = order_description if order_description
+        params[:customer_email] = customer_email if customer_email
+        params[:payout_address] = payout_address if payout_address
+        params[:payout_extra_id] = payout_extra_id if payout_extra_id
+        params[:payout_currency] = payout_currency if payout_currency
+
+        post("invoice-payment", body: params).body
+      end
+
+      # Get invoice details and status
+      # GET /v1/invoice/:invoice_id
+      # @param invoice_id [String, Integer] Invoice ID
+      # @return [Hash] Invoice details with payment status
+      def invoice(invoice_id)
+        get("invoice/#{invoice_id}").body
+      end
+    end
+  end
+end

data/lib/nowpayments/api/payments.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Payment-related endpoints
+    module Payments
+      # Create a new payment
+      # POST /v1/payment
+      # @param price_amount [Numeric] Fiat amount
+      # @param price_currency [String] Fiat currency
+      # @param pay_currency [String] Crypto currency customer pays with
+      # @param pay_amount [Numeric, nil] Optional crypto amount (alternative to price_amount)
+      # @param order_id [String, nil] Optional merchant order ID
+      # @param order_description [String, nil] Optional description
+      # @param ipn_callback_url [String, nil] Optional webhook URL
+      # @param payout_address [String, nil] Optional custom payout address
+      # @param payout_currency [String, nil] Required if payout_address set
+      # @param payout_extra_id [String, nil] Optional extra ID for payout
+      # @param is_fixed_rate [Boolean, nil] Fixed rate flag
+      # @param is_fee_paid_by_user [Boolean, nil] Whether user pays network fees
+      # @return [Hash] Payment details
+      def create_payment(
+        price_amount:,
+        price_currency:,
+        pay_currency:,
+        pay_amount: nil,
+        order_id: nil,
+        order_description: nil,
+        ipn_callback_url: nil,
+        payout_address: nil,
+        payout_currency: nil,
+        payout_extra_id: nil,
+        is_fixed_rate: nil,
+        is_fee_paid_by_user: nil
+      )
+        params = {
+          price_amount: price_amount,
+          price_currency: price_currency,
+          pay_currency: pay_currency
+        }
+
+        params[:pay_amount] = pay_amount if pay_amount
+        params[:order_id] = order_id if order_id
+        params[:order_description] = order_description if order_description
+        params[:ipn_callback_url] = ipn_callback_url if ipn_callback_url
+        params[:payout_address] = payout_address if payout_address
+        params[:payout_currency] = payout_currency if payout_currency
+        params[:payout_extra_id] = payout_extra_id if payout_extra_id
+        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?
+
+        validate_payment_params!(params)
+
+        post("payment", body: params).body
+      end
+
+      # Get payment status
+      # GET /v1/payment/:payment_id
+      # @param payment_id [Integer, String] Payment ID
+      # @return [Hash] Payment status
+      def payment(payment_id)
+        get("payment/#{payment_id}").body
+      end
+
+      # List payments with pagination and filters
+      # GET /v1/payment
+      # @param limit [Integer] Results per page
+      # @param page [Integer] Page number
+      # @param sort_by [String, nil] Sort field
+      # @param order_by [String, nil] Order direction (asc/desc)
+      # @param date_from [String, nil] Start date filter
+      # @param date_to [String, nil] End date filter
+      # @return [Hash] List of payments
+      def payments(limit: 10, page: 0, sort_by: nil, order_by: nil, date_from: nil, date_to: nil)
+        params = { limit: limit, page: page }
+        params[:sortBy] = sort_by if sort_by
+        params[:orderBy] = order_by if order_by
+        params[:dateFrom] = date_from if date_from
+        params[:dateTo] = date_to if date_to
+
+        get("payment", params: params).body
+      end
+
+      # Update payment estimate
+      # PATCH /v1/payment/:payment_id
+      # @param payment_id [Integer, String] Payment ID
+      # @return [Hash] Updated payment
+      def update_payment_estimate(payment_id)
+        patch("payment/#{payment_id}").body
+      end
+    end
+  end
+end

data/lib/nowpayments/api/payouts.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Payout and mass payout endpoints (requires JWT auth)
+    module Payouts
+      # Get account balance
+      # GET /v1/balance
+      # @return [Hash] Balance information with available and pending amounts per currency
+      def balance
+        get("balance").body
+      end
+
+      # Validate payout address
+      # POST /v1/payout/validate-address
+      # @param address [String] Payout address to validate
+      # @param currency [String] Currency code
+      # @param extra_id [String, nil] Optional memo/tag/destination tag
+      # @return [Hash] Validation result
+      def validate_payout_address(address:, currency:, extra_id: nil)
+        params = {
+          address: address,
+          currency: currency
+        }
+        params[:extra_id] = extra_id if extra_id
+
+        post("payout/validate-address", body: params).body
+      end
+
+      # Create payout
+      # POST /v1/payout
+      # Note: This endpoint requires JWT authentication
+      # @param withdrawals [Array<Hash>] Array of withdrawal objects
+      #   Each withdrawal should have:
+      #   - address (String, required): Crypto address
+      #   - currency (String, required): Currency code
+      #   - amount (Numeric, required): Amount to send
+      #   - ipn_callback_url (String, optional): Individual callback URL
+      #   - extra_id (String, optional): Payment extra ID (memo/tag)
+      #   - fiat_amount (Numeric, optional): Fiat equivalent amount
+      #   - fiat_currency (String, optional): Fiat currency code
+      #   - unique_external_id (String, optional): External reference ID
+      #   - payout_description (String, optional): Individual description
+      # @param payout_description [String, nil] Description for entire batch
+      # @param ipn_callback_url [String, nil] Callback URL for entire batch
+      # @return [Hash] Payout result
+      def create_payout(withdrawals:, payout_description: nil, ipn_callback_url: nil)
+        params = { withdrawals: withdrawals }
+        params[:payout_description] = payout_description if payout_description
+        params[:ipn_callback_url] = ipn_callback_url if ipn_callback_url
+
+        post("payout", body: params).body
+      end
+
+      # Verify payout with 2FA code
+      # POST /v1/payout/:batch_withdrawal_id/verify
+      # @param batch_withdrawal_id [String, Integer] Batch withdrawal ID from create_payout
+      # @param verification_code [String] 2FA code from Google Auth app or email
+      # @return [Hash] Verification result
+      def verify_payout(batch_withdrawal_id:, verification_code:)
+        post("payout/#{batch_withdrawal_id}/verify", body: {
+               verification_code: verification_code
+             }).body
+      end
+
+      # Get payout status
+      # GET /v1/payout/:payout_id
+      # @param payout_id [String, Integer] Payout ID
+      # @return [Hash] Payout status and details
+      def payout_status(payout_id)
+        get("payout/#{payout_id}").body
+      end
+
+      # List payouts with pagination
+      # GET /v1/payout
+      # @param limit [Integer] Results per page
+      # @param offset [Integer] Offset for pagination
+      # @return [Hash] List of payouts
+      def list_payouts(limit: 10, offset: 0)
+        get("payout", params: {
+              limit: limit,
+              offset: offset
+            }).body
+      end
+
+      # Get minimum payout amount
+      # GET /v1/payout/min-amount
+      # @param currency [String] Currency code
+      # @return [Hash] Minimum payout amount for currency
+      def min_payout_amount(currency:)
+        get("payout/min-amount", params: { currency: currency }).body
+      end
+
+      # Get payout fee estimate
+      # GET /v1/payout/fee
+      # @param currency [String] Currency code
+      # @param amount [Numeric] Payout amount
+      # @return [Hash] Fee estimate
+      def payout_fee(currency:, amount:)
+        get("payout/fee", params: {
+              currency: currency,
+              amount: amount
+            }).body
+      end
+    end
+  end
+end

data/lib/nowpayments/api/status.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Status and utility endpoints
+    module Status
+      # Check API status
+      # GET /v1/status
+      # @return [Hash] Status response
+      def status
+        get("status").body
+      end
+    end
+  end
+end

data/lib/nowpayments/api/subscriptions.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module NOWPayments
+  module API
+    # Subscription and recurring payment endpoints
+    module Subscriptions
+      # Get subscription plans
+      # GET /v1/subscriptions/plans
+      # @return [Hash] List of subscription plans
+      def subscription_plans
+        get("subscriptions/plans").body
+      end
+
+      # Create subscription plan
+      # POST /v1/subscriptions/plans
+      # @param plan_data [Hash] Plan configuration
+      # @return [Hash] Created plan
+      def create_subscription_plan(plan_data)
+        post("subscriptions/plans", body: plan_data).body
+      end
+
+      # Update subscription plan
+      # PATCH /v1/subscriptions/plans/:plan_id
+      # @param plan_id [String, Integer] Plan ID
+      # @param plan_data [Hash] Updated plan configuration
+      # @return [Hash] Updated plan details
+      def update_subscription_plan(plan_id, plan_data)
+        patch("subscriptions/plans/#{plan_id}", body: plan_data).body
+      end
+
+      # Get specific subscription plan
+      # GET /v1/subscriptions/plans/:plan_id
+      # @param plan_id [String, Integer] Plan ID
+      # @return [Hash] Plan details
+      def subscription_plan(plan_id)
+        get("subscriptions/plans/#{plan_id}").body
+      end
+
+      # Create email subscription
+      # POST /v1/subscriptions
+      # @param plan_id [String] Subscription plan ID
+      # @param email [String] Customer email
+      # @return [Hash] Subscription result
+      def create_subscription(plan_id:, email:)
+        post("subscriptions", body: {
+               plan_id: plan_id,
+               email: email
+             }).body
+      end
+
+      # List recurring payments with filters
+      # GET /v1/subscriptions
+      # @param limit [Integer] Results per page
+      # @param offset [Integer] Offset for pagination
+      # @param status [String, nil] Filter by status (WAITING_PAY, PAID, PARTIALLY_PAID, EXPIRED)
+      # @param subscription_plan_id [String, Integer, nil] Filter by plan ID
+      # @param is_active [Boolean, nil] Filter by active status
+      # @return [Hash] List of recurring payments
+      def list_recurring_payments(limit: 10, offset: 0, status: nil, subscription_plan_id: nil, is_active: nil)
+        params = { limit: limit, offset: offset }
+        params[:status] = status if status
+        params[:subscription_plan_id] = subscription_plan_id if subscription_plan_id
+        params[:is_active] = is_active unless is_active.nil?
+
+        get("subscriptions", params: params).body
+      end
+
+      # Get specific recurring payment
+      # GET /v1/subscriptions/:subscription_id
+      # @param subscription_id [String, Integer] Subscription ID
+      # @return [Hash] Recurring payment details
+      def recurring_payment(subscription_id)
+        get("subscriptions/#{subscription_id}").body
+      end
+
+      # Delete recurring payment
+      # DELETE /v1/subscriptions/:subscription_id
+      # @param subscription_id [String, Integer] Subscription ID
+      # @return [Hash] Deletion result
+      def delete_recurring_payment(subscription_id)
+        delete("subscriptions/#{subscription_id}").body
+      end
+
+      # Get subscription payments
+      # GET /v1/subscriptions/:subscription_id/payments
+      # @param subscription_id [String, Integer] Subscription ID
+      # @return [Hash] Subscription payments
+      def subscription_payments(subscription_id)
+        get("subscriptions/#{subscription_id}/payments").body
+      end
+    end
+  end
+end

data/lib/nowpayments/client.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require_relative "api/status"
+require_relative "api/authentication"
+require_relative "api/currencies"
+require_relative "api/estimation"
+require_relative "api/payments"
+require_relative "api/invoices"
+require_relative "api/payouts"
+require_relative "api/subscriptions"
+require_relative "api/conversions"
+require_relative "api/custody"
+require_relative "api/fiat_payouts"
+
+module NOWPayments
+  # Main client for interacting with the NOWPayments API
+  class Client
+    include API::Status
+    include API::Authentication
+    include API::Currencies
+    include API::Estimation
+    include API::Payments
+    include API::Invoices
+    include API::Payouts
+    include API::Subscriptions
+    include API::Conversions
+    include API::Custody
+    include API::FiatPayouts
+
+    attr_reader :api_key, :ipn_secret, :sandbox
+    attr_accessor :jwt_token, :jwt_expires_at
+
+    BASE_URL = "https://api.nowpayments.io/v1"
+    SANDBOX_URL = "https://api-sandbox.nowpayments.io/v1"
+
+    def initialize(api_key:, ipn_secret: nil, sandbox: false)
+      @api_key = api_key
+      @ipn_secret = ipn_secret
+      @sandbox = sandbox
+      @jwt_token = nil
+      @jwt_expires_at = nil
+    end
+
+    def base_url
+      sandbox ? SANDBOX_URL : BASE_URL
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(url: base_url) do |faraday|
+        faraday.request :json
+        faraday.response :json, content_type: /\bjson$/
+        faraday.adapter Faraday.default_adapter
+        faraday.headers["x-api-key"] = @api_key
+
+        # Add JWT Bearer token if available and not expired
+        faraday.headers["Authorization"] = "Bearer #{@jwt_token}" if @jwt_token && !jwt_expired?
+      end
+    end
+
+    # Reset connection when JWT token changes
+    def reset_connection!
+      @connection = nil
+    end
+
+    def get(path, params: {})
+      connection.get(path, params)
+    end
+
+    def post(path, body: {})
+      connection.post(path, body.to_json)
+    end
+
+    def patch(path, body: {})
+      connection.patch(path, body.to_json)
+    end
+
+    def delete(path, params: {})
+      connection.delete(path, params)
+    end
+
+    def validate_payment_params!(params)
+      return unless params[:payout_address] && !params[:payout_currency]
+
+      raise ValidationError, "payout_currency required when payout_address is set"
+    end
+  end
+end