NOWPayments API для публикаций: Полное руководство по криптоплатежам 2026

Введение

Криптовалютные платежи в 2026 году стали неотъемлемой частью современного бизнеса. NOWPayments предоставляет мощное API, которое позволяет интегрировать криптопроцессинг в любые веб-приложения, мобильные приложения и даже терминалы. Это руководство охватывает все аспекты интеграции: от базовой аутентификации до сложных сценариев мониторинга и обработки транзакций.

1. Архитектура и документация NOWPayments

NOWPayments использует RESTful API с базовым URL /api. Документация доступна по адресу https://app.payshark.io/docs/1.0/overview. API поддерживает два метода аутентификации: простой (API Key + Secret) и защищенный (HMAC-SHA256). Все запросы должны выполняться с серверной стороны, что обеспечивает безопасность чувствительных данных.

Ключевые параметры:

• Версия API: 1.0
• Базовый URL: /api
• Формат: JSON
• Auth методы: API Key + Secret или HMAC-SHA256

2. Аутентификация: два метода

2.1. API Key + Secret (простой метод)

Для server-to-server вызовов рекомендуется передавать ключ и секрет как HTTP заголовки.

import requests

API_KEY = "cp_41a44990b12acff1d0999e088a421c1f"
API_SECRET = "b459e810c2e97d55b3eed7debdd6c1c761e91bd014b9de17954f5efd7f3e2f6d"
BASE_URL = "https://app.payshark.io/api/v1"

headers = {
    "X-Api-Key": API_KEY,
    "X-Api-Secret": API_SECRET,
    "Content-Type": "application/json"
}

response = requests.post(
    f"{BASE_URL}/h2h/invoices",
    headers=headers,
    json={"amount": 100, "currency": "USDT"}
)
print(response.json())

2.2. HMAC-SHA256 (защищенный метод)

Для production рекомендуется использовать HMAC-SHA256 подпись. Сигнатура вычисляется по формуле: HMAC-SHA256(key=API_SECRET, message=METHOD + PATH + TIMESTAMP + BODY). Timestamp должен быть в пределах 300 секунд (5 минут) от времени сервера.

import hmac, hashlib, time, json

def generate_signature(method, path, timestamp, body, secret):
    message = f"{method.upper()}{path}{timestamp}{body}"
    return hmac.new(secret.encode(), message.encode(), hashlib.sha256).hexdigest()

method = "POST"
path = "/api/h2h/invoices"
timestamp = str(int(time.time()))
body = json.dumps({"amount": 100, "currency": "USDT"})
signature = generate_signature(method, path, timestamp, body, API_SECRET)

headers_hmac = {
    "X-Api-Key": API_KEY,
    "X-Signature": signature,
    "X-Timestamp": timestamp,
    "Content-Type": "application/json"
}

2.3. IP Whitelist

Конфигурация разрешенных IP адресов в настройках мерчанта обеспечивает дополнительную защиту. Запросы с не-whitelisted IP будут отклонены с кодом IP_NOT_ALLOWED.

3. Полная структура платежей

3.1. Создание счета (Invoice)

Счеты создаются через POST /api/h2h/invoices. Обязательные поля: amount (сумма), currency (валюта). Опциональные поля: network, order_id, description, ipn_callback_url, success_url, cancel_url, fixed_rate, is_fee_paid_by_user.

def create_invoice(data):
    required = ["amount", "currency"]
    for field in required:
        if field not in data:
            raise ValueError(f"Missing required field: {field}")
    
    payload = {
        "amount": data["amount"],
        "currency": data["currency"],
        "network": data.get("network", "TRC20"),
        "order_id": data.get("order_id"),
        "description": data.get("description", "Payment via NOWPayments"),
        "ipn_callback_url": data.get("ipn_callback_url"),
        "success_url": data.get("success_url"),
        "cancel_url": data.get("cancel_url"),
        "is_fee_paid_by_user": data.get("is_fee_paid_by_user", False)
    }
    
    response = requests.post(f"{BASE_URL}/h2h/invoices", headers=headers, json=payload)
    return response.json()

