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

Введение

В 2026 году криптоплатежи стали стандартом онлайн‑бизнеса. NOWPayments предоставляет мощное API для интеграции криптоплатежей в любые веб‑приложения. Это руководство охватывает все аспекты: от аутентификации до мониторинга статусов и обработки webhooks.

1. Архитектура API NOWPayments

NOWPayments использует RESTful API с JSON‑форматом. Все запросы должны отправляться на базовый URL /api версии 1.0.

• Базовый URL: /api
• Версия API: 1.0
• Формат ответа: JSON
• Методы аутентификации: API Key + Secret или HMAC‑SHA256

2. Методы аутентификации

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

Подходит для сервер‑сервера коммуникаций.

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"
}

2.2. HMAC‑SHA256 (рекомендованный метод)

Подпись генерируется как HMAC‑SHA256(key=API_SECRET, message=METHOD+PATH+TIMESTAMP+BODY).

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"
}

3. IP‑белый список (опционально)

Для повышения безопасности можно ограничить доступ только определёнными IP‑адресами в настройках аккаунта. Запросы с другими IP получат ошибку IP_NOT_ALLOWED.

4. Создание и управление счетами (Invoices)

4.1. Создание счета

invoice_data = {
    "amount": 150,
    "currency": "USDT",
    "network": "TRC20",
    "order_id": "ORDER_2026_001",
    "description": "Оплата заказа №1",
    "ipn_callback_url": "https://myshop.com/ipn",
    "success_url": "https://myshop.com/success",
    "cancel_url": "https://myshop.com/cancel"
}

response = requests.post(f"{BASE_URL}/h2h/invoices", headers=headers, json=invoice_data)
print(response.json())

4.2. Статусы счета

4.3. Получение статуса счета

def get_invoice_status(invoice_id):
    resp = requests.get(f"{BASE_URL}/h2h/invoices/{invoice_id}", headers=headers)
    return resp.json()

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

Для запросов вывода средств необходимо указывать уникальный 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 при изменении статуса.

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

@app.route('/ipn', methods=['POST'])
def ipn_handler():
    payload = request.json
    # Проверка подписи (если используется HMAC)
    # update_order_status(payload['order_id'], payload['status'])
    return jsonify({"status": "ok"})

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

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

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

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

9. Лучшие практики

• Два метода аутентификации: используйте HMAC‑SHA256 в проде.
• Идемпотентность: всегда передавайте Idempotency-Key при выводах.
• Мониторинг статусов: реализуйте периодический polling или webhook.
• Логи и аналитика: сохраняйте каждый запрос/ответ для аудита.
• Безопасность: храните ключи в защищённом хранилище (env, secret manager).

Эта статья может быть опубликована в вашем блоге, чтобы предоставить разработчикам полное и практичное руководство по работе с NOWPayments API.