개발자 문서

인증

모든 요청은 Authorization 헤더에 시크릿 키를 넣어 인증하세요. 대시보드 → 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은 결제 후 몇 초 뒤 고객을 돌려보낼 주소입니다. 생략하면 상점의 돌아갈 URL(Dashboard → Webhooks)이 사용됩니다. 둘 중 하나는 반드시 설정하세요. 둘 다 없으면 고객이 결제 페이지에 갈 곳 없이 남습니다. 누군가 그 URL에 접속했다는 이유만으로 주문을 처리하지 마세요. 결제를 증명하는 것은 서명을 검증한 invoice.paid 웹훅뿐입니다.

결제 상태 추적

인보이스를 폴링하거나 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

웹훅 검증

상태가 변경될 때마다 서명된 이벤트를 귀하의 웹훅 URL로 POST합니다. 신뢰하기 전에 x-nextcryptopay-signature 헤더(상점의 웹훅 시크릿을 사용한 원본 본문의 HMAC-SHA256)를 검증하세요. 15초 이내에 2xx를 반환하세요 — 그렇지 않으면 백오프로 재시도합니다. 기존 x-cryptopay-* 헤더는 2027년 3월 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 잔액에서 차감되거나 플랜 한도로 충당됩니다. 현재 요율은 요금 페이지를 참고하세요.