API compatible NOWPayments

Les chemins, l’en-tête x-api-key, les champs de requête et de réponse, les statuts et la signature IPN x-nowpayments-sig suivent la documentation de NOWPayments : le code existant n’a donc généralement besoin que d’une nouvelle URL de base, d’une nouvelle API key et d’un nouvel IPN secret. Vous venez d’ailleurs ? Consultez l’aperçu de la migration.

Dessous, c’est une facture blockwallets ordinaire : les adresses de réception sont les vôtres, la page de paiement est notre caisse hébergée, et un paiement ne compte qu’une fois confirmé on-chain et recoupé avec un second nœud. Ci-dessous : trois étapes, puis ce que chaque API prend en charge et en quoi elle diffère de l’originale — les paramètres que nous n’implémentons pas renvoient une erreur au lieu d’être ignorés en silence.

Trois étapes

1. Obtenez un compte marchand (demandez-le sur la page d’accueil) et ajoutez vos domaines dans « Domaines du site web », sous « Développeurs › Intégration et clés » du tableau de bord. Les URL de callback (ipn_callback_url) et de redirection (success_url / cancel_url / redirect_url) doivent se trouver sur ces domaines ou sur le domaine de votre URL de callback — une clé divulguée ne peut pas rediriger les webhooks ailleurs.
2. Générez des identifiants compatibles dans le tableau de bord marchand, sous « Développeurs › Intégration et clés », un jeu pour live et un pour test : NOWPayments reçoit une API key + IPN secret, Coinbase Commerce une API key + webhook shared secret. Ils ne sont affichés qu’une fois ; nous ne conservons que des hashs / du texte chiffré.
3. Pointez votre code vers l’URL de base ci-dessous et utilisez les nouvelles clés. Lancez d’abord sur les testnets avec les identifiants de test, puis passez en 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 pris en charge

Non disponibles : payouts, conversions, sous-partenaires en garde, abonnements, update-merchant-estimate, paiements en monnaie fiat. Ces chemins renvoient 404.

Callbacks IPN

Quand un paiement atteint un statut final, nous envoyons un POST à l’ipn_callback_url donnée à la création, avec x-nowpayments-sig = HMAC-SHA512(IPN secret, le JSON trié récursivement par clé) — exactement le code de vérification de NOWPayments. Le corps que nous envoyons est déjà un JSON compact et trié, donc un HMAC sur le corps brut fonctionne aussi (et c’est le choix le plus sûr en PHP / Python, dont le ré-encodage des très petits décimaux peut différer de JS). Les callbacks en échec sont réessayés après 1 min, 5 min, 30 min, … — 8 tentatives en tout.

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 et failed n’apparaissent jamais : une fois confirmé, c’est finished et crédité sur votre solde ; rien n’est transféré.

Tickers des cryptos

Différences avec NOWPayments

• price_currency vaut uniquement usd (plus usdt / usdc à 1:1) ; toute autre monnaie fiat renvoie 400.
• pay_amount (un montant crypto fixe), payout_address / payout_currency / payout_extra_id et customer_email ne sont pas pris en charge et renvoient 400.
• is_fixed_rate est accepté mais sans effet : nous verrouillons toujours le taux (BTC / LTC, etc. à la médiane de plusieurs plateformes, pendant 30 minutes). Avec is_fee_paid_by_user à true, les frais de plateforme sont ajoutés à pay_amount (les frais de plateforme sont de 1%, moins avec un volume plus élevé ; voir les tarifs).
• Les paiements sont valables jusqu’à 12 heures (NOWPayments : 7 jours). partially_paid_url est stocké et renvoyé tel quel, mais la caisse n’y redirige pas.
• payment_id est un nombre à 10 chiffres ; pour les factures (invoices) créées avec /invoice, le payment_id du paiement est égal à l’id de la facture, et une facture a exactement un paiement (pas de redépôts avec parent_payment_id).
• Seuls les IPN de statut final et de partially_paid sont envoyés (tableau ci-dessus), aucun pour waiting / confirming ; fee.serviceFee correspond aux frais de plateforme (le montant reçu × le taux à la création de la facture, 1% en standard), les autres frais sont à 0.

Mode test

Les charges et paiements créés avec des identifiants de test fonctionnent sur le testnet de chaque chaîne et leurs webhooks sont signés avec l’IPN secret / shared secret de test — totalement séparés du live : une clé de test ne voit pas les paiements live.

Tout le reste (caisse, confirmations, réseaux et minimums, remboursements) fonctionne comme dans la documentation principale.