API ที่เข้ากันได้กับ NOWPayments

พาธ เฮดเดอร์ x-api-key ฟิลด์คำขอและการตอบกลับ สถานะ และลายเซ็น IPN x-nowpayments-sig เป็นไปตามเอกสารของ NOWPayments โค้ดเดิมจึงมักต้องการเพียง base URL, API key และ IPN secret ใหม่ ย้ายมาจากที่อื่น? ดูภาพรวมการย้าย

ภายในเป็นใบแจ้งหนี้ blockwallets ปกติ: ที่อยู่รับเงินเป็นของคุณ หน้าชำระเงินคือหน้าชำระเงินที่เราโฮสต์ และการชำระจะนับก็ต่อเมื่อยืนยันบนเชนแล้วและตรวจไขว้กับโหนดที่สอง ต่อไปนี้: สามขั้นตอน จากนั้นสิ่งที่แต่ละ API รองรับและต่างจากต้นฉบับอย่างไร พารามิเตอร์ที่เราไม่ได้ทำจะตอบข้อผิดพลาด ไม่ถูกเมินไปเงียบ ๆ

สามขั้นตอน

1. สมัครบัญชีร้านค้า (ขอใช้งานที่หน้าแรก) และเพิ่มโดเมนของคุณที่ “โดเมนเว็บไซต์” ใน “นักพัฒนา › การเชื่อมต่อและคีย์” ของแดชบอร์ด URL callback (ipn_callback_url) และ URL เปลี่ยนเส้นทาง (success_url / cancel_url / redirect_url) ต้องอยู่ในโดเมนเหล่านั้นหรือโดเมนของ URL callback ของคุณ คีย์ที่รั่วไหลจึงชี้ Webhook ไปที่อื่นไม่ได้
2. สร้างข้อมูลรับรองที่เข้ากันได้ในแดชบอร์ดร้านค้าที่ “นักพัฒนา › การเชื่อมต่อและคีย์” ชุดใช้งานจริงและชุดทดสอบอย่างละชุด: NOWPayments ได้ API key + IPN secret ส่ง Coinbase Commerce ได้ API key + webhook shared secret แสดงเพียงครั้งเดียว เราเก็บเฉพาะค่าแฮช / ข้อความเข้ารหัส
3. ชี้โค้ดของคุณไปที่ base URL ด้านล่างและใช้คีย์ใหม่ รันบนเทสต์เน็ตด้วยข้อมูลรับรองทดสอบก่อน แล้วค่อยสลับเป็นใช้งานจริง

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 ที่รองรับ

ไม่มี: การจ่ายออก การแปลงสกุล sub-partner แบบฝากเก็บ การสมัครสมาชิกแบบรายคาบ update-merchant-estimate การชำระด้วยเงินตรา เส้นทางเหล่านี้ตอบ 404

IPN callback

เมื่อการชำระถึงสถานะสุดท้าย เราส่ง POST ไปที่ ipn_callback_url ที่ระบุตอนสร้าง โดย x-nowpayments-sig = HMAC-SHA512(IPN secret, JSON ที่เรียงตามคีย์แบบเรียกซ้ำ) ซึ่งตรงกับโค้ดตรวจสอบของ NOWPayments ทุกประการ เนื้อหาที่เราส่งเรียงลำดับและกะทัดรัดอยู่แล้ว จึงใช้ HMAC บนเนื้อหาดิบก็ได้เช่นกัน (และปลอดภัยที่สุดใน PHP / Python ที่การเข้ารหัสใหม่ของทศนิยมที่เล็กมากอาจต่างจาก JS) callback ที่ล้มเหลวจะลองใหม่หลัง 1 นาที, 5 นาที, 30 นาที, … รวม 8 ครั้ง

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 และ failed ไม่เคยปรากฏ: เมื่อยืนยันแล้วเป็น finished และบันทึกเข้ายอดคงเหลือของคุณ ไม่มีการโอนต่อ

สัญลักษณ์เหรียญ

ข้อแตกต่างจาก NOWPayments

• price_currency ใช้ได้เฉพาะ usd (และ usdt / usdc ที่ 1:1) เงินตราอื่นตอบ 400
• pay_amount (จำนวนคริปโตคงที่), payout_address / payout_currency / payout_extra_id และ customer_email ไม่รองรับและตอบ 400
• is_fixed_rate รับได้แต่ไม่มีผล: เราล็อกอัตราเสมอ (BTC / LTC เป็นต้นด้วยค่ามัธยฐานจากหลายกระดานเทรด เป็นเวลา 30 นาที) เมื่อ is_fee_paid_by_user เป็น true ค่าธรรมเนียมแพลตฟอร์มจะบวกเข้า pay_amount (ค่าธรรมเนียมแพลตฟอร์มคือ 1% ลดลงเมื่อยอดสูงขึ้น ดูราคา)
• การชำระมีอายุได้สูงสุด 12 ชั่วโมง (NOWPayments: 7 วัน) partially_paid_url ถูกเก็บและส่งกลับ แต่หน้าชำระเงินไม่เปลี่ยนเส้นทางไปที่นั่น
• payment_id เป็นตัวเลข 10 หลัก สำหรับใบแจ้งหนี้ที่สร้างด้วย /invoice payment_id ของการชำระเท่ากับ id ของใบแจ้งหนี้ และหนึ่งใบแจ้งหนี้มีการชำระเดียวพอดี (ไม่มีการฝากซ้ำแบบ parent_payment_id)
• ส่งเฉพาะ IPN ของสถานะสุดท้ายและ partially_paid (ตารางด้านบน) ไม่มี waiting / confirming fee.serviceFee คือค่าธรรมเนียมแพลตฟอร์ม (ยอดที่ได้รับ × อัตราตอนสร้างใบแจ้งหนี้ มาตรฐาน 1%) ค่าธรรมเนียมอื่นเป็น 0

โหมดทดสอบ

charge และการชำระที่สร้างด้วยข้อมูลรับรองทดสอบรันบนเทสต์เน็ตของแต่ละเชน และ Webhook ของมันเซ็นด้วย IPN secret / shared secret ของชุดทดสอบ แยกจากใช้งานจริงโดยสิ้นเชิง: คีย์ทดสอบมองไม่เห็นการชำระจริง

ส่วนที่เหลือทั้งหมด (หน้าชำระเงิน การยืนยัน เครือข่ายและยอดขั้นต่ำ การคืนเงิน) ทำงานเหมือนในเอกสารหลัก