nowpayments-py

Full-featured Python SDK for NOWPayments Cryptocurrency Payment API

Python port of nowpayments-node. Accept Bitcoin, Ethereum, USDT, and 300+ cryptocurrencies via NOWPayments.

API Docs: Postman

Table of Contents

• Installation
• Quick Start
• Configuration
• API Reference (All Methods)
• JWT Authentication
• IPN Webhook
• Payment Helpers
• Exports
• Upgrade Guide
• License

Installation

pip install nowpayments-py

From source (editable):

git clone https://github.com/Foisalislambd/nowpayments-py.git
cd nowpayments-py
pip install -e .

Quick Start

from nowpayments import NowPayments

np = NowPayments(api_key="YOUR_API_KEY", sandbox=True)

# Check API status
status = np.get_status()
print(status)

# Create payment
payment = np.create_payment({
    "price_amount": 29.99,
    "price_currency": "usd",
    "pay_currency": "btc",
    "order_id": "order-123",
})
print(f"Pay {payment['pay_amount']} BTC to {payment['pay_address']}")

# Check status
p = np.get_payment_status(payment["payment_id"])
print(p["payment_status"])

Configuration

np = NowPayments(
    api_key="YOUR_API_KEY",      # Required
    sandbox=True,                # Use sandbox (api-sandbox.nowpayments.io)
    base_url=None,               # Override base URL (overrides sandbox)
    timeout=30000,               # Request timeout in ms
    ipn_secret="YOUR_IPN_SECRET" # For webhook verification
)

Config keys: api_key or apiKey, ipn_secret or ipnSecret (both styles supported).

API Reference (All Methods)

Status & Auth

Currencies

Price & Estimate

Payments

Invoices

Subscriptions

Payouts

Fiat Payouts

Balance

Sub-Partners (Custody)

Conversions

IPN

Total: 44 methods

JWT Authentication

Payouts, custody, and some subscription actions require JWT. Token expires in ~5 minutes.

auth = np.get_auth_token(email="your@email.com", password="your_password")
token = auth["token"]

# Create payout
result = np.create_payout(
    params={
        "withdrawals": [
            {"address": "bc1q...", "currency": "btc", "amount": 0.001}
        ]
    },
    jwt_token=token,
)

IPN Webhook

Verify webhook signature from x-nowpayments-sig header:

from nowpayments import NowPayments, verify_ipn_signature, create_ipn_signature

# With client (uses ipn_secret from config)
np = NowPayments(api_key="...", ipn_secret="YOUR_IPN_SECRET")
if np.verify_ipn(request_body, request_headers.get("x-nowpayments-sig")):
    # Valid webhook
    process_payment(request_body)

# Standalone
if verify_ipn_signature(payload, signature, ipn_secret):
    # Valid
    pass

# Create signature (for testing)
sig = create_ipn_signature(payload_dict, ipn_secret)

Payment Helpers

from nowpayments import (
    is_payment_complete,
    is_payment_pending,
    get_status_label,
    get_payment_summary,
    PAYMENT_STATUS_LABELS,
    PAYMENT_STATUSES,
    PAYMENT_DONE_STATUSES,
    PAYMENT_PENDING_STATUSES,
)

status = payment["payment_status"]
if is_payment_complete(status):
    print("Done")  # finished, failed, refunded, expired
if is_payment_pending(status):
    print("Awaiting payment")  # waiting, confirming, etc.

label = get_status_label(status)  # "Awaiting payment", "Completed", etc.
summary = get_payment_summary(payment)  # "Awaiting payment: 0.001 BTC → bc1q..."

Exports

from nowpayments import (
    NowPayments,           # Main client
    NowPaymentsError,      # API error (message, status_code, code, response)
    verify_ipn_signature,  # IPN verification
    create_ipn_signature,  # IPN signature for tests
    is_payment_complete,
    is_payment_pending,
    get_status_label,
    get_payment_summary,
    PAYMENT_STATUS_LABELS,
    PAYMENT_STATUSES,
    PAYMENT_DONE_STATUSES,
    PAYMENT_PENDING_STATUSES,
)

Upgrade Guide

From 1.0.x to 1.0.y (patch)

No breaking changes. Update:

pip install --upgrade nowpayments-py

Config keys

• api_key or apiKey — both work
• ipn_secret or ipnSecret — both work

Error handling

from nowpayments import NowPayments, NowPaymentsError

try:
    payment = np.create_payment(...)
except NowPaymentsError as e:
    print(e.message, e.status_code, e.code)

License

MIT © Foisalislambd