API compatible con NOWPayments

Las rutas, la cabecera x-api-key, los campos de petición y respuesta, los estados y la firma IPN x-nowpayments-sig siguen la documentación de NOWPayments, así que el código existente normalmente solo necesita una URL base, una API key y un IPN secret nuevos. ¿Vienes de otra pasarela? Consulta el resumen de migración.

Por debajo es una factura normal de blockwallets: las direcciones de cobro son tuyas, la página de pago es nuestra caja alojada, y un pago solo cuenta cuando está confirmado en la cadena y contrastado con un segundo nodo. A continuación: tres pasos y después qué admite cada API y en qué se diferencia de la original: los parámetros que no implementamos devuelven un error en lugar de ignorarse en silencio.

Tres pasos

1. Consigue una cuenta de comercio (solicítala en la página de inicio) y añade tus dominios en “Dominios del sitio web”, en “Desarrolladores › Integración y claves” del panel. Las URL de callback (ipn_callback_url) y de redirección (success_url / cancel_url / redirect_url) deben estar en esos dominios o en el dominio de tu URL de callback: una clave filtrada no puede apuntar los webhooks a otro sitio.
2. Genera credenciales compatibles en el panel del comercio, en “Desarrolladores › Integración y claves”, un juego para live y otro para test: NOWPayments recibe una API key + IPN secret, Coinbase Commerce una API key + webhook shared secret. Se muestran una sola vez; nosotros solo guardamos hashes / texto cifrado.
3. Apunta tu código a la URL base de abajo y usa las nuevas claves. Pruébalo primero en testnets con las credenciales de test y después pasa a 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();

Endpoints admitidos

No disponibles: payouts, conversiones, sub-partners de custodia, suscripciones, update-merchant-estimate, pagos en moneda fiat. Esas rutas devuelven 404.

Callbacks IPN

Cuando un pago llega a un estado final enviamos un POST a la ipn_callback_url indicada al crearlo, con x-nowpayments-sig = HMAC-SHA512(IPN secret, el JSON ordenado recursivamente por clave), exactamente el código de verificación de NOWPayments. El cuerpo que enviamos ya es JSON compacto y ordenado, así que un HMAC sobre el cuerpo bruto también funciona (y es la opción más segura en PHP / Python, cuya recodificación de decimales muy pequeños puede diferir de JS). Los callbacks fallidos se reintentan tras 1 min, 5 min, 30 min, …: 8 intentos en 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 y failed nunca aparecen: una vez confirmado pasa a finished y se acredita en tu saldo; no se reenvía nada.

Tickers de monedas

Diferencias con NOWPayments

• price_currency es solo usd (más usdt / usdc a 1:1); cualquier otra moneda fiat devuelve 400.
• pay_amount (un importe fijo en cripto), payout_address / payout_currency / payout_extra_id y customer_email no se admiten y devuelven 400.
• is_fixed_rate se acepta pero no tiene efecto: siempre bloqueamos la tasa (BTC / LTC, etc., a la mediana de varios exchanges, durante 30 minutos). Con is_fee_paid_by_user en true, la comisión de plataforma se suma a pay_amount (la comisión de plataforma es 1%, menor con más volumen; consulta los precios).
• Los pagos son válidos hasta 12 horas (NOWPayments: 7 días). partially_paid_url se guarda y se devuelve tal cual, pero la caja no redirige a ella.
• payment_id es un número de 10 dígitos; en las facturas (invoices) creadas con /invoice, el payment_id del pago es igual al id de la factura, y una factura tiene exactamente un pago (sin redepósitos con parent_payment_id).
• Solo se envían los IPN de estado final y de partially_paid (tabla de arriba), ninguno de waiting / confirming; fee.serviceFee es la comisión de plataforma (el importe recibido × la tarifa cuando se creó la factura, 1% estándar), las demás comisiones son 0.

Modo de prueba

Los cargos y pagos creados con credenciales de test funcionan en la testnet de cada cadena y sus webhooks se firman con el IPN secret / shared secret de test, totalmente separados de live: una clave de test no puede ver pagos de live.

Todo lo demás (caja, confirmaciones, redes y mínimos, reembolsos) funciona como en la documentación principal.