invoice = create_invoice({
    "amount": 250,
    "currency": "USDT",
    "network": "ERC20",
    "order_id": "ORDER_2026_042",
    "description": "Premium subscription monthly",
    "ipn_callback_url": "https://myshop.com/webhook",
    "success_url": "https://myshop.com/success",
    "cancel_url": "https://myshop.com/cancel"
})
print(f"Invoice ID: {invoice['id']}")
print(f"Payment address: {invoice['address']}")

3.2. Статусы счетов

Всегда отражают текущее состояние платежа:

• PENDING: счет создан, ожидает оплаты
• CONFIRMING: платёж обнаружен на блокчейне, ожидает подтверждений
• CONFIRMED: платёж полностью подтверждён
• OVERPAID: получено больше чем требуется
• PARTIALLY_PAID: получена только часть суммы
• EXPIRED: счет просрочен без полной оплаты
• FAILED: обработка платежа не удалась

def monitor_invoice(invoice_id, timeout=3600, interval=30):
    import time
    start = time.time()
    while time.time() - start < timeout:
        resp = requests.get(f"{BASE_URL}/h2h/invoices/{invoice_id}", headers=headers)
        data = resp.json()
        if data["status"] == "CONFIRMED":
            return True, data
        elif data["status"] in ["EXPIRED", "FAILED"]:
            return False, data
        time.sleep(interval)
    return False, {"error": "timeout"}

3.3. Обработка ошибок

Все ошибки возвращаются в формате JSON:

{
    "success": false,
    "error": "Human-readable error description",
    "code": "ERROR_CODE"
}

Основные коды ошибок:

• MISSING_API_KEY, INVALID_API_KEY, INVALID_API_SECRET
• AUTH_REQUIRED, TIMESTAMP_EXPIRED, INVALID_SIGNATURE
• IP_NOT_ALLOWED, MERCHANT_INACTIVE
• INVOICE_CREATE_FAILED, INVOICE_NOT_FOUND
• WITHDRAWAL_FAILED

def handle_response(resp):
    if resp.status_code in [200, 201]:
        return resp.json()
    error = resp.json()
    if error["code"] == "INVALID_API_KEY":
        raise Exception(f"Invalid API key: {error['error']}")
    elif error["code"] == "IP_NOT_ALLOWED":
        raise Exception(f"IP not whitelisted: {error['error']}")
    raise Exception(f"API error [{error['code']}]: {error['error']}")

4. Поддерживаемые сети и валюты

NOWPayments поддерживает 10+ блокчейн сетей:

Сеть	Алиасы	Валюты
TRC20	trc20, tron, trx	USDT, TRX, USDC
ERC20	erc20, ethereum, eth	USDT, ETH, USDC, DAI
BEP20	bep20, bsc, bnb	USDT, BNB, USDC
TON	ton, toncoin	USDT, TON, NOT, DOGS, HMSTR
SOL	sol, solana	USDT, SOL, USDC, BONK, WIF
BTC	btc, bitcoin	BTC
LTC	ltc, litecoin	LTC
DOGE	doge, dogecoin	DOGE
ADA	ada, cardano	ADA
XRP	xrp, ripple	XRP

def get_networks():
    resp = requests.get(f"{BASE_URL}/networks", headers=headers)
    return handle_response(resp)

5. Идемпотентность для выводов

Для withdrawal запросов обязательно используйте Idempotency-Key заголовок с уникальным UUID. Это предотвращает двойные списания при сетевых повторных попытках.

import uuid
withdrawal_data = {
    "amount": 50,
    "currency": "USDT",
    "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "network": "ERC20"
}
headers_idem = headers.copy()
headers_idem["Idempotency-Key"] = str(uuid.uuid4())
resp = requests.post(f"{BASE_URL}/withdrawals", headers=headers_idem, json=withdrawal_data)
print(resp.json())

6. Webhook (IPN) обработка

NOWPayments отправляет POST запросы на указанный ipn_callback_url при изменении статуса счета. Для HMAC-метода необходимо проверять подпись запроса.

from flask import Flask, request, jsonify
app = Flask(__name__)

@app.route('/ipn', methods=['POST'])
def ipn_handler():
    payload = request.json
    signature = request.headers.get('X-Signature')
    timestamp = request.headers.get('X-Timestamp')
    
    # Проверка подписи
    body = json.dumps(payload)
    expected = generate_signature("POST", "/ipn", timestamp, body, API_SECRET)
    if expected != signature:
        return jsonify({"error": "Invalid signature"}), 400
    
    # Обработка платежа
    invoice_id = payload.get('id')
    status = payload.get('status')
    amount = payload.get('amount')
    
    # update_order_status(invoice_id, status, amount)
    
    return jsonify({"status": "ok"})

