API, совместимый с NOWPayments

Пути, заголовок x-api-key, поля запросов и ответов, статусы и подпись IPN x-nowpayments-sig соответствуют документации NOWPayments, поэтому существующему коду обычно нужны только новый базовый URL, API key и IPN secret. Переходите откуда-то ещё? См. обзор перехода.

Внутри это обычный счёт blockwallets: адреса для приёма ваши, страница оплаты — наша размещённая страница, а платёж засчитывается только после подтверждения в блокчейне и сверки со вторым узлом. Далее: три шага, затем что поддерживает каждый API и чем он отличается от оригинала — параметры, которые мы не реализовали, возвращают ошибку, а не молча игнорируются.

Три шага

1. Получите аккаунт продавца (запросите доступ на главной странице) и добавьте свои домены в разделе «Домены сайта» на странице «Разработчикам › Интеграция и ключи» в кабинете. URL уведомлений (ipn_callback_url) и URL перенаправления (success_url / cancel_url / redirect_url) должны находиться на этих доменах или на домене вашего URL уведомлений — утёкший ключ не сможет направить вебхуки в другое место.
2. Создайте совместимые учётные данные в кабинете продавца в разделе «Разработчикам › Интеграция и ключи», один набор для live и один для test: для NOWPayments — API key + IPN secret, для Coinbase Commerce — API key + webhook shared secret. Они показываются один раз; мы храним только хеши / шифртекст.
3. Направьте код на базовый URL ниже и используйте новые ключи. Сначала запустите его в тестовых сетях с тестовыми учётными данными, затем переключитесь на live.

NOWPayments

- const NP = "https://api.nowpayments.io/v1";
+ const NP = "https://blockwallets.io/nowpayments/v1";

const res = await fetch(`${NP}/payment`, {
  method: "POST",
  headers: { "x-api-key": process.env.NOWPAYMENTS_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({
    price_amount: 49.9, price_currency: "usd", pay_currency: "usdttrc20",
    order_id: "A-1001", order_description: "Pro plan",
    ipn_callback_url: "https://shop.example/ipn/nowpayments",
  }),
});
const { payment_id, pay_address, pay_amount } = await res.json();

Поддерживаемые эндпоинты

Недоступно: выплаты, конвертации, субпартнёры с кастодиальным хранением, подписки, update-merchant-estimate, фиатные платежи. Эти пути возвращают 404.

IPN-уведомления

Когда платёж достигает конечного статуса, мы отправляем POST на ipn_callback_url, указанный при создании, с x-nowpayments-sig = HMAC-SHA512(IPN secret, JSON, рекурсивно отсортированный по ключам) — в точности как в коде проверки NOWPayments. Тело, которое мы отправляем, уже представляет собой отсортированный компактный JSON, поэтому HMAC по исходному телу тоже подходит (и это самый надёжный вариант в PHP / Python, у которых повторное кодирование очень малых десятичных чисел может отличаться от JS). Неудачные уведомления повторяются через 1 мин, 5 мин, 30 мин, … — всего 8 попыток.

import crypto from "node:crypto";

// Same as the NOWPayments docs (our body is already sorted, so hashing the raw body works too)
function sortObject(obj) {
  return Object.keys(obj).sort().reduce((r, k) => {
    r[k] = obj[k] && typeof obj[k] === "object" ? sortObject(obj[k]) : obj[k];
    return r;
  }, {});
}
function verifyIpn(params, sig, ipnSecret) {
  const hmac = crypto.createHmac("sha512", ipnSecret).update(JSON.stringify(sortObject(params))).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(sig || ""));
}
// verifyIpn(req.body, req.headers["x-nowpayments-sig"], process.env.NOWPAYMENTS_IPN_SECRET)

$raw = file_get_contents('php://input');
$data = json_decode($raw, true);
tksort($data);  // the recursive ksort from the NOWPayments docs
$hmac = hash_hmac('sha512', json_encode($data, JSON_UNESCAPED_SLASHES), trim($ipnSecret));
$ok = hash_equals($hmac, $_SERVER['HTTP_X_NOWPAYMENTS_SIG'] ?? '');

Статусы confirmed, sending и failed не встречаются: после подтверждения платёж получает finished и зачисляется на ваш баланс; ничего никуда не пересылается.

Тикеры монет

Отличия от NOWPayments

• price_currency — только usd (плюс usdt / usdc 1:1); другие фиатные валюты возвращают 400.
• pay_amount (фиксированная сумма в криптовалюте), payout_address / payout_currency / payout_extra_id и customer_email не поддерживаются и возвращают 400.
• is_fixed_rate принимается, но ни на что не влияет: курс мы фиксируем всегда (BTC / LTC и др. — по медиане нескольких бирж, на 30 минут). Если is_fee_paid_by_user равен true, комиссия платформы добавляется к pay_amount (комиссия платформы 1%, при больших оборотах ниже; см. цены).
• Платежи действительны до 12 часов (NOWPayments: 7 дней). partially_paid_url сохраняется и возвращается как есть, но страница оплаты на него не перенаправляет.
• payment_id — 10-значное число; для инвойсов, созданных через /invoice, payment_id платежа равен id инвойса, и у инвойса ровно один платёж (повторных пополнений с parent_payment_id нет).
• Отправляются только IPN с конечными статусами и partially_paid (таблица выше), без waiting / confirming; fee.serviceFee — комиссия платформы (полученная сумма × ставка на момент создания счёта, стандартная 1%), остальные комиссии равны 0.

Тестовый режим

Charge и платежи, созданные с тестовыми учётными данными, работают в тестовой сети каждого блокчейна, а их вебхуки подписываются тестовым IPN secret / shared secret — полностью отдельно от live: тестовый ключ не видит live-платежи.

Всё остальное (страница оплаты, подтверждения, сети и минимумы, возвраты) работает так же, как в основной документации.