// ドキュメント

開発者向けドキュメント

NextCryptoPay を数分で導入できます。一般的な連携の流れは次のとおりです。

AIエージェントで開発していますか？

Claude Code、Codex、CursorなどのAIエージェントでプロジェクトを開発している場合は、docs-agent.md をダウンロードしてエージェントに渡してください。NextCryptoPayを自動統合するために必要な情報がすべて含まれています。

docs-agent.md をダウンロード

1. APIキーを作成

ダッシュボード → APIキーでキーを生成します。シークレットはサーバーに保管し、ブラウザには置かないでください。

2. 請求書を作成

金額、通貨、チェーンを請求書エンドポイントに POST し、返却されたチェックアウトURLへお客様をリダイレクトします。

3. Webhookを受信

請求書が支払い済み、確認中、または期限切れになると、署名付きWebhookを送信します。Webhookシークレットで署名を検証してください。

認証

すべてのリクエストで、Authorization ヘッダーにシークレットキーを含めて認証してください。キーはダッシュボード → APIキーでショップごとに作成します（完全なキーは一度だけ表示されます）。

請求書を作成

注文金額、チェーン、アセットを送信します。payAddress とホスト型の checkoutUrl が返却されるので、お客様をそこへリダイレクトしてください。

リクエスト

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

レスポンス

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

支払いステータスを追跡

請求書をポーリングするか、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-cryptopay-signature ヘッダー（ショップのWebhookシークレットを使用した生ボディの HMAC-SHA256）を検証してください。5秒以内に 2xx を返してください — そうでない場合はバックオフ付きで再試行します。

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)
});

対応チェーン

Tron（USDT/USDC · TRC20）、Ethereum（USDT/USDC · ERC20）、BSC（USDT · BEP20）、Bitcoin（BTC）。手数料は成功した支払いごとに0.1%で、前払いの USDT 残高から課金されます（またはプランの枠でカバーされます）。