// tài liệu

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

Tích hợp NextCryptoPay trong vài phút. Dưới đây là hình dung về một tích hợp điển hình.

Bạn đang phát triển dự án bằng AI agent?

Nếu bạn đang dùng Claude Code, Codex, Cursor hay bất kỳ AI agent nào để phát triển dự án, hãy tải docs-agent.md và gửi cho agent của bạn — file chứa mọi thứ cần thiết để tích hợp NextCryptoPay tự động.

Tải docs-agent.md

1. Tạo API key

Tạo khóa ở Dashboard → API keys. Giữ secret ở phía máy chủ, không bao giờ để lộ trên trình duyệt.

2. Tạo hóa đơn

Gửi POST số tiền, loại tiền và chain tới endpoint invoices, rồi chuyển khách hàng tới checkout URL trả về.

3. Nhận webhook

Chúng tôi gửi webhook có chữ ký khi hóa đơn được thanh toán, đang xác nhận hoặc hết hạn. Hãy xác minh chữ ký bằng webhook secret của bạ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, chain và asset. Bạn nhận lại payAddress và checkoutUrl — chuyển khách hàng tới đó.

Request

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

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"
}

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-cryptopay-signature (HMAC-SHA256 của raw body bằng webhook secret của shop) trước khi tin. Trả 2xx trong 5s — nếu không chúng tôi retry với backoff.

import crypto from "node:crypto";

app.post("/webhooks/cryptopay", (req, res) => {
  const signature = req.headers["x-cryptopay-signature"];
  const timestamp = req.headers["x-cryptopay-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.CRYPTOPAY_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-cryptopay-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), Bitcoin (BTC). Phí 0,1% trên mỗi thanh toán thành công, trừ từ số dư USDT trả trước (hoặc phủ bởi hạn mức gói).