nowpayments-ruby
nowpayments-ruby
Full-featured Ruby SDK for NOWPayments
Accept 300+ cryptocurrencies with auto-conversion to your wallet
Quick Start • Features • Examples • API • Links
✨ 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
gem install nowpayments-rubyOr add to your Gemfile:
gem "nowpayments-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 |
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:
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
# 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
# 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..."
endExample: List Payments
# 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"]}"
endExample: Create Invoice
# 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
# 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
# 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)
# 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
# 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"]}"
endExample: IPN Webhook
# 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 testingExample: Custody & Balance
# 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)
# 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
np.get_status
auth = np.get_auth_token("your@email.com", "password")
token = auth["token"]Currencies
np.get_currencies
np.get_currencies(true) # fixed rate
np.get_full_currencies
np.get_merchant_coins
np.get_currency("btc")Payments
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
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
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)
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
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
np.get_balance(token)Subscriptions
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)
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)
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
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
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_LABELSError handling
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 |
| Sandbox | Postman Sandbox |
| Help | nowpayments.io/help |
| Dashboard | account.nowpayments.io |
📄 License
MIT © Foisalislambd