Tài liệu cho lập trình viên

Xác thực

Xác thực mọi request bằng secret key trong header Authorization. Tạo khóa theo từng shop ở Dashboard → API keys (khóa đầy đủ chỉ hiện một lần).

Tạo hóa đơn

Gửi số tiền đơn và asset; chain là tuỳ chọn. Bạn nhận lại checkoutUrl — chuyển khách hàng tới đó. Không truyền chain thì khách tự chọn mạng trên trang thanh toán.

Request

curl -X POST https://nextcryptopay.com/api/v1/invoices \
  -H "Authorization: Bearer ncp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "ORDER-1001",
    "amount": 99.50,
    "currency": "USD",
    "chain": "tron",
    "asset": "USDT",
    "webhookUrl": "https://yourstore.com/webhooks/nextcryptopay",
    "redirectUrl": "https://yourstore.com/thank-you"
  }'

Response

{
  "id": "inv_abc123",
  "orderId": "ORDER-1001",
  "payAddress": "TJ9xH4n2k8sQw7Lm3vR5pZ1aB6cD8eF2g",
  "cryptoAmount": "99.50",
  "asset": "USDT",
  "chain": "tron",
  "status": "PENDING",
  "expiresAt": "2026-06-17T10:00:00.000Z",
  "checkoutUrl": "https://nextcryptopay.com/pay/inv_abc123"
}

redirectUrl là nơi khách được đưa về vài giây sau khi trả tiền. Bỏ trống thì hệ thống dùng URL quay về của shop (Dashboard → Webhooks). Hãy đặt một trong hai — không có cái nào thì khách trả tiền xong đứng lại ở trang thanh toán, không có đường về cửa hàng. Tuyệt đối đừng giao hàng chỉ vì ai đó vào URL đó: chỉ webhook invoice.paid đã xác minh chữ ký mới chứng minh được đã thanh toán.

Theo dõi trạng thái

Poll hóa đơn, hoặc nhận cập nhật trực tiếp qua Server-Sent Events. Trạng thái: PENDING → CONFIRMING → PAID (hoặc EXPIRED / PARTIALLY_PAID).

# Poll the invoice
curl https://nextcryptopay.com/api/v1/invoices/inv_abc123

# Or subscribe to live updates (Server-Sent Events)
GET https://nextcryptopay.com/api/v1/invoices/inv_abc123/stream

Xác minh webhook

Mỗi khi đổi trạng thái, chúng tôi POST một sự kiện có chữ ký tới webhook URL của bạn. Hãy xác minh header x-nextcryptopay-signature (HMAC-SHA256 của raw body bằng webhook secret của shop) trước khi tin. Trả 2xx trong 15s — nếu không chúng tôi retry với backoff. Bộ header cũ x-cryptopay-* vẫn được gửi song song với giá trị y hệt cho tới 31/03/2027; mã mới nên dùng tên x-nextcryptopay-*.

import crypto from "node:crypto";

// Legacy x-cryptopay-* headers carry identical values and are still sent in
// parallel until 2027-03-31 — prefer x-nextcryptopay-* in new code.
app.post("/webhooks/nextcryptopay", (req, res) => {
  const signature = req.headers["x-nextcryptopay-signature"];
  const timestamp = req.headers["x-nextcryptopay-timestamp"];

  // Reject stale deliveries (replay protection): within 5 minutes
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(401).end();
  }

  // Signature is HMAC of "timestamp.rawBody"
  const expected = crypto
    .createHmac("sha256", process.env.NEXTCRYPTOPAY_WEBHOOK_SECRET)
    .update(timestamp + "." + req.rawBody) // raw JSON body
    .digest("hex");

  if (
    signature.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  ) {
    return res.status(401).end();
  }

  // Dedupe by delivery id (same event may be retried)
  const deliveryId = req.headers["x-nextcryptopay-delivery"];
  if (alreadyProcessed(deliveryId)) return res.status(200).end();

  const { event, invoice } = req.body;
  if (event === "invoice.paid") fulfillOrder(invoice.orderId);

  res.status(200).end(); // reply 2xx within 15s, else we retry (6 attempts, backoff)
});

Chain hỗ trợ

Tron (USDT/USDC · TRC20), Ethereum (USDT/USDC · ERC20), BSC (USDT · BEP20), TON (USDT · jetton), Bitcoin (BTC). Mỗi khoản thanh toán thành công chịu một khoản phí nền tảng có trần cho từng giao dịch, trừ từ số dư USDT trả trước của bạn (hoặc do hạn mức gói cước gánh). Xem trang Bảng giá để biết mức hiện hành.