NOWPayments-compatible API

Paths, the x-api-key header, request and response fields, statuses and the x-nowpayments-sig IPN signature follow NOWPayments’ docs, so existing code usually needs only a new base URL, API key and IPN secret. Coming from somewhere else? See the migration overview.

Underneath it is a regular blockwallets bill: the receiving addresses are yours, the payment page is our hosted checkout, and a payment only counts once it is confirmed on chain and cross-checked against a second node. Below: three steps, then what each API supports and how it differs from the original — parameters we don't implement return an error instead of being silently ignored.

Three steps

1. Get a merchant account (apply on the home page) and add your domains under “Website domains” on “Developers › Integration & keys” in the dashboard. Callback URLs (ipn_callback_url) and redirect URLs (success_url / cancel_url / redirect_url) must be on those domains or your callback URL's domain — a leaked key can't point webhooks elsewhere.
2. Generate compatible credentials in the merchant dashboard under “Developers › Integration & keys”, one set for live and one for test: NOWPayments gets an API key + IPN secret, Coinbase Commerce an API key + webhook shared secret. They are shown once; we only keep hashes / ciphertext.
3. Point your code at the base URL below and use the new keys. Run it on testnets with the test credentials first, then switch to 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();

Supported endpoints

Not available: payouts, conversions, custody sub-partners, subscriptions, update-merchant-estimate, fiat payments. Those paths return 404.

IPN callbacks

When a payment reaches a final status we POST to the ipn_callback_url given at creation, with x-nowpayments-sig = HMAC-SHA512(IPN secret, the JSON sorted by key recursively) — exactly NOWPayments' verification code. The body we send is already sorted, compact JSON, so an HMAC over the raw body works too (and is the safest choice in PHP / Python, whose re-encoding of very small decimals can differ from JS). Failed callbacks are retried after 1 min, 5 min, 30 min, … — 8 attempts in total.

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 and failed never appear: once confirmed it is finished and credited to your balance; nothing is forwarded.

Currency tickers

Differences from NOWPayments

• price_currency is usd only (plus usdt / usdc at 1:1); other fiat returns 400.
• pay_amount (a fixed crypto amount), payout_address / payout_currency / payout_extra_id and customer_email are not supported and return 400.
• is_fixed_rate is accepted but has no effect: we always lock the rate (BTC / LTC etc. at the median of several exchanges, for 30 minutes). With is_fee_paid_by_user true the platform fee is added to pay_amount (the platform fee is 1%, lower at higher volume; see pricing).
• Payments are valid for up to 12 hours (NOWPayments: 7 days). partially_paid_url is stored and echoed back, but the checkout does not redirect to it.
• payment_id is a 10-digit number; for invoices created with /invoice the payment's payment_id equals the invoice id, and an invoice has exactly one payment (no parent_payment_id re-deposits).
• Only final-status and partially_paid IPNs are sent (table above), no waiting / confirming ones; fee.serviceFee is the platform fee (the amount received × the rate when the bill was created, 1% standard), other fees are 0.

Test mode

Charges and payments created with test credentials run on each chain's testnet and their webhooks are signed with the test IPN secret / shared secret — fully separate from live: a test key can't see live payments.

Everything else (checkout, confirmations, networks and minimums, refunds) works as in the main docs.