API compatível com a NOWPayments

Os caminhos, o cabeçalho x-api-key, os campos de requisição e resposta, os status e a assinatura IPN x-nowpayments-sig seguem a documentação da NOWPayments, então o código existente normalmente só precisa de uma nova URL base, uma nova API key e um novo IPN secret. Vindo de outro lugar? Veja a visão geral da migração.

Por baixo é uma cobrança comum da blockwallets: os endereços de recebimento são seus, a página de pagamento é o nosso checkout hospedado, e um pagamento só vale depois de confirmado na blockchain e conferido com um segundo nó. A seguir: três passos, depois o que cada API suporta e como ela difere da original — parâmetros que não implementamos retornam erro em vez de serem ignorados em silêncio.

Três passos

1. Consiga uma conta de lojista (solicite na página inicial) e cadastre os seus domínios em “Domínios do site”, em “Desenvolvedores › Integração e chaves” no painel. As URLs de callback (ipn_callback_url) e de redirecionamento (success_url / cancel_url / redirect_url) precisam estar nesses domínios ou no domínio da sua URL de callback — uma chave vazada não consegue apontar webhooks para outro lugar.
2. Gere credenciais compatíveis no painel do lojista, em “Desenvolvedores › Integração e chaves”, um conjunto para live e outro para test: a NOWPayments recebe uma API key + IPN secret, a Coinbase Commerce uma API key + webhook shared secret. Elas são exibidas uma única vez; guardamos apenas hashes / texto cifrado.
3. Aponte o seu código para a URL base abaixo e use as novas chaves. Rode primeiro nas testnets com as credenciais de test e depois passe para 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 suportados

Não disponíveis: payouts, conversões, subparceiros de custódia, assinaturas, update-merchant-estimate, pagamentos em moeda fiduciária. Esses caminhos retornam 404.

Callbacks IPN

Quando um pagamento chega a um status final, enviamos um POST para a ipn_callback_url informada na criação, com x-nowpayments-sig = HMAC-SHA512(IPN secret, o JSON ordenado recursivamente por chave) — exatamente o código de verificação da NOWPayments. O corpo que enviamos já é um JSON compacto e ordenado, então um HMAC sobre o corpo bruto também funciona (e é a escolha mais segura em PHP / Python, cuja recodificação de decimais muito pequenos pode diferir da do JS). Callbacks que falham são reenviados após 1 min, 5 min, 30 min, … — 8 tentativas no 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 e failed nunca aparecem: depois de confirmado vira finished e é creditado no seu saldo; nada é repassado.

Tickers das moedas

Diferenças em relação à NOWPayments

• price_currency é apenas usd (mais usdt / usdc a 1:1); qualquer outra moeda fiduciária retorna 400.
• pay_amount (um valor fixo em cripto), payout_address / payout_currency / payout_extra_id e customer_email não são suportados e retornam 400.
• is_fixed_rate é aceito mas não tem efeito: sempre travamos a cotação (BTC / LTC etc. pela mediana de várias corretoras, por 30 minutos). Com is_fee_paid_by_user true, a taxa da plataforma é somada a pay_amount (a taxa da plataforma é 1%, menor com mais volume; veja os preços).
• Os pagamentos valem por até 12 horas (NOWPayments: 7 dias). partially_paid_url é guardado e devolvido como está, mas o checkout não redireciona para ele.
• payment_id é um número de 10 dígitos; nas faturas (invoices) criadas com /invoice, o payment_id do pagamento é igual ao id da fatura, e uma fatura tem exatamente um pagamento (sem redepósitos com parent_payment_id).
• Só são enviados os IPNs de status final e de partially_paid (tabela acima), nenhum de waiting / confirming; fee.serviceFee é a taxa da plataforma (o valor recebido × a taxa quando a cobrança foi criada, 1% padrão), as demais taxas são 0.

Modo de teste

Cobranças e pagamentos criados com credenciais de test rodam na testnet de cada rede e os webhooks deles são assinados com o IPN secret / shared secret de test — totalmente separados do live: uma chave de test não enxerga pagamentos live.

Todo o resto (checkout, confirmações, redes e mínimos, reembolsos) funciona como na documentação principal.