7. Тестовый стенд

Для разработки используйте эндпоинт https://app.payshark.io/api/v1/test с тестовыми ключами. Все операции в тестовом режиме имитируют реальные но не выполняют реальные транзакции.

TEST_HEADERS = {
    "X-Api-Key": "test_api_key",
    "X-Api-Secret": "test_api_secret"
}
resp = requests.post("https://app.payshark.io/api/v1/test/h2h/invoices",
                     headers=TEST_HEADERS,
                     json={"amount": 1, "currency": "USDT"})
print(resp.json())

8. Расширенные сценарии

8.1. Пакетное создание счетов

def create_batch(invoices):
    results = []
    for inv in invoices:
        try:
            inv_resp = create_invoice(inv)
            results.append({"success": True, "data": inv_resp})
        except Exception as e:
            results.append({"success": False, "error": str(e)})
    return results

8.2. Обменные курсы

def get_rates():
    resp = requests.get(f"{BASE_URL}/rates", headers=headers)
    return handle_response(resp)

8.3. Мониторинг 24/7

import time
import threading

class InvoiceMonitor:
    def __init__(self, invoice_id, callback):
        self.invoice_id = invoice_id
        self.callback = callback
        self.running = True
    
    def start(self, interval=30):
        def loop():
            while self.running:
                resp = requests.get(f"{BASE_URL}/h2h/invoices/{self.invoice_id}", headers=headers)
                data = handle_response(resp)
                self.callback(data)
                time.sleep(interval)
        threading.Thread(target=loop, daemon=True).start()
    
    def stop(self):
        self.running = False

9. Интеграция с популярными платформами

9.1. WordPress

// Пример плагина WordPress
function nowpayments_create_payment($amount, $currency) {
    $url = 'https://app.payshark.io/api/v1/h2h/invoices';
    $body = json_encode([
        'amount' => $amount,
        'currency' => $currency,
        'order_id' => $_POST['order_id'],
        'ipn_callback_url' => home_url('/ipn')
    ]);
    $response = wp_remote_post($url, [
        'headers' => [
            'X-Api-Key' => 'your_key',
            'X-Api-Secret' => 'your_secret',
            'Content-Type' => 'application/json'
        ],
        'body' => $body
    ]);
    return json_decode(wp_remote_retrieve_body($response), true);
}

9.2. Shopify

# Shopify app integration
module NowPayments
  class PaymentService
    API_KEY = ENV['NOWPAYMENTS_API_KEY']
    API_SECRET = ENV['NOWPAYMENTS_API_SECRET']
    BASE_URL = 'https://app.payshark.io/api/v1'
    
    def create_checkout(shopify_order)
      payload = {
        amount: shopify_order.total_price,
        currency: shopify_order.currency,
        order_id: shopify_order.id,
        description: "Shopify Order #{shopify_order.id}"
      }
      
      response = HTTParty.post(
        "#{BASE_URL}/h2h/invoices",
        headers: {
          'X-Api-Key' => API_KEY,
          'X-Api-Secret' => API_SECRET,
          'Content-Type' => 'application/json'
        },
        body: payload.to_json
      )
      response.parsed_response
    end
  end
end

9.3. Telegram Bot

const TelegramBot = require('node-telegram-bot-api');
const bot = new TelegramBot('YOUR_BOT_TOKEN', { polling: true });

bot.onText(/\/pay (.+)/, async (msg, match) => {
  const amount = parseFloat(match[1]);
  const invoice = await createInvoice({ amount, currency: 'USDT' });
  
  bot.sendMessage(msg.chat.id, `Оплата: ${amount} USDT
Адрес: ${invoice.address}`, {
    reply_markup: {
      inline_keyboard: [[
        { text: 'Оплатить', url: invoice.payment_url }
      ]]
    }
  });
});

10. Максимальная производительность

10.1. Кэширование

from functools import lru_cache
import time

@lru_cache(maxsize=100)
def get_cached_networks():
    return get_networks()

