// 文档

开发者文档

几分钟即可集成 NextCryptoPay。以下是一次典型集成的大致流程。

正在用 AI Agent 开发项目？

如果你正在使用 Claude Code、Codex、Cursor 或任何 AI Agent 开发项目，请下载 docs-agent.md 并交给你的 Agent——其中包含自动集成 NextCryptoPay 所需的一切。

下载 docs-agent.md

1. 创建 API 密钥

在仪表盘 → API 密钥中生成密钥。请将 secret 保存在您的服务器上，切勿放在浏览器中。

2. 创建发票

将金额、币种和链 POST 到发票接口，然后将客户重定向到返回的收银台 URL。

3. 接收 webhook

当发票支付、确认中或过期时，我们会发送带签名的 webhook。请使用您的 webhook secret 验证签名。

认证

每个请求都需在 Authorization 头中使用您的 secret key 进行认证。在仪表盘 → API 密钥中为每个店铺创建密钥（完整密钥仅显示一次）。

创建发票

发送订单金额和资产；chain 为可选项。你会拿到托管的 checkoutUrl，将客户跳转过去。不传 chain 时，由客户在支付页选择网络。

请求

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

响应

{
  "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 是客户付款几秒后被送回的地址。留空则使用店铺的返回网址（Dashboard → Webhooks）。请至少设置其中一个——两者都没有时，客户付款后会停留在支付页面，无法返回您的商店。切勿仅因为有人访问该地址就发货：只有经过签名校验的 invoice.paid webhook 才能证明已付款。

跟踪付款状态

轮询发票，或通过 Server-Sent Events 订阅实时更新。状态：PENDING → CONFIRMING → PAID（或 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

验证 webhook

每次状态变更时，我们都会向您的 webhook URL POST 一个带签名的事件。在信任之前，请验证 x-nextcryptopay-signature 头（使用您店铺的 webhook secret 对原始正文进行 HMAC-SHA256）。请在 15 秒内返回 2xx——否则我们会以退避方式重试。旧版 x-cryptopay-* 头仍会以相同的值并行发送，直到 2027-03-31；新代码请使用 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)
});

支持的链

Tron (USDT/USDC · TRC20), Ethereum (USDT/USDC · ERC20), BSC (USDT · BEP20), TON (USDT · jetton), Bitcoin (BTC). 每笔成功付款均收取平台费用，且设有单笔交易上限，从您的预付 USDT 余额中扣除（或由套餐额度覆盖）。当前费率请见价格页面。