API kompatibel NOWPayments

Path, header x-api-key, field permintaan dan respons, status, serta tanda tangan IPN x-nowpayments-sig mengikuti dokumentasi NOWPayments, sehingga kode yang ada biasanya hanya perlu base URL, API key, dan IPN secret baru. Datang dari tempat lain? Lihat ringkasan migrasi.

Di baliknya adalah tagihan blockwallets biasa: alamat penerima milik Anda, halaman pembayaran adalah kasir yang kami host, dan pembayaran baru dihitung setelah terkonfirmasi di chain dan diperiksa silang dengan node kedua. Di bawah ini: tiga langkah, lalu apa yang didukung setiap API dan apa bedanya dengan aslinya — parameter yang tidak kami implementasikan mengembalikan error, bukan diabaikan diam-diam.

Tiga langkah

1. Dapatkan akun merchant (ajukan di beranda) dan tambahkan domain Anda di “Domain situs web” pada “Developer › Integrasi & kunci” di dasbor. URL callback (ipn_callback_url) dan URL pengalihan (success_url / cancel_url / redirect_url) harus berada di domain itu atau di domain URL callback Anda — kunci yang bocor tidak bisa mengarahkan webhook ke tempat lain.
2. Buat kredensial kompatibel di dasbor merchant pada “Developer › Integrasi & kunci”, satu set untuk live dan satu untuk uji: NOWPayments mendapat API key + IPN secret, Coinbase Commerce mendapat API key + webhook shared secret. Semuanya ditampilkan sekali; kami hanya menyimpan hash / ciphertext.
3. Arahkan kode Anda ke base URL di bawah dan pakai kunci baru. Jalankan dulu di testnet dengan kredensial uji, lalu beralih ke 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();

Endpoint yang didukung

Tidak tersedia: payout, konversi, sub-partner kustodian, langganan, update-merchant-estimate, pembayaran fiat. Path tersebut mengembalikan 404.

Callback IPN

Saat pembayaran mencapai status akhir, kami mengirim POST ke ipn_callback_url yang diberikan saat pembuatan, dengan x-nowpayments-sig = HMAC-SHA512(IPN secret, JSON yang diurutkan berdasarkan key secara rekursif) — persis kode verifikasi NOWPayments. Body yang kami kirim sudah berupa JSON ringkas yang terurut, jadi HMAC atas body mentah juga berfungsi (dan paling aman di PHP / Python, yang encode ulang desimal sangat kecil bisa berbeda dari JS). Callback yang gagal dicoba lagi setelah 1 mnt, 5 mnt, 30 mnt, … — total 8 percobaan.

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, dan failed tidak pernah muncul: setelah terkonfirmasi statusnya finished dan dikreditkan ke saldo Anda; tidak ada yang diteruskan.

Ticker mata uang

Perbedaan dari NOWPayments

• price_currency hanya usd (plus usdt / usdc pada 1:1); fiat lain mengembalikan 400.
• pay_amount (jumlah kripto tetap), payout_address / payout_currency / payout_extra_id, dan customer_email tidak didukung dan mengembalikan 400.
• is_fixed_rate diterima tetapi tidak berpengaruh: kami selalu mengunci kurs (BTC / LTC dll. pada median beberapa exchange, selama 30 menit). Jika is_fee_paid_by_user true, biaya platform ditambahkan ke pay_amount (biaya platform 1%, makin rendah pada volume lebih tinggi; lihat harga).
• Pembayaran berlaku hingga 12 jam (NOWPayments: 7 hari). partially_paid_url disimpan dan dikembalikan apa adanya, tetapi kasir tidak mengalihkan ke sana.
• payment_id adalah angka 10 digit; untuk invoice yang dibuat dengan /invoice, payment_id pembayarannya sama dengan id invoice, dan satu invoice punya tepat satu pembayaran (tanpa setoran ulang parent_payment_id).
• Hanya IPN berstatus akhir dan partially_paid yang dikirim (tabel di atas), tanpa waiting / confirming; fee.serviceFee adalah biaya platform (jumlah yang diterima × tarif saat tagihan dibuat, 1% standar), biaya lainnya 0.

Mode uji

Charge dan pembayaran yang dibuat dengan kredensial uji berjalan di testnet tiap chain dan webhook-nya ditandatangani dengan IPN secret / shared secret uji — sepenuhnya terpisah dari live: kunci uji tidak bisa melihat pembayaran live.

Sisanya (kasir, konfirmasi, jaringan dan minimum, refund) bekerja seperti di dokumentasi utama.