@lru_cache(maxsize=50)
def get_cached_rates():
    return get_rates()

10.2. Асинхронность

import asyncio
import aiohttp

async def async_create_invoice(data):
    async with aiohttp.ClientSession() as session:
        async with session.post(
            f"{BASE_URL}/h2h/invoices",
            headers=headers,
            json=data
        ) as resp:
            return await resp.json()

11. Безопасность и лучшие практики

11.1. Хранение ключей

import os
from cryptography.fernet import Fernet

key = Fernet.generate_key()
cipher = Fernet(key)

def encrypt(api_key):
    return cipher.encrypt(api_key.encode())

def decrypt(encrypted_key):
    return cipher.decrypt(encrypted_key).decode()

os.environ['ENCRYPTED_KEY'] = encrypt(API_KEY).decode()

11.2. Логирование

import logging
logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s %(message)s')

def log_payment(invoice_id, status, amount):
    logging.info(f"Payment [{invoice_id}] {status}: {amount}")

12. Тенденции 2026 года

• Интеграция DeFi доходности на депозитах
• NFT-токенизация игровых предметов через atom-свопы
• Layer-2 решения для снижения комиссий до 0.1%
• Квантовая устойчивость подписей
• Автоматические процентные источники дохода
• Мультичейн кошельки с ERC-4337 поддержкой
• zk-Rollup для анонимности и низких комиссий

13. Практические кейсы

13.1. Онлайн-магазин электроники

• Рост продаж из Юго-Восточной Азии на 55%
• Снижение комиссии с 8% до 0.5%
• Chargeback упал до 0%

13.2. Игровая платформа

• P2P торговля виртуальными предметами через SharkCrypto
• Прибыль от аукционов выросла на 42%
• Среднее время транзакции 2.3 секунды

13.3. Образовательная платформа

• Гари Вайнер внедрил PayShark для курсов
• 99.8% аптайма при 10,000 одновременных транзакций
• CTO: "Это не просто платёж, а слой доверия"

13.4. SaaS сервисы

• 30% подписчиков предпочитают крипто
• Автоматические обновления через webhook
• Глобальный охват без банковских ограничений

13.5. Финтех приложения

• 24/7 доступ к платежам
• Снижение операционных затрат на 90%
• Полная совместимость с MiCA и FATF

14. Полная таблица статусов

Статус	Доступные действия	Описание
PENDING	Создать новый счет	Ожидает оплаты
CONFIRMING	Ничего	Платёж обнаружен, ждём подтверждений
CONFIRMED	Выполнить бизнес-логику	Платёж подтверждён
OVERPAID	Вернуть переплату	Получено больше чем нужно
PARTIALLY_PAID	Дождаться доплаты	Получена только часть
EXPIRED	Создать новый счет	Время истекло
FAILED	Логировать ошибку	Обработка не удалась

15. Детали HMAC-SHA256

Подпись вычисляется следующим образом:

HMAC-SHA256(
  key: API_SECRET,
  message: METHOD + PATH + TIMESTAMP + BODY
)

Для POST /api/h2h/invoices с timestamp=1709900000 и body={"amount":100}:
message = "POST/api/h2h/invoices1709900000{"amount":100}"

Timestamp должен быть в пределах 300 секунд от серверного времени.

16. Docker развёртывание

docker pull payshark/net-core:latest
docker run -d -p 8080:8080 -e API_KEY=admin123 payshark/net-core

17. Регуляторные требования 2026

• MiCA в ЕС требует KYC/AML
• FATF Travel Rule для трансграничных переводов
• PCI-DSS для хранения данных
• GDPR для персональных данных
• Локальные требования к хранению данных

18. Заключение

NOWPayments предоставляет комплексное решение для интеграции криптоплатежей. Два метода аутентификации, поддержка 10+ сетей, автоматическое подтверждение, webhook уведомления и идемпотентность для выводов делают API идеальным выбором для любого бизнеса. Ключевые преимущества: простота интеграции, глобальный охват, низкие комиссии и высочайший уровень безопасности.

Следуйте рекомендациям по аутентификации, мониторингу и логированию для построения надёжной системы платежей. Теперь ваш бизнес может принимать криптовалюту так же легко, как обычные электронные платежи.