NOWPayments uyumlu API

Yollar, x-api-key başlığı, istek ve yanıt alanları, durumlar ve x-nowpayments-sig IPN imzası NOWPayments dokümanlarını izler; bu yüzden mevcut kod genellikle yalnızca yeni bir temel URL, API key ve IPN secret ister. Başka bir yerden mi geliyorsunuz? Geçişe genel bakışa bakın.

Altta düzenli bir blockwallets faturası vardır: alım adresleri sizindir, ödeme sayfası bizim barındırdığımız ödeme sayfasıdır ve bir ödeme ancak zincirde onaylanıp ikinci bir node ile çapraz kontrol edildiğinde sayılır. Aşağıda: üç adım, ardından her API'nin neyi desteklediği ve orijinalinden nasıl farklı olduğu — uygulamadığımız parametreler sessizce yok sayılmak yerine hata döndürür.

Üç adım

1. Bir satıcı hesabı edinin (ana sayfadan başvurun) ve panelde “Geliştiriciler › Entegrasyon ve anahtarlar” sayfasındaki “Web sitesi alan adları” altına alan adlarınızı ekleyin. Callback URL'leri (ipn_callback_url) ve yönlendirme URL'leri (success_url / cancel_url / redirect_url) bu alan adlarında ya da callback URL'nizin alan adında olmalıdır — sızan bir anahtar webhook'ları başka yere yönlendiremez.
2. Satıcı panelinde “Geliştiriciler › Entegrasyon ve anahtarlar” altında uyumlu kimlik bilgileri oluşturun; canlı için bir, test için bir takım: NOWPayments için bir API key + IPN secret, Coinbase Commerce için bir API key + webhook shared secret. Bir kez gösterilirler; biz yalnızca hash / şifreli metin saklarız.
3. Kodunuzu aşağıdaki temel URL'ye yönlendirin ve yeni anahtarları kullanın. Önce test kimlik bilgileriyle testnet'lerde çalıştırın, sonra canlıya geçin.

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();

Desteklenen endpoint'ler

Mevcut değil: ödemeler (payout), dönüşümler, saklama alt ortakları, abonelikler, update-merchant-estimate, fiat ödemeler. Bu yollar 404 döndürür.

IPN callback'leri

Bir ödeme son duruma ulaştığında oluşturma sırasında verilen ipn_callback_url adresine POST'larız; x-nowpayments-sig = HMAC-SHA512(IPN secret, anahtarlara göre özyinelemeli sıralanmış JSON) — tam olarak NOWPayments'ın doğrulama kodu. Gönderdiğimiz gövde zaten sıralı, sıkıştırılmış JSON'dur; bu yüzden ham gövde üzerinden HMAC de çalışır (ve çok küçük ondalıkları yeniden kodlaması JS'ten farklı olabilen PHP / Python'da en güvenli seçimdir). Başarısız callback'ler 1 dk, 5 dk, 30 dk, … sonra yeniden denenir — toplam 8 deneme.

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 ve failed hiç görünmez: onaylandığında finished olur ve bakiyenize yatırılır; hiçbir şey başka yere iletilmez.

Coin kodları

NOWPayments'tan farklar

• price_currency yalnızca usd olabilir (ayrıca 1:1 usdt / usdc); diğer fiat para birimleri 400 döndürür.
• pay_amount (sabit bir kripto tutarı), payout_address / payout_currency / payout_extra_id ve customer_email desteklenmez ve 400 döndürür.
• is_fixed_rate kabul edilir ama etkisi yoktur: kuru her zaman sabitleriz (BTC / LTC vb. birkaç borsanın medyan fiyatıyla, 30 dakika). is_fee_paid_by_user true ise platform ücreti pay_amount'a eklenir (platform ücreti 1%, hacim arttıkça düşer; bkz. fiyatlar).
• Ödemeler en fazla 12 saat geçerlidir (NOWPayments: 7 gün). partially_paid_url saklanır ve geri döndürülür, ancak ödeme sayfası oraya yönlendirmez.
• payment_id 10 haneli bir sayıdır; /invoice ile oluşturulan faturalarda ödemenin payment_id değeri fatura id değerine eşittir ve bir faturanın tam olarak bir ödemesi vardır (parent_payment_id ile yeniden yatırma yok).
• Yalnızca son durum ve partially_paid IPN'leri gönderilir (yukarıdaki tablo), waiting / confirming olanlar gönderilmez; fee.serviceFee platform ücretidir (alınan tutar × faturanın oluşturulduğu andaki oran, standart 1%), diğer ücretler 0'dır.

Test modu

Test kimlik bilgileriyle oluşturulan charge'lar ve ödemeler her zincirin testnet'inde çalışır ve webhook'ları test IPN secret / shared secret ile imzalanır — canlıdan tamamen ayrıdır: bir test anahtarı canlı ödemeleri göremez.

Geri kalan her şey (ödeme sayfası, onaylar, ağlar ve asgari tutarlar, iadeler) ana dokümanlardaki gibi çalışır.