API tương thích NOWPayments

Đường dẫn, header x-api-key, trường yêu cầu và phản hồi, trạng thái cùng chữ ký IPN x-nowpayments-sig đều theo tài liệu của NOWPayments, nên code hiện có thường chỉ cần URL gốc, API key và IPN secret mới. Đến từ nơi khác? Xem tổng quan chuyển đổi.

Bên dưới đó là một hóa đơn blockwallets bình thường: địa chỉ nhận tiền là của bạn, trang thanh toán là trang thanh toán do chúng tôi lưu trữ, và một khoản thanh toán chỉ được tính khi đã được xác nhận trên chuỗi và đối chiếu với node thứ hai. Phần dưới gồm: ba bước, rồi từng API hỗ trợ gì và khác bản gốc ở đâu — tham số chúng tôi không triển khai sẽ trả về lỗi chứ không bị bỏ qua âm thầm.

Ba bước

1. Có tài khoản người bán (đăng ký dùng ở trang chủ) và thêm tên miền của bạn trong “Tên miền website” ở “Nhà phát triển › Tích hợp & khóa” trong trang quản trị. URL callback (ipn_callback_url) và URL chuyển hướng (success_url / cancel_url / redirect_url) phải thuộc các tên miền đó hoặc tên miền của URL callback của bạn — khóa bị lộ cũng không thể trỏ webhook sang nơi khác.
2. Tạo thông tin xác thực tương thích trong trang quản trị ở mục “Nhà phát triển › Tích hợp & khóa”, một bộ cho live và một bộ cho thử nghiệm: NOWPayments dùng API key + IPN secret, Coinbase Commerce dùng API key + webhook shared secret. Chúng chỉ hiển thị một lần; chúng tôi chỉ lưu giá trị băm / bản mã hóa.
3. Trỏ code của bạn đến URL gốc bên dưới và dùng khóa mới. Chạy thử trên testnet bằng thông tin xác thực thử nghiệm trước, rồi mới chuyển sang 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 được hỗ trợ

Không có: chi trả (payout), quy đổi, đối tác con lưu ký, đăng ký định kỳ, update-merchant-estimate, thanh toán bằng tiền pháp định. Các đường dẫn này trả về 404.

Callback IPN

Khi một khoản thanh toán đạt trạng thái cuối, chúng tôi POST đến ipn_callback_url đã cho lúc tạo, với x-nowpayments-sig = HMAC-SHA512(IPN secret, JSON được sắp xếp đệ quy theo khóa) — đúng như code xác minh của NOWPayments. Nội dung chúng tôi gửi đã là JSON gọn và đã sắp xếp, nên tính HMAC trên nội dung thô cũng được (và là lựa chọn an toàn nhất trong PHP / Python, vì chúng mã hóa lại các số thập phân rất nhỏ có thể khác JS). Callback thất bại được thử lại sau 1 phút, 5 phút, 30 phút, … — tổng cộng 8 lần.

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 và failed không bao giờ xuất hiện: sau khi được xác nhận là finished và được ghi có vào số dư của bạn; không có gì được chuyển tiếp.

Mã coin

Khác biệt so với NOWPayments

• price_currency chỉ là usd (cùng usdt / usdc theo 1:1); tiền pháp định khác trả về 400.
• pay_amount (số tiền mã hóa cố định), payout_address / payout_currency / payout_extra_id và customer_email không được hỗ trợ và trả về 400.
• is_fixed_rate được chấp nhận nhưng không có tác dụng: chúng tôi luôn chốt tỷ giá (BTC / LTC v.v. theo trung vị của nhiều sàn, trong 30 phút). Khi is_fee_paid_by_user là true, phí nền tảng được cộng vào pay_amount (phí nền tảng là 1%, thấp hơn khi doanh số cao hơn; xem bảng giá).
• Khoản thanh toán có hiệu lực tối đa 12 giờ (NOWPayments: 7 ngày). partially_paid_url được lưu và trả lại nguyên vẹn, nhưng trang thanh toán không chuyển hướng đến đó.
• payment_id là số 10 chữ số; với hóa đơn tạo bằng /invoice, payment_id của khoản thanh toán bằng id của hóa đơn, và một hóa đơn chỉ có đúng một khoản thanh toán (không có nạp lại kiểu parent_payment_id).
• Chỉ gửi IPN của trạng thái cuối và partially_paid (bảng trên), không gửi waiting / confirming; fee.serviceFee là phí nền tảng (số tiền đã nhận × mức phí lúc tạo hóa đơn, 1% tiêu chuẩn), các phí khác bằng 0.

Chế độ thử nghiệm

Charge và thanh toán tạo bằng thông tin xác thực thử nghiệm chạy trên testnet của từng chuỗi và webhook của chúng được ký bằng IPN secret / shared secret thử nghiệm — tách biệt hoàn toàn với live: khóa thử nghiệm không thấy được các khoản thanh toán live.

Mọi thứ còn lại (trang thanh toán, xác nhận, mạng và mức tối thiểu, hoàn tiền) hoạt động như trong tài liệu chính.