Migrating from NOWPayments / Coinbase Commerce

Besides the Cryptomus-compatible API, blockwallets offers NOWPayments- and Coinbase Commerce-compatible APIs: paths, auth headers, request / response fields, statuses and webhook signatures follow their official docs, so existing code usually needs only a new base URL and new keys. Coinbase Commerce stopped serving merchants outside the US and Singapore on 2026-03-31 — you can switch straight over.

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” 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), 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.

Coinbase Commerce

All official SDKs take a base URL — change one line (mind the trailing /):

// Node(coinbase-commerce-node)
const { Client } = require("coinbase-commerce-node");
- Client.init(process.env.COINBASE_COMMERCE_API_KEY);
+ Client.init(process.env.COINBASE_COMMERCE_API_KEY, "https://blockwallets.io/coinbase/");

# Python(coinbase-commerce)
- client = Client(api_key=API_KEY)
+ client = Client(api_key=API_KEY, base_api_uri="https://blockwallets.io/coinbase/")

// PHP(coinbase/coinbase-commerce)
- ApiClient::init($apiKey);
+ ApiClient::init($apiKey, 'https://blockwallets.io/coinbase/');

curl -X POST https://blockwallets.io/coinbase/charges \
  -H "X-CC-Api-Key: $COINBASE_COMMERCE_API_KEY" -H "X-CC-Version: 2018-03-22" \
  -H "content-type: application/json" \
  -d '{"name":"Order #12345","description":"Pro plan","pricing_type":"fixed_price",
       "local_price":{"amount":"100.00","currency":"USD"},
       "redirect_url":"https://shop.example/success","cancel_url":"https://shop.example/cancel",
       "metadata":{"order_id":"12345"}}'
# → 201 {"data": {"id": "…", "code": "7C7V5ECK", "hosted_url": "https://blockwallets.io/pay/inv_…", "timeline": [{"status": "NEW", …}], …}}

Supported endpoints

Not available: /charges/:code/resolve (400 — handle underpaid charges in the dashboard), /checkouts, /events, /invoices (404).

Webhooks

Coinbase webhooks are account-level, and so are ours: they go to the callback URL set in your dashboard (charges created with test credentials go to the test callback URL). The body is Coinbase's {id, scheduled_for, attempt_number, event: {id, type, api_version, created_at, data}} with the full charge in data; X-CC-Webhook-Signature = HMAC-SHA256(shared secret, raw body), so the SDKs' Webhook.verifyEventBody works as is. On retries event.id stays the same and attempt_number goes up — dedupe on event.id.

import crypto from "node:crypto";

// Same as the SDK's Webhook.verifySigHeader: HMAC-SHA256(shared secret, raw body)
function verifyWebhook(rawBody, sig, sharedSecret) {
  const hmac = crypto.createHmac("sha256", sharedSecret).update(rawBody, "utf8").digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(sig || ""));
}
// verifyWebhook(rawBody, req.headers["x-cc-webhook-signature"], process.env.COINBASE_WEBHOOK_SECRET)
// or with the official SDK:Webhook.verifyEventBody(rawBody, signature, sharedSecret)

When you query you will also see NEW (awaiting payment) and PENDING (payment seen on chain, confirming). Fulfil on charge:confirmed: we don't send charge:created, charge:pending, charge:delayed or charge:resolved.

Differences from Coinbase Commerce

• pricing_type must be fixed_price; local_price.currency must be USD (USDC / USDT at 1:1). no_price and other fiat return 400.
• The address appears once the customer picks a coin and network at checkout: addresses holds only that network, pricing only local plus settlement once picked; no exchange_rates, checkout or branding fields.
• metadata is stored and returned as is (up to 4 KB).
• Refunds don't show up in the timeline; see them in the dashboard.

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.